Configuration d’i18n.json

i18n.json est le fichier de configuration qui pilote le CLI Lingo.dev et les intégrations CI/CD. Il définit les langues à traduire, l’emplacement du contenu traduisible et le backend de traduction à utiliser.

Exemple minimal#

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

Le champ $schema active l’autocomplétion et la validation dans l’IDE. Le champ version indique la version du schéma afin d’assurer la compatibilité avec les migrations automatiques.

Langue#

La section locale définit les langues source et cibles :

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

Les codes de langue suivent la norme BCP 47 : en, en-US, es-ES, zh-Hans, ainsi que les formats propres aux plateformes comme le en-rUS d’Android, sont tous pris en charge.

Pour afficher les codes de langue disponibles :

npx lingo.dev@latest show locale sources   # Available source languages
npx lingo.dev@latest show locale targets   # Available target languages

Buckets#

Les buckets définissent les motifs de découverte des fichiers et les règles de traitement. Chaque clé de bucket correspond à un format de fichier, et sa valeur détermine quels fichiers inclure ou exclure :

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "exclude": ["locales/[locale]/internal.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

Motifs d’inclusion#

Les motifs d’inclusion utilisent l’espace réservé [locale], qui est remplacé à l’exécution par les codes de langue configurés :

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

Délimiteurs de langue personnalisés#

Par défaut, les codes de langue dans les noms de fichiers utilisent un tiret (-) comme délimiteur : en-US.json. Pour utiliser des underscores à la place, passez un objet avec un champ delimiter :

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

Cela produit legacy/en_US.json au lieu de legacy/en-US.json.

Notation des chemins de clés#

Les tableaux lockedKeys, ignoredKeys et preservedKeys utilisent la notation par barre oblique (/) pour les clés imbriquées et l’astérisque (*) pour les jokers :

{
  "lockedKeys": ["brand/name", "config/*"]
}

Pour consulter la liste complète des types de buckets pris en charge, voir Formats pris en charge.

Fournisseur#

La section provider configure un fournisseur LLM brut pour la traduction. Cette section est facultative : si elle est omise, le CLI utilise un moteur de localisation sur Lingo.dev.

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

Connexion au moteur#

Pour faire passer les traductions par un moteur de localisation spécifique, ajoutez le champ engineId :

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Lorsque engineId est défini, chaque requête de traduction applique automatiquement la voix de marque, le glossaire, les instructions et la configuration du modèle de votre moteur. S’il est omis et que LINGO_API_KEY est défini, le CLI utilise le moteur par défaut de votre organisation.

Pour le guide de configuration complet, voir Connect Your Engine.

Variables d’environnement#

Exemple complet#

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Migration de version#

Le CLI migre automatiquement les anciennes configurations i18n.json vers la dernière version du schéma. Il crée une sauvegarde de votre fichier actuel, met à jour le schéma et conserve tous vos paramètres. Aucune intervention manuelle n’est nécessaire.

Étapes suivantes#