# ADR 0012: i18next with German and English from the start

- Status: accepted
- Date: 2026-07-04

## Context

Kickoff decision: the UI ships with an i18n framework from the beginning,
delivered in German and English. Retro-fitting i18n is expensive; two live
languages keep the framework honest. E-mails and API error messages face
users too.

## Decision

- **i18next** (+ `react-i18next`) in the frontend; a lightweight i18next
  instance in the API for e-mail templates and user-facing error messages.
- Translation resources are JSON files per namespace per language under
  `packages/shared/i18n/<lang>/<namespace>.json`, shared where texts overlap
  (e.g. validation messages).
- Rules for contributors (enforced in review + a CI lint that flags missing
  keys):
  - No hard-coded user-facing strings — every string goes through a key.
  - Every change adds **both** `de` and `en` texts (English is the key
    fallback language).
  - Use ICU-style interpolation/plurals via i18next's built-ins; never
    concatenate translated fragments.
  - Gender-fair wording in both languages (German: neutral forms or pair
    forms — e.g. "Bearbeitende", not generic masculine).
- Language selection: per-user setting; default from `Accept-Language`;
  instance default configurable. Public pages render UI chrome in the
  instance default.
- **Content is not translated** — pages have exactly one body; multilingual
  content management is explicitly out of scope.

## Consequences

- Slightly slower story implementation (every UI story touches two language
  files) — accepted cost for a community-oriented product.
- Additional languages later are pure resource additions.

## Alternatives considered

- **German-only, i18n later**: cheapest now, expensive retrofit, adoption
  barrier for an international open-source audience. Rejected in kickoff.
- **FormatJS/Lingui**: comparable capability; i18next chosen for ubiquity
  and the simplest mental model for contributors.