When to use
Use this at the start of any multi-document or multi-translator project, or when you notice a term rendered inconsistently. The glossary fixes the approved target-language equivalent for each key term, plus do-not-translate lists and style rules (tone, capitalization, punctuation), so every downstream translation stays consistent.
Not for: translating running prose (use i18n-translate), locale formatting (use i18n-localize), tone shifts (use i18n-tone-adapt), or subtitles (use i18n-subtitle).
Method
- Harvest candidate terms: product names, features, recurring domain jargon, UI labels, legal terms, and anything a wrong translation would confuse.
- For each term, decide status. Decision point: TRANSLATE (with the single approved equivalent), DO-NOT-TRANSLATE (brand/code), or FORBIDDEN (renderings to avoid).
- Record part of speech, gender/plural where the target language needs it, and a one-line usage note or example.
- Add style rules: preferred register, capitalization conventions, quotation-mark style, number formatting, Oxford-comma policy, spacing (e.g. French non-breaking space before
:).
- Decision point: when two valid equivalents exist, pick one as canonical and list the other under "avoid" to prevent drift.
- Version the glossary and note the date; treat it as the source of truth reviewers check against.
Example
Project: SaaS dashboard, en → de.
| Source |
Approved (de) |
Status |
Note |
| Dashboard |
Dashboard |
Do-not-translate |
Anglicism accepted in market |
| Sign in |
Anmelden |
Translate |
Not "Einloggen" |
| Workspace |
Arbeitsbereich |
Translate |
n., m. |
| Boost |
— |
Forbidden literal |
Use "Verstärken", never "Boosten" |
Style rule: address the user with formal "Sie", not "du".
Pitfalls
- Multiple equivalents in the wild. Without a canonical choice, three translators produce three words for one feature.
- No do-not-translate list. Brand names and code identifiers get "helpfully" translated.
- Missing grammatical metadata. Omitting gender/plural forces guesswork in gendered languages.
- Static and unversioned. A glossary nobody updates or dates silently rots as the product changes.
Output format
Project: <name> Pair: <src> → <tgt> Version: 1.0 (<date>)
## Terminology
| Source | Approved target | Status | POS/gender | Note |
|--------|-----------------|--------|-----------|------|
## Do-not-translate
- <term>
## Style rules
- Register: <...>
- Capitalization: <...>
- Punctuation/spacing: <...>
1---2name: i18n-glossary3description: Build a bilingual terminology glossary and style guide that enforces consistency across a translation project.4---56## When to use78Use this at the start of any multi-document or multi-translator project, or when you notice a term rendered inconsistently. The glossary fixes the approved target-language equivalent for each key term, plus do-not-translate lists and style rules (tone, capitalization, punctuation), so every downstream translation stays consistent.910**Not for:** translating running prose (use `i18n-translate`), locale formatting (use `i18n-localize`), tone shifts (use `i18n-tone-adapt`), or subtitles (use `i18n-subtitle`).1112## Method13141. Harvest candidate terms: product names, features, recurring domain jargon, UI labels, legal terms, and anything a wrong translation would confuse.152. For each term, decide status. Decision point: TRANSLATE (with the single approved equivalent), DO-NOT-TRANSLATE (brand/code), or FORBIDDEN (renderings to avoid).163. Record part of speech, gender/plural where the target language needs it, and a one-line usage note or example.174. Add style rules: preferred register, capitalization conventions, quotation-mark style, number formatting, Oxford-comma policy, spacing (e.g. French non-breaking space before `:`).185. Decision point: when two valid equivalents exist, pick one as canonical and list the other under "avoid" to prevent drift.196. Version the glossary and note the date; treat it as the source of truth reviewers check against.2021## Example2223Project: SaaS dashboard, en → de.2425| Source | Approved (de) | Status | Note |26|---|---|---|---|27| Dashboard | Dashboard | Do-not-translate | Anglicism accepted in market |28| Sign in | Anmelden | Translate | Not "Einloggen" |29| Workspace | Arbeitsbereich | Translate | n., m. |30| Boost | — | Forbidden literal | Use "Verstärken", never "Boosten" |3132Style rule: address the user with formal "Sie", not "du".3334## Pitfalls3536- **Multiple equivalents in the wild.** Without a canonical choice, three translators produce three words for one feature.37- **No do-not-translate list.** Brand names and code identifiers get "helpfully" translated.38- **Missing grammatical metadata.** Omitting gender/plural forces guesswork in gendered languages.39- **Static and unversioned.** A glossary nobody updates or dates silently rots as the product changes.4041## Output format4243```44Project: <name> Pair: <src> → <tgt> Version: 1.0 (<date>)4546## Terminology47| Source | Approved target | Status | POS/gender | Note |48|--------|-----------------|--------|-----------|------|4950## Do-not-translate51- <term>5253## Style rules54- Register: <...>55- Capitalization: <...>56- Punctuation/spacing: <...>57```
Matrixx0070