210 lines
9.5 KiB
Markdown
210 lines
9.5 KiB
Markdown
<!-- status: done -->
|
||
<!-- lastReviewed: 2026-04-10 -->
|
||
|
||
# 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
|
||
|
||
```mermaid
|
||
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 `platform-core/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 |
|
||
|-------|-----------|
|
||
| `platform-core/modules/shared/i18nRegistry.py` | `_registerRbacLabels`, Aufruf in `_syncRegistryToDb` |
|
||
| `platform-core/modules/system/mainSystem.py` | Nur falls DATA/RESOURCE dort noch nicht importiert werden — Scan |
|
||
| `platform-core/modules/routes/routeI18n.py` | Nur falls Sync-Logik `rbac.*` explizit filtern muss — pruefen |
|
||
|
||
### A.3 Abnahme
|
||
|
||
- [x] Nach Gateway-Start: xx-Set enthaelt neue Eintraege mit `context` `rbac.data` / `rbac.resource` / `rbac.role` / `rbac.quickaction` (118 Keys).
|
||
- [x] Keine Regression: bestehende `ui`- und `api.*`-Keys unveraendert zaehlbar.
|
||
- [x] 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
|
||
|
||
- [x] Dokumentation ist verlinkt.
|
||
- [x] 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
|
||
|
||
- [x] Quick-Action-Labels und -Descriptions als `rbac.quickaction` Keys registriert (C3-Ansatz).
|
||
- [x] 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 `platform-core/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
|
||
|
||
- [x] Nur authentifizierte Nutzer (`Depends(getCurrentUser)`).
|
||
- [x] 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
|
||
|
||
- [x] Role-Formular (multilingual description): Button implementiert.
|
||
- [x] 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: `platform-core/modules/shared/i18nRegistry.py`
|
||
- i18n API: `platform-core/modules/routes/routeI18n.py`
|
||
- Formular: `ui-nyla/src/components/FormGenerator/FormGeneratorForm/FormGeneratorForm.tsx`
|
||
|
||
|