Configuration de la CLI

Définissez les règles de détection des sources, les options de traduction et les chemins cibles dans .lingo/config.json.

.lingo/config.json décrit les fichiers à traduire dans un projet et l’emplacement de leurs fichiers cibles. La CLI remonte depuis le répertoire de travail pour trouver la configuration la plus proche, puis résout les chemins relatifs au projet à partir de cette racine. Les commandes locales de catalogue utilisent cwd lorsqu’aucune configuration n’existe.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "locales/en.json" }]
}

Exécutez link pour ajouter les identifiants de l’organisation et du moteur de localisation nécessaires à la traduction à distance. L’extraction peut utiliser les paramètres i18n localement, sans ces identifiants. Utilisez du JSON strict : les commentaires et les virgules finales ne sont pas acceptés ici.

Champs à la racine #

ChampSignification
orgId, engineIdIdentifiants de ressources non vides ; ils définissent ensemble la liaison distante.
sourceLocaleChaîne non vide indiquant la langue source.
targetLocalesEntrées sous forme de chaînes non vides ; à l’exécution, les doublons et l’entrée correspondant exactement à la langue source sont supprimés.
filesEntrées source décrites ci-dessous.
i18n.messagesPathRépertoire du catalogue pour l’extraction, la vérification et le nettoyage ; valeur par défaut : locales.
i18n.typesPathChemin des déclarations pour l’extraction et la vérification ; valeur par défaut : lingo.d.ts.
github.workflows.onPushToDefaultBranch.enabledDéclencheur d’intégration facultatif pour la branche par défaut.
github.workflows.onPullRequest.enabledDéclencheur d’intégration facultatif pour les demandes de fusion.
github.safety.requireApprovalParamètre facultatif d’approbation des exécutions de l’intégration.

Les clés inconnues à la racine ou dans les entrées de fichiers génèrent un avertissement et sont ignorées. Une faute de frappe peut donc laisser la valeur par défaut s’appliquer, sans entraîner le rejet du fichier entier.

Init écrit les paramètres de localisation ; link écrit les identifiants de liaison ; unlink supprime uniquement ces identifiants. Ces opérations préservent les autres sections à la racine, mais init --force reconstruit les entrées de fichiers, ce qui fait perdre les options avancées. Les paramètres GitHub n’installent pas la GitHub App et ne font pas non plus d’un push de la CLI un déclencheur d’automatisation du dépôt ; utilisez la configuration de l’intégration.

Champs des entrées de fichiers #

ChampSignification
patternUn motif source non vide.
includeMotifs source ; cette liste prime sur pattern, même lorsqu’elle est vide.
excludeMotifs exclus de cette entrée.
formatFormat défini explicitement parmi les formats pris en charge ci-dessous.
localeFormatReprésentation du chemin : bcp47, underscore ou android.
targetPath, sourceRootModèle de sortie et préfixe facultatif à supprimer pour [path].
translateFrontmatterFieldsChamps de métadonnées sélectionnés par les gestionnaires des formats de la famille Markdown.
translateComponentPropsNoms de propriétés ou règles de sélection des propriétés avec filtre par composant.
lockedKeys, preservedKeys, ignoredKeysTableaux non vides de chemins de clés pour les gestionnaires qui les prennent en charge.
injectLocaleBooléen ou { "enabled": true, "key": "language" }.
keyColumnCSV uniquement : en-tête de la colonne des clés ; la première cellule d’en-tête est utilisée par défaut.
lockedPatternsPropriétés uniquement : les expressions régulières RE2 présentes dans les valeurs ne sont pas traduites.

Chaque entrée doit comporter pattern ou include ; un include vide ne sélectionne rien. La première entrée correspondante détermine les options utilisées. Contrôles des clés explique à qui appartiennent les valeurs et où se situent les limites des formats.

Motifs de fichiers #

La recherche de correspondances prend en charge * au sein d’un segment et **/ sur plusieurs niveaux de répertoires. Utilisez docs/en/**/* pour parcourir récursivement un sous-arbre ; un simple ** final n’a pas le même sens. Ne supposez pas que les accolades ou les motifs extglob se comportent comme dans une autre bibliothèque de motifs glob.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "files": [
    {
      "include": ["docs/en/**/*.md", "docs/en/**/*.mdx"],
      "exclude": ["docs/en/private/**/*"]
    }
  ]
}

Une exclusion ne s’applique qu’à son entrée ; une autre entrée peut toujours inclure le fichier. La détection ignore .git et node_modules, mais pas tout le contenu de .gitignore. Les motifs passés comme arguments positionnels à push restreignent davantage les sources configurées par intersection et modifient le mode de planification. Placez-les entre guillemets dans l’interpréteur de commandes.

