# Übersetzungen

Blockstudio liefert seine Übersetzungen im Ordner `languages` aus. WordPress verwendet sie, wenn die Website-Sprache oder die Sprache im Benutzerprofil einer davon entspricht. Das funktioniert genauso, wenn Blockstudio als Plugin, Must-use-Plugin oder Composer-Paket ausgeführt wird.

## Verfügbare Sprachen

Blockstudio enthält Übersetzungen für die WordPress in seinem gebündelten `languages/locales.json` aufgeführten Gebietsschemas, einschließlich regionaler sowie formeller und informeller Varianten. Englisch (`en_US`) ist die Ausgangssprache und benötigt keine Übersetzungsdatei. Die Liste vereint von WordPress unterstützte Gebietsschemas aus GlotPress mit Varianten, die in den Kernübersetzungen von WordPress verfügbar sind (API).

Die vorhandenen Übersetzungen für Deutsch (`de_DE`) und formelles Deutsch (`de_DE_formal`) bleiben erhalten. Die zusätzlichen Übersetzungen wurden mit GPT-6 Luna erzeugt und sind in ihren `.po`-Kopfzeilen als maschinell erstellt gekennzeichnet. Sie bestehen automatisierte Vollständigkeits- und Formatprüfungen, wurden aber nicht alle von Muttersprachlern geprüft. Korrekturen sind willkommen.

Die Übersetzungen decken die Feld-Steuerelemente im Block-Editor, die Admin-Seite, die Arbeitsfläche, die Devtools-Überlagerung und die Meldungen der REST-Endpunkte ab. Bezeichnungen und Hilfetexte in deinen eigenen `block.json`-Dateien gehören zu deinem Theme oder Plugin und verwenden dessen Textdomain.

Wähle die Sprache unter **Einstellungen > Allgemein > Website-Sprache** aus oder lege in deinem WordPress-Profil eine persönliche Sprache fest. Blockstudio verwendet dieses Gebietsschema automatisch. Es fügt dem WordPress-Sprachauswahlmenü keine Sprachen hinzu: Ein Gebietsschema muss auch in deiner WordPress-Installation verfügbar sein. Auf deiner Website sind weder eine KI-Anfrage noch ein Übersetzungsabo oder eine zusätzliche Laufzeiteinstellung erforderlich.

## Eine Übersetzung überschreiben

Übersetzungsdateien in `wp-content/languages/plugins` haben Vorrang vor den gebündelten Dateien, sowohl für die PHP-Strings (`blockstudio-de_DE.mo` oder `blockstudio-de_DE.l10n.php`) als auch für Skripte (eine Datei pro Skript-Handle, zum Beispiel `blockstudio-de_DE-blockstudio-blocks.json`).

## Zu einer Übersetzung beitragen

Jede Sprache liegt als `.po`-Datei vor, die du mit einem beliebigen Texteditor oder einem Übersetzungswerkzeug wie Poedit bearbeiten kannst. Korrekturen und neue Sprachen sind als Pull Requests willkommen.

1. Um eine Sprache hinzuzufügen, kopiere `languages/blockstudio.pot` nach `languages/blockstudio-<locale>.po`, zum Beispiel `blockstudio-fr_FR.po`, und setze die Kopfzeilen `Language` und `Plural-Forms`. Um eine Sprache zu verbessern, bearbeite ihre vorhandene `.po`-Datei.
2. Übersetze die Strings. Behalte Platzhalter wie `%1$s` in der Übersetzung bei.
3. Führe `npm run i18n` aus. Der Befehl erstellt die Dateien `.mo`, `.l10n.php` und `.json`, die WordPress lädt.
4. Übernimm die Datei `.po` zusammen mit den generierten Dateien in einen Commit und erstelle einen Pull Request.

Wenn du `npm` nicht ausführen kannst, genügt ein Pull Request, der nur die Datei `.po` enthält. Die generierten Dateien können vor dem Merge hinzugefügt werden.

## Fehlende Übersetzungen generieren

Maintainer können fehlende Einträge mit einem authentifizierten Codex CLI generieren. Dies ist ein optionaler Entwicklungsbefehl, den WordPress nicht ausführt:

```bash
npm run i18n:translate -- --dry-run
npm run i18n:translate
```

Das Standardmodell ist `gpt-6-luna`. Um an einem Gebietsschema zu arbeiten, verwende `npm run i18n:translate -- --locale fr_FR`. Der Befehl extrahiert die neuesten Ausgangs-Strings, ergänzt fehlende Übersetzungen und kompiliert anschließend `.mo`-, `.l10n.php`- und skriptspezifische `.json`-Dateien. An Codex werden nur öffentliche Interface-Strings, ihr Kontext und vorhandene Formen gesendet, keine Website-Inhalte oder Benutzerdaten.

Vorhandene, nicht leere Übersetzungen werden nie ersetzt. Abgeschlossene Stapel werden gespeichert, damit ein erneuter Lauf nach einer Unterbrechung die fehlende Arbeit fortsetzt. Platzhalter wie `%1$s`, HTML-Markup, technische Bezeichner und die erforderlichen Pluralformen werden vor dem Speichern geprüft. Unsichere Einträge und geänderte Quell-Mehrzahlformen bleiben zur Prüfung durch Übersetzer offen. Wenn das angeforderte Modell nicht verfügbar ist, wird kein Ersatzmodell verwendet.

`npm run i18n:locales` aktualisiert die Gebietsschema-Liste und Pluralregeln ausdrücklich aus WordPress/GlotPress. `npm run i18n:coverage` prüft, ob jedes Gebietsschema in der eingecheckten Liste vollständig ist. Weder Abdeckungsprüfungen noch die normale CI rufen KI auf oder laden Gebietsschema-Daten ab. Im Repository-README findest du Optionen für Stapelverarbeitung, Parallelität und Wiederherstellung.

## Übersetzbare Strings im Code

- PHP: Verwende die Funktionen WordPress mit der Textdomäne `blockstudio`, zum Beispiel `__( 'Invalid block.', 'blockstudio' )`.
- JavaScript: Importiere `__` aus `@/utils/__` und übergib eine Zeichenfolge direkt, zum Beispiel `__( 'Add row' )`. Eine Zeichenfolge, die zur Laufzeit zusammengesetzt wird, kann nicht übersetzt werden. Verwende daher für jede Variante eine einzelne Zeichenfolge.
- Ein neues Skript-Bundle mit übersetzbaren Zeichenfolgen braucht einen Eintrag in `scripts/i18n.ts` und einen Aufruf von `wp_set_script_translations()` mit demselben Handle und `Translations::script_path()`.

Führe nach Änderungen an Zeichenfolgen `npm run i18n` aus. Dadurch werden `languages/blockstudio.pot` und alle Dateien vom Typ `.po` aktualisiert. Neue Zeichenfolgen bleiben auf Englisch, bis ein Übersetzer oder `npm run i18n:translate` sie ergänzt. CI führt `npm run i18n:check` und `npm run i18n:coverage` aus. Damit werden veraltete kompilierte Dateien, Extraktionsprobleme oder eine unvollständige Sprachabdeckung abgelehnt. Die Generierung bleibt eine explizite Maintainer-Aktion.