> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lazylocales.com/llms.txt
> Use this file to discover all available pages before exploring further.

# translate

> Push source file, trigger translation, and pull locale files

The `translate` command is the main workflow command. It pushes your source file, computes a diff, triggers AI translation for changed keys, and downloads the results.

## Usage

```bash theme={null}
npx lazylocales translate [options]
```

## Options

| Flag                    | Description                          |
| ----------------------- | ------------------------------------ |
| `--locale <locales...>` | Only translate specific locales      |
| `--dry-run`             | Show changes without calling the API |
| `--json`                | Output machine-readable JSON         |

## What it does

<Steps>
  <Step title="Check authentication">
    Verifies you're logged in. If not, triggers the login flow automatically.
  </Step>

  <Step title="Load configuration">
    Reads `lazylocales.config.json` from your project root. If no config exists,
    runs the interactive setup flow (project creation or linking).
  </Step>

  <Step title="Push source file">
    Reads the source locale file (e.g. `en.json`) and uploads it to LazyLocales.
    A diff is computed against the previous version:

    ```
    + 3 new keys
    ~ 1 modified key
    - 0 deleted keys
    ```

    Only changed keys are sent for translation.
  </Step>

  <Step title="Trigger translation">
    Starts translation jobs for each target locale. If `--locale` is specified,
    only those locales are translated.
  </Step>

  <Step title="Poll for progress">
    Displays live progress bars while translations are running:

    ```
    nl-NL (Dutch)   ████████████████████ 142/142 ✓ done
    fr-FR (French)  ████████████████████ 142/142 ✓ done
    de (German)     ████████████████████ 142/142 ✓ done
    ```
  </Step>

  <Step title="Download locale files">
    Writes the translated JSON files to your `localesDir`:

    ```
    ┌─────────┬────────────────────────────┬────────┬────────┐
    │ 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    │
    └─────────┴────────────────────────────┴────────┴────────┘
    ```
  </Step>
</Steps>

## Examples

Translate all configured locales:

```bash theme={null}
npx lazylocales translate
```

Translate only Dutch and French:

```bash theme={null}
npx lazylocales translate --locale nl-NL fr-FR
```

Preview changes without translating:

```bash theme={null}
npx lazylocales translate --dry-run
```

Output as JSON (for scripting):

```bash theme={null}
npx lazylocales translate --json
```