langctl

langctl keeps the translation files in your repository in sync with Langctl: pull translations into JSON, Android, iOS or Flutter files, push new source strings, and check in CI that committed files are up to date.

$ langctl init          # once per repo: pick a project, format and path → langctl.json
$ langctl pull          # download translations
+ src/locales/en.json  created
+ src/locales/es.json  created  41/45 translated
$ langctl push          # upload new strings from your source-language file
en  src/locales/en.json  3 new, 0 updated, 42 unchanged

Install

npm install -g langctl        # Node.js 20 or newer
# or, without installing:
npx langctl --help

Quick start

1. Create an API key at app.langctl.com → API Keys (it is shown only once). Langctl API keys look like lc_ followed by 64 hexadecimal characters (lc_3f9a…, 67 characters in total).

2. In your repository:

   langctl init
   

   This asks for the key (input is hidden), lets you pick the project, file format and location, and writes a langctl.json you can commit. Then:

   langctl pull      # write translation files
   langctl push      # upload new keys from your source language file
   

Keys are only included in pull once they are published — drafts stay out of your app until someone reviews them (--include-drafts to override).

Use it in CI

No config file or login step is needed — set the key as a secret environment variable.

# .github/workflows/i18n.yml
name: translations
on: [pull_request]
jobs:
  i18n:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npx langctl@0 pull --check            # fail if committed files are out of date
        env:
          LANGCTL_API_KEY: ${{ secrets.LANGCTL_API_KEY }}

Other useful CI commands:

langctl push --dry-run --json          # preview what a push would change
langctl push --publish                 # upload and publish new source strings (e.g. on main)
langctl pull --require-complete        # fail if any language is missing translations
langctl whoami --json                  # verify the key, org and scopes

In CI langctl never prompts and never animates: spinners are off when CI is set or output isn't a terminal, destructive commands require --yes, and every failure has a distinct exit code. Use a key with only the scopes the job needs — translations:read is enough for pull.

langctl.json

{
  "project": "web-app",
  "format": "json",
  "output": "src/locales/{lang}.json"
}

Command-line flags override the file; langctl looks for langctl.json in the current directory and its parents.

Formats

Placeholders are stored as {{name}}. A placeholder used twice gets the same position on every platform, and literal % is escaped where needed. Output is sorted and has no timestamps, so a pull only changes files when translations change. If two keys map to the same Android/ARB name, the pull fails and names both keys instead of silently dropping one.

Review state: AI vs. human translations

Every translation is either reviewed (written or approved by a person) or an unreviewed AI draft:

An AI draft stops being a draft as soon as its text differs from what the AI produced, however it was changed. So translating with AI, fixing strings in your file, and running push -l hi --overwrite marks the corrected strings as reviewed. Strings you push back unchanged are skipped by the import and stay drafts — approve those with langctl review --approve. pull tells you how many drafts it held back (also with --json, on stderr); a language that comes back empty because everything is still a draft is shown as 0 strings: N awaiting review. Ship drafts anyway with --include-unreviewed.

AI translation (translate)

$ langctl translate -t hi -m mobile
Translating 312/889…
✖ Translated 880, copied 7 unchanged, failed 2 (hi; 2211/50000 AI translations used this month).
Needs a human translation:
  hi  mobile.onboarding.duration.hours  "{h}h"  (empty_result)

• Strings go up 100 per request, a few requests at a time. A progress counter is shown at a terminal; in CI and pipes a progress line is printed about every 10%.
• Strings with nothing to translate (98860 41022, + {name}) are copied unchanged.
• A string the provider can't translate never fails the rest: it is listed (with its source text) and the command exits 8. Add it by hand and re-run — only missing strings are translated.
• Per-key lines go to stdout; the summary and failures go to stderr, so they aren't lost when you redirect stdout. With --json the result has translated, failed (key, language, source text, reason) and counts.
• Key descriptions help reviewers; set them in bulk with push --descriptions (below).

Key prefixes (several apps in one project)

Keys are unique per project. When several apps share a project and need the same key name (common.save), store them with a prefix — dashboard.common.save, web.common.save — and let langctl add and strip it:

langctl pull --strip-prefix dashboard     # only dashboard.* keys, written as common.save, …
langctl push --prefix dashboard           # common.save is uploaded as dashboard.common.save

Or put "prefix": "dashboard." in that app's langctl.json and both directions use it. A prefix without a trailing separator (., _, -, :, /) gets a . appended. On pull, keys without the prefix are skipped and counted in a warning. translate --keys and review --keys accept key names with or without the configured prefix; keys get/update/delete/… take the full stored name.

Descriptions

Descriptions give translators (and reviewers) context. Set them in bulk when pushing:

langctl push --descriptions i18n/descriptions.json --overwrite

descriptions.json is flat: { "common.book": "Verb: book an appointment" }. Only keys present in both files get a description; unmatched entries are reported. New keys always get their description; for keys that already exist pass --overwrite (the server decides whether an existing description is replaced). A flat JSON input file may also carry descriptions inline: { "common.book": { "value": "Book", "description": "Verb" } } (push and import).

Profiles (several organizations)

langctl auth stores one key per profile. The default profile is ~/.langctl/config.json; named profiles live in ~/.langctl/profiles/<name>.json:

echo "$CLIENT_B_KEY" | langctl auth --profile client-b --stdin
langctl pull --profile client-b               # or: export LANGCTL_PROFILE=client-b
langctl whoami                                # shows the profile in use

Storing a key for a different organization in a profile that already has one asks for confirmation; non-interactively it refuses unless you pass --yes. LANGCTL_API_KEY / --api-key still take precedence over any profile.

Commands

Global flags (any position): --json · -q/--quiet · --verbose (log HTTP requests) · -y/--yes · --api-key · --api-url · --profile <name> · --timeout <seconds> · --no-color. Run langctl <command> --help for details.

Configuration & environment

Exit codes

Errors from the API or the AI provider are never reported as 2: they are 5 (network, timeout, 5xx) or 1. If the API no longer knows a path this CLI uses (404 route / 410 Gone), the error says to upgrade: npm i -g langctl@latest.

With --json, errors are also printed to stdout as {"error": {"message", "exitCode", "hint"}}.

Upgrading from 0.2

• Requires Node.js 20+ (0.2 already needed it in practice).
• pull/export default paths follow each platform's layout (locales/{lang}.json, res/values-xx/strings.xml, xx.lproj/…, app_xx.arb). Use -o or langctl.json to keep your old paths.
• Exporting several languages to one file is now an error instead of silently overwriting it.
• Android and ARB output now uses valid identifiers (home_title, homeTitle) and correct escaping.
• Destructive commands (projects delete, keys delete, removing languages, team remove) ask for confirmation, and require --yes when not run interactively.
• keys translate takes the text with -t/--text (-v is the version flag); keys create accepts --value LANG=TEXT for any language. The debug command was replaced by whoami.
• team commands need an API key with the org:admin scope.

See CHANGELOG.md for everything else.

Development

npm ci
npm test                 # unit tests
npm run build
LANGCTL_API_KEY=lc_… LANGCTL_E2E_PROJECT=<test-project> npm run test:e2e   # against a real API

License

MIT