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.

BucketInhaltDokumentiertes Ausgabemodell
json, json5, jsoncStrukturierte JSON-VariantenEigene Datei pro Sprache
json-dictionaryJSON-Werte mit Objekten, deren Schlüssel Sprachen sindGemeinsame Datei
yamlYAML-KatalogEigene Datei pro Sprache
yaml-root-keyYAML unter dem Wurzelschlüssel der AusgabespracheEigene Datei pro Sprache
markdown, mdx, markdocDokumente der Markdown-FamilieEigene Datei pro Sprache
html, mjmlHTML- und E-Mail-MarkupEigene Datei pro Sprache
androidAndroid-XML-RessourcenEigene Datei pro Sprache
xcode-strings, xcode-stringsdictApple-Strings- und PluralressourcenEigene Datei pro Sprache
xcode-xcstringsXcode-String-KatalogGemeinsame Datei
flutterARB-KatalogEigene Datei pro Sprache
poGettext-POEigene Datei pro Sprache
propertiesJava-PropertiesEigene Datei pro Sprache
csvMehrsprachige CSVGemeinsame Datei
csv-per-localeEine CSV pro SpracheEigene Datei pro Sprache
xml, xliffXML und XLIFFEigene Datei pro Sprache
srt, vttUntertitelEigene Datei pro Sprache
phpPHP-LokalisierungsarraysEigene Datei pro Sprache
typescriptTypeScript-LokalisierungsinhalteEigene Datei pro Sprache
vue-jsonVue-i18n-JSON-Blöcke mit Sprachen als SchlüsselnGemeinsame Datei
txtReiner TextEigene 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:

json
{
  "buckets": {
    "json": { "include": ["src/locales/[locale].json"] }
  }
}

Für einen gemeinsamen Xcode-Katalog neben sprachspezifischen Android-Ressourcen:

json
{
  "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:

json
{
  "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.