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

# Keys & Namespaces

> Understand how translation keys and namespaces organize your content.

Keys and namespaces are the foundation of how Entri organizes your translatable content. Understanding how they work helps you design a clean structure that scales with your project.

## What is a key?

A **translation key** is a unique identifier that represents a single translatable string. Every piece of text your application displays — a button label, an error message, a page title — is represented by a key.

A key has:

| Property         | Description                                 | Example                                      |
| ---------------- | ------------------------------------------- | -------------------------------------------- |
| **Name**         | Unique identifier within the namespace      | `button.save`, `error.not_found`             |
| **Source value** | The original string in your source language | `"Save changes"`                             |
| **Description**  | Optional context for translators            | `"Appears on the save button in the editor"` |
| **Tags**         | Optional labels for filtering               | `ui`, `cta`, `marketing`                     |
| **Namespace**    | The group this key belongs to               | `common`, `auth`, `settings`                 |

## Key naming conventions

Key names can follow any convention, but these patterns work well in practice:

<Tabs>
  <Tab title="Flat (snake_case)">
    Simple underscore-separated names. Works best with `json-flat` format.

    ```
    welcome_message
    button_save
    button_cancel
    error_not_found
    error_server_error
    nav_home
    nav_settings
    ```
  </Tab>

  <Tab title="Dot notation">
    Hierarchical names using dots. Naturally maps to `json-nested` format.

    ```
    button.save
    button.cancel
    button.delete
    error.not_found
    error.server_error
    nav.home
    nav.settings
    auth.login
    auth.logout
    ```
  </Tab>

  <Tab title="Section prefix">
    Section name followed by a descriptive identifier.

    ```
    AUTH_LOGIN_TITLE
    AUTH_LOGIN_SUBMIT
    AUTH_LOGOUT_CONFIRM
    EDITOR_SAVE_SUCCESS
    EDITOR_DISCARD_CONFIRM
    ```
  </Tab>
</Tabs>

<Tip>
  Choose a convention and apply it consistently. Dot notation works especially well because it maps directly to nested JSON objects, making your source files easy to read.
</Tip>

## What is a namespace?

A **namespace** is a named group of related keys. Namespaces let you partition your translations by feature, page, or team — keeping large projects manageable.

Common namespace strategies:

* **By feature:** `auth`, `editor`, `settings`, `billing`, `onboarding`
* **By page:** `home`, `dashboard`, `profile`, `checkout`
* **By file:** one namespace per locale file

### Namespaces and file patterns

In your `.nt3.yml`, each file pattern corresponds to a namespace. The `{namespace}` placeholder (when used) maps the file path directly to the namespace name:

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

With this pattern, the file `src/locales/en/auth.json` belongs to the `auth` namespace, and `src/locales/en/common.json` belongs to the `common` namespace.

Alternatively, you can list each namespace as a separate pattern:

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

## Key uniqueness

Keys are unique within a namespace. The same key name can exist in different namespaces without conflict. For example, both `auth` and `settings` can have a key named `title` — they are distinct keys because they live in different namespaces.

A key is globally identified by the combination of **project + namespace + key name**.

## Using descriptions and tags

### Descriptions

Add a description to give translators the context they need to produce accurate translations:

```
Key:         button.save
Source:      Save
Description: Appears on the primary action button in the translation editor.
             Keep it short — maximum 8 characters in most languages.
```

AI translations also use descriptions to produce better, more context-aware results.

### Tags

Tags allow you to filter and bulk-operate on related keys:

* Tag all marketing copy with `marketing` to batch-translate with a specific tone
* Tag UI strings with `ui` to export only interface translations
* Tag strings pending legal review with `legal-review`

## Importing keys

When you run `nt3 push`, the CLI reads your source locale file and creates or updates keys in Entri. By default, existing keys are not overwritten — use `--overwrite` to replace source values and metadata.

```bash theme={null}
nt3 push           # Create new keys; skip existing
nt3 push --overwrite  # Create and update all keys
```

<Warning>
  Using `--overwrite` replaces the source value of existing keys. Any translations that were based on the previous source value will retain their current text but their status may be reset, flagging them for review.
</Warning>