@localizify/cli

Localization from your terminal

Push new keys, translate them with AI and pull finished files back into your repo. One config file, four commands, and it runs the same on your laptop and in CI.

$ npm i -D @localizify/cli

View on npm

$ npx @localizify/cli push
pushed src/locale/messages.xlf: 3 new keys, 148 processed
$ npx @localizify/cli translate --lang uk,de
uk: 3 terms translated
de: 3 terms translated
$ npx @localizify/cli pull
pulled uk -> src/locale/messages.uk.xlf (18342 bytes)
pulled de -> src/locale/messages.de.xlf (18911 bytes)
$

Install

The CLI needs Node.js 20 or newer. Add it as a dev dependency so everyone on the team runs the same version:

$ npm i -D @localizify/cli

Installed this way, the command is just localizify. You can also run it once without installing:

# Or run it without installing
$ npx @localizify/cli --help

Authenticate

Create an API token in Settings → API tokens and expose it as LOCALIZIFY_TOKEN. A token scoped to one project can only touch that project.

$ export LOCALIZIFY_TOKEN=loc_...
# Self-hosted or staging only:
$ export LOCALIZIFY_HOST=https://localizify.com

Keep the token in your shell or CI secrets. Never commit it or put it in the config file.

Configure

Add localizify.json to the root of your repo. Paths are relative to the config file.

{
  "projectId": 123,
  "source": { "provider": "Angular XLIFF", "path": "src/locale/messages.xlf", "lang": "en" },
  "files": [
    { "provider": "Angular XLIFF", "lang": "uk", "path": "src/locale/messages.uk.xlf" },
    { "provider": "Angular XLIFF", "lang": "de", "path": "src/locale/messages.de.xlf" }
  ]
}

projectId · the project id from the project URL
source · the file that holds your source strings, used by push
files · one entry per translated file, used by pull and translate
provider · the format name exactly as the export dialog shows it, such as "JSON Key Value" or "Gettext Po"
lang · a language code enabled in the project

See all supported formats

Commands

Every command reads localizify.json from the current directory and prints one line per result.

localizify push

Imports the source file and adds new keys only. With --with-translations it also imports the file's strings as translations for source.lang, keeping existing ones.

$ localizify push
pushed src/locale/messages.xlf: 3 new keys, 148 processed
$ localizify push --with-translations

localizify translate

Translates every untranslated term. Pick anthropic (default), openai, deepl, google or microsoft with --provider, and limit the targets with --lang.

$ localizify translate --provider anthropic --lang uk,de
uk: 3 terms translated
de: 3 terms translated

localizify pull

Downloads each entry in files and writes it to its path, creating folders as needed.

$ localizify pull
pulled uk -> src/locale/messages.uk.xlf (18342 bytes)
pulled de -> src/locale/messages.de.xlf (18911 bytes)

localizify status

Prints the key count and per-language progress.

$ localizify status
151 keys
uk       145/151 (96%)
de       151/151 (100%)

Run it in CI

Store the token as a CI secret, then push, translate and pull on every merge. The workflow below fails on API errors, so a bad token or a plan limit never ships silently.

# .github/workflows/i18n.yml
name: i18n
on:
  push:
    branches: [main]
jobs:
  sync:
    runs-on: ubuntu-latest
    env:
      LOCALIZIFY_TOKEN: ${{ secrets.LOCALIZIFY_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npx @localizify/cli push
      - run: npx @localizify/cli translate
      - run: npx @localizify/cli pull
      - run: git status --porcelain src/locale

Machine-readable output

Add --json to any command to get a single JSON object on stdout, ready for jq or a build script.

$ localizify status --json
{"termsCount":151,"languages":[{"languageCode":"uk","translatedCount":145,"totalCount":151,"progress":96}]}

Reference

Options

-c, --config <path>	Path to the config file. Default: localizify.json.
--with-translations	push: also import the source file's translations.
--provider <name>	translate: anthropic, openai, deepl, google or microsoft. Default: anthropic.
--lang <a,b>	translate: target language codes. Default: every lang in files except the source.
--json	Print one JSON object instead of text.
-h, --help	Print usage.

Exit codes

0	Success.
1	API or network error: bad token, plan limit or rate limit.
2	Config or usage error.

The CLI wraps the public REST API. For direct API calls and the MCP server, see Developers.