> ## 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.

# Quickstart

> Get LazyLocales up and running in your project in under 5 minutes

## Prerequisites

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

## Setup

<Steps>
  <Step title="Install the CLI">
    Add `lazylocales` as a development dependency:

    ```bash theme={null}
    npm install --save-dev lazylocales
    ```

    Or run it directly without installing:

    ```bash theme={null}
    npx lazylocales translate
    ```
  </Step>

  <Step title="Authenticate">
    Log in using the device authorization flow:

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

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

  <Step title="Run your first translation">
    ```bash theme={null}
    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
  </Step>

  <Step title="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
    ```

    <Tip>
      Always edit `en.source.json` — the clean `en.json` is regenerated automatically on every translate/push.
      See [Source File](/source-file) for annotation syntax.
    </Tip>
  </Step>
</Steps>

## Example output

```bash theme={null}
✓ 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:

```json lazylocales.config.json theme={null}
{
  "projectId": "proj_abc123",
  "localesDir": "./public/locales",
  "sourceLocale": "en"
}
```

This file is safe to commit — it contains no secrets. See the [Configuration](/configuration) page for all options.

## Next steps

<CardGroup cols={2}>
  <Card title="Source File" icon="file-code" href="/source-file">
    Learn the annotation syntax for context and locks
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    Customize the config file for your project
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Explore all available CLI commands
  </Card>

  <Card title="CI/CD Setup" icon="robot" href="/integrations/ci-cd">
    Automate translations in your pipeline
  </Card>
</CardGroup>