Dictionnaires

Les dictionnaires offrent une approche traditionnelle pour organiser les traductions dans des objets imbriqués avec des paires clé‑valeur. Bien que les composants <T> soient l’approche recommandée, les dictionnaires peuvent être utiles lors de la migration depuis d’autres bibliothèques i18n ou si 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 faciliter la migration et la compatibilité avec des flux de travail de traduction existants.

dictionary vs traduction par composant

Modèle 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, monde !</div></T>;
}

Arbitrages

Avantages du dictionary

Stockage centralisé - Toutes les traductions regroupées en un seul endroit
Standard du secteur - Modèle familier d’autres bibliothèques i18n
Adapté aux migrations - Facile de migrer des traductions existantes

Inconvénients du dictionary

Complexité - Plus de configuration et de réglages nécessaires
Maintenabilité - Le contenu, séparé de son utilisation, rend les mises à jour plus difficiles
Débogabilité - Plus difficile de remonter des traductions jusqu’aux composants
Lisibilité - Les clés ne reflètent pas le contenu réel

Prise en main rapide

Étape 1 : Créer un dictionary

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

dictionary.ts

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

export default dictionary;

Ou utilisez le format JSON :

dictionary.json

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

La fonction withGTConfig détecte 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 côté client

import { useTranslations } from 'gt-next';

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

Composants Server

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 à l’aide de la syntaxe {variable} :

dictionary.ts

const dictionary = {
  user: {
    greeting: 'Bonjour {name} !',
    itemCount: 'Vous avez {count} articles',
    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>
  );
}

Utiliser des préfixes

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

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: 'Bienvenue !',
      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 à 'tableau de bord.header'
  const d = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{d('welcome')}</h1> {/* -> tableau de bord.header.welcome */}
      <p>{d('lastLogin', { date: 'Aujourd\'hui' })}</p> {/* -> tableau de bord.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Préfixe différent pour la section statistiques
  const d = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{d('totalUsers', { count: 1000 })}</p> {/* -> tableau de bord.stats.totalUsers */}
      <p>{d('activeUsers', { count: 150 })}</p> {/* -> tableau de bord.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 files 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 les traductions manuellement, 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 lors de la migration de 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 && <...YOUR_BUILD_COMMAND...>"
  }
}

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 précompilé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 du JSX complexe */}
      <T>
        <p>Ceci est un <strong>message complexe</strong> avec des <a href="/link">liens</a>.</p>
      </T>
      
      {/* dictionary pour les libellés 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 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, monde !</div></T>;
}

Arbitrages

Avantages du dictionary

Stockage centralisé - Toutes les traductions regroupées en un seul endroit
Standard du secteur - Modèle familier d’autres bibliothèques i18n
Adapté aux migrations - Facile de migrer des traductions existantes

Inconvénients du dictionary

Complexité - Plus de configuration et de réglages nécessaires
Maintenabilité - Le contenu, séparé de son utilisation, rend les mises à jour plus difficiles
Débogabilité - Plus difficile de remonter des traductions jusqu’aux composants
Lisibilité - Les clés ne reflètent pas le contenu réel

Prise en main rapide

Étape 1 : Créer un dictionary

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

dictionary.ts

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

export default dictionary;

Ou utilisez le format JSON :

dictionary.json

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

La fonction withGTConfig détecte 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 côté client

import { useTranslations } from 'gt-next';

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

Composants Server

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 à l’aide de la syntaxe {variable} :

dictionary.ts

const dictionary = {
  user: {
    greeting: 'Bonjour {name} !',
    itemCount: 'Vous avez {count} articles',
    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>
  );
}

Utiliser des préfixes

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

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: 'Bienvenue !',
      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 à 'tableau de bord.header'
  const d = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{d('welcome')}</h1> {/* -> tableau de bord.header.welcome */}
      <p>{d('lastLogin', { date: 'Aujourd\'hui' })}</p> {/* -> tableau de bord.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Préfixe différent pour la section statistiques
  const d = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{d('totalUsers', { count: 1000 })}</p> {/* -> tableau de bord.stats.totalUsers */}
      <p>{d('activeUsers', { count: 150 })}</p> {/* -> tableau de bord.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 files 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 les traductions manuellement, 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 && <...YOUR_BUILD_COMMAND...>"
  }
}

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 précompilé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 du JSX complexe */}
      <T>
        <p>Ceci est un <strong>message complexe</strong> avec des <a href="/link">liens</a>.</p>
      </T>
      
      {/* dictionary pour les libellés 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 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, monde !</div></T>;
}

Arbitrages

Avantages du dictionary

Stockage centralisé - Toutes les traductions regroupées en un seul endroit
Standard du secteur - Modèle familier d’autres bibliothèques i18n
Adapté aux migrations - Facile de migrer des traductions existantes

Inconvénients du dictionary

Complexité - Plus de configuration et de réglages nécessaires
Maintenabilité - Le contenu, séparé de son utilisation, rend les mises à jour plus difficiles
Débogabilité - Plus difficile de remonter des traductions jusqu’aux composants
Lisibilité - Les clés ne reflètent pas le contenu réel

Prise en main rapide

Étape 1 : Créer un dictionary

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

dictionary.ts

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

export default dictionary;

Ou utilisez le format JSON :

dictionary.json

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

La fonction withGTConfig détecte 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 côté client

import { useTranslations } from 'gt-next';

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

Composants Server

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 à l’aide de la syntaxe {variable} :

dictionary.ts

const dictionary = {
  user: {
    greeting: 'Bonjour {name} !',
    itemCount: 'Vous avez {count} articles',
    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>
  );
}

Utiliser des préfixes

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

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: 'Bienvenue !',
      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 à 'tableau de bord.header'
  const d = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{d('welcome')}</h1> {/* -> tableau de bord.header.welcome */}
      <p>{d('lastLogin', { date: 'Aujourd\'hui' })}</p> {/* -> tableau de bord.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Préfixe différent pour la section statistiques
  const d = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{d('totalUsers', { count: 1000 })}</p> {/* -> tableau de bord.stats.totalUsers */}
      <p>{d('activeUsers', { count: 150 })}</p> {/* -> tableau de bord.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 files 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 les traductions manuellement, 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 && <...YOUR_BUILD_COMMAND...>"
  }
}

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 précompilé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 du JSX complexe */}
      <T>
        <p>Ceci est un <strong>message complexe</strong> avec des <a href="/link">liens</a>.</p>
      </T>
      
      {/* dictionary pour les libellés 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