CSV
Traduisez un tableau CSV regroupant toutes les langues dans un seul fichier, avec une colonne par langue et une colonne de votre choix pour identifier les lignes.
Un tableau de traduction CSV regroupe le texte source et toutes ses traductions dans un seul fichier : une ligne par message, une colonne par langue. Le gestionnaire de fichiers csv remplit les cellules des langues cibles et enregistre le résultat au chemin du fichier source. Il ne modifie que les cellules des langues cibles et ajoute une colonne lorsqu’une langue n’en possède pas, comme l’explique la section Quelles lignes sont traduites. Les autres colonnes, l’ordre des lignes, les guillemets et les fins de ligne restent inchangés. La marque d’ordre des octets UTF-8 placée en début de fichier n’est pas conservée : le fichier enregistré commence sans cette marque. Si votre tableur s’appuie sur elle pour détecter l’UTF-8, vous devrez peut-être importer le fichier en précisant cet encodage.
Structurer le tableau #
La première ligne qui n’est ni vide ni composée uniquement de caractères d’espacement constitue l’en-tête. Une colonne contient la clé qui identifie chaque ligne, une autre contient le texte source, et chaque langue cible dispose de sa propre colonne :
id,en,notes,de
checkout.title,Complete your order,Shown on the last step,Bestellung abschließen
checkout.pay,"Pay now, or later",,- Colonnes de langue. Une colonne correspond à une langue lorsque son en-tête correspond au code de cette langue, sans tenir compte de la casse :
deetDEdésignent la colonne de l’allemand, tandis quede-DEdésigne une autre langue. L’en-tête de la colonne source correspond ausourceLocalede votre configuration. - Colonne de clé. Par défaut, la première cellule de l’en-tête désigne la colonne de clé. Définissez
keyColumndans l’entrée du fichier pour utiliser une autre colonne. La colonne source peut elle-même servir de colonne de clé si le texte source fait office de clé. - Autres colonnes. Les colonnes qui ne correspondent ni à la clé ni à une langue, comme
notes, sont conservées octet pour octet et ne sont jamais envoyées pour traduction. - Syntaxe. Les cellules sont séparées par des virgules. Une cellule contenant une virgule, un guillemet ou un saut de ligne est entourée de guillemets doubles, et chaque guillemet à l’intérieur est doublé (
""). Les fichiers utilisant des points-virgules ou des tabulations comme séparateurs ne sont pas pris en charge.
Configurer la traduction CSV #
Un fichier CSV n’est sélectionné que si une entrée de fichiers utilise un motif se terminant par .csv, auquel cas le format est déduit, ou définit "format": "csv". Une entrée avec "format": "csv" ne sélectionne que les fichiers .csv. Sans ce format, un motif large comme data/**/* ne sélectionne jamais de fichier CSV : une entrée existante ne risque donc pas de réécrire des fichiers de données sans rapport. L’extension est sensible à la casse : un fichier nommé strings.CSV n’est pas traduit. Renommez-le en strings.csv.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "i18n/strings.csv", "keyColumn": "id" }]
}Le fichier sert lui-même de cible pour chaque langue ; targetPath est donc refusé pour ce format. Les lignes CSV ne sont pas comparées aux contrôles des clés ; lockedKeys, preservedKeys et ignoredKeys sont donc également refusés. La même configuration fonctionne dans la CLI et la GitHub App.
Quelles lignes sont traduites #
| Ligne | Résultat |
|---|---|
| Clé et texte source | Traduite pour les langues dont la cellule est vide ou obsolète. |
| Clé, cellule source vide | Conservée telle quelle ; ses cellules de langue restent inchangées. |
| Texte source, cellule de clé vide ou contenant uniquement des espaces | Conservée telle quelle, sans traduction. Attribuez-lui une clé pour la traduire. |
| Clé et source vides, ou ligne vide | Conservée telle quelle, même si elle ne contient que des espaces. |
Une cellule de langue contenant uniquement des espaces est considérée comme vide. Une cellule remplie est réutilisée tant que le texte source de sa ligne n’a pas changé depuis le dernier push. Dès que le texte source d’une ligne change, toutes les cellules de langue de cette ligne sont retraduites. Une ligne ajoutée depuis le dernier push conserve ses cellules remplies : seules ses cellules vides sont traduites. Une ligne dont la clé a changé est considérée comme une nouvelle ligne. Les cellules remplies sont également conservées lors du premier push du fichier, avec --force dans la CLI, lors d’une commande GitHub App qui indique des fichiers sans --force, ainsi que lorsque le fichier du push précédent ne possède pas de colonne source ou de colonne de clé unique permettant la comparaison, par exemple après le renommage de l’une d’elles. Une commande GitHub App avec --force retraduit toutes les lignes du fichier.
Les textes sources suivants sont copiés au lieu d’être traduits : les valeurs composées uniquement des chiffres ASCII de 0 à 9, comme 100 ; une URL qui commence par // ou dont le schéma se compose de lettres, de chiffres ou de traits de soulignement suivis de ://, et dont l’adresse après // commence par localhost ou comporte au moins un caractère, un point, puis au moins deux autres caractères, comme https://lingo.dev/docs ; un identifiant de 22 caractères composé uniquement de lettres et de chiffres, comprenant au moins une majuscule, une minuscule et un chiffre ; et une date ou une date et une heure au format ISO 8601, comme 2024-01-15 ou 2024-01-15T10:00:00Z. Le texte source est copié dans chaque cellule de langue cible de la ligne correspondante et en remplace le contenu. La ligne n’est ni envoyée en traduction ni facturée. Les autres valeurs, comme 1.5, 100%, une adresse e-mail ou une date présentée sous une autre forme, comme 15.01.2024, sont traduites. Les liens mailto: et tel: sont également traduits, tout comme les URL dont le schéma contient d’autres caractères, comme git+ssh://, et celles dont l’adresse ne commence pas par localhost et ne contient aucun point répondant à ces critères, comme https://intranet ou https://a.b.
Lorsqu’une langue cible ne possède pas de colonne, une colonne est ajoutée à la fin de l’en-tête. Si plusieurs colonnes sont ajoutées, elles suivent l’ordre alphabétique des codes de langue. Chaque ligne est ensuite complétée par des cellules vides pour que le tableau reste rectangulaire. Les lignes ne sont jamais réordonnées, ajoutées ni supprimées.
Erreurs #
Le traitement du fichier échoue avant toute traduction ou facturation, avec un message indiquant le problème, dans les cas suivants :
- le
keyColumnconfiguré ne figure pas dans l’en-tête, ou la première cellule de l’en-tête est vide et aucunkeyColumnn’est défini ; - deux lignes ont la même clé, car leurs traductions seraient placées dans les mauvaises lignes ;
- l’en-tête ne contient aucune colonne pour la langue source ;
- la colonne de clé est aussi la colonne d’une langue cible ;
- l’en-tête mentionne plusieurs fois le
keyColumnconfiguré, la langue source ou une langue cible ; - une ligne contient plus de cellules que l’en-tête ;
- une cellule entre guillemets n’a pas de guillemet fermant ;
- du texte suit un guillemet fermant dans la même cellule.
Corrigez le fichier et effectuez un nouveau push. La CLI affiche le message une seule fois sous le fichier, et non une fois par langue. Si l’exécution entière échoue, la ligne finale Run failed: reprend ce message. La GitHub App l’affiche dans l’exécution de vérification.
Corriger une traduction existante #
Pour ajuster précisément une formulation, modifiez directement la cellule. Pour régénérer une traduction, videz la cellule concernée, conservez le reste de la ligne et effectuez un simple push :
lingo push --waitLa commande CLI --force réutilise les cellules remplies, comme pour les catalogues de chaînes Apple. --key ne réduit pas le périmètre de traitement d’un fichier CSV : la CLI interrompt le push avec une erreur, et la GitHub App ignore le fichier. La purge via la CLI ignore le fichier, car la source et la sortie partagent le même chemin. Examinez toutes les différences du fichier avant d’en faire un commit.