Configuration i18n.json

i18n.json est un fichier de configuration standard qui contrôle le comportement de Lingo.dev CLI et des intégrations CI/CD de Lingo.dev.

i18n.json implémente une configuration basée sur un schéma qui sépare les paramètres de langue, les modèles de découverte de fichiers et la configuration du moteur de traduction IA en sections distinctes. Par conséquent, les développeurs comprennent exactement comment fonctionne leur flux de travail de localisation en lisant le fichier de configuration.

Ce guide suppose que vous avez installé Lingo.dev CLI et que vous configurez un flux de travail de traduction. À la fin, vous comprendrez la structure complète de i18n.json, les options de configuration et comment chaque section contrôle le comportement de traduction.

Version

Le champ version spécifie la version du schéma de configuration :

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8
}

Éléments de configuration :

  • $schema — Pointe vers la définition du schéma JSON pour l'autocomplétion et la validation de l'IDE. Le schéma aide à détecter les erreurs de configuration tôt en fournissant une documentation inline et une vérification de type.
  • version — Version du schéma de configuration pour la compatibilité de migration.

Lingo.dev CLI utilise ce champ pour la migration automatique de configuration lorsque de nouvelles versions de schéma sont publiées.

Configuration des locales

La section locale définit quelles langues Lingo.dev CLI traite :

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja", "de"]
  }
}

Les codes de langue suivent la norme BCP 47 pour les balises de langue, qui incorpore les codes de langue de ISO 639 et les codes de région optionnels de ISO 3166-1. Les exemples incluent en, en-US, es-ES, et zh-Hans.

Lingo.dev CLI prend également en charge les formats de locale spécifiques aux plateformes comme la convention en-rUS d'Android pour les répertoires de ressources. Pour obtenir la liste complète des codes de locale pris en charge, exécutez :

npx lingo.dev@latest show locale sources  # Langues sources disponibles
npx lingo.dev@latest show locale targets  # Langues cibles disponibles

Si votre code de locale n'est pas pris en charge, veuillez ouvrir une pull request pour l'ajouter !

Éléments de configuration :

  • locale.source — Code de langue source qui identifie quels fichiers contiennent le contenu faisant autorité. Toutes les traductions vont de la source aux cibles.
  • locale.targets — Tableau des codes de langue cible représentant vos marchés cibles. Chaque code correspond à un fichier séparé ou à une section dans un fichier, selon le format.

Commandes de vérification de langue :

Configuration du fournisseur

La section provider détermine quel service de traduction IA Lingo.dev CLI utilise. Cette section est facultative et utilise par défaut le moteur de traduction IA de Lingo.dev lorsqu'elle est omise.

Pour l'accès direct à l'API LLM :

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Votre instruction personnalisée de traduction avec les variables {source} et {target}"
  }
}

Pour le moteur Lingo.dev :

Pour utiliser le moteur Lingo.dev, omettez complètement la section provider. Le moteur sélectionne automatiquement les modèles et les instructions en fonction des recherches d'optimisation et de vos paramètres du moteur Lingo.dev.

Éléments de configuration :

  • provider.id — Identifiant du service de traduction IA (par exemple « openai » ou « anthropic »).
  • provider.model — Nom du modèle de traduction IA (par exemple « gpt-4o-mini » pour OpenAI ou « claude-3-haiku » pour Anthropic).
  • provider.prompt — Instruction système qui guide le comportement de traduction. Les variables {source} et {target} sont remplacées par les codes de langue réels lors de l'exécution.

Configuration des buckets

