stwaidele/dorfteich
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 22 Wiki Activity
6c38abc20c
dorfteich/docs/architecture/adr/0012-i18n.md
Claude Fable 5 0629411966 Add architecture documentation, ADRs, and operations concept 
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>
2026-07-04 14:36:16 +02:00

1.9 KiB
Raw Blame History

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.