# General Translation Knowledge Base: Comment nommer les clés de traduction i18n ? URL: https://generaltranslation.com/fr/kb/i18n-key-naming.mdx Docs index: https://generaltranslation.com/llms.txt Description: 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. Category: Internationalisation Last updated: 2026-10-20 Authors: Kevin Wu, Jackie Chen Published: 2026-10-20 Une clé est l’identifiant qu’utilise votre code pour retrouver une traduction, comme dans `t('summary.title', { ns: 'checkout' })`. Des noms bien choisis résistent aux retouches rédactionnelles, indiquent aux traducteurs où le texte apparaît et permettent de repérer facilement les clés mortes. Les conventions ci-dessous s’appliquent à i18next, react-i18next, Rails I18n, vue-i18n et à toute autre bibliothèque qui lit des fichiers JSON ou YAML organisés par clés ; les exemples utilisent la syntaxe i18next et ont été testés avec i18next 26.5.3. ## 1. Utiliser un espace de noms par fonctionnalité ou par écran Commencez chaque clé par la zone du produit à laquelle elle appartient, puis indiquez le composant, puis l'élément. * ✅ `checkout.summary.title`, `settings.billing.cancelButton` * ❌ `title1`, `text_47`, `newString` Lorsque le premier segment correspond à un fichier distinct, il s'agit d'un espace de noms et non d'une partie du chemin de la clé. Si `summary.title` est stockée dans `checkout.json`, i18next la trouve via `t('summary.title', { ns: 'checkout' })` ou `t('checkout:summary.title')`. En revanche, `t('checkout.summary.title')` renvoie la chaîne de caractères de la clé elle-même, car i18next cherche alors un objet `checkout` dans l'espace de noms par défaut. Le préfixe indique au traducteur où le texte apparaît et vous permet de répartir les catalogues dans plusieurs fichiers. i18next appelle ces fichiers des [espaces de noms](https://www.i18next.com/principles/namespaces) et recommande de les découper par vue, par fonctionnalité ou par module chargé en différé, avec en complément un espace de noms `common` pour les libellés comme « Enregistrer » et « Annuler ». Dans React, react-i18next charge un espace de noms avec `useTranslation('checkout')`, et l'[option `keyPrefix`](https://react.i18next.com/latest/usetranslation-hook) permet de raccourcir les chemins profonds. ## 2. Décrire le sens, pas la formulation Une clé doit rester valable même après que l'équipe marketing a réécrit la phrase. * ✅ `auth.login.submit` * ❌ `auth.login.clickHereToSignInNow` Si le bouton affiche plus tard « Continuer », la première clé reste exacte. La seconde décrit désormais un texte qui n'existe plus, et quelqu'un finira tôt ou tard par la renommer, ce qui cassera toutes les références et rendra les traductions orphelines. ## 3. Une clé par contexte, et non une par chaîne de caractères anglaise Deux chaînes identiques en anglais se traduisent souvent différemment. « Open » sur un bouton est un verbe ; « Open » comme état d'un ticket est un adjectif. L'allemand emploie *Öffnen* dans le premier cas et *Offen* dans le second. * ✅ `files.actions.open` et `tickets.status.open` * ❌ un seul `common.open` réutilisé pour les deux Réservez l'espace de noms partagé `common` aux libellés dont le sens est identique partout, comme un bouton Annuler. Les systèmes fondés sur le texte source résolvent ce même problème grâce au contexte : le [`msgctxt`](https://www.gnu.org/software/gettext/manual/html_node/Contexts.html) de GNU gettext permet d'associer deux traductions à une même chaîne de caractères anglaise. ## 4. Choisissez entre JSON imbriqué et JSON plat, sans les mélanger Dans `checkout.json`, i18next interprète `summary.title` comme un chemin, car son `keySeparator` vaut `.` par défaut. Les deux structures fonctionnent ; choisissez-en une seule pour que tous les fichiers, relecteurs et outils s'accordent sur la même convention. ```json title="locales/en/checkout.json (nested)" { "summary": { "title": "Order summary", "taxNotice": "Tax is calculated at checkout." } } ``` ```json title="locales/en/checkout.json (flat)" { "summary.title": "Order summary", "summary.taxNotice": "Tax is calculated at checkout." } ``` Pour les fichiers plats, la [documentation de configuration](https://www.i18next.com/overview/configuration-options) d’i18next recommande de définir `keySeparator` sur `false`. Choisissez aussi une convention de casse (segments en `camelCase` ou en `snake_case`) et appliquez-la dans tous vos fichiers. ## 5. Utilisez les suffixes de pluriel et de contexte de votre bibliothèque i18next sélectionne les formes du pluriel à l'aide de suffixes et exige que la variable s'appelle `count`. Une entrée `_zero` remplace la règle de la langue lorsque `count` vaut 0, et les ordinaux ajoutent le suffixe `_ordinal` : ```json title="locales/en/checkout.json" { "cart": { "itemCount_zero": "Your cart is empty", "itemCount_one": "{{count}} item", "itemCount_other": "{{count}} items" } } ``` `t('cart.itemCount', { count: 0 })` renvoie "Votre panier est vide", avec 1, on obtient "1 article" et avec 5, "5 articles". Une langue qui compte davantage de catégories de pluriel ajoute des clés telles que `itemCount_few` et `itemCount_many`. (Consultez la [documentation i18next sur les formes plurielles](https://www.i18next.com/translation-function/plurals), ainsi que [Qu'est-ce que le format de message ICU ?](/kb/icu-message-format) pour connaître les catégories de chaque langue.) * ✅ `itemCount_one`, `itemCount_other` et, pour les textes genrés, des clés de [contexte](https://www.i18next.com/translation-function/context) comme `friend_male` et `friend_female` * ❌ des suffixes inventés tels que `itemCount_singular` et `itemCount_plural`, que la bibliothèque ne sélectionnera jamais Les bibliothèques reposant sur le format de message ICU (react-intl, next-intl, Lingui) regroupent quant à elles toutes les formes du pluriel dans un seul message, sous une seule clé. ## 6. Ne construisez jamais une phrase à partir de plusieurs clés L'ordre des mots varie d'une langue à l'autre : une phrase répartie sur plusieurs clés ne peut donc pas être traduite correctement. * ❌ `t('account.hello') + name + t('account.welcomeBack')` * ✅ une seule clé avec un espace réservé : `"account.welcome": "Hello, {{name}}! Welcome back."` Lorsqu'un message comporte un nombre, conservez là aussi la phrase entière dans chaque forme du pluriel, à l'aide des suffixes de la convention 5. Le [manuel GNU gettext](https://www.gnu.org/software/gettext/manual/html_node/Preparing-Strings.html) énonce la même règle pour ses catalogues : traduisez des phrases entières et utilisez des chaînes de format plutôt que la concaténation. ## 7. Choisir entre des clés stables et le texte source comme clé Tous les systèmes n'inventent pas de noms. Toute la question est de savoir à qui revient l'identifiant : | Approche | Exemple | Avantage | Coût | | ----------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Clés sémantiques (i18next, Rails I18n) | `t('summary.title', { ns: 'checkout' })` | Les modifications de texte n'impliquent aucun changement de code ; les clés indiquent l'emplacement | Quelqu'un doit nommer, ranger et nettoyer chaque clé | | Texte source comme clé (gettext) | `_("Order summary")` | Le code reste lisible ; pas d'étape de nommage | Toute modification du texte anglais crée une nouvelle entrée ; les conflits entre textes identiques nécessitent `msgctxt` | | ID générés à partir du texte intégré (FormatJS) | `defaultMessage="Order summary"` | Le message se trouve là où il est utilisé ; les ID sont générés automatiquement | Nécessite un plugin de compilation et une étape d'extraction | Utilisez des clés sémantiques lorsque les textes sont gérés en dehors de la base de code (par exemple, par une équipe de contenu qui modifie les chaînes dans un TMS) ou lorsque les applications web et mobiles partagent un même catalogue. Privilégiez le texte source ou des messages intégrés lorsque les développeurs rédigent eux-mêmes les textes et que vous souhaitez voir, lors de la revue de code, les mots exacts affichés aux utilisateurs. ## 8. Tenir les clés à l'écart des URL, des analytics et de la logique Les clés et les chaînes traduites servent uniquement à l'affichage. N'utilisez pas `t('checkout:cta')` comme nom d'événement analytics (chaque paramètre régional remonterait un événement différent), ne construisez pas un slug de route à partir d'une clé, et ne faites pas dépendre une condition de `label === t('status.open')`. Utilisez plutôt un nom d'événement fixe, un slug que vous maîtrisez, et une énumération ou un code d'état. Ainsi, renommer une clé ou modifier une traduction ne risque plus de casser un tableau de bord, un lien ou une condition. ## 9. Nettoyer automatiquement les clés inutilisées et manquantes Les catalogues finissent par se désynchroniser : des clés subsistent après la suppression de leur composant, et de nouvelles clés partent en production sans traduction. Exécutez un outil de vérification dans votre CI. * **i18next** : [`i18next-cli`](https://github.com/i18next/i18next-cli) remplace `i18next-parser`, désormais obsolète. Sur un petit projet de test, `npx i18next-cli status --unused` a signalé une clé orpheline `oldPromoBanner` sans modifier aucun fichier ; `npx i18next-cli extract` l'a ensuite supprimée (son option `removeUnusedKeys` vaut `true` par défaut) et a généré des entrées allemandes vides pour chaque clé, y compris `itemCount_one` et `itemCount_other`. `npx i18next-cli status` renvoie une erreur tant que des traductions manquent, et `rename-key` renomme une clé à la fois dans les fichiers source et dans les fichiers de paramètres régionaux. L'analyse statique ne détecte pas les clés construites à l'exécution, comme ``t(`status.${code}`)`` : `extract` les considère donc comme inutilisées et les supprime. Listez ces préfixes dans l'option `preservePatterns` (par exemple, `'status.*'`), ou écrivez chaque clé en toutes lettres dans le code. * **Rails** : i18n-tasks signale les clés manquantes et inutilisées en analysant votre code Ruby et ERB. (Voir [General Translation vs. i18n-tasks](/kb/general-translation-vs-i18n-tasks).) ## Comment General Translation gère les clés Avec le composant [``](/docs/react/reference/components/t) de `gt-react` ou `gt-next`, le texte anglais reste directement dans le composant et vous n'avez aucune clé à nommer : ```tsx title="CheckoutSummary.tsx" import { T } from 'gt-react'; export function CheckoutSummary() { return (

