feat(bisaya-course): enhance German course content and localization support
All checks were successful
Deploy to production / deploy (push) Successful in 2m47s
All checks were successful
Deploy to production / deploy (push) Successful in 2m47s
- Updated the create-german-for-bisaya-course-content.js script to improve lesson pattern retrieval by introducing a new function for generating a lesson pattern pool. - Added new exercises for various topics including 'Wohnung & Nachbarn', 'Besuch empfangen', 'Arzt, Apotheke, Termin', and 'Amt, Dokumente, Anmeldung', enhancing practical language skills for learners. - Improved localization by integrating translation keys for various UI elements and error messages across multiple components, ensuring a consistent user experience in both German and Bisaya. - Enhanced the main.js file to recognize Bisaya language preferences in browser settings, improving accessibility for users.
This commit is contained in:
Torsten Schulz (local)
520
docs/BISAYA_SITE_LOCALIZATION_IMPLEMENTATION_SPEC.md
Normal file
520
docs/BISAYA_SITE_LOCALIZATION_IMPLEMENTATION_SPEC.md
Normal file
@@ -0,0 +1,520 @@
|
||||
# Bisaya-Lokalisierung der Gesamtwebseite: Umsetzungsdokument
|
||||
|
||||
## 1. Ziel
|
||||
|
||||
Die gesamte Webseite soll zusätzlich in `Bisaya` verfügbar werden, nicht nur einzelne Sprachkurse.
|
||||
|
||||
Das Ziel ist:
|
||||
|
||||
- die komplette Produktoberfläche für Bisaya-Nutzer verständlich zu machen
|
||||
- Hauptnavigation, Formulare, Dialoge, Fehlermeldungen und Lernbereiche konsistent zu übersetzen
|
||||
- vorhandene i18n-Struktur weiterzuverwenden statt einen Sonderpfad zu bauen
|
||||
- die Qualität der Übersetzungen hoch zu halten, besonders bei Alltagssprache und sprachdidaktischen Inhalten
|
||||
|
||||
Das ist kein reines JSON-Kopieren. Es ist eine Kombination aus:
|
||||
|
||||
- technischer i18n-Erweiterung
|
||||
- Audit von hartcodierten Strings
|
||||
- kontrollierter Übersetzungsarbeit
|
||||
- fachlicher QA
|
||||
|
||||
## 2. Ist-Stand
|
||||
|
||||
Die aktuelle Lokalisierung ist in [frontend/src/i18n/index.js](/mnt/share/torsten/Programs/YourPart3/frontend/src/i18n/index.js) zentral verdrahtet.
|
||||
|
||||
Derzeit existieren drei Web-Locales:
|
||||
|
||||
- `de`
|
||||
- `en`
|
||||
- `es`
|
||||
|
||||
Die Struktur ist modulartig aufgebaut:
|
||||
|
||||
- `general.json`
|
||||
- `header.json`
|
||||
- `navigation.json`
|
||||
- `home.json`
|
||||
- `chat.json`
|
||||
- `settings.json`
|
||||
- `socialnetwork.json`
|
||||
- `falukant.json`
|
||||
- weitere Funktionsbereiche
|
||||
|
||||
Die bestehende Struktur ist grundsätzlich gut genug für eine vierte Sprache.
|
||||
|
||||
Der Haken ist:
|
||||
|
||||
- es gibt weiterhin viele hartcodierte Texte in Vue-Komponenten
|
||||
- manche Bereiche nutzen bereits sauber `$t(...)`
|
||||
- andere mischen i18n und direkte Strings
|
||||
- einige `tr:`-Muster umgehen die normale Komponentensprache
|
||||
|
||||
Für Bisaya reicht es deshalb nicht, nur neue Locale-Dateien zu erzeugen.
|
||||
|
||||
## 3. Sprachentscheidung
|
||||
|
||||
### 3.1 Locale-Code
|
||||
|
||||
Empfehlung:
|
||||
|
||||
- Web-Locale-Code: `ceb`
|
||||
|
||||
Begründung:
|
||||
|
||||
- `ceb` ist der etablierte technische Code für Cebuano/Bisaya
|
||||
- besser anschlussfähig an Standards und spätere Integrationen
|
||||
- klarer als ein frei erfundener Key wie `bis`
|
||||
|
||||
### 3.2 Sichtbarer Sprachname
|
||||
|
||||
Empfehlung im UI:
|
||||
|
||||
- `Bisaya`
|
||||
|
||||
Optional im Admin-/Technik-Kontext:
|
||||
|
||||
- `Bisaya (Cebuano)`
|
||||
|
||||
### 3.3 Sprachstil
|
||||
|
||||
Der Stil darf nicht zu formal oder zu schulbuchartig sein.
|
||||
|
||||
Empfohlen:
|
||||
|
||||
- alltagsnah
|
||||
- warm
|
||||
- direkt verständlich
|
||||
- kurze Sätze
|
||||
- neutrale, breit verständliche Bisaya-Formulierungen
|
||||
|
||||
Nicht empfohlen:
|
||||
|
||||
- künstlich hochsprachliche Formulierungen
|
||||
- unnötig spanisch geprägte oder regionale Spezialformen, wenn einfachere Alternativen reichen
|
||||
- gemischtes Englisch-Bisaya ohne klare Regel
|
||||
|
||||
## 4. Produktentscheidung
|
||||
|
||||
Die Bisaya-Lokalisierung wird als vollwertige vierte Oberfläche behandelt, nicht als Teil des Sprachkurs-Features.
|
||||
|
||||
Das heißt:
|
||||
|
||||
- Bisaya ist globale UI-Sprache
|
||||
- dieselbe Sprache kann zusätzlich als Lernsprache in Kursen vorkommen
|
||||
- Website-Locale und Sprachkursinhalt sind fachlich getrennt
|
||||
|
||||
Wichtig:
|
||||
|
||||
- `Website-Bisaya` ist Produkt-Lokalisierung
|
||||
- `Bisaya-Sprachkurs` ist Lerninhalt
|
||||
|
||||
Das muss technisch und redaktionell getrennt bleiben.
|
||||
|
||||
## 5. Hauptprobleme, die vor der Übersetzung geklärt werden müssen
|
||||
|
||||
### 5.1 Hartcodierte Strings
|
||||
|
||||
Die größte technische Altlast sind direkte Texte in Komponenten.
|
||||
|
||||
Beispiele aus dem aktuellen Frontend:
|
||||
|
||||
- Abschnittslabels in Komponenten wie [AppSectionBar.vue](/mnt/share/torsten/Programs/YourPart3/frontend/src/components/AppSectionBar.vue)
|
||||
- direkte Buttontexte und Statusmeldungen in Views
|
||||
- Fehlermeldungen, die als deutscher Klartext im Code stehen
|
||||
- teils auch Titel, Platzhalter und Hilfetexte
|
||||
|
||||
Konsequenz:
|
||||
|
||||
- vor oder während der Bisaya-Einführung müssen diese Texte systematisch in i18n überführt werden
|
||||
|
||||
### 5.2 Fallback-Logik
|
||||
|
||||
Aktuell ist `fallbackLocale: 'de'` gesetzt.
|
||||
|
||||
Für Bisaya ist das kurzfristig okay, aber fachlich nicht ideal.
|
||||
|
||||
Empfehlung:
|
||||
|
||||
- während der Einführung: globaler Fallback kann vorerst `de` bleiben
|
||||
- mittelfristig: für `ceb` bevorzugt auf `en` oder spezifisches Ketten-Fallback umstellen
|
||||
|
||||
Zielbild:
|
||||
|
||||
```js
|
||||
fallbackLocale: {
|
||||
ceb: ['en', 'de'],
|
||||
default: ['de']
|
||||
}
|
||||
```
|
||||
|
||||
So landet ein Bisaya-Nutzer bei fehlenden Schlüsseln nicht sofort in Deutsch.
|
||||
|
||||
### 5.3 Übersetzungstiefe
|
||||
|
||||
Nicht alles muss in einem Schritt übersetzt werden.
|
||||
|
||||
Wir brauchen klare Ebenen:
|
||||
|
||||
- Shell und Navigation zuerst
|
||||
- Hauptnutzungspfade danach
|
||||
- Spezialbereiche später
|
||||
|
||||
## 6. Übersetzungsprinzipien
|
||||
|
||||
### 6.1 Quelle
|
||||
|
||||
Primäre Übersetzungsquelle sollte `de` sein.
|
||||
|
||||
Begründung:
|
||||
|
||||
- das Produkt wird aktuell stark deutsch geführt
|
||||
- viele Texte sind fachlich auf Deutsch zuerst gepflegt
|
||||
- so vermeiden wir doppelte Drift zwischen `de` und `en`
|
||||
|
||||
### 6.2 Glossar
|
||||
|
||||
Vor dem Massenübersetzen braucht es ein verbindliches Glossar.
|
||||
|
||||
Pflichtbegriffe:
|
||||
|
||||
- Anmeldung
|
||||
- Einstellungen
|
||||
- Freunde
|
||||
- Nachrichten
|
||||
- Chat
|
||||
- Kurs
|
||||
- Lektion
|
||||
- Übung
|
||||
- Wiederholung
|
||||
- Abschluss
|
||||
- Senden
|
||||
- Löschen
|
||||
- Speichern
|
||||
- Suche
|
||||
- Zurück
|
||||
- Weiter
|
||||
|
||||
Zusätzlich fachliche Glossare für:
|
||||
|
||||
- Vokabeltrainer
|
||||
- Falukant
|
||||
- Socialnetwork
|
||||
- Moderation
|
||||
- Erotik-Bereich
|
||||
|
||||
### 6.3 Nicht alles wörtlich
|
||||
|
||||
Die beste Bisaya-UI ist nicht immer die wörtlichste.
|
||||
|
||||
Beispiel:
|
||||
|
||||
- kurze, handlungsnahe Buttons sind wichtiger als exakte 1:1-Übertragung
|
||||
- Hilfetexte dürfen freier formuliert werden, solange der Zweck gleich bleibt
|
||||
|
||||
### 6.4 Konsistenzregeln
|
||||
|
||||
Es muss pro Begriff genau eine Standardform geben, außer es gibt einen klaren Kontextgrund.
|
||||
|
||||
Beispiel:
|
||||
|
||||
- `Weiter` nicht an einer Stelle frei übersetzen und an anderer nur halb Englisch lassen
|
||||
- `Lektion` und `Kurs` nicht ständig unterschiedlich umschreiben
|
||||
|
||||
## 7. Rollout-Phasen
|
||||
|
||||
## 7.1 Phase A: Technische Basis
|
||||
|
||||
Ziel:
|
||||
|
||||
- `ceb` als viertes Locale technisch einführen
|
||||
|
||||
Umfang:
|
||||
|
||||
- neue Locale-Dateien unter `frontend/src/i18n/locales/ceb/`
|
||||
- Ergänzung in [index.js](/mnt/share/torsten/Programs/YourPart3/frontend/src/i18n/index.js)
|
||||
- Sprachumschalter auf `ceb` erweitern
|
||||
- Store- und Default-Sprachlogik prüfen
|
||||
|
||||
Ergebnis:
|
||||
|
||||
- die App kann Bisaya als UI-Sprache laden
|
||||
- zunächst mit vielen Fallbacks, aber technisch sauber
|
||||
|
||||
## 7.2 Phase B: Shell und globale Oberfläche
|
||||
|
||||
Ziel:
|
||||
|
||||
- die Seite fühlt sich sofort als Bisaya-Oberfläche an
|
||||
|
||||
Umfang:
|
||||
|
||||
- `general.json`
|
||||
- `header.json`
|
||||
- `navigation.json`
|
||||
- `message.json`
|
||||
- `error.json`
|
||||
|
||||
Zusätzlich:
|
||||
|
||||
- hartcodierte Hauptnavigationen in Komponenten in i18n überführen
|
||||
|
||||
Ergebnis:
|
||||
|
||||
- Header, Footer, Navigation, Standarddialoge, Basisaktionen und Fehlermeldungen sind in Bisaya
|
||||
|
||||
## 7.3 Phase C: Einstiegspfade
|
||||
|
||||
Ziel:
|
||||
|
||||
- zentrale Nutzungspfade vollständig lokalisieren
|
||||
|
||||
Umfang:
|
||||
|
||||
- `home.json`
|
||||
- `register.json`
|
||||
- `activate.json`
|
||||
- `passwordReset.json`
|
||||
- `settings.json`
|
||||
- allgemeine No-Login-/Login-Flows
|
||||
|
||||
Ergebnis:
|
||||
|
||||
- neue Nutzer können die Plattform in Bisaya betreten und bedienen
|
||||
|
||||
## 7.4 Phase D: Socialnetwork und Sprachlernen
|
||||
|
||||
Ziel:
|
||||
|
||||
- Hauptanwendungsbereich für Community und Lernen abdecken
|
||||
|
||||
Umfang:
|
||||
|
||||
- `socialnetwork.json`
|
||||
- `friends.json`
|
||||
- Vokabeltrainer-Views
|
||||
- Sprachkurs-Views
|
||||
- Such- und Dialogflächen im Social-Bereich
|
||||
|
||||
Wichtig:
|
||||
|
||||
- Sprachlerntexte im Kurs selbst nicht blind mitsynchronisieren
|
||||
- UI-Texte ja, Lerninhalte separat prüfen
|
||||
|
||||
## 7.5 Phase E: Falukant und Spezialbereiche
|
||||
|
||||
Ziel:
|
||||
|
||||
- komplexe Produktmodule sauber nachziehen
|
||||
|
||||
Umfang:
|
||||
|
||||
- `falukant.json`
|
||||
- `blog.json`
|
||||
- `chat.json`
|
||||
- `minigames.json`
|
||||
- Admin-Bereiche optional später
|
||||
|
||||
Hinweis:
|
||||
|
||||
- Falukant ist textlich sehr groß und fachlich komplex
|
||||
- dafür braucht es gesonderte QA
|
||||
|
||||
## 8. Technische Umsetzung
|
||||
|
||||
### 8.1 Neue Locale-Dateien
|
||||
|
||||
Geplante Struktur:
|
||||
|
||||
```text
|
||||
frontend/src/i18n/locales/ceb/
|
||||
activate.json
|
||||
admin.json
|
||||
blog.json
|
||||
chat.json
|
||||
error.json
|
||||
falukant.json
|
||||
friends.json
|
||||
general.json
|
||||
header.json
|
||||
home.json
|
||||
message.json
|
||||
minigames.json
|
||||
navigation.json
|
||||
passwordReset.json
|
||||
personal.json
|
||||
register.json
|
||||
settings.json
|
||||
socialnetwork.json
|
||||
```
|
||||
|
||||
### 8.2 Import in i18n
|
||||
|
||||
In [frontend/src/i18n/index.js](/mnt/share/torsten/Programs/YourPart3/frontend/src/i18n/index.js):
|
||||
|
||||
- alle `ceb`-Dateien importieren
|
||||
- vierten `messages.ceb`-Block ergänzen
|
||||
- Fallback-Regel ggf. modernisieren
|
||||
|
||||
### 8.3 Sprachwahl im Store
|
||||
|
||||
In [frontend/src/store/index.js](/mnt/share/torsten/Programs/YourPart3/frontend/src/store/index.js):
|
||||
|
||||
- `setLanguage` muss `ceb` akzeptieren
|
||||
- Browser-Spracherkennung bleibt vorerst `de/en`, außer wir wollen `ceb` aktiv auch automatisch setzen
|
||||
|
||||
Empfehlung:
|
||||
|
||||
- Auto-Default nicht auf `ceb`
|
||||
- Bisaya bewusst auswählbar machen
|
||||
|
||||
### 8.4 UI-Auswahl erweitern
|
||||
|
||||
Komponenten wie:
|
||||
|
||||
- [SettingsWidget.vue](/mnt/share/torsten/Programs/YourPart3/frontend/src/components/SettingsWidget.vue)
|
||||
|
||||
müssen `ceb` als auswählbare Sprache bekommen.
|
||||
|
||||
## 9. Audit von Nicht-i18n-Texten
|
||||
|
||||
Vor der Vollübersetzung braucht es einen String-Audit.
|
||||
|
||||
Kategorien:
|
||||
|
||||
1. komplett hartcodierte Texte
|
||||
2. gemischte Texte mit Teil-i18n
|
||||
3. technische Fehlermeldungen
|
||||
4. Admin-/Debugtexte, die bewusst vorerst unübersetzt bleiben dürfen
|
||||
|
||||
Besonders kritisch:
|
||||
|
||||
- [AppSectionBar.vue](/mnt/share/torsten/Programs/YourPart3/frontend/src/components/AppSectionBar.vue)
|
||||
- Views mit hero-texten und Buttons
|
||||
- direkte Dialogtitel
|
||||
- direkte Success-/Error-Meldungen in JS-Dateien
|
||||
|
||||
Empfehlung:
|
||||
|
||||
- zuerst Audit-Backlog erzeugen
|
||||
- dann Bereich für Bereich in i18n ziehen
|
||||
|
||||
## 10. Übersetzungsworkflow
|
||||
|
||||
### 10.1 Empfohlener Ablauf pro Datei
|
||||
|
||||
1. deutsche Quelldatei nehmen
|
||||
2. Schlüsselstruktur unverändert lassen
|
||||
3. Bisaya-Datei anlegen
|
||||
4. problematische Begriffe mit Glossar abgleichen
|
||||
5. UI-Stichprobe im echten Produkt machen
|
||||
|
||||
### 10.2 Qualitätssicherung
|
||||
|
||||
Jede größere Datei braucht:
|
||||
|
||||
- formale Prüfung: alle Keys vorhanden
|
||||
- Produktprüfung: Text passt im Layout
|
||||
- Sprachprüfung: natürliches Bisaya
|
||||
- Kontextprüfung: Button- und Fehlermeldungstexte klingen im UI sinnvoll
|
||||
|
||||
### 10.3 Platzhalter und Variablen
|
||||
|
||||
Besondere Aufmerksamkeit für:
|
||||
|
||||
- `{count}`
|
||||
- `{minutes}`
|
||||
- `{title}`
|
||||
- `{name}`
|
||||
- plural-/choice-nahe Muster
|
||||
|
||||
Bisaya-Übersetzungen müssen Variablen und Platzhalter exakt beibehalten.
|
||||
|
||||
## 11. Inhaltliche Risiken
|
||||
|
||||
### 11.1 Falukant
|
||||
|
||||
Falukant hat viele produktinterne Begriffe.
|
||||
|
||||
Risiko:
|
||||
|
||||
- zu direkte Übersetzung zerstört die interne Fachsprache
|
||||
|
||||
Empfehlung:
|
||||
|
||||
- einige Begriffe bewusst nicht übersetzen
|
||||
- stattdessen mit konsistenten Lehnformen arbeiten
|
||||
|
||||
### 11.2 Sprachkurs-Bereich
|
||||
|
||||
Risiko:
|
||||
|
||||
- UI wird lokalisiert, Lerninhalt aber versehentlich mitübersetzt, obwohl er als Kursmaterial bestehen bleiben soll
|
||||
|
||||
Empfehlung:
|
||||
|
||||
- klare Trennung zwischen:
|
||||
- UI-Text
|
||||
- Kursinhalt
|
||||
- Vokabel-/Satzmaterial
|
||||
|
||||
### 11.3 Mischnutzung Deutsch/Bisaya
|
||||
|
||||
Viele Nutzer könnten Deutsch lernen und gleichzeitig die Website in Bisaya benutzen.
|
||||
|
||||
Das ist erlaubt, aber nur wenn:
|
||||
|
||||
- UI-Lokalisierung stabil ist
|
||||
- Kursinhalt nicht durcheinandergerät
|
||||
|
||||
## 12. Priorisierte Umsetzung
|
||||
|
||||
Empfohlene Reihenfolge:
|
||||
|
||||
1. `ceb` technisch einführen
|
||||
2. Sprachumschalter erweitern
|
||||
3. `general/header/navigation/message/error`
|
||||
4. hartcodierte Shell-Texte bereinigen
|
||||
5. `settings/home/register/passwordReset`
|
||||
6. `socialnetwork/friends`
|
||||
7. Vokabeltrainer- und Kurs-UI
|
||||
8. Chat/Blog/Minigames
|
||||
9. Falukant
|
||||
10. Admin-Bereich optional zuletzt
|
||||
|
||||
## 13. Definition von "fertig"
|
||||
|
||||
Die Bisaya-Weblokalisierung ist erst dann wirklich fertig, wenn:
|
||||
|
||||
- `ceb` als Sprache global auswählbar ist
|
||||
- Hauptnavigation und Standardsystemtexte lokalisiert sind
|
||||
- zentrale Nutzerflüsse ohne Deutsch funktionieren
|
||||
- Sprachkurs-UI sauber lokalisiert ist
|
||||
- Falukant und Spezialmodule zumindest konsistent oder bewusst ausgeklammert sind
|
||||
- fehlende Keys systematisch kontrolliert werden
|
||||
|
||||
## 14. Konkrete nächste technische Phase
|
||||
|
||||
Die sinnvolle erste echte Bauphase ist:
|
||||
|
||||
### Phase 1
|
||||
|
||||
- `frontend/src/i18n/locales/ceb/` anlegen
|
||||
- `index.js` für `ceb` erweitern
|
||||
- `SettingsWidget.vue` Sprachwahl erweitern
|
||||
- `AppSectionBar.vue` und vergleichbare Shell-Komponenten in i18n ziehen
|
||||
- `general/header/navigation/message/error` auf Bisaya anlegen
|
||||
|
||||
Erst danach lohnt es sich, größere Produktbereiche wie Socialnetwork oder Falukant vollständig zu übersetzen.
|
||||
|
||||
## 15. Ergebnis
|
||||
|
||||
Die Website in Bisaya zu lokalisieren ist machbar und passt gut zur bestehenden Struktur, aber nur, wenn wir es als echtes Produktprojekt behandeln.
|
||||
|
||||
Die richtige Reihenfolge ist:
|
||||
|
||||
- erst technische Sprachbasis
|
||||
- dann Shell und Kernpfade
|
||||
- dann die großen Module
|
||||
- parallel dazu Audit und Bereinigung harter Strings
|
||||
|
||||
So entsteht keine halbfertige vierte Sprache, sondern eine wirklich benutzbare Bisaya-Oberfläche.
|
||||
Reference in New Issue
Block a user