CSV par locale - Lingo.dev CLI

Qu'est-ce que CSV par locale ?

CSV par locale est une approche de traduction où chaque locale possède son propre fichier CSV séparé, plutôt que de stocker toutes les locales dans un seul fichier CSV avec plusieurs colonnes. Ce format est utile lorsque vous avez des données structurées avec plusieurs colonnes (comme des catalogues de produits, des données utilisateur ou des systèmes de gestion de contenu) où chaque ligne représente un enregistrement et les colonnes représentent différents champs.

Par exemple :

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3

Contrairement au bucket CSV standard qui stocke toutes les locales dans un seul fichier avec des colonnes comme KEY,en,es, le bucket csv-per-locale maintient des fichiers séparés pour chaque locale, préservant la structure CSV originale avec toutes les colonnes.

Qu'est-ce que Lingo.dev CLI ?

Lingo.dev CLI est un CLI gratuit et open source pour traduire des applications et du contenu avec l'IA. Il est conçu pour remplacer les logiciels de gestion de traduction traditionnels tout en s'intégrant aux pipelines existants.

Pour en savoir plus, consultez Présentation.

À propos de ce guide

Ce guide explique comment traduire des fichiers CSV en utilisant le bucket csv-per-locale avec Lingo.dev CLI.

Vous apprendrez à :

Créer un projet à partir de zéro
Configurer un pipeline de traduction avec des fichiers CSV séparés par locale
Générer des traductions avec l'IA
Utiliser des clés verrouillées et ignorées

Prérequis

Pour utiliser Lingo.dev CLI, assurez-vous que Node.js v18+ est installé :

❯ node -v
v22.17.0

Étape 1. Configurer un projet

Dans le répertoire de votre projet, créez un fichier i18n.json :

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Ce fichier définit le comportement du pipeline de traduction, y compris les langues entre lesquelles traduire et l'emplacement du contenu localisable sur le système de fichiers.

Pour en savoir plus sur les propriétés disponibles, consultez i18n.json.

Étape 2. Configurer la locale source

La locale source est la langue et la région d'origine dans lesquelles votre contenu a été rédigé. Pour configurer la locale source, définissez la propriété locale.source dans le fichier i18n.json :

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

La locale source doit être fournie sous forme de balise de langue BCP 47.

Pour la liste complète des codes de locale pris en charge par Lingo.dev CLI, consultez Codes de locale pris en charge.

Étape 3. Configurer les locales cibles

Les locales cibles sont les langues et régions vers lesquelles vous souhaitez traduire votre contenu. Pour configurer les locales cibles, définissez la propriété locale.targets dans le fichier i18n.json :

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Étape 4. Créer le contenu source

Si ce n'est pas déjà fait, créez un fichier CSV pour votre locale source. Le fichier doit contenir :

Une ligne d'en-tête avec les noms de colonnes
Une ou plusieurs lignes de données
Toutes les colonnes dont vous avez besoin (non limitées à des noms de colonnes spécifiques)

Le fichier CSV doit être situé à un chemin qui inclut la locale source quelque part dans le chemin (par exemple, comme nom de répertoire tel que en/ ou comme partie du nom de fichier tel que data.en.csv).

Remarque : contrairement au bucket CSV standard, vous n'avez pas besoin d'une colonne « KEY » ou d'une colonne correspondant à la locale source. Le bucket csv-per-locale traite chaque ligne comme un enregistrement et traduira tout le contenu textuel du CSV tout en préservant la structure.

Étape 5. Créer un bucket

Dans le fichier i18n.json, ajoutez un objet "csv-per-locale" à l'objet buckets :

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {}
  }
}

