yourpart3/docs/BISAYA_SITE_LOCALIZATION_IMPLEMENTATION_SPEC.md

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 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
• 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:

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
• 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:

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:

• 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:

• 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

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
• 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.