ai-l10n

AI-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.

Powered by l10n.dev

Features

One 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.

npx ai-l10n translate ./locales/en.json --update

Translate

• 🤖 165 languages — context-aware AI translation, not word-by-word machine output
• 🎯 Any text-based format — JSON, JSONC, Flutter ARB, Shopify themes, YAML, PO (gettext), XLIFF, and more (full list)
• 📁 Zero setup — target languages are auto-detected from your file and folder layout
• 🔄 Incremental by default — --update translates only new and changed strings and leaves the rest untouched

Quality you can ship

• 🛠️ 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)
• 🌐 Correct plural forms — every i18next suffix is generated, including complex rules in Russian, Arabic, and Polish
• 🔒 Type-safe JSON — numbers stay numbers, booleans stay booleans, null stays null
• 📚 Glossary & terminology — lock brand, legal, and product terms so the AI can't pick a synonym
• ✍️ Linguistic instructions — set tone and style once, e.g. --instruction "Use formal tone"

Built for automation

• ⚙️ Runs anywhere — CLI, SDK, npm scripts, GitHub Action, GitLab CI, Jenkins, and MCP for AI agents
• 🕵️ 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
• 🔍 Content filtering — filtered strings are saved to a separate file for review instead of failing the run
• 📊 Usage tracking — monitor character usage and balance; 10,000 characters free every month, pay-as-you-go after that

Installation

For CLI + Programmatic (SDK)

npm install ai-l10n

For AI Agents (MCP Server)

Use the 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 for configuration instructions.

{

  "mcpServers": {

    "l10n": {

      "command": "npx",

      "args": ["-y", "ai-l10n-mcp"]

    }

  }

}

For SDK Only

npm install ai-l10n-sdk

Getting Started

1. Get Your API Key

Get your free API key from l10n.dev/ws/keys

2. Configure API Key

You can provide your API key in three ways:

Option A: Save it globally

npx ai-l10n config --api-key YOUR_API_KEY

Option B: Use environment variable

export L10N_API_KEY=your_api_key_here

Option C: Pass it directly in code or CLI

npx ai-l10n translate path/to/file.json --api-key YOUR_API_KEY

3. Translate Your Files

Basic Translation

# Auto-detect target languages from project structure

npx ai-l10n translate path/to/en.json



# Specify target languages

npx ai-l10n translate path/to/en.json --languages es,fr,de



# Update existing files with only new translations

npx ai-l10n translate path/to/en.json --update

Advanced Options

npx ai-l10n translate ./locales/en.json \

  --languages es,fr,de \

  --plural \                    # Generate plural forms (adds suffixes, e.g., for i18next)

  --shorten \                   # Use shortening

  --no-contractions \           # Don't use contractions (e.g., "don't" vs "do not")

  --update \                    # Update existing files (translates only new and changed strings)

  --replace \                   # Replace existing files (rewrites file with new translations, overwise it adds a copy number e.g., `es (1).json`)

  --glossary \                  # Generate and save glossary for future translations

  --instruction "Be formal" \   # Control the overall style, tone, and translation behavior

  --language-regex "^emails\.(?<language>[\w-]+)\.json$" \  # Locate the language code in file names

  --verbose                     # Detailed logging

Batch Translation

Create a config file translate-config.json:

[

  {

    "sourceFile": "./locales/en/common.json",

    "targetLanguages": ["pl", "ru", "ar"],

    "generatePluralForms": true,

    "translateOnlyNewStrings": true

  },

  {

    "sourceFile": "./locales/en/admin.json",

    "targetLanguages": ["pl", "ru", "ar", "de"],

    "replace": true

  }

]

Run batch translation:

npx ai-l10n batch translate-config.json

Configuration Management

# View current API key status

npx ai-l10n config



# Set API key

npx ai-l10n config --api-key YOUR_API_KEY



# Clear API key

npx ai-l10n config --clear

Programmatic Usage

import { AiTranslator } from 'ai-l10n';



const translator = new AiTranslator();



const result = await translator.translate({

  sourceFile: './locales/en.json',

  targetLanguages: ['es', 'fr', 'de'],

});

📚 See the ai-l10n-sdk README for:

• Complete API documentation and TypeScript interfaces
• Advanced usage examples
• Custom logger integration
• Error handling and type definitions

NPM Scripts Integration

Add scripts to your package.json:

{

  "scripts": {

    "translate": "ai-l10n translate ./locales/en.json",

    "translate:update": "ai-l10n translate ./locales/en.json --update",

    "translate:replace": "ai-l10n translate ./locales/en.json --replace",

    "translate:all": "ai-l10n batch translate-config.json"

  }

}

Then run:

npm run translate

npm run translate:update

npm run translate:replace

npm run translate:all

CI/CD Integration

GitHub Actions

ai-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.

Quick Setup:

1. Create a translation config file ai-l10n.config.json in your repository root:

[

  {

    "sourceFile": "./locales/en/common.json",

    "targetLanguages": ["es", "fr", "de"],

    "translateOnlyNewStrings": true

  }

]

2. Add the workflow file:

name: Auto-translate i18n files



on:

  push:

    branches:

      - main

    paths:

      - 'locales/en.json'

      - 'locales/en/**'

      - 'ai-l10n.config.json'



permissions:

  contents: write



jobs:

  translate:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      

      - uses: l10n-dev/ai-l10n@v1

        with:

          api-key: ${{ secrets.L10N_API_KEY }}

          config-file: 'ai-l10n.config.json'

          pull-request: false

Action Inputs:

ℹ️ Note on Pull Requests: To use pull-request: true, you have two options:

1. Enable repository setting (recommended): Go to Settings > Actions > General and enable "Allow GitHub Actions to create and approve pull requests"
2. Use Personal Access Token: Provide a PAT with repo scope via github-token input

📚 More Examples:

• Pull Request workflow - Creates PR for review (recommended for main/master)
• Direct Commit workflow - Commits directly (for feature branches)
• Manual Trigger workflow - Run manually with custom inputs

GitLab CI

translate:

  stage: build

  script:

    - npm install

    - npx ai-l10n translate ./locales/en.json --update

  only:

    changes:

      - locales/en.json

  variables:

    L10N_API_KEY: $L10N_API_KEY

Jenkins