LazyLocales CLI

AI-powered translation management for modern applications. Translate your app into multiple languages with a single command.

Features

• 🚀 One-command translation — npx lazylocales translate handles everything
• 🤖 AI-powered — High-quality translations using GPT-4o
• 🔄 Incremental updates — Only translates changed or new keys
• 🎯 Context-aware — Supports pluralization, variables, and technical terminology
• 📦 i18next integration — Works seamlessly with i18next-http-backend
• 🔐 CI/CD ready — Use API tokens for automated translation pipelines

Quick Start

Installation

npm install --save-dev lazylocales

Or use directly without installing:

npx lazylocales translate

Usage

1. Authenticate with your LazyLocales account:

   npx lazylocales login

2. Run translation:

   npx lazylocales translate

The CLI will guide you through:

• Project selection (create new or use existing)
• Source file selection (interactive file picker)
• Target locale selection (multi-select with fuzzy search)
• Live translation progress with real-time updates

3. Get translated files written to your locales directory automatically.

Commands

lazylocales translate

Main command that handles the complete translation workflow:

• Detects or creates project configuration
• Picks source locale file interactively
• Selects target languages
• Pushes source file
• Triggers translation jobs
• Polls for completion with progress bars
• Pulls translated files

Options:

• --locale <locales...> — Translate specific locales only
• --dry-run — Show diff without triggering translation

lazylocales login

Authenticate using Device Authorization Flow. Opens your browser for authorization.

lazylocales logout

Clear stored credentials from ~/.config/lazylocales/.

lazylocales status

Show translation coverage for all configured locales.

lazylocales push

Upload source locale file only (without triggering translation).

lazylocales pull

Download translated locale files only (without triggering translation).

lazylocales whoami

Show currently logged-in user information.

Configuration

After the first run, a lazylocales.config.json file is created at your repo root:

{
  "projectId": "proj_abc123",
  "localesDir": "./public/locales",
  "sourceLocale": "en"
}

This file is safe to commit — it never contains secrets, only environment variable names.

CI/CD Usage

For non-interactive environments (GitHub Actions, GitLab CI, etc.):

1. Generate an API token in your LazyLocales project settings
2. Add token to CI secrets as LAZYLOCALES_API_KEY
3. Run in CI — the CLI automatically uses the token when the env var is set:

   - name: Translate
     run: npx lazylocales translate --json
     env:
       LAZYLOCALES_API_KEY: ${{ secrets.LAZYLOCALES_API_KEY }}

i18next Integration

Load translations at runtime using i18next-http-backend:

import i18next from 'i18next';
import HttpBackend from 'i18next-http-backend';

i18next.use(HttpBackend).init({
  backend: {
    loadPath: 'https://your-deployment.convex.site/v1/projects/PROJ_ID/locales/{{lng}}',
    customHeaders: {
      Authorization: 'Bearer ll_your_api_token',
    },
  },
  lng: 'en',
  fallbackLng: 'en',
});

Requirements

• Node.js >= 18
• A LazyLocales account (sign up at app.lazylocales.com)

How It Works

1. Source file detection — Interactive file picker with smart heuristics
2. Diff computation — Only changed/new keys are translated
3. AI translation — High-quality translations using GPT-4o with context awareness
4. Progress tracking — Live progress bars showing translation status per locale
5. File writing — Translated files written to your locales directory

Example Output

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

Source file changed since last run
+ 3 new keys
~ 1 modified key
- 0 deleted keys

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

3 files written to public/locales/

Documentation

• Full Documentation
• API Reference
• Dashboard

Support

• GitHub Issues
• Documentation

License

MIT © LazyLocales