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 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. Ainsi, les développeurs comprennent exactement comment fonctionne leur workflow de localisation en lisant le fichier de configuration.

Ce guide suppose que vous avez installé Lingo.dev CLI et que vous configurez un workflow de traduction. À la fin, vous comprendrez la structure complète d'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.10"
}

Éléments de configuration :

  • $schema — Pointe vers la définition du schéma JSON pour l'autocomplétion et la validation dans l'IDE. Le schéma aide à détecter les erreurs de configuration en amont en fournissant une documentation en ligne 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 lors de la publication de nouvelles versions de schéma.

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 intègre 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  # Available source languages
npx lingo.dev@latest show locale targets  # Available target languages

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 de référence. Toutes les traductions vont de la source vers les cibles.
  • locale.targets — Tableau de 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 optionnelle 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": "Your custom translation prompt with {source} and {target} placeholders"
  }
}

Pour Lingo.dev Engine :

Pour utiliser Lingo.dev Engine, omettez entièrement la section provider. Le moteur sélectionne automatiquement les modèles et les prompts en fonction de la recherche d'optimisation et de vos paramètres Lingo.dev Engine.

É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 — Prompt système qui guide le comportement de traduction. Les placeholders {source} et {target} sont remplacés 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 le placeholder [locale].
      • buckets.[bucket-type].include.[object] — Configuration de modèle avancée avec les propriétés suivantes :
        • path — Le modèle de chemin de fichier avec le placeholder [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 lors du 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. Utilisez l'astérisque * pour correspondre à plusieurs clés.
    • buckets.[bucket-type].ignoredKeys — Tableau de clés qui doivent être ignorées lors de la traduction. Utilise la barre oblique / comme séparateur pour les clés imbriquées. Utilisez l'astérisque * pour correspondre à plusieurs clés.
    • buckets.[bucket-type].injectLocale — Tableau de clés où le code de locale doit être automatiquement injecté. Utilise la barre oblique / comme séparateur pour les clés imbriquées. Utilisez l'astérisque * pour correspondre à plusieurs clés.

Structure de base des motifs

Les motifs d'inclusion utilisent une syntaxe de type glob avec l'espace réservé spécial [locale] :

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

Les motifs d'exclusion empêchent le traitement de fichiers spécifiques dans les motifs d'inclusion.

Options avancées des motifs

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
  • _ (trait de soulignement) : en_US.json

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

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 hérités
  • 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 de tableaux 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.10",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Configuration monorepo

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "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 de version intelligente qui met automatiquement à jour votre configuration vers les 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 lors de 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 la rétrocompatibilité avec les projets existants.