Keys and strings
Keys, source strings, plural forms and placeholders, and how transglot stores them.
Keys
A key is the name your code asks for, such as checkout.title. Each key holds one source string in the project's source language and one translation per target language. Keys and their source strings arrive from a push, an upload, or a connected repository or content platform. Source text is read-only in the console: to change it, change your source file and push or upload it again. New key in the editor adds a key and its details.
| Field | What it is for |
|---|---|
| Key name | The identifier your code uses. Nested keys from JSON or YAML files are stored with dotted names, such as cart.items. |
| Description (context for translators & AI) | What the string is and where it appears. Glossa and your translators both read it, so "Headline shown on the checkout page" gets a better translation than nothing. |
| Plural key | Marks the key as plural, so it holds one form per plural category instead of a single string. |
| Max length (optional) | The longest a translation may be, in characters. Glossa aims to stay within it, and the quality checks report a translation that goes over. |
| Tags | Labels for grouping keys, such as the release or feature they belong to. The editor can filter by tag. |
A key can also carry screenshots, which show reviewers where the string appears, and comments, where your team discusses it. See The screenshot library and Comment on a string.
From the CLI, a key metadata file can set descriptions and maximum lengths for formats that have nowhere to keep them. See Configuration.
Plural forms
Languages differ in how many plural forms they have. English has one and other; Polish has one, few, many and other; Arabic has six. A plural key stores one form per CLDR plural category of each language, so a translation into Polish has four forms even when the English source has two. Glossa writes every form the target language needs, and a translation missing a form is flagged. See Plural forms.
Placeholders
A placeholder is a part of a string your code fills in at runtime. transglot recognises these syntaxes and keeps them intact in every translation:
| Syntax | Example |
|---|---|
| Double braces (i18next, Vue, Handlebars) | {{count}} |
| Single braces (ICU, .NET, Python) | {name} |
| printf | %s, %d, %1$s |
| Laravel | :name |
| HTML tags | <strong>, </a> |
The editor highlights placeholders in the source and the translation. A translation that loses, adds or changes a placeholder is flagged, because shipping it would break the string at runtime.
The project's Message syntax setting, under Checks, decides how strictly strings are read as ICU MessageFormat: Auto reads a string as ICU only when it holds a plural, select, ordinal, number, date or time; ICU reads every string as ICU; Legacy never does.
When source strings change or disappear
When a source string changes, its existing translations are marked stale until someone reads them again. While the project's Auto-translate setting is on, Glossa drafts new translations for the changed string. A translation you have edited or reviewed is never overwritten by AI: it stays as it is, marked stale, for a person to update.
A push adds and updates keys but does not delete keys that are missing from the pushed file, unless you ask it to with transglot push --sync-removals. You can also delete keys in the editor.