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 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 les flux de travail de traduction existants.

dictionary vs traduction via 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>;
}

Modèle 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 issu d'autres bibliothèques i18n
Facile à migrer - Migration aisée des traductions existantes

Inconvénients du dictionary

Complexité - Nécessite davantage de configuration et de paramétrage
Maintenabilité - Le contenu étant séparé de son utilisation, les mises à jour sont plus difficiles
Débogabilité - Plus difficile de faire remonter une traduction jusqu’au composant
Lisibilité - Les clés ne reflètent pas le contenu réel

Démarrage 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"
  }
}

Ensuite, transmettez-le à votre composant <GTProvider> :

index.js

import dictionary from "./dictionary.js";
import config from "./gt.config.json";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider {...config} dictionary={dictionary}>
      <App />
    </GTProvider>
  </StrictMode>
);

Étape 2 : Utilisation dans les composants

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

import { useTranslations } from 'gt-react';

function MyComponent() {
  const d = useTranslations();
  
  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} é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 à l’aide 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 ensuite une fonction loadTranslations pour charger les fichiers de traduction générés :

src/loadTranslations.ts

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

Passez-le à votre <GTProvider> :

src/index.tsx

import loadTranslations from './loadTranslations';
import dictionary from './dictionary';

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider 
      {...config} 
      dictionary={dictionary}
      loadTranslations={loadTranslations}
    >
      <App />
    </GTProvider>
  </StrictMode>
);

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 pour migrer des fichiers de traduction existants.

Configuration pour la production

Processus de compilation

Ajoutez les traductions à votre pipeline de compilation :

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 une clé d’API de développement
Production : Toutes les traductions du dictionary sont générées à l’avance lors de l’étape de build

Combiner avec des composants

Les dictionaries et les <T> components 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

dictionary vs traduction via 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>;
}

Modèle 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 issu d'autres bibliothèques i18n
Facile à migrer - Migration aisée des traductions existantes

Inconvénients du dictionary

Complexité - Nécessite davantage de configuration et de paramétrage
Maintenabilité - Le contenu étant séparé de son utilisation, les mises à jour sont plus difficiles
Débogabilité - Plus difficile de faire remonter une traduction jusqu’au composant
Lisibilité - Les clés ne reflètent pas le contenu réel

Démarrage 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"
  }
}

Ensuite, transmettez-le à votre composant <GTProvider> :

index.js

import dictionary from "./dictionary.js";
import config from "./gt.config.json";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider {...config} dictionary={dictionary}>
      <App />
    </GTProvider>
  </StrictMode>
);

Étape 2 : Utilisation dans les composants

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

import { useTranslations } from 'gt-react';

function MyComponent() {
  const d = useTranslations();
  
  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} é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 à l’aide 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 ensuite une fonction loadTranslations pour charger les fichiers de traduction générés :

src/loadTranslations.ts

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

Passez-le à votre <GTProvider> :

src/index.tsx

import loadTranslations from './loadTranslations';
import dictionary from './dictionary';

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider 
      {...config} 
      dictionary={dictionary}
      loadTranslations={loadTranslations}
    >
      <App />
    </GTProvider>
  </StrictMode>
);

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 compilation

Ajoutez les traductions à votre pipeline de compilation :

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 une clé d’API de développement
Production : Toutes les traductions du dictionary sont générées à l’avance lors de l’étape de build

Combiner avec des composants

Les dictionaries et les <T> components 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

dictionary vs traduction via 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>;
}

Modèle 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 issu d'autres bibliothèques i18n
Facile à migrer - Migration aisée des traductions existantes

Inconvénients du dictionary

Complexité - Nécessite davantage de configuration et de paramétrage
Maintenabilité - Le contenu étant séparé de son utilisation, les mises à jour sont plus difficiles
Débogabilité - Plus difficile de faire remonter une traduction jusqu’au composant
Lisibilité - Les clés ne reflètent pas le contenu réel

Démarrage 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"
  }
}

Ensuite, transmettez-le à votre composant <GTProvider> :

index.js

import dictionary from "./dictionary.js";
import config from "./gt.config.json";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider {...config} dictionary={dictionary}>
      <App />
    </GTProvider>
  </StrictMode>
);

Étape 2 : Utilisation dans les composants

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

import { useTranslations } from 'gt-react';

function MyComponent() {
  const d = useTranslations();
  
  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} é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 à l’aide 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 ensuite une fonction loadTranslations pour charger les fichiers de traduction générés :

src/loadTranslations.ts

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

Passez-le à votre <GTProvider> :

src/index.tsx

import loadTranslations from './loadTranslations';
import dictionary from './dictionary';

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider 
      {...config} 
      dictionary={dictionary}
      loadTranslations={loadTranslations}
    >
      <App />
    </GTProvider>
  </StrictMode>
);

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 compilation

Ajoutez les traductions à votre pipeline de compilation :

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 une clé d’API de développement
Production : Toutes les traductions du dictionary sont générées à l’avance lors de l’étape de build

Combiner avec des composants

Les dictionaries et les <T> components 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

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