Dans l'objet "csv-per-locale", définissez un tableau d'un ou plusieurs motifs include :
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"]
    }
  }
}
```
Ces motifs définissent quels fichiers traduire.

Les motifs eux-mêmes :
- doivent contenir [locale] comme espace réservé pour la locale configurée
- peuvent pointer vers des chemins de fichiers (par exemple, "[locale]/data.csv")
- peuvent utiliser des astérisques comme espaces réservés génériques (par exemple, "[locale]/*.csv")
Les motifs glob récursifs (par exemple, **/*.csv) ne sont pas pris en charge.

Optionnellement, vous pouvez configurer lockedKeys et ignoredKeys :

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}

lockedKeys : Clés (valeurs de colonne dans la première colonne, généralement un ID) qui ne doivent pas être traduites
ignoredKeys : Clés qui ne doivent pas apparaître dans les fichiers de locale cible

Étape 6. Configurer un LLM

Lingo.dev CLI utilise des modèles de langage de grande taille (LLM) pour traduire du contenu avec l'IA. Pour utiliser l'un de ces modèles, vous avez besoin d'une clé API d'un fournisseur pris en charge.

Pour démarrer le plus rapidement possible, nous recommandons d'utiliser Lingo.dev Engine — notre propre plateforme hébergée qui offre 10 000 tokens d'utilisation mensuelle gratuite :

Créez un compte Lingo.dev.
Exécutez la commande suivante :
```
npx lingo.dev@latest login
```
Cela ouvrira votre navigateur par défaut et vous demandera de vous authentifier.
Suivez les instructions.

Étape 7. Générer les traductions

Dans le répertoire qui contient le fichier i18n.json, exécutez la commande suivante :

npx lingo.dev@latest run

Cette commande :

Lit le fichier i18n.json.
Trouve les fichiers qui doivent être traduits.
Extrait le contenu traduisible des fichiers CSV.
Utilise le LLM configuré pour traduire le contenu extrait.
Écrit le contenu traduit dans des fichiers CSV séparés pour chaque locale cible.

La première fois que les traductions sont générées, un fichier i18n.lock est créé. Ce fichier garde une trace du contenu qui a été traduit, évitant ainsi les retraductions inutiles lors des exécutions suivantes.

Exemple

en/example.csv (avant traduction)

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3
4,Success,Operation completed successfully,2024-01-01,true,4
5,Loading,Please wait while we load your data,2024-01-01,true,5

es/example.csv (après traduction)

id,name,description,created,enabled,sort
1,Bienvenida,Bienvenido a nuestra aplicación,2024-01-01,true,1
2,Guardar,Guarda tus cambios,2024-01-01,true,2
3,Error,Ha ocurrido un error,2024-01-01,true,3
4,Éxito,Operación completada con éxito,2024-01-01,true,4
5,Cargando,Por favor espera mientras cargamos tus datos,2024-01-01,true,5

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}

i18n.lock

version: 1
checksums:
  e8b273672f895de0944f0a2317670d7c:
    0/name: 1308168cca4fa5d8d7a0cf24e55e93fc
    0/description: 8de4bc8832b11b380bc4cbcedc16e48b
    1/name: f7a2929f33bc420195e59ac5a8bcd454
    1/description: 8de4bc8832b11b380bc4cbcedc16e48b
    2/name: d3d99b147cc363dc6db8a48e8a13d4c1
    2/description: 7cd986af1fe5e89abe7ecffba5413110

Différences avec le bucket CSV

Le bucket csv-per-locale diffère du bucket csv standard de plusieurs façons :

Structure de fichiers : csv-per-locale utilise des fichiers séparés pour chaque locale (par exemple, en/example.csv, es/example.csv), tandis que csv utilise un seul fichier avec plusieurs colonnes (par exemple, KEY,en,es).
Exigences de colonnes : csv-per-locale ne nécessite pas de colonne "KEY" ni de colonnes nommées selon les locales. Vous pouvez utiliser n'importe quelle structure de colonnes qui correspond à vos données.
Cas d'usage : csv-per-locale est idéal pour les données structurées comme les catalogues de produits, les systèmes de gestion de contenu ou les bases de données où chaque ligne représente un enregistrement avec plusieurs champs. Le bucket csv standard est mieux adapté aux tables de traduction simples clé-valeur.
Mutations de fichiers : Les deux buckets modifient directement les fichiers, mais csv-per-locale crée des fichiers séparés pour chaque locale, tandis que csv ajoute de nouvelles colonnes au fichier existant.