PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/c-work/4-done/2026-04-gateway-i18n-phase-7-implementation.md
ValueOn AG 93edc94da3 upd
2026-04-10 22:44:27 +02:00

9.4 KiB
Raw Blame History

Gateway i18n — Phase 7: Konkreter Umsetzungsplan

Dieses Dokument ist der ausfuehrbare Umsetzungsplan fuer die in c-work/2-build/2026-04 gateway-i18n-unified.md beschriebene Phase 7 (RBAC-/Katalog-Labels, Quick Actions, optional Phase 7b TextMultilingual-KI-Button). Es ergaenzt das Konzeptdokument um Reihenfolge, Abhaengigkeiten, Dateien und Abnahmekriterien.

1. Ziele

ID Ziel Messbar
G1 Alle RBAC-relevanten statischen Texte (DATA/RESOURCE-Katalog, optional Template-Rollenbeschreibung de) erscheinen im xx-Basisset und sind fuer AI-Sync / Admin-Sprachen abbildbar Keys in UiLanguageSet(xx).entries mit context rbac.*
G2 Kein Bruch von TextMultilingual in der DB (Role.description etc.); FormGenerator bleibt multilingual-kompatibel Bestehende Formulare unveraendert nutzbar
G3 Quick Actions: Uebersetzungen konsistent mit dem gewaehlten Ansatz (siehe Arbeitspaket C) Sichtbar korrekte Sprache nach Wechsel
G4 Phase 7b: Ein-Klick-Uebersetzung fuer TextMultilingual-Felder im Formular (optional eigenes Release) Button fuellt Zielsprachen; Fehler/Loading klar

2. Nicht-Ziele (Scope-Ausschluss)

  • Kein Ersatz von TextMultilingual durch reine String-Keys in datamodelRbac.Role ohne Migrationskonzept.
  • Kein vollstaendiges Umbauen aller Admin-UI-Tabellen auf t() fuer Katalog-Labels in einem Schritt (kann folgen, wenn G1 live ist).
  • Keine Aenderung der Bedeutung von AccessRules oder RBAC-Resolution — nur Label-/i18n-Schicht.

3. Abhaengigkeiten zwischen Arbeitspaketen

flowchart LR
  A[WP-A: _registerRbacLabels] --> B[WP-B: Admin-Zaehler / Doku]
  A --> C[WP-C: Quick Actions]
  D[WP-D: Phase 7b API] --> E[WP-E: FormGenerator Button]
  A -.-> D
  • WP-A ist Grundlage fuer xx-Set und AI-Workflows zu Katalog-Texten.
  • WP-C (Quick Actions) kann parallel zu B starten, baut aber auf gleicher i18n-Policy auf; empfohlen: A zuerst merge-faehig.
  • WP-D/E (Phase 7b) sind unabhaengig von A fuer die reine API, aber sinnvoll nach A, damit _translateBatch-Nutzung und Billing einheitlich dokumentiert sind.

4. Arbeitspaket A — _registerRbacLabels() und Boot-Sync

A.1 Inhalt

  1. In gateway/modules/shared/i18nRegistry.py Funktion _registerRbacLabels() implementieren (falls noch nicht vorhanden):
    • Alle Feature-Module mit DATA_OBJECTS / RESOURCE_OBJECTS durchlaufen (gleiche Modulliste wie bei _registerFeatureUiLabels oder erweitern).
    • Pro Eintrag: label ist Dict → key = label.get("de") or label.get("en") (nicht-leer); context:
      • rbac.data fuer DATA_OBJECTS
      • rbac.resource fuer RESOURCE_OBJECTS
    • Optional System-mainSystem: DATA_OBJECTS / RESOURCE_OBJECTS aus modules/system/mainSystem.py falls vorhanden.
  2. TEMPLATE_ROLES[].description: nur de-Text als Key registrieren, context rbac.role (ein Key pro Rolle reicht fuer Admin-Uebersicht; Duplikat-Texte teilen sich dieselbe Key-Zeile — akzeptabel).
  3. _syncRegistryToDb() um Aufruf _registerRbacLabels() nach _registerFeatureUiLabels() erweitern (Reihenfolge dokumentieren).
  4. Merge-Logik (routeI18n.py / xx-Sync): sicherstellen, dass context rbac.* wie andere Gateway-Kontexte behandelt werden (nicht ui ueberschreiben).

A.2 Dateien (voraussichtlich)

Datei Aenderung
gateway/modules/shared/i18nRegistry.py _registerRbacLabels, Aufruf in _syncRegistryToDb
gateway/modules/system/mainSystem.py Nur falls DATA/RESOURCE dort noch nicht importiert werden — Scan
gateway/modules/routes/routeI18n.py Nur falls Sync-Logik rbac.* explizit filtern muss — pruefen

A.3 Abnahme

  • Nach Gateway-Start: xx-Set enthaelt neue Eintraege mit context rbac.data / rbac.resource / rbac.role / rbac.quickaction (118 Keys).
  • Keine Regression: bestehende ui- und api.*-Keys unveraendert zaehlbar.
  • Log-Zeile: i18n rbac labels: 118 new keys (rbac.* context).

A.4 Aufwand

  • Klein (ca. 0.5–1 Tag), wenn Modulliste und Dict-Extraktion zentral und getestet sind.

5. Arbeitspaket B — Admin-Sprachen-UI und Doku

B.1 Inhalt

  1. AdminLanguagesPage (optional): Spalte oder Filter „Kontext“ — rbac.* sichtbar (falls noch nicht generisch).
  2. Wiki: gateway-i18n-unified.md — Verweis auf dieses Umsetzungsplan-Dokument; Status Phase 7 in Arbeit → done nach Merge.
  3. coding-conventions.md (kurz): Regel „neue DATA/RESOURCE-Labels: de-Text als Basis-Key; en/fr im Dict fuer Legacy-Anzeige bis Migration“.

