Quickstart

This guide uses the CLI and gets you to your first translated files. You will need Node.js 18+ and Git 2+.

Install (or run via npx)

npx @neoiq/localize@latest --help

If you prefer a global install:

Terminal

npm install -g @neoiq/localize

Authenticate

npx @neoiq/localize@latest auth login

This opens a browser once and stores a session in ~/.neoiq-localize. For CI or headless environments, use NEOIQ_LOCALIZE_API_KEY and NEOIQ_LOCALIZE_PROJECT_ID instead.

Initialize configuration

npx @neoiq/localize@latest init

The init flow asks for your source locale, target locales, and file pattern, then creates neoiq-localize.json.

neoiq-localize.json (example)

{
  "projectId": "prj_your_project_id",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "files": {
    "json": {
      "include": ["src/locales/[locale].json"]
    }
  }
}

Add a source file

Create or confirm your source locale file, for example:

src/locales/en.json

{
  "welcome": "Welcome to our application!",
  "user": {
    "greeting": "Hi, {{name}}!"
  },
  "notifications": {
    "messages": "You have {{count}} new message(s)."
  }
}

Translate

npx @neoiq/localize@latest translate

This will:

Create translation files for each target language
Translate only new or changed keys
Update neoiq-localize.lock to track translation state

Commit both neoiq-localize.json and neoiq-localize.lock to your repo.

Tips

If you add a new locale, backfill existing keys:

npx @neoiq/localize@latest translate --force fr

In CI, check for missing translations without writing files:

npx @neoiq/localize@latest translate --check

For monorepos, run the CLI in the folder that contains neoiq-localize.json.

Next steps

Authentication

Configuration

File patterns, formats, and project IDs.

CLI

Commands, flags, and advanced workflows.

GitHub Actions

Run translations in CI with the official action.