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

8.4 KiB

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

  • 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.
  • I18N_ENABLED_LOCALES validiert unbekannte, doppelte, leere und nicht release-fertige Werte fail-closed; Default ist de,en.
  • Locale-Auflösung und Selector respektieren ausschließlich aktivierte Sprachen in der Reihenfolge User → Tenant → Accept-Language → DE; deaktivierte Cookies/Preferences/Header werden ignoriert.
  • 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.
  • 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.
  • 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.
  • Knowledge-Base-Inhaltssprachen und nutzergenerierte Inhalte bleiben vom UI-Locale-Ausbau getrennt.
  • Verbindliches SHK-/HiveGrid-Glossar sowie Styleguide je Zielsprache dokumentieren Fachbegriffe, Ton und informelle/formelle Anrede.
  • 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).
  • Review-Manifest je Zielsprache enthält Source-Hashes, automatisierten Übersetzungs-/Zweitprüfstatus, Muttersprachler-Stichprobe und Release-Status; geänderte DE-Quellen invalidieren den Reviewstatus.
  • 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.
  • Startzeit/RSS mit zwei versus sechs Katalogen sind gemessen; bei mehr als 250 ms oder 30 MB Delta wird vor Freigabe localeweise gecacht geladen.
  • 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.
  • 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.