Keys & Namespaces

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:

Flat (snake_case)
Dot notation
Section prefix

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

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

Section name followed by a descriptive identifier.

AUTH_LOGIN_TITLE
AUTH_LOGIN_SUBMIT
AUTH_LOGOUT_CONFIRM
EDITOR_SAVE_SUCCESS
EDITOR_DISCARD_CONFIRM

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.

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:

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:

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.

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.

nt3 push           # Create new keys; skip existing
nt3 push --overwrite  # Create and update all keys

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.

Getting Started

CLI

Integrations

Concepts

Open source

Keys & Namespaces

What is a key?

Key naming conventions

What is a namespace?

Namespaces and file patterns

Key uniqueness

Using descriptions and tags

Descriptions

Tags

Importing keys

​What is a key?

​Key naming conventions

​What is a namespace?

​Namespaces and file patterns

​Key uniqueness

​Using descriptions and tags

​Descriptions

​Tags

​Importing keys

What is a key?

Key naming conventions

What is a namespace?

Namespaces and file patterns

Key uniqueness

Using descriptions and tags

Descriptions

Tags

Importing keys