GitHub

Les dictionnaires offrent une approche traditionnelle pour organiser les traductions sous forme d’objets imbriqués avec des paires clé‑valeur. Bien que les composants <T> soient l’approche recommandée, les dictionnaires peuvent être utiles pour migrer depuis d’autres bibliothèques d’i18n ou lorsque vous préférez centraliser le stockage des traductions.

Recommandation : Utilisez les composants <T> pour les nouveaux projets. Les dictionnaires sont principalement pris en charge pour la migration et la compatibilité avec des workflows de traduction existants.

dictionary vs traduction par composant

Modèle de dictionary

// dictionary.ts
export default {
  greetings: {
    hello: 'Bonjour le monde !',
    welcome: 'Bienvenue, {name} !'
  }
};

// Component usage
function MyComponent() {
  const d = useTranslations();
  return <div>{d('greetings.hello')}</div>;
}

Patron de composant

// Utilisation directe du composant - recommandée
function MyComponent() {
  return <T><div>Bonjour le monde !</div></T>;
}

Arbitrages

Avantages du dictionary

Stockage centralisé - Toutes les traductions au même endroit
Standard du secteur - Modèle familier des autres bibliothèques i18n
Facile à migrer - Permet d’importer aisément des traductions existantes

Inconvénients du dictionary

Complexité - Nécessite davantage de configuration et de paramétrage
Maintenabilité - La séparation du contenu et de son utilisation complique les mises à jour
Débogage - Plus difficile de rattacher les traductions aux composants
Lisibilité - Les clés ne reflètent pas le contenu réel

Prise en main rapide

Étape 1 : Créer le dictionary

Créez un fichier dictionary à la racine de votre projet ou dans le répertoire src :

dictionary.ts

const dictionary = {
  greetings: {
    hello: 'Bonjour le monde !',
    welcome: 'Bienvenue dans notre application !'
  },
  navigation: {
    home: 'Accueil',
    about: 'À propos',
    contact: 'Contact'
  }
};

export default dictionary;

Ou utilisez le format JSON :

dictionary.json

{
  "greetings": {
    "hello": "Bonjour le monde !",
    "welcome": "Bienvenue dans notre application !"
  },
  "navigation": {
    "home": "Accueil", 
    "about": "À propos",
    "contact": "Contact"
  }
}

La fonction withGTConfig détectera automatiquement le fichier dictionary à la racine de votre projet ou dans le répertoire src.

Étape 2 : Utilisation dans les composants

Le hook useTranslations vous permet d’accéder aux entrées du dictionary :

Composants clients

import { useTranslations } from 'gt-next';

function MyComponent() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('greetings.hello')}</h1>
      <p>{d('greetings.welcome')}</p>
    </div>
  );
}

Composants côté serveur

import { getTranslations } from 'gt-next/server';

async function MyServerComponent() {
  const d = await getTranslations();
  
  return (
    <div>
      <h1>{d('greetings.hello')}</h1>
      <p>{d('greetings.welcome')}</p>
    </div>
  );
}

Utilisation des variables

Ajoutez des variables aux entrées du dictionary en utilisant la syntaxe {variable} :

dictionary.ts

const dictionary = {
  user: {
    greeting: 'Bonjour {name} !',
    itemCount: 'Vous avez {count} éléments',
    orderTotal: 'Total : {amount} $'
  }
};

function UserDashboard() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('user.greeting', { name: 'Alice' })}</h1>
      <p>{d('user.itemCount', { count: 5 })}</p>
      <p>{d('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}

Utilisation des préfixes

Limitez l’accès au dictionary à des sections spécifiques au moyen de préfixes :

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: 'Bon retour !',
      lastLogin: 'Dernière connexion : {date}'
    },
    stats: {
      totalUsers: 'Nombre total d\'utilisateurs : {count}',
      activeUsers: 'Utilisateurs actifs : {count}'
    }
  }
};