B.2 Abnahme

  • Dokumentation ist verlinkt.
  • Kein Muss fuer UI-Spalte, wenn Tabelle bereits nach context filterbar ist.

6. Arbeitspaket C — Quick Actions (Entscheidung + Umsetzung)

C.0 Entscheidung (vor Codieren)

Option Beschreibung Aufwand
C1 Backend: de-String aus Dict als Basis; Aufloesung in getQuickActions via t() / Cache (Request-Sprache) statt nur language-Dict-Lookup Mittel
C2 Backend liefert nur deutsche Keys; Frontend QuickActionBoard nutzt t(action.label) / t(action.description) (wie Navigation) Mittel
C3 Status quo belassen; nur WP-A registriert Keys — Admin kann Sprachen pflegen, API bleibt dict-basiert bis spaeter Gering

Empfehlung: Zuerst C3 mit A; C1 oder C2 in einem separaten PR nach Product-Entscheidung.

C.1 Schritte fuer C1 (falls gewaehlt)

  1. mainTrustee.py (und ggf. andere Features): QUICK_ACTIONS / Kategorien auf deutsche Basis-Strings umstellen (analog UI_OBJECTS) oder Dict beibehalten und zusaetzlich key/labelKey einfuehren.
  2. routeFeatureTrustee.getQuickActions: _resolveText ersetzen/ergaenzen durch t() aus i18nRegistry mit Request-Sprache.
  3. Keys in xx/_REGISTRY via WP-A oder dedizierte Registrierung.

C.2 Abnahme

  • Quick-Action-Labels und -Descriptions als rbac.quickaction Keys registriert (C3-Ansatz).
  • Keine doppelten Keys ohne context-Trennung (Composite-Key-Modell beachten).

7. Arbeitspaket D — Phase 7b: API translate-field

D.1 Inhalt

  1. Neuer Endpoint in gateway/modules/routes/routeI18n.py, z. B.:
    • POST /api/i18n/translate-field
    • Body: { "sourceText": string, "sourceLang": string, "targetLangs": string[] }
    • Response: { "translations": { "de": "...", "fr": "..." } } (ohne Source-Lang)
  2. Intern: Wiederverwendung von _translateBatch mit einem kuenstlichen Key-Set (oder schlanker Helper), inkl. _matchCapitalization.
  3. Auth: Depends(getRequestContext); Billing: gleicher Callback wie bei translate Jobs.
  4. Rate-Limit und Payload-Groesse (max. Zeichen) begrenzen.

D.2 Abnahme

  • Nur authentifizierte Nutzer (Depends(getCurrentUser)).
  • Leerer sourceText → 422 (Pydantic min_length=1).
  • Integrationstest oder manueller Test mit zwei Zielsprachen.

D.3 Aufwand

  • Klein bis mittel (ca. 1 Tag inkl. Tests).

8. Arbeitspaket E — Phase 7b: FormGenerator Button

E.1 Inhalt

  1. FormGeneratorForm.tsx — renderMultilingualField:
    • Button „In alle Sprachen uebersetzen“ (Text via t()).
    • Quellsprache: implementierte Regel festhalten (z. B. erste nicht-leere Sprache in multilingualLangs-Reihenfolge, sonst en).
    • Ziel: alle anderen Codes aus multilingualLangs ohne Quelle.
  2. onClick: POST /api/i18n/translate-field, dann handleMultilingualChange pro Ziel.
  3. UX: Loading-Spinner, disabled waehrend Request, Toast bei Fehler.
  4. Optional: Tooltip Hinweis KI-Qualitaet.

E.2 Abnahme

  • Role-Formular (multilingual description): Button implementiert.
  • Readonly-Modus: kein Button (nur in Edit-/Create-Modus sichtbar).

E.3 Aufwand

  • Mittel (ca. 1–1.5 Tage inkl. Styling und Edge Cases).

9. Testplan (Phase 7 gesamt)

Nr Szenario Erwartung
T1 Boot mit WP-A xx-Set enthaelt rbac.* Eintraege
T2 Admin: AI-Uebersetzung fuer ein rbac.data-Key Wert in Zielsprache gesetzt
T3 Quick Actions (nach C1/C2) Texte passen zur UI-Sprache
T4 Phase 7b: Button + leerer Source Validation / keine KI-Call
T5 Phase 7b: langer Text Limit oder Chunking klar

10. Risiken und Rollback

Risiko Massnahme
Zu viele Keys in xx (Duplikate) Composite-Key (key, context) bleibt Massstab; Dokumentation
KI-Kosten Phase 7b Limits, Feature-Flag optional
Regression Boot-Sync Feature-Flag _registerRbacLabels optional abschaltbar

Rollback: WP-A durch Entfernen des Aufrufs _registerRbacLabels() deaktivieren; keine DB-Schema-Aenderung fuer A.

11. Reihenfolge-Empfehlung (Sprints)

Sprint Inhalt Deliverable
S1 WP-A + B (minimal) Rbac-Keys im xx-Set, Doku-Link
S2 WP-C (nach Entscheidung C1/C2/C3) Quick Actions Policy
S3 WP-D + E Phase 7b fertig

12. Links

  • Konzept & Phase-7-Text: c-work/2-build/2026-04 gateway-i18n-unified.md
  • i18n Registry: gateway/modules/shared/i18nRegistry.py
  • i18n API: gateway/modules/routes/routeI18n.py
  • Formular: frontend_nyla/src/components/FormGenerator/FormGeneratorForm/FormGeneratorForm.tsx