# General Translation Knowledge Base: Comment traduire des fichiers JSON i18n ? URL: https://generaltranslation.com/fr/kb/translate-json-files.mdx Docs index: https://generaltranslation.com/llms.txt Description: 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. Category: Traduction Last updated: 2026-10-20 Authors: Kevin Wu, Jackie Chen Published: 2026-10-20 Cette réponse porte sur les fichiers de paramètres régionaux chargés par les bibliothèques i18n telles que i18next, react-intl, next-intl et vue-i18n, dans lesquels chaque clé correspond à une chaîne de caractères de l’IU. Les fichiers JSON de données quelconques (réponses d’API, catalogues de produits) demandent une autre approche, car il faut alors décider champ par champ de ce qui doit être traduit. ## À quoi ressemblent les fichiers de paramètres régionaux JSON La plupart des fichiers de paramètres régionaux sont imbriqués et regroupent les clés dans des objets, comme ci-dessous. Dans un fichier plat, ce même chemin s'écrit sous la forme d'une seule clé à points, par exemple `"nav.home": "Home"`. ```json title="locales/en/common.json" { "nav": { "home": "Home", "save": "Save" }, "greeting": "Hello, {{name}}!", "inbox_one": "You have {{count}} new message", "inbox_other": "You have {{count}} new messages", "terms": "Read our <1>terms before you continue." } ``` La syntaxe des chaînes de caractères dépend de la bibliothèque, et toute traduction doit la préserver telle quelle : * **i18next** interpole avec des doubles accolades (`{{name}}`) et stocke les formes plurielles dans des clés distinctes, avec des [suffixes](https://www.i18next.com/translation-function/plurals) tels que `_one`, `_few`, `_many` et `_other`, selon les règles de pluriel de chaque langue. Le composant `` de react-i18next ajoute des balises numérotées, comme `<1>terms`. * **react-intl et next-intl** stockent des messages ICU, dans lesquels les espaces réservés utilisent des accolades simples et les formes plurielles figurent directement dans la chaîne : `{count, plural, one {# message} other {# messages}}`. (Voir [Qu'est-ce que le format de message ICU ?](/kb/icu-message-format)). * **vue-i18n** utilise des espaces réservés à accolades simples et sépare les formes du pluriel par une barre verticale : `no apples | one apple | {count} apples` ([pluralisation dans vue-i18n](https://vue-i18n.intlify.dev/guide/essentials/pluralization)). Le nommage des clés a aussi son importance, car le traducteur ne dispose souvent que de la clé et de la valeur. (Voir [Comment nommer les clés de traduction i18n ?](/kb/i18n-key-naming)). ## Ce qui coince quand vous collez du JSON dans un traducteur Un traducteur généraliste traite le fichier comme du simple texte, ce qui met sa structure en péril : * **Les clés sont traduites.** `"nav"` devient `"nawigacja"`, et l'application ne trouve plus la chaîne de caractères. * **Les espaces réservés sont modifiés.** `{{name}}` devient `{{nombre}}`, ou une accolade disparaît, et l'interpolation échoue à l'exécution. * **Les balises sont endommagées.** `<1>terms` est traduite, renumérotée ou supprimée, si bien que le lien n'encapsule plus les bons mots. * **Le fichier n'est plus du JSON valide.** Des guillemets typographiques, un `"` non échappé dans une chaîne traduite ou une virgule finale suffisent à faire échouer l'analyse de tout le fichier. * **Des clés de pluriel manquent.** Traduire `inbox_one` et `inbox_other` clé par clé prive le polonais des clés `inbox_few` et `inbox_many` dont i18next a besoin : « 5 messages » n'a alors aucune forme polonaise correcte à afficher. (Consultez [Qu'est-ce que le format de message ICU ?](/kb/icu-message-format) pour connaître les catégories de pluriel de chaque langue.) * **Les chaînes courtes perdent leur sens.** `"save": "Save"` se traduit en allemand par *speichern* (enregistrer un fichier) ou *sparen* (économiser), et la clé seule permet rarement de trancher. ## Méthodes pour traduire des fichiers JSON de paramètres régionaux | Approche | Clés et espaces réservés | Formes du pluriel | Contexte pour les chaînes courtes | Suivi des modifications | | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | À la main, ou par un traducteur travaillant directement dans le fichier | Fiable si la personne est rigoureuse | La personne les ajoute, si elle connaît les règles | La personne peut poser des questions | Manuel à chaque modification | | Traducteur JSON en ligne (téléverser un fichier, télécharger une traduction) | Variable selon l’outil ; testez d’abord avec un fichier riche en espaces réservés | Variable selon l’outil | Variable selon l’outil | Téléverser à nouveau le fichier à chaque modification | | Script utilisant l’API DeepL ou Google Cloud Translation | Vous parcourez le JSON et n’envoyez que les valeurs ; l’API de documents de DeepL accepte aussi les fichiers `.json` et protège les espaces réservés par défaut | Vous générez vous-même les clés manquantes | Paramètre `context` de DeepL ; Google ne propose rien au niveau de la chaîne | Vous relancez le script et comparez la sortie avec un diff | | Soumettre le fichier à un LLM | Généralement conservés, mais sans aucune garantie | Ajoutées si vous le demandez en précisant les catégories | Ce que vous indiquez dans le prompt | Vous relancez le prompt et validez chaque exécution | | CLI de General Translation | Lit la structure JSON et traduit les valeurs | Traduit les entrées existantes ; vérifiez les familles de pluriel de la langue cible | Notes et limites de longueur par clé, glossaire et instructions personnalisées partagés | Réutilise les traductions correspondantes ; génère les mises à jour avant la compilation | | Système de gestion de la traduction (TMS) | Analyse selon le format, les clés sont donc préservées | Dépend du TMS et du format de fichier | Captures d’écran, commentaires et descriptions par clé | Synchronisation des fichiers via l’intégration de dépôt du TMS | Deux des options par script méritent d’être détaillées. L’[API de documents](https://developers.deepl.com/api-reference/document) de DeepL compte `json` parmi les formats pris en charge et, par défaut, conserve tels quels les espaces réservés comme `{stars}` ou `{{userName}}` et protège les squelettes de pluriel ICU, en ne traduisant que le texte de leurs branches. La [traduction de documents](https://docs.cloud.google.com/translate/docs/advanced/translate-documents) de Google accepte les fichiers Office et les PDF, mais pas le JSON, et le site grand public Google Traduction n’accepte que les fichiers `.docx`, `.pdf`, `.pptx` et `.xlsx` ; avec Google, vous devez donc extraire vous-même les valeurs des chaînes et les envoyer à l’API de texte. Optez pour une passe manuelle rigoureuse ou pour l’API de documents de DeepL lorsque vous traduisez un petit fichier une seule fois. Optez pour un script ou un prompt LLM si vous assumez vous-même la validation et les relances. Choisissez General Translation si vous souhaitez que des catalogues générés et relus soient livrés avec les modifications du code, tout en conservant votre bibliothèque de rendu existante. Choisissez un [système de gestion de la traduction](/kb/what-is-a-translation-management-system) lorsqu’une équipe de traducteurs travaille en dehors de la base de code. ## Comment traduire des fichiers JSON avec General Translation Lorsque les fichiers se trouvent dans votre dépôt et évoluent à chaque livraison, une commande intégrée à votre processus de compilation peut les tenir à jour. La CLI de General Translation, `gt`, traduit les fichiers JSON de paramètres régionaux, y compris les catalogues i18next et ceux basés sur ICU. Vous pouvez conserver la bibliothèque qui se charge de leur rendu. Installez la CLI avec `npm install gt --save-dev`, exécutez [`npx gt init`](/docs/cli/reference/commands/init) pour créer `gt.config.json` et vous connecter, puis faites pointer `files.json.include` vers vos fichiers sources. L'espace réservé `[locale]` indique à la CLI où lire le paramètre régional source et où écrire chaque locale cible : ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["de"], "files": { "json": { "include": ["locales/[locale]/*.json"] } } } ``` Pour un projet existant, exécutez d'abord [`npx gt upload`](/docs/cli/reference/commands/upload) afin d'importer la source et les traductions déjà relues. [`npx gt translate`](/docs/cli/reference/commands/translate) lit ensuite chaque fichier situé dans `locales/en/` et écrit les fichiers allemands dans `locales/de/`, prêts à être relus et commités ; ajoutez `--dry-run` pour lister les fichiers détectés sans appeler l'API. Cet exemple utilise l'anglais et l'allemand, dont les messages cardinaux utilisent tous deux les catégories `one` et `other` présentées ci-dessus. Lors des exécutions suivantes, les traductions correspondantes peuvent être réutilisées. Si votre `package.json` déclare `i18next` ou `next-intl`, la CLI conserve la syntaxe de chaînes de caractères propre à cette bibliothèque, y compris les messages ICU. (Consultez la [référence du format JSON](/docs/cli/reference/formats/json-files).) Pour lever l'ambiguïté d'une chaîne courte comme « Save », ajoutez un fichier associé `common.metadata.json` contenant les mêmes clés, avec une note `context` ou une limite `maxChars` pour chaque chaîne. (Consultez [Métadonnées associées aux clés](/docs/cli/reference/keyed-metadata).) Pour `nav.save`, utilisez une note telle que « Save the edited document to disk », afin que le service ne dispose pas seulement d'un libellé ambigu. Les termes du glossaire et les instructions personnalisées issus des groupes de contexte de votre projet s'appliquent également. Relisez les formulations générées dans l'[éditeur du tableau de bord](/docs/platform/dashboard/guides/reviewing-translations) ; utilisez [`npx gt save-local`](/docs/cli/reference/commands/save-local) si les relecteurs modifient les fichiers téléchargés. Les vérifications ci-dessous valident la structure des messages, indépendamment de cette relecture linguistique. ## Vérifier les fichiers traduits avant leur mise en production Validez le résultat avec le même format de message et les mêmes règles de paramètre régional que votre application : * **Analysez le JSON et comparez les clés non plurielles.** Vérifiez les chemins de clés imbriquées comme les clés de premier niveau. Des clés manquantes ou renommées peuvent faire échouer les recherches, même si le JSON est analysé sans erreur. Traitez les tableaux et les valeurs autres que des chaînes de caractères conformément au schéma de votre application. * **Vérifiez les formes plurielles i18next par familles.** Regroupez les clés telles que `inbox_one` et `inbox_other` selon leur clé de base, puis vérifiez les catégories de la locale cible. Le polonais exige également `inbox_few` et `inbox_many` : il s'agit d'ajouts obligatoires, et non de clés inattendues. Le japonais peut se contenter de `inbox_other`. i18next s'appuie sur `Intl.PluralRules` et autorise aussi une forme spéciale `_zero` ; appliquez les règles appropriées aux messages cardinaux ou ordinaux. (Consultez les [règles de pluriel d'i18next](https://www.i18next.com/translation-function/plurals).) * **Préservez les espaces réservés et les balises dans chaque forme traduite.** Vérifiez aussi les formes du pluriel nouvellement ajoutées. `{{name}}` doit toujours faire référence à `name`, et les balises numérotées doivent toujours désigner les composants prévus, même si leur ordre change. * **Analysez les messages ICU et comparez leurs arguments.** Utilisez un analyseur tel que le [FormatJS ICU message parser](https://formatjs.github.io/docs/icu-messageformat-parser/) plutôt qu'une expression régulière pour gérer les accolades imbriquées. L'analyse seule ne suffit pas : remplacer l'argument de pluriel `count` par `total` donne une syntaxe valide, qui ne correspond pourtant plus à la valeur fournie par l'application. Vérifiez les noms et types d'arguments, les balises de texte enrichi, les cas de sélection, les sélecteurs de nombre exact tels que `=0` et les décalages de pluriel. Tolérez les catégories de pluriel locale-specific : la branche `other`, obligatoire en ICU, sert de contenu de secours, si bien que les messages ICU n'ont pas besoin de contenir toutes les catégories CLDR. Les clés plurielles manquantes passent inaperçues. Ce fichier polonais contient les quatre catégories, alors qu'une traduction clé par clé se serait arrêtée à `inbox_one` et `inbox_other` : ```json title="locales/pl/common.json" { "inbox_one": "Masz {{count}} nową wiadomość", "inbox_few": "Masz {{count}} nowe wiadomości", "inbox_many": "Masz {{count}} nowych wiadomości", "inbox_other": "Masz {{count}} nowej wiadomości" } ``` Chargé avec i18next 26.5.3 et `fallbackLng: 'en'`, le fichier traduit clé par clé se rabat sur l'anglais pour chaque valeur de count nécessitant `few` ou `many`, au lieu d'utiliser la forme polonaise `other` : ```text title="Output" count category key-by-key file complete file 1 one Masz 1 nową wiadomość Masz 1 nową wiadomość 2 few You have 2 new messages Masz 2 nowe wiadomości 5 many You have 5 new messages Masz 5 nowych wiadomości 22 few You have 22 new messages Masz 22 nowe wiadomości 1.5 other Masz 1.5 nowej wiadomości Masz 1.5 nowej wiadomości ``` La valeur décimale s'affiche sous la forme `1.5`, car elle n'est pas formatée comme un nombre ; formatez-la selon le paramètre régional si des fractions sont possibles. Enfin, chargez les messages via la bibliothèque d’i18n de votre application et procédez à leur relecture en contexte. Testez des valeurs qui déclenchent chaque forme du pluriel, y compris zéro et les décimales le cas échéant. Les vérifications syntaxiques ne permettent pas de savoir si une traduction est exacte ni si son texte tient dans l'interface. Les règles d'interpolation personnalisées et la syntaxe à barre verticale de vue-i18n nécessitent des vérifications adaptées à ces formats. ## Points clés * Traduisez les valeurs en préservant la syntaxe des messages. Les clés non plurielles restent inchangées ; les clés plurielles peuvent différer d'une langue à l'autre. * Les catégories de pluriel varient selon la langue : le polonais nécessite des clés `_few` et `_many` absentes d'une source anglaise. * L'API de documents de DeepL accepte le JSON et protège les espaces réservés par défaut ; la traduction de documents de Google, elle, ne prend pas en charge le JSON. * Pour les traduire avec la CLI `gt`, définissez `files.json.include` sur un motif contenant `[locale]` et exécutez [`npx gt translate`](/docs/cli/reference/commands/translate) ; les métadonnées associées aux clés permettent d'ajouter du contexte et des limites de longueur propres à chaque chaîne de caractères. * Validez les familles de pluriels i18next en fonction de la locale cible, et analysez les messages ICU avec un parseur plutôt que de vérifier leur syntaxe imbriquée à l'aide d'une expression régulière. ## Related questions - [Qu’est-ce que le format de message ICU ?](https://generaltranslation.com/fr/kb/icu-message-format.mdx): Le format de message ICU est une syntaxe qui permet à une seule chaîne traduisible de contenir des variables, des formes plurielles, des choix select et des ordinaux, par exemple {count, plural, one {# file} other {# files}}. Chaque langue utilise les catégories de pluriel CLDR dont elle a besoin : l’anglais utilise one et other, tandis que le polonais y ajoute few et many. - [Comment nommer les clés de traduction i18n ?](https://generaltranslation.com/fr/kb/i18n-key-naming.mdx): Nommez les clés selon l’endroit où le texte apparaît et ce qu’il signifie, par exemple checkout.summary.title, et non selon sa formulation anglaise. Attribuez une clé distincte à chaque usage, même si le texte anglais est identique : en allemand, le bouton Open se traduit par Öffnen, alors que l’état Open se traduit par Offen. - [General Translation vs i18next, react-intl et next-intl : quelle bibliothèque d’i18n choisir ?](https://generaltranslation.com/fr/kb/general-translation-vs-i18n-libraries.mdx): Les bibliothèques open source comme i18next, react-intl et next-intl ne traduisent rien. Elles affichent les traductions que vous leur fournissez dans un fichier de catalogue par langue, rédigées par vous, vos traducteurs ou un service tiers. Les bibliothèques de General Translation sont elles aussi open source et remplissent le même rôle, mais General Translation se charge en plus de la traduction, en s’appuyant sur votre code comme contexte. - [Peut-on faire de l’i18n sans fichiers de traduction ?](https://generaltranslation.com/fr/kb/i18n-without-translation-files.mdx): Oui. Les bibliothèques gt-react et gt-next de General Translation permettent d’internationaliser React et Next.js sans clés de traduction ni fichier JSON par langue à maintenir. Le texte reste intégré au JSX, dans le composant ``, et la commande gt translate génère les traductions de chaque langue lors de la compilation, en s’appuyant sur le contexte de votre code. Locadex peut les tenir à jour via des pull requests. - [La traduction par IA est-elle assez précise pour une application en production ?](https://generaltranslation.com/fr/kb/is-ai-translation-accurate.mdx): Souvent, pour les langues les plus parlées, mais seulement après une évaluation concluante sur vos propres langues, vos chaînes de caractères d’IU et vos contenus plus sensibles. Lors du WMT25, Gemini 2.5 Pro a égalé ou surpassé les traductions humaines de référence pour 10 des 16 paires de langues, mais un benchmark portant sur des documents ne permet pas de savoir si de courtes chaînes de caractères d’interface sont prêtes à être livrées. ## Previous and next questions - Previous question: [Comment rendre un site web multilingue ?](https://generaltranslation.com/fr/kb/make-website-multilingual.mdx) - Next question: [Comment traduire des sous-titres SRT sans casser la synchronisation ?](https://generaltranslation.com/fr/kb/translate-srt-subtitles.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/fr/kb/sitemap.md) for every article.