Quickstart - LazyLocales Documentation

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

Install the CLI

Add lazylocales as a development dependency:

npm install --save-dev lazylocales

Or run it directly without installing:

npx lazylocales translate

Authenticate

npx lazylocales login

This opens your browser to authorize the CLI. Your session is stored securely in ~/.config/lazylocales/.

Run your first translation

npx lazylocales translate

The CLI walks you through:

Project setup — create a new project or link to an existing one
Source file selection — interactive file picker with locale scoring
Target languages — multi-select picker with fuzzy search
Translation — live progress bars for each locale
Output — translated files written to your locales directory

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

​Prerequisites

​Setup

​Example output

​Configuration file

​Next steps

Source File

Configuration

CLI Reference

CI/CD Setup

Prerequisites

Setup

Example output

Configuration file

Next steps