i18n Conventions
Internationalization conventions for Stella. Apply when adding or
modifying user-facing strings.
Stack
use-intl for runtime.
Supported Languages
en is the source language. Check apps/web/src/i18n/langs/ for
the current list of target languages (add translations to every
.json file found there).
Translation Flow
Add keys to apps/web/src/i18n/langs/en.json; bun run i18n:check (from
apps/web) names every structural fix.
- Write natural, idiomatic translations into every target language file, then
read the rendered sentence in context, including interpolation and plural
branches. Passing key parity is not proof that a translation is natural or
that placeholders remain grammatically valid. [review]
Changing existing English
i18n-source-lock.json beside each catalog records the English every key's
translations follow. i18n:check fails on a key whose en.json value no
longer matches it, and i18n:sync never updates an existing entry.
- Run
bun --filter @stll/web i18n:brief --locale=<code> for each target
locale (@stll/landing and @stll/transactional have the same script). It
lists every message i18n:check fails on for that locale with the English
it was written for, the current translation, placeholders, plural forms the
locale needs, glossary terms and the source lines that use the key.
[check: i18n:check]
- Rework each translation to say what the English now says, then record it
with
bun --filter @stll/web i18n:accept <key> ... once every locale is
updated. Accepting without retranslating is right only when the English
change leaves every translation correct (casing, punctuation).
[check: i18n:check]
The product name is lowercase stella in every locale and grammatical form,
sentence starts included (stellu, stelle).
Key Naming
- Prefer generic, reusable keys over feature-specific ones. Before adding
any new i18n key, search
en.json for an existing key with the same or
similar wording (e.g., common.filter, common.sort, common.columns).
Reuse common.* or shared namespace keys instead of creating feature-scoped
duplicates like billing.expenses.deleteExpense. Feature-specific keys are
only justified when the wording truly differs from the generic version (e.g.,
a confirmation message that mentions the resource by name). [review]
- When a translation key crosses indirection through a constant, map, prop, or
helper return type, type it with
TranslationKey from
apps/web/src/i18n/types.ts instead of string. Missing or stale keys must
fail typecheck at the point where they are stored. [review]
- Prefer complete translatable sentences over fragments assembled in JSX. Keep
interpolation variables semantic (
{documentName}, not {value}), use ICU
plural/select branches for grammatical variation, and never concatenate
translated fragments whose word order differs by locale. [review]
- Never call anything an "entity" in user-facing copy, in English or as a
calque (
entita, Entität, entidad, entité, entidade, encja, ...).
It is the database's word for a row and means nothing to a lawyer. Name the
concrete thing the string is about — document, file, folder, task, matter —
and fall back to "item" only when the string genuinely covers all of them. In
anonymization, what the detector finds is a match, not an entity. The
item concept in glossary.json enforces this with forbiddenAlways, so it
fires on the English source too, not only on translations. [check: i18n:check]
Key naming, pluralization, and style rules are documented
in apps/web/src/i18n/TERMINOLOGY.md.
Terminology (glossary)
Canonical legal/domain terms live in
apps/web/src/i18n/glossary.json (the source of truth);
glossary-gen renders them into the tables in TERMINOLOGY.md.
The i18n-lint checker enforces them: per concept it flags a
translation that uses a forbidden rendering when the English
source is about that concept (concept-gated, so a common word only
fires in the right context).
When introducing a NEW concept (or changing a preferred term):
- Research it first. Confirm the sector-standard term and the
synonyms to avoid in each language against authoritative
sources (IATE/EU terminology, national legal glossaries,
established legal-tech usage) — do not guess. Record the
rationale in the concept's
note. [review]
- Add it to
glossary.json, never only to TERMINOLOGY.md
(the .md is generated). Run bun run i18n:sync (from
apps/web) to regenerate the tables. [check: i18n:check]
- Account for declensions/inflections. The lint matches
forbidden terms whole-word (English source triggers also match
their regular plural), so list the actual inflected, declined,
and compound forms a translator might use — e.g. de
Sache/Sachen/Mandatsdaten, sk Vec/veci/vecou, et
asi/asja/asjad. A base form alone misses inflected drift. [review]
- Pick the right ban field.
forbidden is concept-gated: it fires
only where the English source names the concept (or a keyTriggers
path matches), which is what stops a common word from false-firing
everywhere. forbiddenAlways drops that gate, for wording that is
wrong in every context. Use it when a concept-gated ban would go
blind the moment someone rewords the English source, and only once
you have checked that no legitimate use of the word exists in that
locale. [review]
- Apply consistently.
bun run i18n:check fails on new
forbidden renderings; fix the translations, or — only for
genuine pre-existing debt — grandfather with
i18n-lint <dir> --write-baseline and flag for native review.
[check: i18n:check]
Landing (marketing) catalogs
The landing app has its own catalogs (apps/landing/src/i18n/messages/)
with the same glossary enforcement plus marketing-specific rules —
register per locale, the identity phrase, hero structure differences,
meta-string length budgets, cognate policy, and brand handling. Before
translating landing strings, read
apps/landing/src/i18n/TRANSLATION.md; it explains the intent behind
each rule so translations stay coherent rather than merely passing the
checks. Landing gates: bun run i18n:sync and bun run i18n:check
from apps/landing.
1---2name: conventions-i18n3description: "Internationalization conventions for Stella. Apply when adding or modifying user-facing strings."4metadata:5 source: https://skillmd.com/skills/stella/conventions-i18n6---78# i18n Conventions910Internationalization conventions for Stella. Apply when adding or11modifying user-facing strings.1213## Stack1415`use-intl` for runtime.1617## Supported Languages1819en is the source language. Check `apps/web/src/i18n/langs/` for20the current list of target languages (add translations to every21`.json` file found there).2223## Translation Flow2425Add keys to `apps/web/src/i18n/langs/en.json`; `bun run i18n:check` (from26`apps/web`) names every structural fix.2728- Write natural, idiomatic translations into every target language file, then29 read the rendered sentence in context, including interpolation and plural30 branches. Passing key parity is not proof that a translation is natural or31 that placeholders remain grammatically valid. [review]3233### Changing existing English3435`i18n-source-lock.json` beside each catalog records the English every key's36translations follow. `i18n:check` fails on a key whose `en.json` value no37longer matches it, and `i18n:sync` never updates an existing entry.38391. Run `bun --filter @stll/web i18n:brief --locale=<code>` for each target40 locale (`@stll/landing` and `@stll/transactional` have the same script). It41 lists every message `i18n:check` fails on for that locale with the English42 it was written for, the current translation, placeholders, plural forms the43 locale needs, glossary terms and the source lines that use the key.44 [check: i18n:check]452. Rework each translation to say what the English now says, then record it46 with `bun --filter @stll/web i18n:accept <key> ...` once every locale is47 updated. Accepting without retranslating is right only when the English48 change leaves every translation correct (casing, punctuation).49 [check: i18n:check]5051The product name is lowercase `stella` in every locale and grammatical form,52sentence starts included (`stellu`, `stelle`).5354## Key Naming5556- **Prefer generic, reusable keys over feature-specific ones.** Before adding57 any new i18n key, search `en.json` for an existing key with the same or58 similar wording (e.g., `common.filter`, `common.sort`, `common.columns`).59 Reuse `common.*` or shared namespace keys instead of creating feature-scoped60 duplicates like `billing.expenses.deleteExpense`. Feature-specific keys are61 only justified when the wording truly differs from the generic version (e.g.,62 a confirmation message that mentions the resource by name). [review]63- When a translation key crosses indirection through a constant, map, prop, or64 helper return type, type it with `TranslationKey` from65 `apps/web/src/i18n/types.ts` instead of `string`. Missing or stale keys must66 fail typecheck at the point where they are stored. [review]67- Prefer complete translatable sentences over fragments assembled in JSX. Keep68 interpolation variables semantic (`{documentName}`, not `{value}`), use ICU69 plural/select branches for grammatical variation, and never concatenate70 translated fragments whose word order differs by locale. [review]71- **Never call anything an "entity" in user-facing copy**, in English or as a72 calque (`entita`, `Entität`, `entidad`, `entité`, `entidade`, `encja`, ...).73 It is the database's word for a row and means nothing to a lawyer. Name the74 concrete thing the string is about — document, file, folder, task, matter —75 and fall back to "item" only when the string genuinely covers all of them. In76 anonymization, what the detector finds is a **match**, not an entity. The77 `item` concept in `glossary.json` enforces this with `forbiddenAlways`, so it78 fires on the English source too, not only on translations. [check: i18n:check]7980Key naming, pluralization, and style rules are documented81in `apps/web/src/i18n/TERMINOLOGY.md`.8283## Terminology (glossary)8485Canonical legal/domain terms live in86`apps/web/src/i18n/glossary.json` (the source of truth);87`glossary-gen` renders them into the tables in `TERMINOLOGY.md`.88The `i18n-lint` checker enforces them: per concept it flags a89translation that uses a `forbidden` rendering when the English90source is about that concept (concept-gated, so a common word only91fires in the right context).9293When introducing a NEW concept (or changing a preferred term):94951. **Research it first.** Confirm the sector-standard term and the96 synonyms to avoid in **each** language against authoritative97 sources (IATE/EU terminology, national legal glossaries,98 established legal-tech usage) — do not guess. Record the99 rationale in the concept's `note`. [review]1002. **Add it to `glossary.json`**, never only to `TERMINOLOGY.md`101 (the `.md` is generated). Run `bun run i18n:sync` (from102 `apps/web`) to regenerate the tables. [check: i18n:check]1033. **Account for declensions/inflections.** The lint matches104 forbidden terms whole-word (English source triggers also match105 their regular plural), so list the actual inflected, declined,106 and compound forms a translator might use — e.g. de107 `Sache`/`Sachen`/`Mandatsdaten`, sk `Vec`/`veci`/`vecou`, et108 `asi`/`asja`/`asjad`. A base form alone misses inflected drift. [review]1094. **Pick the right ban field.** `forbidden` is concept-gated: it fires110 only where the English source names the concept (or a `keyTriggers`111 path matches), which is what stops a common word from false-firing112 everywhere. `forbiddenAlways` drops that gate, for wording that is113 wrong in every context. Use it when a concept-gated ban would go114 blind the moment someone rewords the English source, and only once115 you have checked that no legitimate use of the word exists in that116 locale. [review]1175. **Apply consistently.** `bun run i18n:check` fails on new118 forbidden renderings; fix the translations, or — only for119 genuine pre-existing debt — grandfather with120 `i18n-lint <dir> --write-baseline` and flag for native review.121 [check: i18n:check]122123## Landing (marketing) catalogs124125The landing app has its own catalogs (`apps/landing/src/i18n/messages/`)126with the same glossary enforcement plus marketing-specific rules —127register per locale, the identity phrase, hero structure differences,128meta-string length budgets, cognate policy, and brand handling. Before129translating landing strings, read130`apps/landing/src/i18n/TRANSLATION.md`; it explains the intent behind131each rule so translations stay coherent rather than merely passing the132checks. Landing gates: `bun run i18n:sync` and `bun run i18n:check`133from `apps/landing`.