Buckets

Configuration des buckets dans Lingo.dev CLI

Introduction

Dans le fichier i18n.json, la propriété buckets définit :

  • les analyseurs utilisés pour extraire le contenu localisable des fichiers
  • où se trouve le contenu localisable dans le système de fichiers
  • certaines fonctionnalités spécifiques aux buckets, comme le verrouillage de clés

La configuration des buckets est une étape essentielle dans la mise en place d'un pipeline de traduction avec Lingo.dev CLI.

Types de buckets

Lingo.dev CLI est compatible avec une large gamme de formats de fichiers standards de l'industrie (et certains moins standards). Chacun de ces formats est associé à un type spécifique de bucket.

Les types de buckets sont généralement synonymes de formats de fichiers, mais ce n'est pas toujours une correspondance directe. Par exemple, les buckets "json" et "json-dictionary" gèrent tous deux le contenu localisable dans des fichiers JSON, mais le CLI s'attend à ce que les fichiers soient structurés différemment, donc les buckets sont distincts.

Mode de sortie

Lors de la localisation du contenu, certains buckets modifient le fichier où existe le contenu source tandis que d'autres buckets créent des fichiers séparés pour chaque locale cible.

La raison de cette différence de comportement est que l'une ou l'autre option est la plus logique selon le bucket. Il n'existe pas d'option unique et correcte qui pourrait fonctionner pour tous les types de buckets.

Par exemple, lors de l'utilisation du bucket CSV, les fichiers .csv sont modifiés directement. C'est parce qu'il est typique pour les fichiers CSV de stocker du contenu localisé pour chaque locale dans le même fichier, dans des colonnes séparées :

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

En revanche, lors de l'utilisation du bucket Markdown, le contenu localisé est généré dans des fichiers séparés car il n'est pas courant de stocker toutes les variations localisées dans un seul fichier.

Il est important de comprendre cela pour plusieurs raisons :

  • Il n'est pas immédiatement évident que différents buckets se comportent de différentes manières.
  • Vous devez définir les modèles include et exclude différemment selon la façon dont les fichiers sont générés.

Création de buckets

Pour créer un bucket, ajoutez une entrée à l'objet buckets dans le fichier i18n.json :

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

Chaque clé doit correspondre à l'un des types de buckets pris en charge, tandis que la valeur doit être un objet contenant une configuration valide pour ce bucket.

La propriété buckets doit avoir au moins une entrée valide.

Inclusion de fichiers

Au minimum, les buckets doivent avoir une propriété include qui définit le contenu à localiser :

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

Cette propriété doit être un tableau de chaînes de caractères.

Chaque chaîne peut être l'un des éléments suivants :

  • chemin de fichier (par exemple, "some/dir/labels.json")
  • modèle glob (par exemple, "some/dir/*.json")

Ces valeurs sont toujours relatives au fichier i18n.json.

Placeholder [locale]

Lorsqu'un bucket génère du contenu localisé dans des fichiers séparés (c'est-à-dire qu'il ne modifie pas un fichier existant), les modèles include doivent contenir un placeholder spécial [locale] :

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

Ce placeholder est remplacé à l'exécution et affecte où la CLI :

  • recherche le contenu source
  • génère le contenu localisé

Par exemple, si la locale source est "en" et la locale cible est "es", alors [locale]/*.mdx trouve tous les fichiers MDX dans le répertoire en/ et génère des fichiers localisés dans le répertoire es/.

La position du placeholder [locale] n'est pas importante, ce qui signifie que tous ces modèles sont valides :

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

Modèles glob récursifs

Lingo.dev CLI ne prend pas en charge les modèles glob récursifs. Cela signifie que les modèles comme "**/*.json" ne fonctionnent pas. Si vous essayez de configurer un modèle glob récursif, une erreur sera générée.

Extensions de fichiers

Dans les modèles include, les extensions de fichiers n'ont pas d'importance. Lingo.dev CLI tentera d'analyser tous les fichiers spécifiés en fonction du type de bucket, quelle que soit l'extension.

Exclusion de fichiers

En plus des modèles include, les buckets prennent également en charge les modèles exclude pour exclure des chemins de fichiers ou des modèles glob de la localisation :

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

Ces modèles suivent les mêmes règles que les modèles include.

Fonctionnalités spécifiques aux buckets

Certains buckets disposent de fonctionnalités que d'autres n'ont pas. C'est généralement parce que ces fonctionnalités n'ont de sens logique que dans le contexte de ces buckets.

Les fonctionnalités spécifiques aux buckets comprennent :

Pour en savoir plus sur ces fonctionnalités, consultez la documentation liée.