Manual
Overview Getting Started Core concepts Quick Start Guide Create an account and sign in Projects Create and manage projects Project settings Languages Workflow and translation lock Translation Keys Key names and groups ICU messages and placeholders Translating The translation editor Keyboard shortcuts Review & Reports Review workflow Reports Branches & Merging Branch workflows: create, merge, and delete The Branches page Translation Memory How translation memory works Glossary The glossary Import & Export Import and export files File formats Integrations GitHub GitLab CI and CLI settings Webhooks Teams & Access Roles and permissions Teams Inviting people Project access Account & Organization Account settings Organization settings Billing & Plans Plans and limits
CLI
Overview Set up the CLI Commands File formats Use the CLI in CI
API
Overview Authentication: API keys and session tokens Endpoints Pull translations for your build
Log in Get started free
Translation Keys

Key names and groups

How keys are named and grouped, where source texts come from, and how to add keys.

3 min read ยท Updated October 2026

A key is one piece of text that needs translating. It has a name, a source text, and one translation per language. Keys live on a branch, so the same key can have different texts on different branches.

Key names #

Choose names that describe where the text is used, for example checkout.title or auth.login.button.

  • Use dots to group keys. The editor groups the key list by the part of the name before the first dot, so checkout.title and checkout.pay_button both appear under the group checkout. Keys without a dot are listed under general.
  • A key name can be up to 120 characters when you create it in the editor. Keys pushed with the CLI or imported from a file can have names of up to 190 characters. Control characters are not allowed.
  • A key name is unique within a branch.

When you import or export nested JSON or YAML, nesting and dots are the same thing: {"checkout": {"title": "Pay"}} becomes the key checkout.title, and is nested again on export. See Import and export.

Source texts #

The source text is the text in the project’s source language that translators work from. It is at most 5,000 characters.

A key without a source text shows as No source and cannot be translated. The editor then asks for the source: type it and choose Confirm source. Once confirmed it is the reference for all translators. Later changes to a source text are for managers, and come in most often through a push from the CLI or an import.

Warning

When the source text of a key changes through a push or an import, its existing translations go back to draft, so they have to be submitted and approved again.

Add keys #

There are three ways:

  1. In the editor. Choose New key in the key list, enter a Key name and optionally a Source text, and choose Add key. Translators, reviewers and managers can all add keys.
  2. Import a file. See Import and export.
  3. Push from your repository with the CLI or through a connected GitHub or GitLab repository.

Adding keys to the protected main branch counts towards the key limit of your plan. See Plans and limits.

Remove keys #

The web app has no button to delete a single key. Keys are removed when you import a file or push with the option to remove keys that are not in the file (Remove keys that are not in the file, or ct push --prune). Removing a key deletes its translations on that branch.

Reviewers and managers can attach context for translators to a key in the editor: Notes (short texts) and Links (a title, an address and an optional description, pointing to documentation, designs or a style guide). Both are copied when you create a branch. See The translation editor.