function DashboardHeader() {
  // Le préfixe limite l'accès à 'dashboard.header'
  const d = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{d('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{d('lastLogin', { date: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Préfixe différent pour la section des statistiques
  const d = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{d('totalUsers', { count: 1000 })}</p> {/* -> dashboard.stats.totalUsers */}
      <p>{d('activeUsers', { count: 150 })}</p> {/* -> dashboard.stats.activeUsers */}
    </div>
  );
}

Prise en charge multilingue

Traduction automatique (recommandée)

La plupart des utilisateurs devraient utiliser loadTranslations pour générer automatiquement des traductions à partir de votre dictionary de base :

dictionary.ts

const dictionary = {
  common: {
    save: 'Enregistrer',
    cancel: 'Annuler',
    delete: 'Supprimer'
  },
  forms: {
    required: 'Ce champ est obligatoire',
    email: 'Veuillez saisir une adresse e-mail valide'
  }
};

export default dictionary;

Créez une fonction loadTranslations pour charger les fichiers de traduction générés :

src/loadTranslations.ts

export default async function loadTranslations(locale) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

withGTConfig détecte automatiquement le fichier loadTranslations.[js|ts] dans votre répertoire src/ ou à la racine du projet.

GT génère automatiquement des traductions pour d’autres langues à partir de votre dictionary de base. Exécutez npx gtx-cli translate pour générer des traductions pour toutes les langues configurées.

Fichiers de traduction manuels (migration)

Pour migrer depuis d’autres bibliothèques i18n ou gérer manuellement les traductions, utilisez loadDictionary :

src/loadDictionary.ts

export default async function loadDictionary(locale: string) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

Cela charge des fichiers de traduction JSON depuis votre répertoire public/locales/ :

es.json

fr.json

de.json

Choisissez la bonne approche : utilisez loadTranslations pour les nouveaux projets avec génération automatique des traductions, ou loadDictionary pour migrer des fichiers de traduction existants.

Configuration pour la production

Processus de build

Ajoutez la traduction à votre pipeline de build :

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...VOTRE_COMMANDE_DE_BUILD...>"
  }
}

Comportement en développement vs en production

Développement : Entrées du dictionary traduites à la demande avec la clé d’API de développement
Production : Toutes les traductions du dictionary sont générées lors de l’étape de build

Combiner avec des composants

Les dictionaries et les composants <T> peuvent fonctionner ensemble :

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Dictionary pour les chaînes simples */}
      <h1>{d('page.title')}</h1>
      
      {/* Composant T pour JSX complexe */}
      <T>
        <p>Ceci est un <strong>message complexe</strong> avec des <a href="/link">liens</a>.</p>
      </T>
      
      {/* Dictionary pour les étiquettes de formulaire */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Prochaines étapes

Guide des langues - Configurer les langues prises en charge et les paramètres de locale
Guide du contenu dynamique - Gérer les besoins de traduction à l’exécution
Référence de l’API :
- Hook useTranslations
- Fonction getTranslations

dictionary vs traduction par composant

Modèle de dictionary

// dictionary.ts
export default {
  greetings: {
    hello: 'Bonjour le monde !',
    welcome: 'Bienvenue, {name} !'
  }
};

// Component usage
function MyComponent() {
  const d = useTranslations();
  return <div>{d('greetings.hello')}</div>;
}

Patron de composant

// Utilisation directe du composant - recommandée
function MyComponent() {
  return <T><div>Bonjour le monde !</div></T>;
}

Arbitrages

Avantages du dictionary

Stockage centralisé - Toutes les traductions au même endroit
Standard du secteur - Modèle familier des autres bibliothèques i18n
Facile à migrer - Permet d’importer aisément des traductions existantes

Inconvénients du dictionary

Complexité - Nécessite davantage de configuration et de paramétrage
Maintenabilité - La séparation du contenu et de son utilisation complique les mises à jour
Débogage - Plus difficile de rattacher les traductions aux composants
Lisibilité - Les clés ne reflètent pas le contenu réel

Prise en main rapide

Étape 1 : Créer le dictionary

Créez un fichier dictionary à la racine de votre projet ou dans le répertoire src :

dictionary.ts

const dictionary = {
  greetings: {
    hello: 'Bonjour le monde !',
    welcome: 'Bienvenue dans notre application !'
  },
  navigation: {
    home: 'Accueil',
    about: 'À propos',
    contact: 'Contact'
  }
};

export default dictionary;

Ou utilisez le format JSON :

dictionary.json

{
  "greetings": {
    "hello": "Bonjour le monde !",
    "welcome": "Bienvenue dans notre application !"
  },
  "navigation": {
    "home": "Accueil", 
    "about": "À propos",
    "contact": "Contact"
  }
}

La fonction withGTConfig détectera automatiquement le fichier dictionary à la racine de votre projet ou dans le répertoire src.

Étape 2 : Utilisation dans les composants

Le hook useTranslations vous permet d’accéder aux entrées du dictionary :

Composants clients

import { useTranslations } from 'gt-next';

function MyComponent() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('greetings.hello')}</h1>
      <p>{d('greetings.welcome')}</p>
    </div>
  );
}

Composants côté serveur

import { getTranslations } from 'gt-next/server';

async function MyServerComponent() {
  const d = await getTranslations();
  
  return (
    <div>
      <h1>{d('greetings.hello')}</h1>
      <p>{d('greetings.welcome')}</p>
    </div>
  );
}

Utilisation des variables

Ajoutez des variables aux entrées du dictionary en utilisant la syntaxe {variable} :

dictionary.ts