Sélection du format #

Les formats configurés sont json, jsonc, md, mdx, markdoc, yaml-openapi, po, flutter, xcode-strings, yaml, android, typescript, xcode-xcstrings, srt, xliff, xcode-stringsdict, php, yaml-root-key, html, txt, csv et properties.

SuffixeFormat déduit
.json, .jsoncJSON ou JSONC.
.md, .mdx, .mdocMarkdown, MDX, Markdoc.
.html, .htmHTML.
.po, .arbGettext, Flutter.
.strings, .xcstrings, .stringsdictFormat Apple correspondant.
.ts, .mts, .ctsTypeScript.
.srt, .xlf, .xliff, .phpSubRip, XLIFF, PHP.
.txtTexte brut, uniquement si le motif se termine par .txt ou si le format txt est défini.
.csvCSV, uniquement si le motif se termine par .csv ou si le format csv est défini.
.propertiesPropriétés Java, uniquement pour un motif se terminant par le format .properties ou properties.
.yaml, .ymlDéfinissez explicitement yaml, yaml-root-key ou le format OpenAPI basé sur yaml.
.xmlDéfinissez explicitement android ; le XML générique n’est pas pris en charge.

Pour OpenAPI, l’identifiant exact est yaml-openapi. Même lorsqu’un format est sélectionné explicitement, la liste des suffixes pris en charge par la détection reste applicable. Un fichier .txt, .csv ou .properties ne peut être associé qu’à une entrée dont le motif se termine par cette extension ou qui spécifie le format correspondant, txt, csv ou properties. Cette entrée ne sélectionne que les fichiers portant cette extension. Les fichiers .js, .tsx, .pot, MJML et VTT ne sont pas configurés comme fichiers d’entrée de la CLI. L’extraction React TSX est une opération distincte.

La traduction HTML remplace le texte et les attributs sélectionnés directement dans la source d’origine, tout en préservant le balisage intact, les commentaires et la mise en forme. Un élément <html> explicite reçoit la langue cible dans son attribut lang ; les fragments restent des fragments. Consultez HTML pour en savoir plus sur la sélection du texte et le comportement de sortie.

Formats décrit le comportement des analyseurs, notamment les structures ignorées et les limites de reconstruction. Les gestionnaires partagés côté serveur n’étendent pas la liste des formats de la CLI.

Chemins de sortie #

Utilisez un modèle explicite lorsque les chemins source n’indiquent pas leur langue :

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [
    {
      "pattern": "docs/**/*.md",
      "sourceRoot": "docs",
      "targetPath": "i18n/[locale]/docs/[path]"
    }
  ]
}

docs/start.md devient i18n/de/docs/start.md et i18n/fr/docs/start.md. [locale] utilise la représentation de la langue définie dans l’entrée ; [path] retire la racine source en respectant les limites des segments. Une racine docs ne retire pas une partie de docsite.

Les modèles nécessitent [locale] ; les entrées utilisant des motifs glob nécessitent aussi [path]. Ce sont les seuls paramètres substituables. Les chemins absolus, .., les racines glob, les racines en dehors des entrées et les sorties détectées à nouveau comme sources configurées sont rejetés. sourceRoot sans targetPath est invalide. Push vérifie également les collisions entre chemins de sortie sans tenir compte de la casse.

Push, pull et purge suivent également les chemins du système de fichiers : si une source, une cible, .lingo/lock.json ou .lingo/config.json pointe en dehors de la racine du projet ou dans .git, par exemple via un lien symbolique, la commande s’arrête avec une erreur avant toute lecture, écriture ou suppression à cet emplacement. Les liens qui restent dans le projet fonctionnent toujours, mais aucune écriture n’est effectuée à travers une cible ou un Lockfile qui est lui-même un lien. Dans un monorepo, exécutez la commande depuis une racine contenant les fichiers partagés plutôt que de créer des liens vers eux depuis un paquet.

Sans modèle, la déduction du chemin essaie successivement un répertoire de langue source, le nom de fichier entier sans extension, les structures propres aux plateformes, puis l’insertion d’un répertoire de langue, accompagnée d’un avertissement. Exemples : locales/en.json → locales/de.json, app_en.arb → app_de.arb, Base.lproj → une cible .lproj, et Android values → des ressources identifiées par langue. Lisez les avertissements et vérifiez que l’application charge cette destination.