Order summary

Tax is calculated at checkout. ); } ``` [`npx gt translate`](/docs/cli/reference/commands/translate) extrait le contenu encore présent dans votre source : supprimer un composant vous dispense donc de maintenir ses clés à la main. Les différents usages de « Open » nécessitent toujours un contexte : `Open` ou `gt('Open', { $context: 'Ticket status' })` avec [`useGT`](/docs/react/reference/hooks/use-gt). Une prop [`id`](/docs/react/reference/components/t#id) facultative sur [``](/docs/react/reference/components/t), ou une option `$id` sur la fonction de traduction, attribue à une entrée un identifiant stable dans l'éditeur de traduction. (Voir [Peut-on faire de l'i18n sans fichiers de traduction ?](/kb/i18n-without-translation-files).) Les équipes qui préfèrent les clés peuvent les conserver. Rédigez un dictionnaire source unique, par exemple `dictionary.json`, et lisez-le avec [`useTranslations`](/docs/react/reference/hooks/use-translations) ; la même commande se charge de le traduire, et la recherche d'un id absent du dictionnaire lève une exception au lieu d'afficher une clé brute. (Voir [Traduire avec des dictionnaires](/docs/react/guides/translating-with-dictionaries).) Les fichiers JSON i18next ou next-intl existants sont traduits tels quels, et un [fichier `.metadata.json`](/docs/cli/reference/keyed-metadata) associé permet d'ajouter un contexte ou une limite de caractères par clé : c'est l'équivalent, pour les clés, de la convention 3. ## Points clés * Nommez les clés selon leur emplacement et leur sens (`checkout.summary.title`), jamais selon leur formulation ou leur position (`text_47`). * Attribuez des clés distinctes à « Open » (le verbe) et à « Open » (l'état) ; ne partagez une clé que lorsque le sens est identique. * Respectez scrupuleusement les suffixes de pluriel de la bibliothèque : i18next utilise `_one`, `_other` et `_zero`, tandis que les bibliothèques ICU regroupent les formes plurielles dans un seul message. * Exécutez `i18next-cli status --unused` ou i18n-tasks dans votre CI pour éviter que les clés inutilisées ou manquantes ne s'accumulent. * Le composant [``](/docs/react/reference/components/t) de General Translation se passe entièrement de clés, et son mode dictionnaire avec [`useTranslations`](/docs/react/reference/hooks/use-translations) permet de les conserver pour les équipes qui le souhaitent. ## Related questions - [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. - [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. - [Alternatives à i18next : General Translation ou i18next](https://generaltranslation.com/fr/kb/general-translation-vs-i18next.mdx): Choisissez General Translation pour conserver vos textes directement dans vos composants React et générer des traductions en tirant parti de leur structure JSX et du contexte de votre produit. Vous pouvez aussi conserver i18next et utiliser General Translation pour traduire vos catalogues existants. i18next assure le rendu des messages et la sélection des formes plurielles ; la génération des traductions relève d’un service distinct. - [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 trouver les chaînes codées en dur qui ne sont pas traduites ?](https://generaltranslation.com/fr/kb/find-hardcoded-strings.mdx): Exécutez dans votre CI un linter qui signale les littéraux de chaîne de caractères visibles par l’utilisateur, comme la règle no-literal-string d’eslint-plugin-i18next pour JSX, la vérification HardcodedText d’Android Lint ou le linter HardCodedString d’erb_lint pour Rails. Parcourez ensuite l’application avec un pseudo-paramètre régional pour repérer le texte que les vérifications statiques ne peuvent pas détecter. ## Previous and next questions - Previous question: [Comment localiser une app iOS avec les String Catalogs ?](https://generaltranslation.com/fr/kb/localize-ios-app.mdx) - Next question: [Comment prendre en charge les langues RTL (right-to-left) en CSS ?](https://generaltranslation.com/fr/kb/right-to-left-css.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/fr/kb/sitemap.md) for every article.