const dictionary = {
  user: {
    greeting: 'Bonjour {name} !',
    itemCount: 'Vous avez {count} éléments',
    orderTotal: 'Total : {amount} $'
  }
};

function UserDashboard() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('user.greeting', { name: 'Alice' })}</h1>
      <p>{d('user.itemCount', { count: 5 })}</p>
      <p>{d('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}

Utilisation des préfixes

Limitez l’accès au dictionary à des sections spécifiques au moyen de préfixes :

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: 'Bon retour !',
      lastLogin: 'Dernière connexion : {date}'
    },
    stats: {
      totalUsers: 'Nombre total d\'utilisateurs : {count}',
      activeUsers: 'Utilisateurs actifs : {count}'
    }
  }
};

function DashboardHeader() {
  // Le préfixe limite l'accès à 'dashboard.header'
  const d = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{d('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{d('lastLogin', { date: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Préfixe différent pour la section des statistiques
  const d = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{d('totalUsers', { count: 1000 })}</p> {/* -> dashboard.stats.totalUsers */}
      <p>{d('activeUsers', { count: 150 })}</p> {/* -> dashboard.stats.activeUsers */}
    </div>
  );
}

Prise en charge multilingue

Traduction automatique (recommandée)

La plupart des utilisateurs devraient utiliser loadTranslations pour générer automatiquement des traductions à partir de votre dictionary de base :

dictionary.ts

const dictionary = {
  common: {
    save: 'Enregistrer',
    cancel: 'Annuler',
    delete: 'Supprimer'
  },
  forms: {
    required: 'Ce champ est obligatoire',
    email: 'Veuillez saisir une adresse e-mail valide'
  }
};

export default dictionary;

Créez une fonction loadTranslations pour charger les fichiers de traduction générés :

src/loadTranslations.ts

export default async function loadTranslations(locale) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

withGTConfig détecte automatiquement le fichier loadTranslations.[js|ts] dans votre répertoire src/ ou à la racine du projet.

Fichiers de traduction manuels (migration)

Pour migrer depuis d’autres bibliothèques i18n ou gérer manuellement les traductions, utilisez loadDictionary :

src/loadDictionary.ts

export default async function loadDictionary(locale: string) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

Cela charge des fichiers de traduction JSON depuis votre répertoire public/locales/ :

es.json

fr.json

de.json

Configuration pour la production

Processus de build

Ajoutez la traduction à votre pipeline de build :

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...VOTRE_COMMANDE_DE_BUILD...>"
  }
}

Comportement en développement vs en production

Développement : Entrées du dictionary traduites à la demande avec la clé d’API de développement
Production : Toutes les traductions du dictionary sont générées lors de l’étape de build

Combiner avec des composants

Les dictionaries et les composants <T> peuvent fonctionner ensemble :

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Dictionary pour les chaînes simples */}
      <h1>{d('page.title')}</h1>
      
      {/* Composant T pour JSX complexe */}
      <T>
        <p>Ceci est un <strong>message complexe</strong> avec des <a href="/link">liens</a>.</p>
      </T>
      
      {/* Dictionary pour les étiquettes de formulaire */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Prochaines étapes

Guide des langues - Configurer les langues prises en charge et les paramètres de locale
Guide du contenu dynamique - Gérer les besoins de traduction à l’exécution
Référence de l’API :
- Hook useTranslations
- Fonction getTranslations

dictionary vs traduction par composant

Modèle de dictionary

// dictionary.ts
export default {
  greetings: {
    hello: 'Bonjour le monde !',
    welcome: 'Bienvenue, {name} !'
  }
};

// Component usage
function MyComponent() {
  const d = useTranslations();
  return <div>{d('greetings.hello')}</div>;
}

Patron de composant

// Utilisation directe du composant - recommandée
function MyComponent() {
  return <T><div>Bonjour le monde !</div></T>;
}

Arbitrages

Avantages du dictionary

Stockage centralisé - Toutes les traductions au même endroit
Standard du secteur - Modèle familier des autres bibliothèques i18n
Facile à migrer - Permet d’importer aisément des traductions existantes

Inconvénients du dictionary

Complexité - Nécessite davantage de configuration et de paramétrage
Maintenabilité - La séparation du contenu et de son utilisation complique les mises à jour
Débogage - Plus difficile de rattacher les traductions aux composants
Lisibilité - Les clés ne reflètent pas le contenu réel

Prise en main rapide

Étape 1 : Créer le dictionary

Créez un fichier dictionary à la racine de votre projet ou dans le répertoire src :

dictionary.ts

const dictionary = {
  greetings: {
    hello: 'Bonjour le monde !',
    welcome: 'Bienvenue dans notre application !'
  },
  navigation: {
    home: 'Accueil',
    about: 'À propos',
    contact: 'Contact'
  }
};

export default dictionary;

Ou utilisez le format JSON :

dictionary.json

{
  "greetings": {
    "hello": "Bonjour le monde !",
    "welcome": "Bienvenue dans notre application !"
  },
  "navigation": {
    "home": "Accueil", 
    "about": "À propos",
    "contact": "Contact"
  }
}

La fonction withGTConfig détectera automatiquement le fichier dictionary à la racine de votre projet ou dans le répertoire src.

Étape 2 : Utilisation dans les composants

Le hook useTranslations vous permet d’accéder aux entrées du dictionary :

Composants clients

import { useTranslations } from 'gt-next';

function MyComponent() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('greetings.hello')}</h1>
      <p>{d('greetings.welcome')}</p>
    </div>
  );
}

