Buckets

Konfiguration von Buckets in Lingo.dev CLI

Einführung

In der i18n.json-Datei definiert die buckets-Eigenschaft:

  • die Parser, die zum Extrahieren von lokalisierbarem Content aus Dateien verwendet werden
  • wo lokalisierbarer Content im Dateisystem existiert
  • bestimmte bucket-spezifische Funktionen, wie z. B. Key Locking

Die Konfiguration von Buckets ist ein wesentlicher Schritt beim Einrichten einer Übersetzungs-Pipeline mit Lingo.dev CLI.

Bucket-Typen

Lingo.dev CLI ist mit einer Vielzahl von branchenüblichen Dateiformaten (und einigen weniger standardisierten) kompatibel. Jedes dieser Formate ist mit einem bestimmten Bucket-Typ verknüpft.

Bucket-Typen sind im Allgemeinen synonym mit Dateiformaten, aber es handelt sich nicht immer um eine Eins-zu-eins-Zuordnung. Beispielsweise verarbeiten die "json"- und "json-dictionary"-Buckets beide lokalisierbaren Content in JSON-Dateien, aber die CLI erwartet, dass die Dateien unterschiedlich strukturiert sind, sodass die Buckets unterschiedlich sind.

Output-Modus

Beim Lokalisieren von Content mutieren einige Buckets die Datei, in der der Quell-Content existiert, während andere Buckets separate Dateien für jede Ziel-Locale erstellen.

Der Grund für diesen Unterschied im Verhalten liegt darin, dass je nach Bucket die eine oder andere Option am sinnvollsten ist. Es gibt keine einzelne, korrekte Option, die für alle Bucket-Typen funktionieren könnte.

Beispielsweise werden beim Verwenden des CSV-Buckets .csv-Dateien direkt mutiert. Dies liegt daran, dass es typisch für CSV-Dateien ist, lokalisierten Content für jede Locale in derselben Datei in separaten Spalten zu speichern:

KEY,en,es
welcome_message,Welcome to our application,Bienvenido a nuestra aplicación

Beim Verwenden des Markdown-Buckets hingegen wird der lokalisierte Content in separate Dateien ausgegeben, da es nicht üblich ist, alle lokalisierten Varianten in einer einzigen Datei zu speichern.

Dies ist aus mehreren Gründen wichtig zu verstehen:

  • Es ist nicht sofort offensichtlich, dass sich verschiedene Buckets unterschiedlich verhalten.
  • Sie müssen die include und exclude Muster unterschiedlich definieren, je nachdem, wie Dateien ausgegeben werden.

Buckets erstellen

Um einen Bucket zu erstellen, fügen Sie einen Eintrag zum buckets Objekt in der i18n.json Datei hinzu:

{
  "buckets": {
    "json": {}
  }
}

Jeder Schlüssel muss einem der unterstützten Bucket-Typen entsprechen, während der Wert ein Objekt sein muss, das eine gültige Konfiguration für diesen Bucket enthält.

Die buckets Eigenschaft muss mindestens einen gültigen Eintrag haben.

Dateien einbeziehen

Buckets müssen mindestens eine include Eigenschaft haben, die den zu lokalisierenden Inhalt definiert:

{
  "buckets": {
    "json": {
      "include": []
    }
  }
}

Diese Eigenschaft muss ein Array von Strings sein.

Jeder String kann eines der folgenden sein:

  • Dateipfad (z. B. "some/dir/labels.json")
  • Glob-Muster (z. B. "some/dir/*.json")

Diese Werte sind immer relativ zur i18n.json Datei.

[locale] Platzhalter

Wenn ein Bucket lokalisierten Inhalt in separate Dateien ausgibt (d. h. er verändert keine bestehende Datei), müssen die include Muster einen speziellen [locale] Platzhalter enthalten:

{
  "buckets": {
    "json": {
      "include": ["[locale]/*.mdx"]
    }
  }
}

Dieser Platzhalter wird zur Laufzeit ersetzt und beeinflusst, wo die CLI:

  • nach dem Quellinhalt sucht
  • den lokalisierten Inhalt ausgibt

Wenn beispielsweise die Quellsprache "en" und die Zielsprache "es" ist, dann findet [locale]/*.mdx alle MDX-Dateien im en/ Verzeichnis und gibt lokalisierte Dateien in das es/ Verzeichnis aus.

Die Position des [locale] Platzhalters ist nicht wichtig, das heißt, alle diese Muster sind gültig:

  • content/[locale]/*.mdx
  • [locale]/*.mdx
  • *.[locale].mdx

Rekursive Glob-Muster

Lingo.dev CLI unterstützt keine rekursiven Glob-Muster. Das bedeutet, dass Muster wie "**/*.json" nicht funktionieren. Wenn Sie versuchen, ein rekursives Glob-Muster zu konfigurieren, wird ein Fehler ausgegeben.

Dateierweiterungen

In den includeMustern spielen die Dateierweiterungen keine Rolle. Lingo.dev CLI versucht, die angegebenen Dateien basierend auf dem Bucket-Typ zu parsen, unabhängig von der Erweiterung.

Dateien ausschließen

Zusätzlich zu includeMustern unterstützen Buckets auch excludeMuster zum Ausschließen von Dateipfaden oder Glob-Mustern von der Lokalisierung:

{
  "buckets": {
    "json": {
      "include": ["[locale]/*.mdx"],
      "exclude": ["[locale]/ignored/*.mdx"],
    }
  }
}

Diese Muster folgen denselben Regeln wie die includeMuster.

Bucket-spezifische Funktionen

Einige Buckets verfügen über bestimmte Funktionen, die andere nicht haben. Dies liegt in der Regel daran, dass die Funktionen nur im Kontext dieser Buckets logisch sinnvoll sind.

Zu den bucket-spezifischen Funktionen gehören:

Weitere Informationen zu diesen Funktionen finden Sie in der verlinkten Dokumentation.