CLI-v0-Formate
Stimme einen installierten Legacy-Parser auf die Sprachstruktur seiner Dateien ab und validiere die rekonstruierte Datei im nativen Format.
Wähle den Bucket danach aus, welche Daten du extrahieren möchtest und welche Dateien du als Ergebnis erwartest. V0 bestimmt den Parser über den Bucket-Typ, nicht über die Dateiendung. Ein JSON-Katalog und ein mehrsprachiger Xcode-Katalog brauchen deshalb unterschiedliche Konfigurationen, auch wenn beide Meldungen enthalten.
Zuerst das Ausgabemodell wählen #
Die meisten Buckets schreiben pro Sprache eine eigene Datei und nutzen dafür [locale] im Pfad. CSV, Xcode-String-Kataloge, JSON-Wörterbücher und Vue-i18n-Blöcke können dagegen mehrere Sprachen in einer Datei bündeln. Sieh dir bei einer gemeinsamen Ausgabedatei nach der Übersetzung sowohl den Ziel- als auch den Quellabschnitt an.
| Bucket | Inhalt | Dokumentiertes Ausgabemodell |
|---|---|---|
json, json5, jsonc | Strukturierte JSON-Varianten | Eigene Datei pro Sprache |
json-dictionary | JSON-Werte mit Objekten, deren Schlüssel Sprachen sind | Gemeinsame Datei |
yaml | YAML-Katalog | Eigene Datei pro Sprache |
yaml-root-key | YAML unter dem Wurzelschlüssel der Ausgabesprache | Eigene Datei pro Sprache |
markdown, mdx, markdoc | Dokumente der Markdown-Familie | Eigene Datei pro Sprache |
html, mjml | HTML- und E-Mail-Markup | Eigene Datei pro Sprache |
android | Android-XML-Ressourcen | Eigene Datei pro Sprache |
xcode-strings, xcode-stringsdict | Apple-Strings- und Pluralressourcen | Eigene Datei pro Sprache |
xcode-xcstrings | Xcode-String-Katalog | Gemeinsame Datei |
flutter | ARB-Katalog | Eigene Datei pro Sprache |
po | Gettext-PO | Eigene Datei pro Sprache |
properties | Java-Properties | Eigene Datei pro Sprache |
csv | Mehrsprachige CSV | Gemeinsame Datei |
csv-per-locale | Eine CSV pro Sprache | Eigene Datei pro Sprache |
xml, xliff | XML und XLIFF | Eigene Datei pro Sprache |
srt, vtt | Untertitel | Eigene Datei pro Sprache |
php | PHP-Lokalisierungsarrays | Eigene Datei pro Sprache |
typescript | TypeScript-Lokalisierungsinhalte | Eigene Datei pro Sprache |
vue-json | Vue-i18n-JSON-Blöcke mit Sprachen als Schlüsseln | Gemeinsame Datei |
txt | Reiner Text | Eigene Datei pro Sprache |
Das hier ist die Legacy-Bucket-Familie – keine Kompatibilitätsliste für andere Tools. In früheren v0-Versionen fehlen womöglich einzelne Einträge. Die Parser für TypeScript, PHP und Vue verarbeiten die jeweils unterstützten Lokalisierungsstrukturen; dass es sie gibt, heißt nicht, dass beliebiger ausführbarer Quellcode umgeschrieben werden darf.
Der 0.138.10-Dispatcher enthält außerdem ail, ejs, twig, dato und xcode-xcstrings-v2. Behalte den Parser, den ein installiertes Projekt bereits nutzt, so lange bei, bis du dir seine Ein- und Ausgabe genau angesehen hast. Ein Schema-Enum allein genügt nicht: Das Legacy-Schema nennt zwar auch compiler, für diesen Dispatch-Pfad gibt es aber keinen passenden Loader.
yaml-root-key rekonstruiert nur den Wurzelknoten der ausgewählten Sprache. Lass Quelle und Ziel deshalb nicht auf dieselbe gemeinsame YAML-Datei zeigen – ein Schreibvorgang kann sonst ihre übrigen Wurzelknoten überschreiben. Nutze stattdessen einen sprachspezifischen Pfad wie locales/[locale].yml. Anders verhält es sich bei einem JSON-Wörterbuch oder Vue-Block, der eine neue Sprache ausdrücklich in die bestehende Struktur einfügt.
Eine repräsentative Datei konfigurieren #
Bei JSON legt dasselbe Muster eine Quelldatei und separate Zieldateien fest:
{
"buckets": {
"json": { "include": ["src/locales/[locale].json"] }
}
}Für einen gemeinsamen Xcode-Katalog neben sprachspezifischen Android-Ressourcen:
{
"buckets": {
"xcode-xcstrings": { "include": ["ios/Localizable.xcstrings"] },
"android": {
"include": ["android/app/src/main/res/values-[locale]/strings.xml"]
}
}
}Passe die Schreibweise der Android-Sprachkennungen und die Ressourcenverzeichnisse an deine Anwendung an. Validiere nach dem ersten Durchlauf beide nativen Formate mit den zugehörigen Build-Tools und stelle sicher, dass die Anwendung die gewählte Zielsprache lädt. Nur weil die Konfiguration akzeptiert wird, ist noch nicht belegt, dass der Pfad auch funktioniert.
Dateien finden, ohne generierte Ausgaben zu erfassen #
Pfade werden relativ zu i18n.json aufgelöst; * findet Treffer innerhalb einer Ebene. Rekursives ** gibt es seit 0.135.0. Standardmäßig ausgeschlossen sind node_modules, .git, dist, build, .next und .turbo. Weitere generierte Inhalte musst du ausdrücklich ausschließen:
{
"buckets": {
"markdown": {
"include": ["docs/[locale]/*.md"],
"exclude": ["docs/[locale]/drafts/*.md"]
}
}
}Entscheide dich bei mehreren Paketen für eine gemeinsame oder paketweise Konfiguration – je nachdem, welche Sprachen gebraucht werden und wer für die Lokalisierungs-Engine zuständig ist. Eng gefasste Pfade sorgen dafür, dass generierte Ausgaben nicht unbeabsichtigt als Quelle eingelesen werden.
Formatspezifische Schutzmechanismen kontrollieren #
Setze bei Schlüssel-Wert-Katalogen Steuerungsoptionen für Schlüssel danach ein, wer für den jeweiligen Wert zuständig ist. Kommentare in JSONC- und Xcode-Katalogen können Übersetzungshinweise transportieren. Frei strukturierte Dokumente und Untertitel nutzen diese Funktionen nicht unbedingt auf dieselbe Weise.
Sieh dir genau an, was der Parser rekonstruiert hat: Katalogschlüssel und -werte, Dokument-Markup und Links, Zeitmarken von Untertiteln oder native Ressourcenkennungen. Übernimm die Ausgabe erst, wenn der nachgelagerte Parser oder Build sie tatsächlich verarbeiten kann. Ziehe bei einer Migration das aktuelle Formathandbuch und die Liste der unterstützten Formate des aufrufenden Tools heran, statt davon auszugehen, dass diese Legacy-Matrix weiterhin gilt.