Composants côté serveur

import { getTranslations } from 'gt-next/server';

async function MyServerComponent() {
  const d = await getTranslations();
  
  return (
    <div>
      <h1>{d('greetings.hello')}</h1>
      <p>{d('greetings.welcome')}</p>
    </div>
  );
}

Utilisation des variables

Ajoutez des variables aux entrées du dictionary en utilisant la syntaxe {variable} :

dictionary.ts

const dictionary = {
  user: {
    greeting: 'Bonjour {name} !',
    itemCount: 'Vous avez {count} éléments',
    orderTotal: 'Total : {amount} $'
  }
};

function UserDashboard() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('user.greeting', { name: 'Alice' })}</h1>
      <p>{d('user.itemCount', { count: 5 })}</p>
      <p>{d('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}

Utilisation des préfixes

Limitez l’accès au dictionary à des sections spécifiques au moyen de préfixes :

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: 'Bon retour !',
      lastLogin: 'Dernière connexion : {date}'
    },
    stats: {
      totalUsers: 'Nombre total d\'utilisateurs : {count}',
      activeUsers: 'Utilisateurs actifs : {count}'
    }
  }
};

function DashboardHeader() {
  // Le préfixe limite l'accès à 'dashboard.header'
  const d = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{d('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{d('lastLogin', { date: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Préfixe différent pour la section des statistiques
  const d = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{d('totalUsers', { count: 1000 })}</p> {/* -> dashboard.stats.totalUsers */}
      <p>{d('activeUsers', { count: 150 })}</p> {/* -> dashboard.stats.activeUsers */}
    </div>
  );
}

Prise en charge multilingue

Traduction automatique (recommandée)

La plupart des utilisateurs devraient utiliser loadTranslations pour générer automatiquement des traductions à partir de votre dictionary de base :

dictionary.ts

const dictionary = {
  common: {
    save: 'Enregistrer',
    cancel: 'Annuler',
    delete: 'Supprimer'
  },
  forms: {
    required: 'Ce champ est obligatoire',
    email: 'Veuillez saisir une adresse e-mail valide'
  }
};

export default dictionary;

Créez une fonction loadTranslations pour charger les fichiers de traduction générés :

src/loadTranslations.ts

export default async function loadTranslations(locale) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

withGTConfig détecte automatiquement le fichier loadTranslations.[js|ts] dans votre répertoire src/ ou à la racine du projet.

Fichiers de traduction manuels (migration)

Pour migrer depuis d’autres bibliothèques i18n ou gérer manuellement les traductions, utilisez loadDictionary :

src/loadDictionary.ts

export default async function loadDictionary(locale: string) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

Cela charge des fichiers de traduction JSON depuis votre répertoire public/locales/ :

es.json

fr.json

de.json

Configuration pour la production

Processus de build

Ajoutez la traduction à votre pipeline de build :

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...VOTRE_COMMANDE_DE_BUILD...>"
  }
}

Comportement en développement vs en production

Développement : Entrées du dictionary traduites à la demande avec la clé d’API de développement
Production : Toutes les traductions du dictionary sont générées lors de l’étape de build

Combiner avec des composants

Les dictionaries et les composants <T> peuvent fonctionner ensemble :

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Dictionary pour les chaînes simples */}
      <h1>{d('page.title')}</h1>
      
      {/* Composant T pour JSX complexe */}
      <T>
        <p>Ceci est un <strong>message complexe</strong> avec des <a href="/link">liens</a>.</p>
      </T>
      
      {/* Dictionary pour les étiquettes de formulaire */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Prochaines étapes

Guide des langues - Configurer les langues prises en charge et les paramètres de locale
Guide du contenu dynamique - Gérer les besoins de traduction à l’exécution
Référence de l’API :
- Hook useTranslations
- Fonction getTranslations

Dictionnaires

Sur cette page

Dictionnaires

Sur cette page

Dictionnaires

Sur cette page

GitHubMettre une étoile sur GitHub

GitHubMettre une étoile sur GitHub

Mettre une étoile sur GitHub

Mettre une étoile sur GitHub