87 lines
8.4 KiB
Markdown
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`.
|