{
  "markdown": "# ai-l10n\r\n\r\n[![npm version](https://img.shields.io/npm/v/ai-l10n.svg)](https://www.npmjs.com/package/ai-l10n)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\r\n\r\nAI-powered translation for app localization. Automatically translate your i18n files to 165 languages using AI. Supports JSON, JSONC, Flutter ARB, YAML, PO, XLIFF, and all other text-based localization formats with intelligent project structure detection.\r\n\r\nPowered by [l10n](https://l10n.dev).dev\r\n\r\n![ai-localization example](https://raw.githubusercontent.com/l10n-dev/ai-l10n/main/demonstration-dark-ai-l10n.gif)\r\n\r\n## Features\r\n\r\nOne command turns your source file into 165 languages — from the CLI, an npm script, your CI pipeline, or your AI agent. No pasting files into a chat window, no broken placeholders, no re-translating everything because one string changed.\r\n\r\n```bash\r\nnpx ai-l10n translate ./locales/en.json --update\r\n```\r\n\r\n**Translate**\r\n\r\n- 🤖 **165 languages** — context-aware AI translation, not word-by-word machine output\r\n- 🎯 **Any text-based format** — JSON, JSONC, Flutter ARB, Shopify themes, YAML, PO (gettext), XLIFF, and more ([full list](https://l10n.dev/ws/translate-i18n-files#supported-formats))\r\n- 📁 **Zero setup** — target languages are auto-detected from your file and folder layout\r\n- 🔄 **Incremental by default** — `--update` translates only new and changed strings and leaves the rest untouched\r\n\r\n**Quality you can ship**\r\n\r\n- 🛠️ **Nothing breaks** — placeholders, HTML tags, and formatting are preserved; dates and numbers are localized; proper names, URLs, and technical terms are left alone ([how it works](https://l10n.dev/help/i18n-translation-using-ai))\r\n- 🌐 **Correct plural forms** — every i18next suffix is generated, including complex rules in Russian, Arabic, and Polish\r\n- 🔒 **Type-safe JSON** — numbers stay numbers, booleans stay booleans, null stays null\r\n- 📚 **Glossary & terminology** — lock brand, legal, and product terms so the AI can't pick a synonym\r\n- ✍️ **Linguistic instructions** — set tone and style once, e.g. `--instruction \"Use formal tone\"`\r\n\r\n**Built for automation**\r\n\r\n- ⚙️ **Runs anywhere** — CLI, SDK, npm scripts, GitHub Action, GitLab CI, Jenkins, and MCP for AI agents\r\n- 🕵️ **Self-checking** — detects lost placeholders and retries; splits large files into chunks while keeping context, avoiding the silent content loss you get pasting strings into Claude or GPT\r\n- 🔍 **Content filtering** — filtered strings are saved to a separate file for review instead of failing the run\r\n- 📊 **Usage tracking** — monitor character usage and balance; 10,000 characters free every month, pay-as-you-go after that\r\n\r\n## Installation\r\n\r\n### For CLI + Programmatic (SDK)\r\n```bash\r\nnpm install ai-l10n\r\n```\r\n\r\n### For AI Agents (MCP Server)\r\n\r\nUse the [ai-l10n-mcp](https://www.npmjs.com/package/ai-l10n-mcp) package to connect AI agents (Claude Desktop, Cursor, Windsurf, GitHub Copilot, OpenAI Codex) directly to l10n.dev. See the [MCP server README](./ai-l10n-mcp/README.md) for configuration instructions.\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"l10n\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"ai-l10n-mcp\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### For SDK Only\r\n\r\n```bash\r\nnpm install ai-l10n-sdk\r\n```\r\n\r\n## Getting Started\r\n\r\n### 1. Get Your API Key\r\n\r\nGet your free API key from [l10n.dev/ws/keys](https://l10n.dev/ws/keys)\r\n\r\n### 2. Configure API Key\r\n\r\nYou can provide your API key in three ways:\r\n\r\n**Option A: Save it globally**\r\n```bash\r\nnpx ai-l10n config --api-key YOUR_API_KEY\r\n```\r\n\r\n**Option B: Use environment variable**\r\n```bash\r\nexport L10N_API_KEY=your_api_key_here\r\n```\r\n\r\n**Option C: Pass it directly in code or CLI**\r\n```bash\r\nnpx ai-l10n translate path/to/file.json --api-key YOUR_API_KEY\r\n```\r\n\r\n### 3. Translate Your Files\r\n\r\n#### Basic Translation\r\n\r\n```bash\r\n# Auto-detect target languages from project structure\r\nnpx ai-l10n translate path/to/en.json\r\n\r\n# Specify target languages\r\nnpx ai-l10n translate path/to/en.json --languages es,fr,de\r\n\r\n# Update existing files with only new translations\r\nnpx ai-l10n translate path/to/en.json --update\r\n```\r\n\r\n#### Advanced Options\r\n\r\n```bash\r\nnpx ai-l10n translate ./locales/en.json \\\r\n  --languages es,fr,de \\\r\n  --plural \\                    # Generate plural forms (adds suffixes, e.g., for i18next)\r\n  --shorten \\                   # Use shortening\r\n  --no-contractions \\           # Don't use contractions (e.g., \"don't\" vs \"do not\")\r\n  --update \\                    # Update existing files (translates only new and changed strings)\r\n  --replace \\                   # Replace existing files (rewrites file with new translations, overwise it adds a copy number e.g., `es (1).json`)\r\n  --glossary \\                  # Generate and save glossary for future translations\r\n  --instruction \"Be formal\" \\   # Control the overall style, tone, and translation behavior\r\n  --language-regex \"^emails\\.(?<language>[\\w-]+)\\.json$\" \\  # Locate the language code in file names\r\n  --verbose                     # Detailed logging\r\n```\r\n\r\n#### Batch Translation\r\n\r\nCreate a config file `translate-config.json`:\r\n\r\n```json\r\n[\r\n  {\r\n    \"sourceFile\": \"./locales/en/common.json\",\r\n    \"targetLanguages\": [\"pl\", \"ru\", \"ar\"],\r\n    \"generatePluralForms\": true,\r\n    \"translateOnlyNewStrings\": true\r\n  },\r\n  {\r\n    \"sourceFile\": \"./locales/en/admin.json\",\r\n    \"targetLanguages\": [\"pl\", \"ru\", \"ar\", \"de\"],\r\n    \"replace\": true\r\n  }\r\n]\r\n```\r\n\r\nRun batch translation:\r\n\r\n```bash\r\nnpx ai-l10n batch translate-config.json\r\n```\r\n\r\n#### Configuration Management\r\n\r\n```bash\r\n# View current API key status\r\nnpx ai-l10n config\r\n\r\n# Set API key\r\nnpx ai-l10n config --api-key YOUR_API_KEY\r\n\r\n# Clear API key\r\nnpx ai-l10n config --clear\r\n```\r\n\r\n### Programmatic Usage\r\n\r\n```typescript\r\nimport { AiTranslator } from 'ai-l10n';\r\n\r\nconst translator = new AiTranslator();\r\n\r\nconst result = await translator.translate({\r\n  sourceFile: './locales/en.json',\r\n  targetLanguages: ['es', 'fr', 'de'],\r\n});\r\n```\r\n\r\n**📚 See the [ai-l10n-sdk README](https://github.com/AntonovAnton/ai-l10n/tree/main/sdk#readme) for:**\r\n- Complete API documentation and TypeScript interfaces\r\n- Advanced usage examples\r\n- Custom logger integration\r\n- Error handling and type definitions\r\n\r\n### NPM Scripts Integration\r\n\r\nAdd scripts to your `package.json`:\r\n\r\n```json\r\n{\r\n  \"scripts\": {\r\n    \"translate\": \"ai-l10n translate ./locales/en.json\",\r\n    \"translate:update\": \"ai-l10n translate ./locales/en.json --update\",\r\n    \"translate:replace\": \"ai-l10n translate ./locales/en.json --replace\",\r\n    \"translate:all\": \"ai-l10n batch translate-config.json\"\r\n  }\r\n}\r\n```\r\n\r\nThen run:\r\n\r\n```bash\r\nnpm run translate\r\nnpm run translate:update\r\nnpm run translate:replace\r\nnpm run translate:all\r\n```\r\n\r\n### CI/CD Integration\r\n\r\n#### GitHub Actions\r\n\r\nai-l10n provides a ready-to-use GitHub Action for automated translations. The action uses the batch command with a config file for flexible, multi-file translation workflows.\r\n\r\n**Quick Setup:**\r\n\r\n1. Create a translation config file `ai-l10n.config.json` in your repository root:\r\n\r\n```json\r\n[\r\n  {\r\n    \"sourceFile\": \"./locales/en/common.json\",\r\n    \"targetLanguages\": [\"es\", \"fr\", \"de\"],\r\n    \"translateOnlyNewStrings\": true\r\n  }\r\n]\r\n```\r\n\r\n2. Add the workflow file:\r\n\r\n```yaml\r\nname: Auto-translate i18n files\r\n\r\non:\r\n  push:\r\n    branches:\r\n      - main\r\n    paths:\r\n      - 'locales/en.json'\r\n      - 'locales/en/**'\r\n      - 'ai-l10n.config.json'\r\n\r\npermissions:\r\n  contents: write\r\n\r\njobs:\r\n  translate:\r\n    runs-on: ubuntu-latest\r\n    steps:\r\n      - uses: actions/checkout@v4\r\n      \r\n      - uses: l10n-dev/ai-l10n@v1\r\n        with:\r\n          api-key: ${{ secrets.L10N_API_KEY }}\r\n          config-file: 'ai-l10n.config.json'\r\n          pull-request: false\r\n```\r\n\r\n**Action Inputs:**\r\n\r\n| Input | Description | Default | Required |\r\n|-------|-------------|---------|----------|\r\n| `version` | L10n.dev CLI version | `latest` | No |\r\n| `api-key` | L10n.dev Platform API Key | - | No (can use `L10N_API_KEY` env var) |\r\n| `github-token` | GitHub token for PR creation (optional if repo setting enabled) | `github.token` | No |\r\n| `config-file` | Path to translation config file | `ai-l10n.config.json` | No |\r\n| `pull-request` | Create PR instead of direct commit | `false` | No |\r\n| `commit-message` | Commit message | `feat: update translations via L10n.dev` | No |\r\n| `pull-request-title` | Pull request title | `feat: update translations via L10n.dev` | No |\r\n| `commit-author-name` | Git commit author name | `L10n.dev` | No |\r\n| `commit-author-email` | Git commit author email | `support@l10n.dev` | No |\r\n| `process-own-commits` | Process commits made by this action | `false` | No |\r\n| `working-directory` | Working directory (for monorepos) | `.` | No |\r\n| `skip-setup-node` | Skip Node.js setup if already installed | `false` | No |\r\n\r\n> **ℹ️ Note on Pull Requests:** To use `pull-request: true`, you have two options:\r\n> 1. **Enable repository setting** (recommended): Go to **Settings > Actions > General** and enable **\"Allow GitHub Actions to create and approve pull requests\"**\r\n> 2. **Use Personal Access Token**: Provide a [PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo` scope via `github-token` input\r\n\r\n**📚 More Examples:**\r\n- [Pull Request workflow](examples/github-action/translate-pr.yml) - Creates PR for review (recommended for main/master)\r\n- [Direct Commit workflow](examples/github-action/translate-commit.yml) - Commits directly (for feature branches)\r\n- [Manual Trigger workflow](examples/github-action/translate-manual.yml) - Run manually with custom inputs\r\n\r\n#### GitLab CI\r\n\r\n```yaml\r\ntranslate:\r\n  stage: build\r\n  script:\r\n    - npm install\r\n    - npx ai-l10n translate ./locales/en.json --update\r\n  only:\r\n    changes:\r\n      - locales/en.json\r\n  variables:\r\n    L10N_API_KEY: $L10N_API_KEY\r\n```\r\n\r\n#### Jenkins\r\n\r\n```groovy\r\npipeline {\r\n  agent any\r\n  \r\n  environment {\r\n    L10N_API_KEY = credentials('l10n-api-key')\r\n  }\r\n  \r\n  stages {\r\n    stage('Translate') {\r\n      steps {\r\n        sh 'npm install'\r\n        sh 'npx ai-l10n translate ./locales/en.json --update'\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Project Structure\r\n\r\nai-l10n automatically detects your project structure and generates translations accordingly.\r\n\r\n### Folder-Based Structure\r\n\r\n```\r\nlocales/\r\n  en/\r\n    common.json\r\n    errors.json\r\n  es/                  # Auto-detected\r\n    common.json\r\n    errors.json\r\n  zh-Hans-CN/          # Auto-detected\r\n    common.json\r\n```\r\n\r\n### File-Based Structure (JSON)\r\n\r\n```\r\nlocales/\r\n  en.json              # Source\r\n  es.json              # Auto-detected\r\n  fr-FR.json           # Auto-detected\r\n  zh-Hans-CN.json      # Auto-detected\r\n```\r\n\r\n### File-Based Structure (Flutter ARB)\r\n\r\n```\r\nlib/l10n/\r\n  app_en.arb           # Source\r\n  app_es.arb           # Auto-detected\r\n  app_fr_FR.arb        # Auto-detected\r\n  app_zh_Hans_CN.arb   # Auto-detected\r\n```\r\n\r\n### Language Code Inside the File Name\r\n\r\nThe language code may also sit next to other parts of the file name. Files following the\r\nsame naming pattern are detected, and target files keep that pattern:\r\n\r\n```\r\nlocales/\r\n  emails.en.json       # Source                -> emails.ru-RU.json\r\n  emails.es.json       # Auto-detected\r\n  en-US.common.json    # Source                -> ja.common.json\r\n  emails-en.json       # Source                -> emails-fr.json\r\n  common.en-Latn-US.yml\r\n  messages_en_US.properties  # Source          -> messages_ru_RU.properties\r\n```\r\n\r\nEvery part of the code is validated against the known ISO language, script and region\r\ncodes, so ordinary file names such as `strings.min.json` or `config.dev.json` are not\r\nmistaken for localization files. For naming conventions that are not recognized, describe\r\nthem with `languageCodeRegex` (`--language-regex` on the CLI):\r\n\r\n```bash\r\nai-l10n translate locales/emails.en.json -l ru-RU \\\r\n  --language-regex \"^emails\\.(?<language>[\\w-]+)\\.json$\"\r\n```\r\n\r\nThe pattern must contain a `(?<language>...)` group; the text before and after it is reused\r\nto find files of other languages and to build target file names.\r\n\r\n## Configuration Options\r\n\r\n| Option | Type | Default | Description |\r\n|--------|------|---------|-------------|\r\n| `sourceFile` | `string` | **required** | Path to source file. Supports JSON, JSONC, ARB, YAML, PO, XLIFF, and all other text-based formats. See the [full supported formats list](https://l10n.dev/ws/translate-i18n-files#supported-formats) |\r\n| `targetLanguages` | `string[]` | auto-detect | Target language codes (e.g., `[\"es\", \"fr\", \"de\"]`) |\r\n| `apiKey` | `string` | env/stored | API key for l10n.dev |\r\n| `generatePluralForms` | `boolean` | `false` | Generate plural forms with suffixes (e.g., for i18next). Don't use for strict source-to-target mapping |\r\n| `useShortening` | `boolean` | `false` | Use shortening in translations |\r\n| `useContractions` | `boolean` | `true` | Use contractions in translations (using contractions makes the translation less formal) |\r\n| `translateMetadata` | `boolean` | `false` | Translate metadata along with UI strings. For example, in Flutter ARB files, metadata entries like @key contain descriptions that can also be translated. Disabling this option ensures that metadata remains unchanged in the target files |\r\n| `saveFilteredStrings` | `boolean` | `true` | Save filtered strings (i18n JSON format with source strings excluded due to content policy violations) to a separate `.filtered` file |\r\n| `translateOnlyNewStrings` | `boolean` | `false` | Update existing files with only new/changed translations. When `true`, we store hashes of source strings (without text itself), so the system can detect which strings are new vs. old based on the presence of their hashes. |\r\n| `replace` | `boolean` | `false` | Replace existing files with new translations, overwise if the target file already exists it adds a copy number (e.g., `es (1).json`) |\r\n| `verbose` | `boolean` | `false` | Enable detailed logging |\r\n| `sourceLanguageCode` | `string \\| null` | auto-detect | BCP-47 source language code (e.g., `\"en\"`, `\"en-US\"`). Auto-detected from the file path when not set |\r\n| `languageCodeRegex` | `string` | auto-detect | Regex locating the language code in file names, e.g. `\"^emails\\\\.(?<language>[\\\\w-]+)\\\\.json$\"`. Must contain a `(?<language>...)` group; the text around it is reused for target file names. Only needed when the naming convention is not detected automatically. CLI: `--language-regex` |\r\n| `generateGlossary` | `boolean` | `false` | Generate and save a glossary from source and translated content for this language pair. Balance debited upfront for full source content. See [Translation Glossary](#translation-glossary) |\r\n| `glossary` | `GlossaryEntry[] \\| null` | use active | Override the active glossary: `null`/omit = use active, `[]` = disable, entries = replace for this request |\r\n| `instruction` | `string \\| null` | use active | Override the active linquistic instruction: `null`/omit = use active, ` ` = disable, `string` = replace for this request |\r\n| `terminology` | `TerminologyEntry[]` | none | Terms for consistent translation — synonyms are replaced with the preferred term |\r\n\r\n## Content Filtering\r\n\r\nThe service uses automated content filtering systems configured at moderate sensitivity levels to balance safety with service availability. When content is filtered:\r\n\r\n- **Filtered strings are saved** in i18n JSON format to a `.filtered` file (if `saveFilteredStrings` is enabled)\r\n- **Content filtering operates automatically** and does not constitute editorial control over your content\r\n\r\nIf strings are filtered, you'll see:\r\n```\r\n⚠️ Some strings were excluded due to content policy violations\r\nℹ️ View content policy at: https://l10n.dev/terms-of-service#content-policy\r\n📝 Filtered strings saved to: path/to/file.filtered.json\r\n```\r\n\r\n## Translation Glossary\r\n\r\nA translation glossary maps specific source-language terms to approved target-language equivalents, ensuring the AI uses your exact terminology instead of valid-but-unintended synonyms. Glossaries are especially valuable for brand names, legal terms, clinical vocabulary, and product-specific concepts.\r\n\r\n### AI Glossary Generation (`--glossary` / `generateGlossary`)\r\n\r\nUse `--glossary` (CLI) or `generateGlossary: true` (config) to automatically build a glossary from the source and translated target content, then save it as the active glossary for this source/target language pair:\r\n\r\n```bash\r\nnpx ai-l10n translate ./locales/en.json --languages de,fr --glossary\r\n```\r\n\r\nOnce saved, the glossary is applied automatically on all future translations for the same language pair. \r\nManage your saved glossaries at [l10n.dev/ws/translation-glossary](https://l10n.dev/ws/translation-glossary).\r\n\r\n> **Balance note:** When `--glossary` is enabled, your balance is debited for the full source content upfront — even when `--update` is on. When disabled (default), a temporary internal glossary is generated automatically at no extra cost only for large files that exceed the AI chunk size.\r\n\r\n### Manual Glossary Override (`glossary`)\r\n\r\nSupply your own term mappings via `glossary` in `TranslationConfig` (programmatic / batch config):\r\n\r\n```json\r\n{\r\n  \"sourceFile\": \"./locales/en.json\",\r\n  \"targetLanguages\": [\"de\"],\r\n  \"glossary\": [\r\n    { \"sourceTerm\": \"Settings\", \"targetTerm\": \"Einstellungen\" },\r\n    { \"sourceTerm\": \"bank\", \"targetTerm\": \"Bank\", \"context\": \"financial institution\" }\r\n  ]\r\n}\r\n```\r\n\r\n- **Omit or `null`**: use the active saved glossary for this language pair\r\n- **Empty array `[]`**: disable glossary entirely for this request\r\n- **One or more entries**: replace the active glossary for this request only\r\n\r\n### Terminology\r\n\r\nUse `terminology` to enforce consistent terms across translations. List synonyms that should be replaced by the preferred term:\r\n\r\n```json\r\n{\r\n  \"sourceFile\": \"./locales/en.json\",\r\n  \"targetLanguages\": [\"de\", \"fr\"],\r\n  \"terminology\": [\r\n    { \"term\": \"Settings\", \"synonyms\": [\"Preferences\", \"Options\"] },\r\n    { \"term\": \"Dashboard\" }\r\n  ]\r\n}\r\n```\r\n\r\n## Linguistic Instructions\r\n\r\nUse `instruction` to set a Linguistic Instruction, it let you guide AI, for example:\r\n- 📝 \"Use formal tone\"\r\n- 📝 \"Do not translate product names\"\r\n- 📝 \"Use active voice\"\r\n\r\nUnlike glossaries that control specific terms, Linguistic Instructions control the overall style, tone, and translation behavior.\r\nCombined with AI Glossaries, they give much more control over localization quality and brand consistency. \r\n\r\n```bash\r\nnpx ai-l10n translate ./locales/en.json --languages de,fr --instruction \"Use formal tone\"\r\n```\r\n\r\nIf not set it applies saved active linguistic Instruction.  \r\nManage your saved linguistic Instructions at [l10n.dev/ws/linguistic-instructions](https://l10n.dev/ws/linguistic-instructions).\r\n\r\n## Managing Glossaries via CLI\r\n\r\nUse the `glossary` command group to manage your translation glossaries directly from the terminal.\r\n\r\n### Glossary commands\r\n\r\n```bash\r\n# List all glossaries\r\nnpx ai-l10n glossary list\r\n\r\n# Create a glossary (active by default)\r\nnpx ai-l10n glossary create --source en --target de --name \"My German Glossary\"\r\n\r\n# Show glossary details\r\nnpx ai-l10n glossary get 1\r\n\r\n# Activate or rename a glossary\r\nnpx ai-l10n glossary update 1 --activate\r\nnpx ai-l10n glossary update 1 --name \"Updated Name\" --deactivate\r\n\r\n# Delete a glossary (and all its entries)\r\nnpx ai-l10n glossary delete 1\r\n```\r\n\r\n### Glossary entry commands\r\n\r\n```bash\r\n# List all term mappings in a glossary\r\nnpx ai-l10n glossary entries 1\r\n\r\n# Add a term mapping\r\nnpx ai-l10n glossary add-entry 1 --source \"settings\" --target \"Einstellungen\"\r\nnpx ai-l10n glossary add-entry 1 --source \"bank\" --target \"Bank\" --context \"financial institution\"\r\n\r\n# Update a term mapping\r\nnpx ai-l10n glossary update-entry 1 42 --source \"settings\" --target \"Einstellungen\"\r\n\r\n# Remove a term mapping\r\nnpx ai-l10n glossary delete-entry 1 42\r\n```\r\n\r\n## Managing Linguistic Instructions via CLI\r\n\r\nUse the `instruction` command group to manage linguistic instructions.\r\n\r\n```bash\r\n# List all instructions\r\nnpx ai-l10n instruction list\r\n\r\n# Create an instruction (active by default)\r\nnpx ai-l10n instruction create --source en --target de --text \"Use formal tone (Sie, not du)\"\r\n\r\n# Show instruction details\r\nnpx ai-l10n instruction get 1\r\n\r\n# Update an instruction\r\nnpx ai-l10n instruction update 1 --text \"Use formal tone\" --activate\r\n\r\n# Delete an instruction\r\nnpx ai-l10n instruction delete 1\r\n```\r\n\r\n## Language Support\r\n\r\nl10n.dev supports 165 languages with varying proficiency levels:\r\n\r\n- **Strong (12 languages)**: English, Spanish, French, German, Chinese, Russian, Portuguese, Italian, Japanese, Korean, Arabic, Hindi\r\n- **High (53 languages)**: Most European and Asian languages including Dutch, Swedish, Polish, Turkish, Vietnamese, Thai, and more\r\n- **Moderate (100 languages)**: Wide range of world languages\r\n\r\n## Language Codes\r\n\r\nUse standard language codes (BCP-47 with optional script and region):\r\n\r\n- Simple: `es`, `fr`, `de`, `ja`, `zh`\r\n- With region: `en-US`, `en-GB`, `pt-BR`, `zh-CN`\r\n- With script: `zh-Hans`, `zh-Hant`\r\n- Full format: `zh-Hans-CN`\r\n\r\nFor ARB files, use underscores: `en_US`, `zh_Hans_CN`\r\n\r\n## Troubleshooting\r\n\r\n### API Key Issues\r\n\r\n```bash\r\n# Check if API key is configured\r\nnpx ai-l10n config\r\n\r\n# Set new API key\r\nnpx ai-l10n config --api-key YOUR_API_KEY\r\n\r\n# Or use environment variable\r\nexport L10N_API_KEY=your_api_key_here\r\n```\r\n\r\n### No Languages Detected\r\n\r\nAuto-detection covers language-code folders (`locales/en/common.json`), language-code file\r\nnames (`locales/en.json`, `app_en.arb`) and language codes inside file names\r\n(`locales/emails.en.json`). If your file names embed the code differently, describe the\r\npattern:\r\n\r\n```bash\r\nnpx ai-l10n translate ./locales/emails.en.json \\\r\n  --language-regex \"^emails\\.(?<language>[\\w-]+)\\.json$\"\r\n```\r\n\r\nOtherwise, specify languages explicitly:\r\n\r\n```bash\r\nnpx ai-l10n translate ./locales/en.json --languages es,fr,de\r\n```\r\n\r\n### Insufficient Balance\r\n\r\nPurchase more characters at [l10n.dev/#pricing](https://l10n.dev/#pricing)\r\n\r\n## Related Projects\r\n\r\n- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=l10n-dev.translate-i18n-json) - Translate directly in VS Code\r\n\r\n## Support\r\n\r\n- 📧 Email: support@l10n.dev\r\n- 🐛 Issues: [GitHub Issues](https://github.com/l10n-dev/ai-l10n/issues)\r\n- 📚 API Documentation: [api.l10n.dev/doc](https://api.l10n.dev/doc)\r\n- 🌐 Website: [l10n](https://l10n.dev).dev\r\n\r\n## Pricing\r\n\r\n- **Free Characters**: 10,000 characters free every month\r\n- **Pay-as-you-go**: Affordable character-based pricing with no subscription required\r\n- **Current Pricing**: Visit [l10n.dev/#pricing](https://l10n.dev/#pricing) for up-to-date rates\r\n\r\n## Privacy & Security\r\n\r\n- **Secure API Keys**: Stored securely in your home directory (~/.ai-l10n/config.json) or via environment variables\r\n- **No Data Storage**: Source code and translations are not stored on our servers beyond processing time\r\n- **Encrypted Communication**: All communication with l10n.dev API uses HTTPS encryption\r\n- **Privacy First**: Built by developers for developers with privacy, reliability, and quality as top priorities\r\n\r\n> **💡 Tip for Large-Files Translation:**\r\n>\r\n> This npm package translates files in real-time via the [Translate API](https://api.l10n.dev/doc/#tag/ai-translation) and does not store your translations on our servers. For very large files, translation may take several minutes.\r\n>\r\n> On the [I18N File Translation](https://l10n.dev/ws/translate-i18n-files) page, you can:\r\n> - Securely create translation jobs for batch processing\r\n> - Set custom terminology for consistent translations\r\n> - Monitor progress in real-time\r\n> - Download files when complete with full control (delete anytime)\r\n\r\n## Important: Working with Arrays in JSON\r\n\r\n⚠️ **When using \"Translate Only New Strings\"**: If your JSON contains arrays (not just objects), ensure array indexes in your target file match those in the source file. When adding new strings, always append them to the end of the array.\r\n\r\n**Example:**\r\n\r\n```json\r\n// ✅ CORRECT: New items added at the end\r\n// source.json\r\n[\"Apple\", \"Banana\", \"Orange\"]\r\n\r\n// target.json (existing)\r\n[\"Manzana\", \"Plátano\"]\r\n\r\n// After translation (new item appended)\r\n[\"Manzana\", \"Plátano\", \"Naranja\"]\r\n\r\n// ❌ INCORRECT: Items inserted in the middle\r\n// This will cause misalignment!\r\n[\"Apple\", \"Cherry\", \"Banana\", \"Orange\"]\r\n```\r\n\r\nFor object-based JSON structures (recommended for i18n), this is not a concern as translations are matched by key names.\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## Credits\r\n\r\nPowered by [l10n.dev](https://l10n.dev) - AI-powered localization service\r\n\r\n",
  "bytes": 24863,
  "sha": "fbdd807383f841d83ac911ef84f8ce838119fedbaa1631fbef59a8119660af5d",
  "repo_slug": "l10n-dev/ai-l10n",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_l10n_dev_ai_l10n_mcp_d0ad40e3/readme"
}