Dictionaries

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

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

dictionary vs traduction par composants

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 au même endroit
Standard de l’industrie - Modèle familier issu d’autres bibliothèques i18n
Compatible avec les migrations - Facile de migrer des traductions existantes

Inconvénients du dictionary

Complexité - Davantage d’installation et de configuration nécessaires
Maintenabilité - Le contenu séparé de son utilisation complique les mises à jour
Débogabilité - Plus difficile de faire remonter les traductions jusqu’aux composants
Lisibilité - Les clés n’affichent 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 le monde !",
    "welcome": "Bienvenue sur notre application !",
  },
  "navigation": {
    "home": "Accueil", 
    "about": "À propos",
    "contact": "Contact"
  }
}

Vous le transmettez ensuite à 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} 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>
  );
}

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: '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;

Ensuite, créez une fonction loadTranslations pour charger les files 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.

Files de traduction manuelle (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 les files 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 files de traduction existants.

Configuration pour la production

Processus de build

Intégrez 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 une clé d’API de développement
Production : Toutes les traductions du dictionary pré-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 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 au runtime
Référence de l’API :
- Crochet useTranslations

dictionary vs traduction par composants

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 au même endroit
Standard de l’industrie - Modèle familier issu d’autres bibliothèques i18n
Compatible avec les migrations - Facile de migrer des traductions existantes

Inconvénients du dictionary

Complexité - Davantage d’installation et de configuration nécessaires
Maintenabilité - Le contenu séparé de son utilisation complique les mises à jour
Débogabilité - Plus difficile de faire remonter les traductions jusqu’aux composants
Lisibilité - Les clés n’affichent 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 le monde !",
    "welcome": "Bienvenue sur notre application !",
  },
  "navigation": {
    "home": "Accueil", 
    "about": "À propos",
    "contact": "Contact"
  }
}

Vous le transmettez ensuite à 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} 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>
  );
}

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: '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;

Ensuite, créez une fonction loadTranslations pour charger les files 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>
);

Files de traduction manuelle (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 les files de traduction JSON depuis votre répertoire public/locales/ :

es.json

fr.json

de.json

Configuration pour la production

Processus de build

Intégrez 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 une clé d’API de développement
Production : Toutes les traductions du dictionary pré-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 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 au runtime
Référence de l’API :
- Crochet useTranslations

dictionary vs traduction par composants

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 au même endroit
Standard de l’industrie - Modèle familier issu d’autres bibliothèques i18n
Compatible avec les migrations - Facile de migrer des traductions existantes

Inconvénients du dictionary

Complexité - Davantage d’installation et de configuration nécessaires
Maintenabilité - Le contenu séparé de son utilisation complique les mises à jour
Débogabilité - Plus difficile de faire remonter les traductions jusqu’aux composants
Lisibilité - Les clés n’affichent 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 le monde !",
    "welcome": "Bienvenue sur notre application !",
  },
  "navigation": {
    "home": "Accueil", 
    "about": "À propos",
    "contact": "Contact"
  }
}

Vous le transmettez ensuite à 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} 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>
  );
}

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: '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;

Ensuite, créez une fonction loadTranslations pour charger les files 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>
);

Files de traduction manuelle (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 les files de traduction JSON depuis votre répertoire public/locales/ :

es.json

fr.json

de.json

Configuration pour la production

Processus de build

Intégrez 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 une clé d’API de développement
Production : Toutes les traductions du dictionary pré-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 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 au runtime
Référence de l’API :
- Crochet useTranslations

Dictionaries

Sur cette page

Dictionaries

Sur cette page

Dictionaries

Sur cette page

GitHubMettre une étoile sur GitHub

GitHubMettre une étoile sur GitHub

Mettre une étoile sur GitHub

Mettre une étoile sur GitHub