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

# Configuration (.nt3.yml)

> Configure the CLI using a .nt3.yml file in your project root.

The CLI reads a `.nt3.yml` file from your project root (the directory where you run `nt3` commands). This file defines which Entri project to sync with and where your translation files are located.

## Minimal example

```yaml theme={null}
project_id: "proj_abc123"
source_language: en
file_patterns:
  - path: "src/locales/{lang}.json"
    format: json-nested
```

## Full reference

### `project_id`

**Required.** The ID of your Entri project. Found in the Entri dashboard under **Project Settings**.

```yaml theme={null}
project_id: "proj_abc123"
```

### `source_language`

**Required.** The language code for your source strings — the language your developers write in. Common values: `en`, `de`, `fr`, `ja`.

```yaml theme={null}
source_language: en
```

### `update_translations` (optional)

Controls whether `nt3 push` overwrites existing translations. Mirrors the `--overwrite` CLI flag, but lets you set a per-project default in the config file.

| Value             | Behaviour                                                    |
| ----------------- | ------------------------------------------------------------ |
| `false` (default) | Existing translations are skipped; only new keys are created |
| `true`            | Existing translations are replaced on every push             |

```yaml theme={null}
update_translations: true
```

The `--overwrite` flag always takes precedence over this setting when both are present.

### `file_patterns`

**Required.** A list of file pattern objects. Each entry defines one set of translation files to sync.

```yaml theme={null}
file_patterns:
  - path: "src/locales/{lang}.json"
    format: json-nested
```

Each file pattern has the following fields:

#### `path`

**Required.** The file path pattern with a `{lang}` placeholder. The CLI replaces `{lang}` with the language code at runtime.

```yaml theme={null}
path: "src/locales/{lang}.json"
# Resolves to: src/locales/en.json, src/locales/fr.json, etc.
```

The path is resolved relative to the directory where you run `nt3` commands (typically your project root).

#### `format`

**Required.** The file format. Must be one of the supported format identifiers:

| Value             | File type                                                   |
| ----------------- | ----------------------------------------------------------- |
| `json-flat`       | Flat key-value JSON (e.g., `{"key": "value"}`)              |
| `json-nested`     | Nested JSON objects (e.g., `{"section": {"key": "value"}}`) |
| `yaml`            | YAML key-value                                              |
| `po`              | GNU gettext PO files                                        |
| `xliff`           | XLIFF 1.2                                                   |
| `xliff2`          | XLIFF 2.0                                                   |
| `arb`             | Application Resource Bundle (Flutter)                       |
| `android-xml`     | Android string resources (`res/values/strings.xml`)         |
| `ios-strings`     | iOS Localizable.strings                                     |
| `ios-stringsdict` | iOS Stringsdict files (plurals)                             |

#### `namespace` (optional)

A namespace string to scope this file's keys within the project. Useful when multiple file patterns share the same project but represent different parts of the app.

```yaml theme={null}
file_patterns:
  - path: "src/locales/{lang}/common.json"
    format: json-nested
    namespace: common
  - path: "src/locales/{lang}/checkout.json"
    format: json-nested
    namespace: checkout
```

## Multiple file patterns

Projects that split translations across multiple files — by feature, by library, or by format — can define multiple patterns:

```yaml theme={null}
project_id: "proj_abc123"
source_language: en
file_patterns:
  - path: "src/locales/{lang}.json"
    format: json-nested
    namespace: app
  - path: "public/locales/{lang}/marketing.json"
    format: json-flat
    namespace: marketing
  - path: "mobile/ios/{lang}.strings"
    format: ios-strings
    namespace: ios
```

All patterns are processed in order when you run `nt3 push` or `nt3 pull`.

## Mobile app example

```yaml theme={null}
project_id: "proj_abc123"
source_language: en
file_patterns:
  - path: "android/app/src/main/res/values-{lang}/strings.xml"
    format: android-xml
```

<Note>
  For Android XML, the source language file path should use the base `values` directory convention. When using the CLI, make sure the path pattern resolves correctly for both the source and target languages.
</Note>

## Flutter example

```yaml theme={null}
project_id: "proj_abc123"
source_language: en
file_patterns:
  - path: "lib/l10n/intl_{lang}.arb"
    format: arb
```

## GNU gettext example

```yaml theme={null}
project_id: "proj_abc123"
source_language: en
file_patterns:
  - path: "locales/{lang}/LC_MESSAGES/messages.po"
    format: po
```

## Generating the config file

Rather than writing `.nt3.yml` by hand, use `nt3 init` to create it interactively or non-interactively:

```bash theme={null}
nt3 init -p proj_abc123 -f po --path "locales/{lang}/messages.po"
```

Use `--force` to overwrite an existing config:

```bash theme={null}
nt3 init --force -p proj_new123
```