Better I18N
How do I manage my translation glossary?
A glossary fixes how specific terms get translated — brand names, product nouns, technical vocabulary — so "workspace" does not come back as espace de travail in one key and espace in the next.
What a term holds #
| Field | Notes |
|---|---|
| Term | The source-language word or phrase |
| Type | brand, technical, product, feature or ui |
| Description | Required — what the term means in your product |
| Part of speech | Optional; disambiguates a word that is both noun and verb |
| Context | Optional; where it appears, when that changes the translation |
| Per-language translation | The approved translation for each locale you want to pin |
| Do not translate | Keeps the source value as-is |
The description is not paperwork. It is what the model reads to decide whether the term applies to the string in front of it — a term with no explanation is a string match with no reason attached, and "run" will be pinned in a sentence about running late.
Adding a term #
- Open the project's glossary
- Add a term
- Fill in the term, its type and a description
- Pin translations for the languages you care about, or mark it do not translate
You do not have to pin every language. A term with a description and no translations still helps: it tells the model that this word is a product noun rather than a common one.
How it reaches a translation #
Approved terms are indexed for semantic retrieval, so a term is found even when the wording in the string is not identical to the entry. Matching is by meaning, not by exact substring — which is why an entry needs its description and type to be right, and why a near-duplicate entry is worth merging rather than leaving.
Which translation paths actually carry it:
- The AI drawer (
⌘I) and MCP agents — the relevant terms travel with the request, so the model is told your term before it guesses one - Machine-translation engines — DeepL and friends keep glossaries as their own resources, so yours is synced across to the provider. A term added a minute before a large run should be synced first
- A one-off suggestion on a single cell does not carry the glossary. It translates the string in front of it with your project instructions, and nothing else. So a pinned term can come back as a synonym there — if terminology matters for a value, translate it through the drawer. See How does AI translation work?
Where terms come from #
Each term records its source:
| Source | Meaning |
|---|---|
manual | You added it |
website_analysis | Extracted from a crawl of your site |
repo_analysis | Extracted from your repository |
Terms produced by an analysis arrive as proposals — they are reviewed before they start shaping translations, which is the point of the approval step. See How does website analysis improve translations?.
Editing and clearing #
Terms can be edited or deleted individually, and the whole glossary can be cleared in one action — useful after a rebrand, or when an early analysis filled it with terms you never really used. Clearing is a deliberate reset, not a cleanup habit: everything the model knew about your vocabulary goes with it.
What does not exist #
Two things people expect and then look for:
- No CSV import or TBX export. Terms come from the dashboard, from an analysis, or through the API — there is no file round-trip today. If your terminology lives in a spreadsheet, the API is the honest path.
- No case-sensitivity flag. Matching is semantic rather than literal, so a case switch would not mean what it means in a find-and-replace tool.