Claude Fable 5
0629411966
Initial deliverable of the architecture phase: 16 ADRs (stack, CRDT collaboration, plugin sandbox, import/export, backups, CI/CD), data model, permission model, real-time collaboration and plugin concepts, deployment/operations/security documentation, and the milestone roadmap that the implementation issues are derived from. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
47 lines
1.9 KiB
Markdown
47 lines
1.9 KiB
Markdown
# 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.
|