# General Translation Knowledge Base: Comment traduire des fichiers de paramètres régionaux YAML ? URL: https://generaltranslation.com/fr/kb/translate-yaml-files.mdx Docs index: https://generaltranslation.com/llms.txt Description: Traduisez uniquement les valeurs de chaînes de caractères et conservez tels quels les clés, les espaces réservés comme %{name} ou {{name}}, ainsi que les ancres. Mettez entre guillemets les valeurs qui contiennent un deux-points ou qui commencent par % ou {, définissez la racine de paramètre régional ou le nom de chaque fichier, et ajoutez les clés de pluriel requises par la langue cible. Le CLI de General Translation traduit les valeurs YAML sur place sans toucher aux clés. Category: Traduction Last updated: 2026-10-28 Authors: General Translation Team Published: 2026-10-28 Un fichier de paramètres régionaux YAML associe des clés à des chaînes de caractères affichées à l’utilisateur, à raison d’un fichier (ou d’une clé de premier niveau) par langue. Le traduire consiste à remplacer les valeurs de chaînes de caractères en laissant les clés, les espaces réservés et la structure du fichier exactement tels que le framework les attend. Avec YAML, l’exercice est plus délicat qu’avec JSON : un deux-points sans guillemets ou un `%` en début de valeur fait échouer l’analyse, et `no` peut être interprété comme un booléen. Une traduction correcte à la lecture peut donc tout de même produire un fichier que votre application rejette ou interprète mal. ## Organisations courantes des fichiers de paramètres régionaux YAML Chaque framework place la langue à un endroit différent et utilise sa propre syntaxe d'espace réservé ; un fichier traduit doit respecter les mêmes règles : | Framework | Fichier source | Emplacement de la langue | Espaces réservés | Formes plurielles | | --------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | | [Rails I18n](https://guides.rubyonrails.org/i18n.html) | `config/locales/en.yml` | Clé de premier niveau (`en:`) | `%{name}` | Clés `one` et `other` ; davantage avec rails-i18n | | [Symfony](https://symfony.com/doc/current/translation.html#translation-resource-file-names-and-locations) | `translations/messages.en.yaml` | Nom de fichier (`domain.locale.yaml`) | `%name%`, ou `{name}` dans les fichiers `+intl-icu` | Formes plurielles ICU dans la chaîne de caractères | | [Hugo](https://gohugo.io/functions/lang/translate/#translation-tables) | `i18n/en.yaml` | Nom de fichier | Modèles Go tels que `{{ . }}` | Clés CLDR (`one`, `few`, `many`, `other`) | | i18next avec [i18next-fs-backend](https://github.com/i18next/i18next-fs-backend) | `locales/en/common.yml` | Répertoire | `{{name}}` | Clés suffixées telles que `_one` et `_other` | | vue-i18n avec [unplugin-vue-i18n](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n) | `locales/en.yaml` | Nom de fichier | `{name}` | Formes séparées par des barres verticales dans une même chaîne de caractères | C'est Rails qui est le plus strict en matière de structure. Selon le [guide Rails](https://guides.rubyonrails.org/i18n.html#configuring-the-load-paths-and-default-locale), tous les fichiers `.yml` et `.rb` situés dans `config/locales` sont chargés, et dans chaque fichier, « la clé de premier niveau est le paramètre régional ». Un fichier espagnol doit donc commencer par `es:`, quel que soit son nom. ## Les pièges YAML qui cassent les fichiers traduits Voici un fichier Rails rédigé de façon à ce que chaque valeur survive à la traduction : ```yaml title="config/locales/en.yml" en: checkout: title: "Note: prices include VAT" joined: "%{name} joined your team" confirm_no: "No" terms: | By paying, you agree to our terms. Refunds take 5 to 7 days. items: one: "%{count} item" other: "%{count} items" ``` Chaque ligne prévient une erreur courante : * **Les deux-points.** `title: Note: prices include VAT` sans guillemets provoque une erreur de syntaxe, et une traduction peut introduire un deux-points absent du texte anglais. * **Les valeurs qui commencent par un caractère indicateur.** Une valeur simple ne peut pas commencer par `%`, `{`, `[`, `@` ni par un accent grave. `joined: %{name} joined your team` provoque un échec de l'analyse, et `{{name}} joined` est interprété comme le début d'une correspondance. L'ordre des mots change à la traduction : un espace réservé situé en milieu de phrase en anglais se retrouve donc souvent en tête. C'est d'ailleurs pour cette raison que la documentation de Hugo met elle-même `'{{ . }} day'` entre guillemets. * **Les booléens.** L'analyseur YAML de Ruby suit YAML 1.1 : `yes`, `no`, `on` et `off` sans guillemets deviennent donc `true` et `false`, alors que les analyseurs YAML 1.2, dont la plupart des outils JavaScript, les lisent comme des chaînes. Le guide Rails précise que [ces clés doivent être échappées](https://guides.rubyonrails.org/i18n.html#configuring-the-load-paths-and-default-locale), et il en va de même pour les valeurs. Même un fichier norvégien dont la racine est `no:` est chargé par Ruby sous la clé `false`. * **Les scalaires de bloc.** `|` conserve les sauts de ligne et `>` les remplace par des espaces. Les lignes traduites doivent respecter l'indentation du bloc, sans quoi la valeur s'arrête trop tôt ou le fichier ne peut plus être analysé. * **Les ancres et les alias.** `&name` définit un bloc et `*name` le réutilise : modifier une valeur ancrée modifie donc tous les alias. Rails les charge, mais unplugin-vue-i18n indique que ses ressources YAML [ne prennent pas en charge les alias](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n) ; vérifiez donc votre loader avant de vous en servir. Avec les lignes `title` et `joined` sans guillemets, chacune dans son propre fichier, l'analyseur de Ruby (Ruby 2.6, Psych 3.1) les rejette toutes les deux avant même que Rails ne lise la moindre clé : ```text title="Output" unquoted-colon.yml: mapping values are not allowed in this context at line 3 column 16 unquoted-placeholder.yml: found character that cannot start any token while scanning for the next token at line 3 column 13 ``` La règle la plus simple consiste à mettre chaque valeur entre guillemets : une chaîne de caractères entre guillemets doubles est toujours interprétée comme une chaîne de caractères, et `%{name}`, les deux-points et `No` restent du texte. ### Les clés de pluriel varient selon la langue L'anglais utilise `one` et `other`, mais le russe et le polonais ont aussi besoin de `few` et `many`. Une clé manquante ne déclenche aucune erreur. Avec le backend de pluralisation de la gem i18n et une règle de pluriel russe comme celle fournie par rails-i18n, un fichier traduit clé par clé depuis l'anglais se rabat sans le moindre avertissement sur `other` pour tous les nombres qui exigent `few`. Les deux fichiers russes ci-dessous contiennent les traductions de General Translation : ```text title="Output" count key-by-key (one, other) complete (one, few, many, other) 1 У вас 1 непрочитанное сообщение. У вас 1 непрочитанное сообщение. 3 У вас 3 непрочитанных сообщений. У вас 3 непрочитанных сообщения. 5 У вас 5 непрочитанных сообщений. У вас 5 непрочитанных сообщений. 22 У вас 22 непрочитанных сообщений. У вас 22 непрочитанных сообщения. ``` Le [guide Rails](https://guides.rubyonrails.org/i18n.html#locale-specific-rules) précise que seules les règles de pluriel de l'anglais s'appliquent par défaut ; le backend I18n `Pluralization` ou la gem rails-i18n fournissent les autres. Les tables de traduction de Hugo reposent sur les mêmes catégories CLDR, de `zero` à `other`. ### La clé racine du paramètre régional doit changer Dans Rails, un fichier traduit qui commence encore par `en:` ne provoque pas d'erreur. Il est chargé comme de l'anglais : lors d'un test avec la gem i18n, un fichier espagnol laissé sous la racine `en:` a remplacé le titre anglais par sa version espagnole, et `I18n.t` pour `es` a renvoyé un message de traduction manquante. Renommez la racine dans chaque fichier traduit et veillez à garder `config.i18n.available_locales` synchronisé. ## Méthodes pour traduire des fichiers de paramètres régionaux YAML | Approche | Clés et espaces réservés | Clés de pluriel | Contexte pour les chaînes courtes | Suivi des modifications | | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------- | | À la main | Sûr si le traducteur connaît YAML | Ajoutées si le traducteur connaît les règles de la langue | Le traducteur peut poser la question | Manuel à chaque modification | | [i18n-tasks](https://github.com/glebm/i18n-tasks) `translate-missing` (Rails) avec Google Translate, DeepL ou OpenAI | Remplace `%{...}` par des jetons avant l'envoi | `missing` signale les formes du pluriel absentes lorsque les règles rails-i18n sont chargées | Options et instructions propres à chaque moteur | Complète les clés manquantes ; l'anglais modifié n'est pas retraduit | | Un système de gestion de la traduction (TMS) | Analysés syntaxiquement selon le format | Dépend du TMS | Captures d'écran, commentaires, glossaire | Synchronisation du dépôt ou échange de fichiers | | Un script LLM appliqué au fichier | Généralement conservés, mais rien ne garantit les guillemets | Ajoutées uniquement si vous le demandez | Tout ce que vous mettez dans l'instruction | Relancer et valider à chaque fois | | [CLI de General Translation](/docs/cli/reference/formats/yaml-files) | Traduit uniquement les valeurs de chaînes de caractères ; les clés restent intactes | Traduit les clés présentes dans votre source | Glossaire, instructions personnalisées, métadonnées par clé | Réutilise les traductions inchangées à chaque exécution | Pour un ou deux petits fichiers, modifiez-les à la main. Utilisez i18n-tasks lorsqu'une application Rails doit vérifier les clés manquantes et que vous acceptez de combler les manques par une traduction automatique que vous relisez vous-même. (Consultez [General Translation vs. i18n-tasks](/kb/general-translation-vs-i18n-tasks) pour voir comment les deux outils se complètent.) Utilisez un [TMS](/kb/what-is-a-translation-management-system) lorsque les fichiers sont gérés par des traducteurs. Utilisez General Translation lorsque chaque fichier de paramètres régionaux doit être régénéré au fil des modifications de l'anglais, avec une terminologie commune à votre application, votre documentation et votre site marketing. ## Traduire des fichiers YAML avec General Translation La CLI de General Translation, `gt`, traduit les fichiers `.yaml` et `.yml` grâce à une entrée `yaml` dans `gt.config.json`. L'espace réservé `[locale]` indique où placer la langue : les formats qui incluent le paramètre régional dans le nom de fichier fonctionnent donc tels quels. Pour Symfony, `translations/*.[locale].yaml` fait correspondre `messages+intl-icu.en.yaml` à `messages+intl-icu.fr.yaml` ; pour Hugo : ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["de", "pt-BR"], "files": { "yaml": { "include": ["i18n/[locale].yaml"] } } } ``` Vérifiée avec `gt` 2.26.11, la résolution des chemins de la CLI fait correspondre `i18n/en.yaml` à `i18n/de.yaml` et `i18n/pt-BR.yaml`, ce qui correspond aux noms de fichiers de Hugo basés sur les étiquettes de langue. Connectez-vous avec [`npx gt login`](/docs/cli/reference/commands/login) et définissez un identifiant de projet ([informations d’authentification de la CLI](/docs/cli/guides/configuring#credentials)), importez vos traductions existantes avec [`npx gt upload`](/docs/cli/reference/commands/upload), puis exécutez [`npx gt translate`](/docs/cli/reference/commands/translate). General Translation traduit les valeurs de type chaîne de caractères et laisse tout le reste intact : les clés, les nombres, les booléens et les commentaires restent en place, et un bloc ancré n’est traduit qu’une seule fois, ses alias continuant de pointer vers lui. Quelques détails propres au framework restent donc à votre charge : * **Racines de paramètre régional de Rails.** La CLI ne renomme pas les clés, y compris la clé de premier niveau `en:`, et l’option [`transform`](/docs/cli/reference/config#files) renomme les fichiers de sortie, pas les clés. Conservez pour la CLI des fichiers de travail sans racine, comme `translations/en.yml`, et ajoutez la racine du paramètre régional lorsque vous les exportez vers `config/locales`. (Consultez [General Translation vs. Rails I18n](/kb/general-translation-vs-rails-i18n) pour un court script d’export.) * **Clés de pluriel.** La CLI traduit les clés de pluriel présentes dans votre source : un fichier russe issu d’une source anglaise en `one`/`other` contiendra donc `one` et `other`. Exécutez `i18n-tasks missing` avec rails-i18n chargé pour repérer les clés `few` et `many` qu’il reste à ajouter. * **`yes`, `no`, `on` et `off` sans guillemets.** General Translation analyse le YAML selon les règles de la version 1.2, dans laquelle ces valeurs sont des chaînes de caractères ; elles sont donc traduites comme du texte. Mettez-les entre guillemets dans votre source, comme vous le feriez de toute façon pour Rails. * **Syntaxe des bibliothèques.** Les syntaxes de chaînes de caractères personnalisées, comme les messages ICU, sont prises en charge pour `i18next` et `next-intl` ; pour les autres bibliothèques, vérifiez les chaînes de caractères utilisant une syntaxe personnalisée après la première exécution. Pour lever l’ambiguïté d’une chaîne de caractères courte comme « Save », ajoutez un fichier associé `.metadata.yaml` contenant, pour chaque clé, une note `context` ou une limite `maxChars` ([métadonnées associées aux clés](/docs/cli/reference/formats/yaml-files#metadata)). Un glossaire et des instructions personnalisées définis dans un [groupe de contexte](/docs/platform/dashboard/guides/defining-context-for-translations) garantissent la cohérence des termes produit dans vos catalogues YAML comme dans tous les autres projets du groupe, et les relecteurs peuvent [modifier les traductions dans le tableau de bord](/docs/platform/dashboard/guides/reviewing-translations). Si quelqu’un modifie un fichier traduit en local, exécutez [`npx gt save-local`](/docs/cli/reference/commands/save-local) avant la prochaine exécution pour éviter qu’il ne soit écrasé. Après chaque exécution, chargez les fichiers comme le fait votre application : `i18n-tasks missing` et `i18n-tasks check-consistent-interpolations` pour Rails, `lint:translations` pour Symfony, et une compilation pour Hugo. (Consultez [General Translation vs. Symfony Translation](/kb/general-translation-vs-symfony-translation) pour la configuration initiale de Symfony, et [Comment traduire des fichiers JSON i18n ?](/kb/translate-json-files) si vos catalogues sont au format JSON.) ## Questions fréquentes ### Faut-il mettre chaque valeur entre guillemets dans un fichier de paramètres régionaux YAML ? Mettre systématiquement chaque valeur entre guillemets est la pratique la plus sûre. Une valeur entre guillemets doubles est toujours interprétée comme une chaîne de caractères : les deux-points, un `%{name}` en début de valeur ou des mots comme `No` ne peuvent donc pas modifier l'analyse du fichier, que ce soit avant ou après la traduction. ### Pourquoi mon application Rails affiche-t-elle « translation missing » pour une langue que j'ai traduite ? Vérifiez d'abord la clé de premier niveau du fichier. Un fichier dont la racine est encore `en:` est chargé en tant qu'anglais : le nouveau paramètre régional ne contient donc aucune clé. Vérifiez également que le paramètre régional figure bien dans `config.i18n.available_locales`. ### Puis-je utiliser des ancres et des alias dans les fichiers de paramètres régionaux ? Rails les prend en charge, mais ce n'est pas le cas de tous les loaders, notamment unplugin-vue-i18n pour vue-i18n. Traduire une valeur ancrée modifie tous les alias qui y renvoient ; réservez-les donc au texte qui doit être identique partout. ## Points clés * Ne traduisez que les valeurs ; les clés, les espaces réservés comme `%{name}` et `{{name}}`, ainsi que l'indentation des blocs restent inchangés. * Mettez entre guillemets les valeurs qui contiennent des deux-points, qui commencent par `%` ou `{`, ou qui sont des mots comme `yes`, `no`, `on` et `off` ; sans guillemets, Ruby les interprète comme des booléens. * Le russe et le polonais nécessitent des clés `few` et `many` qui n'existent pas dans une source anglaise ; sans elles, Rails se rabat silencieusement sur `other`. * Chaque fichier Rails doit avoir sa propre racine de paramètre régional ; un fichier espagnol dont la racine est `en:` est chargé comme un fichier anglais. * La CLI de General Translation traduit les valeurs de chaînes de caractères YAML grâce à `"yaml": { "include": [...] }` et [`npx gt translate`](/docs/cli/reference/commands/translate), tout en conservant les clés, les commentaires et les ancres ; les racines Rails et les clés de pluriel manquantes restent à votre charge. ## Related questions - [General Translation ou Rails I18n : avez-vous besoin des deux ?](https://generaltranslation.com/fr/kb/general-translation-vs-rails-i18n.mdx): Rails I18n recherche les messages et formate les dates et les nombres. General Translation produit les traductions, les tient à jour au fil de l’évolution de votre texte anglais et offre à votre équipe un tableau de bord pour la relecture. Utilisez les deux pour livrer des catalogues Rails traduits à chaque version. - [General Translation ou i18n-tasks : lequel choisir ?](https://generaltranslation.com/fr/kb/general-translation-vs-i18n-tasks.mdx): i18n-tasks est une gem Ruby qui détecte les clés Rails I18n manquantes ou inutilisées, fait le ménage dans les fichiers de paramètres régionaux et peut compléter les clés manquantes via Google Translate, DeepL, OpenAI, Yandex ou watsonx. General Translation traduit des fichiers de paramètres régionaux entiers en s’appuyant sur votre glossaire, vos instructions personnalisées et la relecture dans le tableau de bord. Les deux outils remplissent des rôles différents, et de nombreuses équipes peuvent les utiliser ensemble. - [General Translation ou Symfony Translation : lequel choisir ?](https://generaltranslation.com/fr/kb/general-translation-vs-symfony-translation.mdx): Symfony Translation affiche les messages en PHP et en Twig. General Translation traduit ses catalogues YAML en CI, les maintient à jour à mesure que votre source évolue et offre aux relecteurs un tableau de bord pour les modifier. Conservez le rendu de Symfony et intégrez la traduction automatisée à votre workflow de livraison. - [Comment traduire des fichiers JSON i18n ?](https://generaltranslation.com/fr/kb/translate-json-files.mdx): Traduisez uniquement les valeurs de type chaîne de caractères d’un fichier JSON de paramètres régionaux. Conservez telles quelles les clés non plurielles, les espaces réservés comme {{name}} et les balises, mais attendez-vous à ce que les clés de pluriel varient selon la langue : le polonais exige inbox_few et inbox_many. Utilisez un outil ou une API qui prend en charge le format, puis analysez et validez le résultat avant la relecture. - [Comment traduire des fichiers PO et POT ?](https://generaltranslation.com/fr/kb/translate-po-files.mdx): Remplissez chaque msgstr, y compris chaque forme du pluriel exigée par l’en-tête Plural-Forms, et laissez msgid, msgctxt et les espaces réservés inchangés. Exécutez msgfmt --check pour contrôler les en-têtes, le nombre de formes du pluriel et les espaces réservés des entrées dotées d’une option de format, puis vérifiez séparément qu’aucun msgstr n’est vide. La CLI de General Translation génère un fichier PO traduit pour chaque langue à partir de votre modèle POT. ## Previous and next questions - Previous question: [Comment traduire des animations Lottie ?](https://generaltranslation.com/fr/kb/translate-lottie-animations.mdx) - Next question: [Comment traduire des fichiers PO et POT ?](https://generaltranslation.com/fr/kb/translate-po-files.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/fr/kb/sitemap.md) for every article.