# gt-next: General Translation Next.js SDK: Dictionnaires
URL: https://generaltranslation.com/fr/docs/next/guides/dictionaries.mdx
---
title: Dictionnaires
description: Comment utiliser les approches de traduction traditionnelles basées sur des dictionnaires
---

Les dictionnaires offrent une approche classique pour organiser les traductions sous forme d’objets imbriqués avec des paires clé-valeur. Bien que les [composants `<T>`](/docs/next/guides/t) constituent l’approche recommandée, les dictionnaires peuvent être utiles pour migrer depuis d’autres bibliothèques d’i18n ou si vous préférez un stockage centralisé des traductions.

<Callout>
  **Recommandation :** Utilisez les [composants `<T>`](/docs/next/guides/t) pour les nouveaux projets. Les dictionnaires sont principalement pris en charge pour faciliter la migration et assurer la compatibilité avec les workflows de traduction existants.
</Callout>

## Traduction par dictionnaire vs par composant

### Approche par dictionnaire

```tsx
// dictionary.ts
export default {
  greetings: {
    hello: 'Hello, world!',
    welcome: 'Welcome, {name}!'
  }
};

// Utilisation du composant
function MyComponent() {
  const t = useTranslations();
  return <div>{t('greetings.hello')}</div>;
}
```


### Approche de composant

```tsx
// Utilisation directe du composant - recommandée
function MyComponent() {
  return <T><div>Hello, world!</div></T>;
}
```


## Arbitrages

### Avantages des dictionnaires

* **Stockage centralisé** - Toutes les traductions au même endroit
* **Standard du secteur** - Une approche familière issue d&#39;autres bibliothèques d&#39;i18n
* **Facilite les migrations** - Facile d&#39;importer des traductions existantes

### Inconvénients des dictionnaires

* **Complexité** - Nécessite plus de configuration et de mise en place
* **Maintenance** - Le fait de séparer le contenu de son usage complique les mises à jour
* **Débogage** - Il est plus difficile de rattacher les traductions aux composants
* **Lisibilité** - Les clés ne montrent pas le contenu réel

## Guide de démarrage rapide

### Étape 1 : Créer un dictionnaire

Créez un fichier de dictionnaire à la racine de votre projet ou dans le dossier `src` :

```ts title="dictionary.ts"
const dictionary = {
  greetings: {
    hello: 'Hello, world!',
    welcome: 'Welcome to our app!'
  },
  navigation: {
    home: 'Home',
    about: 'About',
    contact: 'Contact'
  }
};

export default dictionary;
```

Ou utilisez le format JSON :

```json title="dictionary.json"
{
  "greetings": {
    "hello": "Hello, world!",
    "welcome": "Welcome to our app!"
  },
  "navigation": {
    "home": "Home", 
    "about": "About",
    "contact": "Contact"
  }
}
```

La fonction [`withGTConfig`](/docs/next/api/config/with-gt-config) détectera automatiquement le fichier de dictionnaire à la racine de votre projet ou dans le dossier `src`.


### Étape 2 : Utiliser dans les composants

Le hook [`useTranslations`](/docs/next/api/dictionary/use-translations) vous permet d’accéder aux entrées du dictionnaire :

#### Composants côté client

```tsx
import { useTranslations } from 'gt-next';

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


#### Composants serveur

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

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


## Utilisation de variables

Ajoutez des variables aux entrées du dictionnaire à l’aide de la syntaxe `{variable}` :

```ts title="dictionary.ts"
const dictionary = {
  user: {
    greeting: 'Hello, {name}!',
    itemCount: 'You have {count} items',
    orderTotal: 'Total: ${amount}'
  }
};
```

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


## Utilisation des préfixes

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

```ts title="dictionary.ts"
const dictionary = {
  dashboard: {
    header: {
      welcome: 'Welcome back!',
      lastLogin: 'Last login: {date}'
    },
    stats: {
      totalUsers: 'Total Users: {count}',
      activeUsers: 'Active Users: {count}'
    }
  }
};
```

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

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


## Prise en charge multilingue

### Traduction automatique (recommandée)

La plupart des utilisateurs devraient utiliser [`loadTranslations`](/docs/next/api/config/load-translations) pour générer automatiquement les traductions à partir de votre dictionnaire de base :

```ts title="dictionary.ts"  
const dictionary = {
  common: {
    save: 'Save',
    cancel: 'Cancel',
    delete: 'Delete'
  },
  forms: {
    required: 'This field is required',
    email: 'Please enter a valid email'
  }
};

export default dictionary;
```

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

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

[`withGTConfig`](/docs/next/api/config/with-gt-config) détecte automatiquement le fichier `loadTranslations.[js|ts]` dans votre répertoire `src/` ou à la racine du projet.

GT génère automatiquement les traductions dans les autres langues à partir de votre dictionnaire de base. Exécutez `npx gt translate` pour générer les traductions pour toutes les langues configurées.


### Fichiers de traduction manuels (migration)

Pour migrer depuis d’autres bibliothèques d’i18n ou depuis une gestion manuelle des traductions, utilisez [`loadDictionary`](/docs/next/api/config/load-dictionary):

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

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

<Files>
  <Folder name="my-app" defaultOpen={true}>
    <Folder name="public" defaultOpen={true}>
      <Folder name="locales" defaultOpen={true}>
        <File name="es.json" />

        <File name="fr.json" />

        <File name="de.json" />
      </Folder>
    </Folder>

    <Folder name="src">
      <File name="loadDictionary.ts" />
    </Folder>
  </Folder>
</Files>

<Callout>
  **Choisissez la bonne approche :** utilisez [`loadTranslations`](/docs/next/api/config/load-translations) pour les nouveaux projets avec génération automatique des traductions, ou [`loadDictionary`](/docs/next/api/config/load-dictionary) si vous migrez des fichiers de traduction existants.
</Callout>


## Configuration en production

### Processus de build

Ajoutez la traduction à votre pipeline de build :

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && <...YOUR_BUILD_COMMAND...>"
  }
}
```


### Comportement en développement et en production

* **Développement** : les entrées du dictionnaire sont traduites à la demande avec la clé API de développement
* **Production** : toutes les traductions du dictionnaire sont générées à l’avance lors de l’étape de build

## Combiner avec des composants

Les dictionnaires et les [composants `<T>`](/docs/next/guides/t) peuvent fonctionner ensemble :

```tsx
function MixedApproach() {
  const t = useTranslations();
  
  return (
    <div>
      {/* Dictionnaire pour les chaînes simples */}
      <h1>{t('page.title')}</h1>
      
      {/* Composant T pour le JSX complexe */}
      <T>
        <p>This is a <strong>complex message</strong> with <a href="/link">links</a>.</p>
      </T>
      
      {/* Dictionnaire pour les libellés de formulaire */}
      <label>{t('forms.email')}</label>
    </div>
  );
}
```


## Étapes suivantes

<Callout>
  **Voyez-le en action :** Découvrez l’[application d’exemple de l’approche par dictionnaire](https://github.com/gt-examples/dictionary-pattern) avec une démo fonctionnelle — [aperçu en direct](https://dictionary-pattern.generaltranslation.dev).
</Callout>

* [Guide des langues](/docs/next/guides/languages) - Configurez les langues prises en charge et les paramètres régionaux
* [Guide du contenu dynamique](/docs/next/guides/dynamic-content) - Gérez les besoins de traduction au runtime
* Références d’API :
  * [hook `useTranslations`](/docs/next/api/dictionary/use-translations)
  * [fonction `getTranslations`](/docs/next/api/dictionary/get-translations)