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](/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.