Skip to main content

​
Prerequisites

  • Node.js 18 or higher
  • A LazyLocales account — sign up at lazylocales.com
  • A project with a JSON locale file (e.g. public/locales/en.json)

​
Setup

1

Install the CLI

Add lazylocales as a development dependency:
npm install --save-dev lazylocales
Or run it directly without installing:
npx lazylocales translate
2

Authenticate

Log in using the device authorization flow:
npx lazylocales login
This opens your browser to authorize the CLI. Your session is stored securely in ~/.config/lazylocales/.
3

Run your first translation

npx lazylocales translate
The CLI walks you through:
  1. Project setup — create a new project or link to an existing one
  2. Source file selection — interactive file picker with locale scoring
  3. Target languages — multi-select picker with fuzzy search
  4. Translation — live progress bars for each locale
  5. Output — translated files written to your locales directory
4

Check the output

After the command completes, your locales directory will contain the translated files:
public/locales/
├── en.source.json   ← your editable source (supports annotations)
├── en.json           ← auto-generated clean copy (for runtime)
├── nl-NL.json       ← translated
├── fr-FR.json       ← translated
└── de.json          ← translated
Always edit en.source.json — the clean en.json is regenerated automatically on every translate/push. See Source File for annotation syntax.

​
Example output

✓ Project: my-app (proj_abc123)
✓ Source: public/locales/en.source.json (annotated)
✓ Output: public/locales/

Checking for changes...

Source file changed since last run
────────────────────────────────────────────────
+ 3 new keys
  auth.mfa.setup
  auth.mfa.verify
  settings.notifications.email

~ 1 modified key
  common.save

Only these 4 keys will be sent to AI. Existing translations are preserved.

Translating 3 locales...
nl-NL (Dutch)   ████████████████████ 142/142 ✓ done
fr-FR (French)  ████████████████████ 142/142 ✓ done
de (German)     ████████████████████ 142/142 ✓ done

────────────────────────────────────────────────
✓ Translation complete

┌─────────┬────────────────────────────┬────────┬────────┐
│ Locale  │ File                       │ Keys   │ Time   │
├─────────┼────────────────────────────┼────────┼────────┤
│ nl-NL   │ public/locales/nl-NL.json  │ 142    │ 18s    │
│ fr-FR   │ public/locales/fr-FR.json  │ 142    │ 22s    │
│ de      │ public/locales/de.json     │ 142    │ 16s    │
└─────────┴────────────────────────────┴────────┴────────┘

3 files written to public/locales/

​
Configuration file

After the first run, a lazylocales.config.json file is created at your project root:
lazylocales.config.json
{
  "projectId": "proj_abc123",
  "localesDir": "./public/locales",
  "sourceLocale": "en"
}
This file is safe to commit — it contains no secrets. See the Configuration page for all options.

​
Next steps

Source File

Learn the annotation syntax for context and locks

Configuration

Customize the config file for your project

CLI Reference

Explore all available CLI commands

CI/CD Setup

Automate translations in your pipeline