### Install IntlPull CLI Source: https://intlpull.com/docs/cli Install the CLI globally or run it directly using npx. ```bash npm install -g @intlpullhq/cli ``` ```bash npx @intlpullhq/cli ``` -------------------------------- ### Install IntlPull CLI Source: https://intlpull.com/docs/getting-started Install the global CLI tool to manage translation synchronization. ```bash npm install -g @intlpullhq/cli ``` -------------------------------- ### Install Contentful SDK Source: https://intlpull.com/docs/integrations/contentful Install the Contentful SDK for IntlPull using npm or pnpm. ```bash npm install @intlpullhq/contentful # or pnpm add @intlpullhq/contentful ``` -------------------------------- ### Install and Configure next-intl Source: https://intlpull.com/docs/integrations Install next-intl, configure next.config.js, and set up i18n server configuration for dynamic locale loading. ```javascript // Install npm install next-intl // next.config.js const withNextIntl = require('next-intl/plugin')(); module.exports = withNextIntl({}); // i18n.ts import { getRequestConfig } from 'next-intl/server'; export default getRequestConfig(async ({ locale }) => ({ messages: (await import(`./messages/${locale}.json`)).default })); // Use in components import { useTranslation } from '@/hooks/useTranslation'; export default function Welcome() { const { t } = useTranslation('common'); return

{t('welcome')}

; } ``` -------------------------------- ### Install and Configure react-i18next Source: https://intlpull.com/docs/integrations Install react-i18next and i18next, then configure i18n with resources and fallback language. ```javascript // Install npm install react-i18next i18next // Configure import i18n from 'i18next'; import { initReactI18next } from 'react-i18next'; import en from './messages/en.json'; import es from './messages/es.json'; i18n.use(initReactI18next).init({ resources: { en: { translation: en }, es: { translation: es } }, lng: 'en', fallbackLng: 'en', }); // Use in components import { useTranslation } from 'react-i18next'; function Welcome() { const { t } = useTranslation(); return

{t('common.welcome')}

