Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/I18N-01.md
T

87 lines
8.4 KiB
Markdown

<!-- markdownlint-disable MD013 MD060 -->
# I18N-01 · Polnisch, Russisch, Ukrainisch und Ungarisch
| | |
| --- | --- |
| **Typ** | Dev (Code + Kataloge + QA) |
| **Owner** | Raffael |
| **Phase** | Querschnitt · CR-020 |
| **Plane** | `HIVEGRID-243` · Issue `8e7c8c3b-558e-4d58-9650-5decc1b5d3c6` |
| **Cycle/Fenster** | ohne Cycle · Priorität High |
| **Status** | Done |
## Abhängigkeiten & Parallelität
- **Blocked by:** `R-P1b` (Done: i18n-Foundation und `verify:i18n`), genehmigter `CR-020`.
- **Blocks:** keine bestehende Implementierung; die produktive Freigabe jeder neuen Sprache bleibt bis zu ihrem Review-Manifest blockiert.
- **Plane-Prüfung:** `HIVEGRID-243` wurde nach bestätigter Identität `raffael` angelegt. Das abgeschlossene Foundation-Ticket `R-P1b` ist die einzige technische Vorbedingung; das neue Ticket übernimmt keinen bestehenden `blocks`-Vertrag und blockiert nur die sprachweisen Release-Gates in seinen Review-Manifesten.
- **Konflikt-Risiko:** hoch in den zentralen Locale-Dateien und Querschnittsverträgen. Umsetzung deshalb im isolierten Worktree `feat/i18n-pl-ru-uk-hu`, keine Schemaänderung.
## Was wir bauen
HiveGrid erhält vollständige statische Produktübersetzungen für Polnisch (`pl`), Russisch (`ru`), Ukrainisch (`uk`, niemals `ua`) und Ungarisch (`hu`). Der sichtbare Scope umfasst App, Admin, Auth, Fehler, Einstellungen, Billing, Customer-Portal, Dialoge/Toasts und transaktionale E-Mails. Deutsch bleibt fachliche Quelle, Englisch zweite Kontextreferenz.
Vorhandene Kataloge und freigegebene Runtime-Sprachen werden getrennt. `I18N_ENABLED_LOCALES` enthält ohne Konfiguration nur `de,en`. Deaktivierte Sprachen erscheinen nicht im Selector und können weder Cookie, gespeicherte Präferenz noch Browserheader erzwingen. Auflösung: aktivierte User-Präferenz → aktivierter Tenant-Default → aktiviertes `Accept-Language` → Deutsch.
Alle sechs Sprachen sind LTR. Basisdateien sind informell. Formelle Bundles folgen zwingend `<locale>-formal → <locale> → de`; fehlende formelle Übersetzungen einer Zielsprache dürfen nicht direkt nach Deutsch springen. UI-Sprache und Knowledge-Base-Inhaltssprache bleiben getrennt. Nutzergenerierte Inhalte werden nicht maschinell verändert.
## Benötigte Screens
Keine neue Oberfläche. Vorhandene Sprachwahl, App-/Admin-Shell, Customer-Portal und kritische Journeys werden für lange lateinische sowie kyrillische Texte browserseitig geprüft. Die Kataloge landen zunächst deaktiviert; visuelle Produktfreigabe erfolgt Sprache für Sprache.
## Definition of Done
- [x] `SupportedLocale` und alle öffentlichen UI-/Mail-/Portal-Locale-Verträge umfassen exakt `de`, `en`, `pl`, `ru`, `uk`, `hu`; alle sechs sind LTR, keine DB-Migration.
- [x] `I18N_ENABLED_LOCALES` validiert unbekannte, doppelte, leere und nicht release-fertige Werte fail-closed; Default ist `de,en`.
- [x] Locale-Auflösung und Selector respektieren ausschließlich aktivierte Sprachen in der Reihenfolge User → Tenant → `Accept-Language` → DE; deaktivierte Cookies/Preferences/Header werden ignoriert.
- [x] Jede Basis-Sprache liefert alle neun Namespaces mit exakt derselben Key-Struktur wie DE; jede Sprache besitzt vollständige Namespace-Dateien für `<locale>-formal` mit ausschließlich abweichenden Overrides.
- [x] date-fns/Wochenbeginn, Portal-Cookie/`Accept-Language`, Portal-Mailvorlagen, Mail-Worker, React-E-Mail-Dokumentsprache/Betreff/HTML/Plaintext/Footer, inline Mailtexte und Billing-Checkout sind vollständig verdrahtet.
- [x] Mollie erhält `pl_PL` und `hu_HU`; für `ru`/`uk` wird keine erfundene Provider-Locale gesendet. Die HiveGrid-Checkout-Hülle bleibt übersetzt.
- [x] Knowledge-Base-Inhaltssprachen und nutzergenerierte Inhalte bleiben vom UI-Locale-Ausbau getrennt.
- [x] Verbindliches SHK-/HiveGrid-Glossar sowie Styleguide je Zielsprache dokumentieren Fachbegriffe, Ton und informelle/formelle Anrede.
- [x] `verify:i18n` prüft Key-Parität, JSON, leere/unveränderte Texte, Platzhalter/ICU/Tags/URLs, Unicode-Normalisierung, Mojibake und CLDR-Pluralformen (`pl/ru/uk`: one/few/many/other; `hu`: one/other).
- [x] Review-Manifest je Zielsprache enthält Source-Hashes, automatisierten Übersetzungs-/Zweitprüfstatus, Muttersprachler-Stichprobe und Release-Status; geänderte DE-Quellen invalidieren den Reviewstatus.
- [x] Tests decken Locale-Auflösung, deaktivierte Quellen, Profil-/Tenant-Anrede, Portal, Worker/Mail, Billing-Mapping, Formal-Fallback und ICU-Werte `0/1/2/5/21` plus Dezimalwert ab.
- [x] Startzeit/RSS mit zwei versus sechs Katalogen sind gemessen; bei mehr als 250 ms oder 30 MB Delta wird vor Freigabe localeweise gecacht geladen.
- [x] Rollout und Rollback sind dokumentiert: initial alle neuen Sprachen deaktiviert; Freigabe `pl → uk → ru → hu` jeweils erst nach bestandenem Manifest-Gate. Rumänisch ist als nächster Ausbau dokumentiert, aber nicht als Katalog angelegt.
- [x] Fokussierte Tests, `pnpm typecheck`, `pnpm lint`, `pnpm test`, `pnpm run verify:i18n`, `verify:ci-baseline` und `verify:source-health` sind grün.
**Fortschritt:** 14/14 DoD = 100 % done · 0 Punkte selbst machbar. Die Muttersprachler-Freigabe ist kein Merge-Gate dieses initial deaktivierten Katalog-PRs; alle vier Sprachen bleiben bis dahin technisch vorhanden, aber produktiv gesperrt (`nativeReview: pending`, `release: disabled`).
## Technische Bausteine
- `packages/i18n`: statische versus aktivierte Locales, Parser/Resolver, Formal-Fallback, Plural-/Token-Verträge.
- `apps/web/public/locales/{pl,ru,uk,hu}` und `{pl,ru,uk,hu}-formal`: neun Namespaces je Verzeichnis.
- `apps/web/app/locale`: Serverressourcen, Cookie/Header/User-/Tenant-Auflösung, date-fns und Mail-Translator.
- `apps/web/app/services/customer-portal`, `apps/web/app/modules/emails`, `apps/worker`: Portal- und Outbound-Wiring.
- `packages/mail`, `packages/billing`: Mail-Dokumentsprache und unterstützte Mollie-Locales.
- `scripts/i18n-check.ts` plus Review-/Glossar-Artefakte unter `docs/i18n/`.
## Qualitäts- und Release-Prozess
1. Deutsch ist die fachliche Quelle; Englisch wird als Kontextreferenz verwendet.
2. Automatische Erstübersetzung läuft namespaceweise und schützt Platzhalter, ICU, Tags und URLs.
3. Ein separater semantischer Zweitlauf und die statischen Validatoren prüfen Bedeutung und Vertragsintegrität.
4. Vor produktiver Aktivierung prüft ein Muttersprachler Auth, Fehler, Billing, Mail, alle formellen Overrides, kritische App-/Portal-Journeys und mindestens 200 geschichtete Stichproben. Reviewer, Datum und Korrekturen landen im Manifest.
## Quellen
- `docs/CHANGE-REQUESTS.md` → CR-020.
- `.planning/REQUIREMENTS.md` → `REQ-i18n-architektur`, `REQ-i18n-six-locale-outbound`.
- `.planning/ROADMAP.md` → Phase 3 und revidierter Phase-30-i18n-Scope.
- `AGENTS.md` → Querschnitt i18n, Ticket-Treue, EU-Stack, keine Runtime-LLM-Abhängigkeit.
- Unicode CLDR Plural Rules sowie Mollie Locale-Vertrag (Links im Rollout-/QA-Dokument).
## Rollback
`I18N_ENABLED_LOCALES` wird auf `de,en` zurückgesetzt und der vorherige immutable Image-SHA erneut deployt. Katalogdateien können dabei im Image verbleiben: deaktivierte Sprachen sind weder auswählbar noch über Cookie/Präferenz/Header aktivierbar. Es gibt keine Migration und keinen Daten-Rollback.
## Umsetzungs-Notiz
**2026-08-02 · 14/14 DoD = 100 % done.** Umsetzung in `feat/i18n-pl-ru-uk-hu` ab `origin/main` (`86eb01825`) mit atomaren Commits `52b94bd8a`, `d23b22f10`, `21e1c8997`, `9d83caedd`, `46624686f`, `f37cedf8c`, `e4b9890d0`, `6b7686cb9`, `79ab32c10`, `e60303dc6`, `216a7373e`, `6527f2d8f`, `9839cf0e3`, `5c7b33c72` und `7cf0bafa5`; aktuelles `origin/main` samt Avatar-Crop-Texten über `c4af2e0c0` integriert.
Proof: sechs Basis-Kataloge und sechs Formal-Bundles mit je neun Namespaces; `verify:i18n` meldet nach Integration des aktuellen `origin/main` 16.483 identische Keys pro Basis-Locale. `pnpm typecheck`, `pnpm lint`, 1.197 Core-Testdateien, `verify:i18n`, `verify:i18n-performance`, `verify:ci-baseline`, `verify:source-health` und `verify:secrets` sind grün. Die finale Performance-Messung ergab gegenüber `de,en` +22,62 ms Startladezeit und +11,09 MB RSS (Grenzen: +250 ms/+30 MB), daher bleibt das einmalige eager Laden bestehen.
Kein Schema- oder Migrations-Nachzug. Runtime-Default und Produktion bleiben `de,en`. Die Review-Manifeste halten Polnisch, Ukrainisch, Russisch und Ungarisch bis zur dokumentierten muttersprachlichen Prüfung von kritischen Oberflächen, Du/Sie-Ton, Fachterminologie und mindestens 200 Stichproben ausdrücklich auf `pending`/`disabled`.