Les buckets définissent les modèles de découverte de fichiers et les règles de traitement. Chaque bucket représente un format de fichier avec des modèles d'inclusion/exclusion spécifiques.

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json", "app/[locale]/*.json"],
      "exclude": ["locales/[locale]/internal.json"],
      "lockedKeys": ["app/version", "config/apiUrl"],
      "injectLocale": ["settings.language"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

Éléments de configuration :

  • buckets.[bucket-type] — Groupe de configuration pour un bucket de format de fichier spécifique.
    • buckets.[bucket-type].include — Tableau de modèles de découverte de fichiers. Peut contenir des chaînes ou des objets.
      • buckets.[bucket-type].include.[string] — Modèle de chemin de fichier simple avec la variable [locale].
      • buckets.[bucket-type].include.[object] — Configuration avancée de modèle avec les propriétés suivantes :
        • path — Le modèle de chemin de fichier avec la variable [locale].
        • delimiter — Le délimiteur à utiliser pour les codes de locale. Par défaut - (tiret), peut être remplacé par _ (underscore). Remplace le délimiteur de la configuration de locale.
    • buckets.[bucket-type].exclude — Tableau de modèles d'exclusion de fichiers à ignorer pendant le traitement.
    • buckets.[bucket-type].lockedKeys — Tableau de clés qui ne doivent pas être traduites. Utilise la barre oblique / comme séparateur pour les clés imbriquées.
    • buckets.[bucket-type].ignoredKeys — Tableau de clés qui doivent être ignorées pendant la traduction. Utilise la barre oblique / comme séparateur pour les clés imbriquées.
    • buckets.[bucket-type].injectLocale — Tableau de clés où le code de locale doit être automatiquement injecté.

Structure de base des modèles

Les modèles d'inclusion utilisent une syntaxe de type glob avec le placeholder spécial [locale] :

  • locales/[locale].json → locales/en.json, locales/es.json
  • docs/[locale]/*.md → docs/en/*.md, docs/es/*.md

Les modèles d'exclusion empêchent le traitement de fichiers spécifiques au sein des modèles d'inclusion.

Options avancées des modèles

Délimiteurs de locale personnalisés pour différents formats de noms de fichiers :

{
  "include": [
    "standard/[locale].json",
    {
      "path": "underscore/[locale].json",
      "delimiter": "_"
    }
  ]
}

Délimiteurs disponibles :

  • - (tiret) : en-US.json
  • _ (underscore) : en_US.json

Conseil : Ce paramètre contrôle le délimiteur utilisé dans le nom du fichier, vous pouvez donc l'utiliser dans une configuration monorepo où différents projets ont des conventions de délimiteurs différentes.

Types de buckets pris en charge

Lingo.dev CLI prend en charge les types de buckets suivants pour différents formats de fichiers :

  • android — Fichiers de ressources XML Android
  • csv — Fichiers CSV avec des fichiers séparés pour chaque langue cible
  • flutter — Fichiers ARB Flutter
  • html — Fichiers HTML avec des fichiers séparés pour chaque langue cible
  • json — Fichiers JSON avec des fichiers séparés pour chaque langue cible
  • markdown — Fichiers Markdown avec des fichiers séparés pour chaque langue cible
  • mdx — Fichiers MDX avec des fichiers séparés pour chaque langue cible
  • xcode-strings — Fichiers .strings Xcode legacy
  • xcode-stringsdict — Fichiers .stringsdict Xcode pour la pluralisation
  • xcode-xcstrings — Fichiers de catalogue de chaînes Xcode
  • yaml — Fichiers YAML avec des fichiers séparés pour chaque langue cible
  • yaml-root-key — Fichiers YAML avec des clés racine basées sur la locale
  • properties — Fichiers .properties Java
  • po — Fichiers .po GNU gettext
  • xml — Fichiers XML génériques avec des fichiers séparés pour chaque langue cible
  • php — Fichiers d'array PHP
  • vue-json — Fichiers JSON Vue.js i18n
  • typescript — Fichiers TypeScript avec des fichiers séparés pour chaque langue cible

Exemples de configuration

Configuration de base

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Configuration monorepo

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en-US",
    "targets": ["es-ES", "fr-FR"]
  },
  "buckets": {
    "json": {
      "include": ["apps/web/locales/[locale].json"]
    },
    "mdx": {
      "include": ["packages/docs/content/[locale]/*.mdx"]
    },
    "xcode-xcstrings": {
      "include": ["ios/Localizable.xcstrings"]
    },
    "android": {
      "include": ["android/values-[locale]/strings.xml"]
    }
  }
}

Migration de version

i18n.json implémente une migration intelligente des versions qui met automatiquement à jour votre configuration vers des versions de schéma plus récentes tout en préservant tous les paramètres utilisateur.

Lorsque Lingo.dev CLI détecte une version de configuration plus ancienne, il :

  1. Crée une sauvegarde de votre fichier i18n.json actuel
  2. Migre la configuration vers la dernière version du schéma
  3. Préserve tous les paramètres y compris les fournisseurs personnalisés, les configurations de bucket et les clés verrouillées
  4. Met à jour le champ de version pour correspondre au schéma actuel

Comportement de migration :

La migration se déclenche automatiquement pendant toute opération CLI qui lit le fichier de configuration. Aucune intervention manuelle n'est requise, et votre flux de travail de traduction se poursuit sans interruption.

Ce système de migration garantit que les configurations i18n.json restent compatibles avec les mises à jour de Lingo.dev CLI tout en maintenant une rétrocompatibilité avec les projets existants.