# Conventions I18N

> Internationalization conventions for Stella. Apply when adding or modifying user-facing strings.

- Skill: `stella/conventions-i18n` (Agent Skill)
- Install (CLI): `npx get-skill add stella/conventions-i18n`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stella/conventions-i18n/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: stella (https://skillmd.com/u/stella)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/stella/conventions-i18n

---


# 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.

1. 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]
2. 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):

1. **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]
2. **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]
3. **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]
4. **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]
5. **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`.

