Localingos CLI

AI-powered translation for developers. Localize your app into 56 languages with one command.

npm install -g localingos
localingos init
localingos sync

Setup

1. Create an API Key

Go to localingos.com → Developer Tools → API Keys → Create API Key.

2. Initialize your project

localingos init

This creates two config files:

• localingos.config.json — commit this. Contains project settings (no secrets).
• .localingos.json — gitignored. Contains your API key for local development.

// localingos.config.json
{
  "projectId": "your-project-id",
  "sourceLocale": "en-US",
  "format": "json-nested",
  "sourceFile": "./src/i18n/en-US.json",
  "outputDir": "./src/i18n",
  "outputPattern": "{locale}.json"
}

If the source file doesn't exist yet, init will offer you three options:

• 🤖 Generate an AI prompt to extract all strings from your codebase
• 📝 Create a sample file with hello-world entries
• ⏭️ Skip and create it yourself

3. Extract translatable strings (new projects)

localingos extract

Detects your project type (React, Next.js, Vue, Angular, etc.) and generates a tailored AI prompt. Paste it into your AI assistant (Cursor, Copilot, Claude, ChatGPT) and it will:

1. Scan your codebase for all user-facing strings
2. Create the source locale file (e.g., en-US.json)
3. Replace hardcoded strings with t('key') calls
4. Set up an i18n library if needed

4. Sync translations

localingos sync

One command to:

1. Push source strings to Localingos
2. Pull all available translations
3. Write locale files (e.g., es-ES.json, fr-FR.json, zh-CN.json)

Commands

| Command | Description | |---------|-------------| | localingos init | Interactive setup wizard | | localingos extract | Generate AI prompt to extract translatable strings | | localingos sync | Push source strings and pull translations | | localingos push | Push source strings only | | localingos pull | Pull translations and write locale files | | localingos mcp-serve | Start MCP server for AI coding agents |

Options

| Option | Description | |--------|-------------| | --dry-run | Preview without making API calls (sync/push) | | --prune | Remove stale keys from locale files (sync) | | -c, --config <path> | Path to config file | | -V, --version | Show version | | -h, --help | Show help |

MCP Server

The CLI includes a built-in Model Context Protocol server. Give your AI coding agent direct access to your translation workflow.

localingos mcp-serve

Configure your AI agent:

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "localingos": { "command": "localingos", "args": ["mcp-serve"] }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "localingos": { "command": "localingos", "args": ["mcp-serve"], "cwd": "/path/to/your/project" }
  }
}

Remote (no install needed):

{
  "mcpServers": {
    "localingos": {
      "type": "streamable-http",
      "url": "https://mcp.localingos.com?apiKey=YOUR_KEY&projectId=YOUR_PROJECT_ID"
    }
  }
}

Available Tools (20)

| Tool | Description | |---|---| | localingos_sync | Push source strings & pull translations | | localingos_push | Push source strings only | | localingos_pull | Pull translations and write locale files | | localingos_status | Show project, locales, key counts | | localingos_search | Search keys/text across source strings | | localingos_extract | Run i18n extraction script | | localingos_list_projects | List all projects you have access to | | localingos_get_translatables | Get all source strings for a project | | localingos_get_translations | Get all translations for a project | | localingos_get_translation | Get translations for a single key | | localingos_get_translations_batch | Get translations for multiple keys | | localingos_update_translations | Create or update translations manually | | localingos_delete_translatables | Delete source strings (prune stale keys) | | localingos_translation_jobs | List translation jobs, filter by state | | localingos_retry_job | Retry a single failed translation job | | localingos_retry_all_jobs | Retry all failed/blocked jobs | | localingos_project_members | List members of a project | | localingos_add_member | Add a member to a project | | localingos_remove_member | Remove a member | | localingos_billing_status | Show billing status, plan, and usage |

Supported Formats

Set format to whichever your framework already uses. Each of these is read and written natively, so there is no conversion step in your build.

| Format | Files | Description | |--------|-------|-------------| | json-nested | .json | Nested JSON objects — { "welcome": { "title": "Hello" } }. The default; what react-i18next, vue-i18n, svelte-i18n and next-intl expect. | | json-flat | .json | Flat key-value JSON — { "welcome.title": "Hello" }. | | yaml | .yml, .yaml | Nested YAML with no locale root key. | | yaml-rails | .yml | Rails-style YAML rooted at the locale (en:). The root is stripped on read, so ids stay locale-free, and restored with the target locale on write. | | properties | .properties | Java / Spring resource bundles. Flat keys, UTF-8, handling \n, \uXXXX and line continuations. | | csv | .csv | Needs a header row with key and text; an optional description column supplies translator context. | | po | .po | gettext (Django, Flask). Key is msgctxt when present, else msgid. #. comments round-trip as descriptions. msgid_plural entries are skipped and reported, never flattened. | | arb | .arb | Flutter Application Resource Bundles. @key.description supplies context, @@locale is written for you, and @key metadata such as placeholders is preserved so flutter gen-l10n keeps working. |

Aliases are accepted where unambiguous: json → json-nested, yml → yaml, rails → yaml-rails, gettext/pot → po, flutter → arb.

ICU MessageFormat is not a format setting. ICU syntax lives inside your strings and is preserved whichever catalogue format you choose. Note that translation returns the same number of plural forms it was given — it does not expand a two-form source into a language's full CLDR category set, so author every form your target languages need.

CI/CD Integration

GitHub Actions — Auto-sync on push

Automatically sync translations when source files change on main:

1. Add your API key as a repository secret: LOCALINGOS_API_KEY
2. Commit localingos.config.json (project config, no secrets)
3. Copy examples/github-actions-sync.yml to .github/workflows/localingos-sync.yml

# Minimal example
- name: Sync translations
  run: npx localingos sync
  env:
    LOCALINGOS_API_KEY: ${{ secrets.LOCALINGOS_API_KEY }}

GitHub Actions — PR check

Fail PRs if i18n source files are out of date:

Copy examples/github-actions-check.yml to .github/workflows/localingos-check.yml

Environment variable

The CLI resolves the API key in this order:

1. apiKeyEnv custom env var (if set in config)
2. LOCALINGOS_API_KEY env var
3. apiKey in .localingos.json

Monorepo support

Each project gets its own localingos.config.json with a different apiKeyEnv:

// apps/web/localingos.config.json
{ "apiKeyEnv": "LOCALINGOS_KEY_WEB", "projectId": "...", ... }

// apps/docs/localingos.config.json
{ "apiKeyEnv": "LOCALINGOS_KEY_DOCS", "projectId": "...", ... }

env:
  LOCALINGOS_KEY_WEB: ${{ secrets.LOCALINGOS_KEY_WEB }}
  LOCALINGOS_KEY_DOCS: ${{ secrets.LOCALINGOS_KEY_DOCS }}

How It Works

Your codebase                    Localingos
┌──────────────┐                ┌──────────────┐
│ en-US.json   │ ──── push ──→  │ Process &    │
│ (source)     │                │ Translate    │
│              │ ←── pull ────  │ (AI-powered) │
│ es-ES.json   │                │              │
│ fr-FR.json   │                │              │
│ zh-CN.json   │                │              │
└──────────────┘                └──────────────┘

Links

• Website
• Documentation
• MCP Server
• Pricing