; } ``` -------------------------------- ### Copilot Instructions for i18next Source: https://intlpull.com/docs/copilot Configure Copilot instructions to guide it on your project's i18n patterns, specifically for i18next. This includes key conventions, usage examples, translation file locations, and what should not be hardcoded. ```markdown # Translation Guidelines This project uses i18next for internationalization. ## Key Conventions - Use `useTranslation` hook for all user-facing text - Import from react-i18next: `import { useTranslation } from 'react-i18next'` - Key format: namespace.section.element (e.g., checkout.form.submitButton) ## Example Usage ```tsx import { useTranslation } from 'react-i18next'; function Button() { const { t } = useTranslation('common'); return ; } ``` ## Translation Files - Location: ./messages/{lang}.json - Source language: English (en) - Use IntlPull CLI for syncing: `npx @intlpullhq/cli upload` and `npx @intlpullhq/cli download` ## Never Hardcode - Button labels, form labels, error messages - Navigation items, page titles, headings - Placeholder text, tooltips, descriptions ## Pluralization Use ICU message format: ```json { "items": "{count, plural, =0 {No items} one {# item} other {# items}}" } ``` ``` -------------------------------- ### IntlPull Configuration File Source: https://intlpull.com/docs/cli Example structure of the intlpull.config.js file. ```javascript module.exports = { projectId: 'proj_abc123', sourceLanguage: 'en', outputDir: './messages', format: 'json', namespaces: ['common', 'auth', 'settings'] } ``` -------------------------------- ### Install MCP Server Globally Source: https://intlpull.com/docs/mcp Install the IntlPull MCP server globally using npm. This command is typically run once to set up the server on your machine. ```bash npm install -g @intlpullhq/mcp-server ``` -------------------------------- ### Install and Configure vue-i18n Source: https://intlpull.com/docs/integrations Install vue-i18n, configure the i18n instance with legacy mode disabled, and provide messages. ```javascript // Install npm install vue-i18n // main.js import { createApp } from 'vue'; import { createI18n } from 'vue-i18n'; import en from './messages/en.json'; import es from './messages/es.json'; const i18n = createI18n({ legacy: false, locale: 'en', messages: { en, es } }); createApp(App).use(i18n).mount('#app'); // Use in components ``` -------------------------------- ### Example .windsurfrules Configuration Source: https://intlpull.com/docs/windsurf Define your internationalization workflow in a .windsurfrules file. This includes extraction, key management, naming conventions, and translation processes. ```plaintext When handling internationalization: 1. Extract hardcoded strings to translation keys 2. Use IntlPull MCP for key management 3. Follow the project's naming conventions 4. Add descriptions for context Key naming format: namespace.section.element Example: checkout.form.submitButton Translation files location: ./messages/{lang}.json When creating translation keys: - Use IntlPull MCP to create keys - Include context descriptions - Set max_length for UI constraints When translating: - Use IntlPull MCP to translate missing keys - Review translations for UI fit - Check pluralization rules for target languages ``` -------------------------------- ### GET /api/v1/projects Source: https://intlpull.com/docs/api Retrieve a list of all projects associated with the authenticated account. ```APIDOC ## GET /api/v1/projects ### Description List all projects available in the account. ### Method GET ### Endpoint /api/v1/projects ### Response #### Success Response (200) - **projects** (array) - List of project objects #### Response Example { "projects": [ { "id": "proj_abc123", "name": "My App", "sourceLanguage": "en", "targetLanguages": ["es", "fr", "de"], "stringCount": 1250 } ] } ``` -------------------------------- ### Get Project Translations Source: https://intlpull.com/docs/api Retrieve all translations for a specific project, organized by language. ```json { "translations": { "en": { "common.welcome": "Welcome", "common.logout": "Log out" }, "es": { "common.welcome": "Bienvenido", "common.logout": "Cerrar sesión" } } } ``` -------------------------------- ### GET /api/v1/projects/:id/export Source: https://intlpull.com/docs/api Export project translations. ```APIDOC ## GET /api/v1/projects/:id/export ### Description Export translations in various formats. ### Method GET ### Endpoint /api/v1/projects/:id/export ### Parameters #### Path Parameters - **id** (string) - Required - The project ID ### Response #### Success Response (200) - **data** (object) - Exported translation data #### Response Example { "common.welcome": "Welcome", "common.logout": "Log out" } ``` -------------------------------- ### GET /api/v1/projects/:id/translations Source: https://intlpull.com/docs/api Retrieve all translation strings for a specific project. ```APIDOC ## GET /api/v1/projects/:id/translations ### Description Get all translations for a project. ### Method GET ### Endpoint /api/v1/projects/:id/translations ### Parameters #### Path Parameters - **id** (string) - Required - The project ID ### Response #### Success Response (200) - **translations** (object) - Map of language codes to translation keys and values #### Response Example { "translations": { "en": { "common.welcome": "Welcome", "common.logout": "Log out" }, "es": { "common.welcome": "Bienvenido", "common.logout": "Cerrar sesión" } } } ``` -------------------------------- ### Export Translations Source: https://intlpull.com/docs/api Export translations from a project. The response format depends on the requested export format (not specified in this example). ```json { "common.welcome": "Welcome", "common.logout": "Log out" } ``` -------------------------------- ### Initialize IntlPull Project Source: https://intlpull.com/docs/getting-started Run this command in the project root to generate the configuration file and link the project. ```bash npx @intlpullhq/cli init ``` -------------------------------- ### Create Copilot Instructions File Source: https://intlpull.com/docs/copilot Create the directory and an empty file for Copilot instructions. ```bash mkdir -p .github && touch .github/copilot-instructions.md ``` -------------------------------- ### Configure API Key and Project ID Source: https://intlpull.com/docs/mcp Set environment variables for your IntlPull API key and optionally your project ID. The API key is required for authentication. ```bash # Set your API key export INTLPULL_API_KEY="ip_live_your_api_key_here" # Optionally set a default project export INTLPULL_PROJECT_ID="your_project_id" ``` -------------------------------- ### Initialize ContentfulSync SDK Source: https://intlpull.com/docs/integrations/contentful Initialize the ContentfulSync class with your Contentful and IntlPull credentials and configuration. This sets up the connection for pulling and pushing content. ```javascript import { ContentfulSync } from '@intlpullhq/contentful'; const sync = new ContentfulSync({ // Contentful credentials spaceId: 'your-space-id', environment: 'master', accessToken: 'your-delivery-api-token', managementToken: 'your-management-api-token', // For push // IntlPull credentials projectId: 'your-intlpull-project-id', apiKey: 'your-intlpull-api-key', // Configuration sourceLocale: 'en-US', contentTypes: ['blogPost', 'page'], // Optional namespace: 'contentful', }); ``` -------------------------------- ### List All Projects Source: https://intlpull.com/docs/api Retrieve a list of all projects associated with your account. ```json { "projects": [ { "id": "proj_abc123", "name": "My App", "sourceLanguage": "en", "targetLanguages": ["es", "fr", "de"], "stringCount": 1250 } ] } ``` -------------------------------- ### Implement IntlPull in Android (Kotlin) Source: https://intlpull.com/docs/sdks Initialize the SDK in the Application class and use the translation function in activities, fragments, or Jetpack Compose. ```kotlin // Application.kt import com.intlpull.IntlPull class MyApplication : Application() { override fun onCreate() { super.onCreate() IntlPull.configure(this, "proj_abc123") IntlPull.sync() } } // Use in activities/fragments import com.intlpull.IntlPull.t class MainActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) binding.welcomeText.text = t("common.welcome") } } // With Jetpack Compose @Composable fun Welcome() { val t = rememberIntlPull() Text(text = t("common.welcome")) } ``` -------------------------------- ### Implement IntlPull in iOS (Swift) Source: https://intlpull.com/docs/sdks Configure the SDK in the AppDelegate and access translations via the IntlPull static helper or SwiftUI environment. ```swift // AppDelegate.swift import IntlPull @main class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { IntlPull.configure(projectId: "proj_abc123") IntlPull.shared.sync() return true } } // Use in views import IntlPull struct ContentView: View { var body: some View { Text(IntlPull.t("common.welcome")) } } // Or with SwiftUI environment struct ContentView: View { @Environment(\.intlpull) var t var body: some View { Text(t("common.welcome")) } } ``` -------------------------------- ### CI/CD Sync Source: https://intlpull.com/docs/cli Sync translations as part of a build pipeline. ```bash npx @intlpullhq/cli sync && npm run build ``` -------------------------------- ### IntlPull CLI: Download Translations Source: https://intlpull.com/docs/copilot Download the latest translations from the IntlPull service to your local translation files. ```bash npx @intlpullhq/cli download ``` -------------------------------- ### Upload Translation Keys Source: https://intlpull.com/docs/getting-started Push local translation keys to the IntlPull dashboard. ```bash npx @intlpullhq/cli upload ``` -------------------------------- ### Project i18n Guidelines Source: https://intlpull.com/docs/cursor Define project-specific internationalization conventions in a `.cursorrules` file. This includes translation key formats, workflow steps, pluralization rules, and file structure. ```plaintext # i18n Guidelines When working with translations in this project: ## Key Conventions - Always use react-i18next for translations - Namespace format: feature.section.element (e.g., checkout.form.submitButton) - Never hardcode user-facing strings - Use IntlPull MCP to create and manage translation keys ## Translation Workflow 1. Extract hardcoded strings to translation keys 2. Use IntlPull MCP to create keys with English values 3. Add context descriptions for translators 4. Translate to target languages using IntlPull ## Plurals and Formatting - Use ICU message format for plurals - Keep key names in English, values localized - Add max_length constraints for UI elements with limited space ## File Structure - Translation files: ./messages/{lang}.json - Use flat keys within namespaces ``` -------------------------------- ### Configure MCP Server in Cursor Source: https://intlpull.com/docs/cursor Configure the MCP server settings in Cursor by editing the `~/.cursor/mcp.json` file. Ensure your IntlPull API key is correctly set in the environment variables. ```json { "mcpServers": { "intlpull": { "command": "npx", "args": ["-y", "@intlpullhq/mcp-server"], "env": { "INTLPULL_API_KEY": "ip_live_your_api_key" } } } } ``` -------------------------------- ### MCP Server Configuration File Source: https://intlpull.com/docs/mcp Add IntlPull to your MCP configuration file. This JSON object specifies how the MCP server should run the IntlPull CLI, including environment variables. ```json { "mcpServers": { "intlpull": { "command": "npx", "args": ["-y", "@intlpullhq/mcp-server"], "env": { "INTLPULL_API_KEY": "ip_live_your_api_key_here" } } } } ``` -------------------------------- ### CLI: Pull Content Source: https://intlpull.com/docs/integrations/contentful Use the IntlPull CLI to pull content from Contentful. This command initiates the synchronization process from your command line. ```bash # Pull content from Contentful npx @intlpullhq/cli contentful pull ``` -------------------------------- ### Watch for Changes Source: https://intlpull.com/docs/cli Monitor translation changes and sync in real-time. ```bash npx @intlpullhq/cli watch ``` -------------------------------- ### POST /api/v1/projects/:id/import Source: https://intlpull.com/docs/api Import translation data into a project from a file. ```APIDOC ## POST /api/v1/projects/:id/import ### Description Import translations from file. ### Method POST ### Endpoint /api/v1/projects/:id/import ### Parameters #### Path Parameters - **id** (string) - Required - The project ID ### Response #### Success Response (200) - **imported** (number) - Count of imported items - **updated** (number) - Count of updated items - **skipped** (number) - Count of skipped items #### Response Example { "imported": 150, "updated": 25, "skipped": 0 } ``` -------------------------------- ### Migrate Translations Source: https://intlpull.com/docs/cli Import translations from external platforms. ```bash npx @intlpullhq/cli migrate --from lokalise ``` -------------------------------- ### CLI: Push Translations Source: https://intlpull.com/docs/integrations/contentful Use the IntlPull CLI to push translations to Contentful for specific locales. Specify locales using a comma-separated list. ```bash # Push translations to Contentful npx @intlpullhq/cli contentful push --locales de-DE,fr-FR ``` -------------------------------- ### CLI: Sync Specific Content Types Source: https://intlpull.com/docs/integrations/contentful Use the IntlPull CLI to pull content, filtering by specific content types. This allows for targeted synchronization of your Contentful data. ```bash # Sync specific content types npx @intlpullhq/cli contentful pull --content-types blogPost,page ``` -------------------------------- ### GitLab CI Configuration for Translation Sync Source: https://intlpull.com/docs/integrations Integrates IntlPull CLI sync command into a GitLab CI pipeline. It runs on the main branch and saves translated files as artifacts. ```yaml # .gitlab-ci.yml sync-translations: stage: prepare image: node:20 script: - npx @intlpullhq/cli sync artifacts: paths: - messages/ only: - main ``` -------------------------------- ### Test API Key with Curl Source: https://intlpull.com/docs/cursor Test your IntlPull API key by making a curl request to the IntlPull API. This helps diagnose issues if the MCP server is not connecting. ```bash curl -H "X-API-Key: ip_live_..." https://api.intlpull.com/v1/projects ``` -------------------------------- ### Verify IntlPull Connection with Claude Source: https://intlpull.com/docs/cursor Verify the connection to your IntlPull projects by asking Claude in the Cursor IDE. This confirms your API key and server configuration are correct. ```plaintext Can you check my IntlPull connection and list my projects? ``` -------------------------------- ### Create Translation Key Source: https://intlpull.com/docs/api Create a new translation key within a project. Requires the project ID. ```json { "key": { "id": "key_xyz789", "name": "common.submit", "value": "Submit", "namespace": "common" } } ``` -------------------------------- ### VS Code Tasks for IntlPull Source: https://intlpull.com/docs/copilot Configure VS Code tasks in `.vscode/tasks.json` to quickly execute common IntlPull CLI commands for managing translations. ```json { "version": "2.0.0", "tasks": [ { "label": "IntlPull: Push translations", "type": "shell", "command": "npx @intlpullhq/cli upload", "problemMatcher": [] }, { "label": "IntlPull: Pull translations", "type": "shell", "command": "npx @intlpullhq/cli download", "problemMatcher": [] }, { "label": "IntlPull: Translate missing", "type": "shell", "command": "npx @intlpullhq/cli translate --lang es,fr,de", "problemMatcher": [] }, { "label": "IntlPull: Check status", "type": "shell", "command": "npx @intlpullhq/cli status", "problemMatcher": [] } ] } ``` -------------------------------- ### Sync Translations Source: https://intlpull.com/docs/getting-started Download translations from the dashboard to the local messages directory. ```bash npx @intlpullhq/cli sync ``` -------------------------------- ### POST /api/v1/projects/:id/keys Source: https://intlpull.com/docs/api Create a new translation key within a specific project. ```APIDOC ## POST /api/v1/projects/:id/keys ### Description Create a new translation key. ### Method POST ### Endpoint /api/v1/projects/:id/keys ### Parameters #### Path Parameters - **id** (string) - Required - The project ID ### Response #### Success Response (200) - **key** (object) - The created key details #### Response Example { "key": { "id": "key_xyz789", "name": "common.submit", "value": "Submit", "namespace": "common" } } ``` -------------------------------- ### Import Translations Source: https://intlpull.com/docs/api Import translations into a project from a file. The response indicates the number of imported, updated, and skipped entries. ```json { "imported": 150, "updated": 25, "skipped": 0 } ``` -------------------------------- ### Configure Claude Code MCP Server Source: https://intlpull.com/docs/claude-code Add the IntlPull MCP server configuration to your Claude Code MCP config file. Ensure your INTLPULL_API_KEY is set. ```json # ~/.config/claude/mcp.json (or the appropriate config path) { "mcpServers": { "intlpull": { "command": "npx", "args": ["-y", "@intlpullhq/mcp-server"], "env": { "INTLPULL_API_KEY": "ip_live_your_api_key" } } } } ``` -------------------------------- ### API Base URL Source: https://intlpull.com/docs/api The base URL for all IntlPull API endpoints. ```url https://api.intlpull.com ``` -------------------------------- ### IntlPull CLI: Translate Missing Content Source: https://intlpull.com/docs/copilot Automatically translate missing strings to specified target languages (e.g., Spanish, French, German) using the IntlPull CLI. ```bash npx @intlpullhq/cli translate --lang es,fr,de ``` -------------------------------- ### GitHub Actions Workflow for Syncing Translations Source: https://intlpull.com/docs/integrations This GitHub Actions workflow synchronizes translations on push to the main branch using IntlPull CLI. It requires an INTLPULL_API_KEY secret. ```yaml # .github/workflows/sync-translations.yml name: Sync Translations on: push: branches: [main] jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node uses: actions/setup-node@v4 with: node-version: '20' - name: Sync translations run: npx @intlpullhq/cli sync env: INTLPULL_API_KEY: ${{ secrets.INTLPULL_API_KEY }} - name: Commit changes uses: stefanzweifel/git-auto-commit-action@v5 with: commit_message: 'chore: sync translations' ``` -------------------------------- ### CLAUDE.md i18n Workflow Configuration Source: https://intlpull.com/docs/claude-code Define i18n guidelines and conventions in your CLAUDE.md file for Claude to understand your translation workflow. This includes key conventions, translation commands, and project structure. ```markdown ## i18n Workflow This project uses IntlPull for translation management. ### Key Conventions - Use IntlPull MCP to create and manage translation keys - Namespace format: feature.section.element (e.g., checkout.form.submitButton) - Never hardcode user-facing strings - Always add context descriptions for translators ### Translation Commands - Create key: Use IntlPull MCP to create keys with English values - Translate: Run `npx @intlpullhq/cli upload` after adding new keys - Sync: Run `npx @intlpullhq/cli download` to get latest translations ### Project Structure - Translation keys: ./messages/{lang}.json - Source language: English (en) - Target languages: Spanish (es), French (fr), German (de) ``` -------------------------------- ### Push Translations to Contentful Source: https://intlpull.com/docs/integrations/contentful Use the `push` method on the ContentfulSync instance to export translations from IntlPull back to Contentful for specified locales. Logs the number of translations pushed. ```javascript // Push translations from IntlPull to Contentful const pushResult = await sync.push(['de-DE', 'fr-FR']); console.log(`Pushed ${pushResult.stats.translationsPushed} translations`); ``` -------------------------------- ### Check Translation Status Source: https://intlpull.com/docs/cli Display translation status and identify missing keys. ```bash npx @intlpullhq/cli status ``` -------------------------------- ### Find Missing Translations Source: https://intlpull.com/docs/cli Scan for missing translation keys across all languages. ```bash npx @intlpullhq/cli check ``` -------------------------------- ### Implement IntlPull in React Native Source: https://intlpull.com/docs/sdks Wrap the application with the IntlPullProvider and use the useTranslation hook for component-level localization. ```typescript // App.tsx import { IntlPullProvider } from '@intlpullhq/react-native'; export default function App() { return ( ); } // Use in components import { useTranslation } from '@intlpullhq/react-native'; function Welcome() { const { t, language, setLanguage } = useTranslation(); return ( {t('common.welcome')}