Formats

Le CLI traduit dix-huit formats de fichier. Le format est déduit de l’extension du fichier ; définissez format sur une entrée files[] pour le remplacer, ou pour les trois formats qui l’exigent toujours (yaml-openapi, yaml-root-key, android).

npx degit lingodotdev/lingo.dev/demo/new-cli my-lingo-demo
cd my-lingo-demo

JSON et JSONC#

Traduction clé/valeur simple. Chaque valeur de chaîne est traduite, sauf si un contrôle de clé indique le contraire.

{ "pattern": "content/en/app.json", "lockedKeys": ["meta.version"] }

JSONC conserve aussi les commentaires, que le moteur interprète comme du contexte — voir les notes pour les traducteurs.

{ "pattern": "content/en/settings.jsonc", "preservedKeys": ["featureFlags"] }

Markdown, MDX et Markdoc#

Le texte principal est traduit par défaut. Le frontmatter et les composants embarqués ne sont pas traduits, sauf si vous activez cette option.

Frontmatter#

Listez les champs de frontmatter à traduire avec translateFrontmatterFields :

{
  "pattern": "content/en/guide.md",
  "translateFrontmatterFields": ["title", "description"]
}

Props des composants MDX#

Avec MDX, traduisez des props précises sur des composants précis via translateComponentProps :

{
  "pattern": "content/en/landing.mdx",
  "translateFrontmatterFields": ["title"],
  "translateComponentProps": [{ "component": ["Hero", "Callout"], "props": ["title", "body"] }]
}

Cela traduit les props title et body sur <Hero> et <Callout>, et laisse toutes les autres props intactes.

Markdoc#

Markdoc fonctionne comme Markdown, avec frontmatter et attributs de balise préservés :

{
  "pattern": "content/en/changelog.mdoc",
  "translateFrontmatterFields": ["title"]
}

YAML#

Le YAML générique est détecté automatiquement à partir de .yaml/.yml — chaque valeur de chaîne est traduite, tandis que les clés et la structure sont préservées :

{ "pattern": "content/en/strings.yaml" }

Les spécifications OpenAPI sont un cas à part : elles partagent l’extension .yaml, mais nécessitent un format explicite pour que le moteur ne traduise que les champs visibles par les utilisateurs (résumés, descriptions) et laisse intacts les clés de schéma, les chemins et les ID d’opération :

{ "pattern": "content/en/api.yaml", "format": "yaml-openapi" }

Les fichiers de langue au format Rails constituent l’autre cas particulier : la langue correspond à la clé racine YAML (en:) et le fichier cible doit avoir pour racine la langue cible (es:). Définissez également format explicitement pour ces fichiers :

{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" }

Formats d’application et de framework#

PO, Flutter ARB, .strings Xcode, .stringsdict Xcode, les modules de langue TypeScript, XLIFF, SubRip et PHP suivent tous la même règle : le texte traduisible est traduit, tout le reste est préservé (clés, ID, métadonnées, placeholders, timecodes, code, mise en forme). Chacun est détecté automatiquement à partir de son extension — il suffit de pointer un motif vers le fichier source :

{ "pattern": "lib/l10n/app_en.arb" }
{ "pattern": "locales/en.po" }
{ "pattern": "Localizable.strings" }
{ "pattern": "l10n/en.xlf" }

L’un d’eux nécessite un format explicite, car son extension est trop ambiguë pour être détectée automatiquement :

{ "pattern": "res/values/strings.xml", "format": "android" }

Catalogues de chaînes Xcode#

Un fichier .xcstrings (String Catalog) regroupe toutes les langues dans un seul fichier. Il n’existe pas de chemin de sortie par langue — le CLI lit la langue source et réécrit chaque cible dans ce même fichier :

{ "pattern": "Localizable.xcstrings" }

Les chaînes marquées "shouldTranslate": false dans le catalogue sont ignorées : le CLI les laisse non traduites et telles quelles.

Chemins de sortie#

Le motif désigne votre fichier source ; tous les chemins cibles en découlent. Quatre règles s’appliquent, dans cet ordre :

1. Un segment de chemin entier ou un nom de fichier correspondant à la langue — c’est le cas le plus courant. content/en/app.json → content/de/app.json, locales/en.json → locales/de.json.
2. Une langue en fin de segment ou de nom de fichier, pour les structures qui la notent ainsi — Android, Xcode .strings/.stringsdict, Flutter et yaml-root-key. res/values-en/ → res/values-de/, app_en.arb → app_de.arb, devise.en.yml → devise.de.yml.
3. Le nom réservé d’une plateforme pour la langue par défaut, sans aucune langue dans le chemin. Le simple res/values/ d’Android devient res/values-de/, et le Base.lproj de Xcode devient de.lproj.
4. Le String Catalog, où le chemin cible est le chemin source, puisqu’un seul fichier contient toutes les langues.

Android est la seule plateforme dont les chemins cibles ne suivent pas le format BCP 47 : le CLI écrit le qualificateur de ressource qu’Android lit réellement ; ainsi, pt-BR se retrouve dans values-pt-rBR/ et zh-Hans dans values-b+zh+Hans/.

Si aucune de ces règles ne s’applique — la langue source n’apparaît nulle part dans le chemin — le CLI se rabat sur un répertoire <locale>/ créé à côté du fichier, et lingo push vous signale qu’il a dû le déduire. Prenez cet avertissement comme le signe que le motif est incorrect. Voir Configuration.

Vous venez du CLI historique ?#

La plupart des formats du CLI historique sont désormais disponibles dans le CLI actuel (PO, XLIFF, chaînes Android/Xcode, Flutter ARB, et plus encore — voir le tableau ci-dessus). Quelques formats moins courants (par ex. CSV, HTML, MJML, .properties) ne sont pas encore pris en charge ; en attendant que le vôtre arrive, la documentation du CLI historique les couvre.