XCStrings et CSV stockent toutes les langues dans le fichier source et rejettent targetPath. Plusieurs sorties de langues partagent volontairement ce fichier ; sa présence ne garantit pas que chaque langue s’y trouve. Purge ignore le fichier partagé et ne peut donc pas supprimer les entrées d’une langue donnée.

Sélectionner les métadonnées et le texte des composants #

Pour les formats de la famille Markdown, la traduction sélectionne les champs title et description des métadonnées frontmatter lorsque l’option n’est pas renseignée. Une liste vide désactive cette sélection ; une liste explicite permet de sélectionner d’autres champs. Les chemins imbriqués de valeurs scalaires et de tableaux nécessitent des métadonnées frontmatter analysables ; si elles sont mal formées, l’analyse peut se rabattre sur le niveau supérieur.

json
{
  "pattern": "docs/en/**/*.mdx",
  "translateFrontmatterFields": ["title", "description"],
  "translateComponentProps": ["aria-label", { "component": ["Card", "Callout"], "props": ["title"] }]
}

Une chaîne sélectionne une propriété sans filtre par composant. Un objet sélectionne props et peut limiter la sélection à certains noms de composants. Ces règles sélectionnent le contenu littéral traduisible, et non le code des composants ni l’ensemble des attributs. Markdown, MDX et Markdoc se comportent différemment ; vérifiez le gestionnaire lorsque vous changez de chemins.

Pour fournir des consignes de traduction en JSONC, placez @context immédiatement avant la chaîne concernée. La sortie JSONC générale conserve les marqueurs @orphan mais supprime les autres commentaires. Les métadonnées @src de React doivent donc suivre la politique de chargement du catalogue ; ne supposez pas que pull les préserve.

Pour les frameworks de documentation, choisissez les répertoires réels de source et de sortie indépendamment du routage. OpenAPI utilise yaml-openapi ; les racines de langues de type Rails utilisent yaml-root-key ; le YAML générique utilise yaml. Une extension correspondante ne suffit pas à sélectionner la bonne sémantique.

Langues #

La configuration vérifie que les chaînes ne sont pas vides, sans les comparer à une liste exhaustive de langues. Utilisez les identifiants nécessaires à votre modèle et à votre application, en précisant la région ou le système d’écriture si nécessaire. localeFormat détermine les chemins : bcp47 conserve les traits d’union, underscore produit pt_BR et android produit des formes telles que pt-rBR ou b+zh+Hans. Le format Android utilise la représentation Android, sauf remplacement explicite ; cela influe aussi sur la correspondance des sources.

Terminez les mises à jour courantes des sources en attente avant d’ajouter une cible et de compléter rétroactivement ses fichiers manquants. Ajouter une langue explique comment cet ordre permet de garder les langues existantes à jour. Retirer une cible empêche sa sélection à l’avenir, sans supprimer les fichiers existants. Les métadonnées de langue intégrées et les catalogues partagés doivent suivre les règles de leur gestionnaire. Un chemin correctement orthographié ne garantit ni le sens d’écriture, ni le routage, ni la qualité linguistique.

Chemins des catalogues #

Pour l’extraction et la vérification, les valeurs explicites --out/--types priment sur les paramètres i18n, qui priment à leur tour sur les valeurs par défaut. --source-locale utilise en par défaut, indépendamment du paramètre de localisation sourceLocale. Modifier messagesPath ne met pas à jour files[] ; sélectionnez le chemin JSONC généré pour la traduction.

Monorepos #

Une configuration à la racine peut partager les langues et un moteur de localisation entre des chemins de paquets récursifs ou explicites. À l’inverse, des configurations par paquet permettent de garder les langues, la configuration et les Lockfile indépendants. Exécutez la commande depuis la racine du paquet voulu pour éviter que la recherche de la configuration la plus proche ne sélectionne un répertoire parent de façon inattendue.

Une matrice de répertoires CI doit préserver les sorties collectées pour chaque projet et éviter les écritures concurrentes sur les mêmes fichiers. Les pointeurs d’exécution stockés localement dans le répertoire personnel dépendent des racines absolues et ne sont pas partagés via un Lockfile. lingo check compare chaque source sélectionnée par files au Lockfile au niveau des fichiers ; il ne vérifie pas les clés qu’ils contiennent.

Configuration de la notation #

lingo score utilise le fichier exécutable lingo.config.ts, chargé via Jiti. Ce fichier est distinct du JSON du projet et n’enregistre pas de chargeurs de formats locaux arbitraires. Gardez les extensions de notation de confiance séparées des paramètres de localisation de fichiers à distance.