Buckets

Konfiguration von Buckets in der Lingo.dev CLI

Einführung

In der Datei i18n.json definiert die Eigenschaft buckets:

  • die Parser, die verwendet werden, um lokalisierbaren Inhalt aus Dateien zu extrahieren
  • wo lokalisierbarer Inhalt im Dateisystem existiert
  • bestimmte bucket-spezifische Funktionen, wie z.B. Key Locking

Die Konfiguration von Buckets ist ein wesentlicher Schritt bei der Einrichtung einer Übersetzungspipeline mit der Lingo.dev CLI.

Bucket-Typen

Die Lingo.dev CLI ist mit einer breiten Palette von Industriestandard-Dateiformaten (und einigen weniger standardisierten) kompatibel. Jedes dieser Formate ist mit einem spezifischen Bucket-Typ verknüpft.

Bucket-Typen sind im Allgemeinen synonym mit Dateiformaten, aber es handelt sich nicht immer um eine 1:1-Zuordnung. Zum Beispiel verarbeiten sowohl die Buckets "json" als auch "json-dictionary" lokalisierbaren Inhalt in JSON-Dateien, aber die CLI erwartet, dass die Dateien unterschiedlich strukturiert sind, daher sind die Buckets unterschiedlich.

Ausgabemodus

Bei der Lokalisierung von Inhalten verändern einige Buckets die Datei, in der der Quellinhalt existiert, während andere Buckets separate Dateien für jede Zielsprache erstellen.

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

Beim Verwenden des CSV-Buckets werden beispielsweise .csv-Dateien direkt verändert. Dies liegt daran, dass es typisch für CSV-Dateien ist, lokalisierten Inhalt für jede Sprache in derselben Datei in separaten Spalten zu speichern:

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

Bei Verwendung des Markdown-Buckets hingegen wird der lokalisierte Inhalt 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 ersichtlich, dass verschiedene Buckets sich unterschiedlich verhalten.
  • Sie müssen die Muster include und exclude je nach Ausgabemethode der Dateien unterschiedlich definieren.

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 lokalisierte Inhalte 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
  • die lokalisierten Inhalte ausgibt

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

Die Position des [locale]-Platzhalters ist nicht wichtig, was bedeutet, dass all diese gültigen Muster sind:

  • 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 include-Mustern spielen die Dateierweiterungen keine Rolle. Die Lingo.dev CLI wird versuchen, alle angegebenen Dateien basierend auf dem Bucket-Typ zu analysieren, unabhängig von der Erweiterung.

Dateien ausschließen

Zusätzlich zu den include-Mustern unterstützen Buckets auch exclude-Muster, um Dateipfade oder Glob-Muster von der Lokalisierung auszuschließen:

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

Diese Muster folgen denselben Regeln wie die include-Muster.

Bucket-spezifische Funktionen

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

Zu den bucket-spezifischen Funktionen gehören:

Um mehr über diese Funktionen zu erfahren, siehe die verlinkte Dokumentation.