Skip to main 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:
PropertyDescriptionExample
NameUnique identifier within the namespacebutton.save, error.not_found
Source valueThe original string in your source language"Save changes"
DescriptionOptional context for translators"Appears on the save button in the editor"
TagsOptional labels for filteringui, cta, marketing
NamespaceThe group this key belongs tocommon, auth, settings

​
Key naming conventions

Key names can follow any convention, but these patterns work well in practice:
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
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.

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