Référence des Dictionnaires

Aperçu

Dans ce guide de référence, nous vous présenterons le modèle de dictionnaire. N'hésitez pas à parcourir cette page selon vos besoins. Nous couvrirons les points suivants :

• Qu'est-ce qu'un dictionnaire ?
• Comment utiliser les dictionnaires
• Chargement de dictionnaires pour d'autres langues
• Utilisation des dictionnaires
• Considérations pour la production

Qu'est-ce qu'un dictionnaire ?

La Traduction Générale permet de stocker le contenu traduisible dans un fichier dictionnaire. Un dictionnaire est un objet imbriqué avec des valeurs de type chaîne de caractères qui peut être utilisé pour stocker du contenu traduisible. Ce fichier dictionnaire (.ts, .js, ou .json) est ensuite utilisé pour générer une traduction.

Les dictionnaires peuvent être utilisés seuls ou en conjonction avec les composants <T>.

Dictionnaire vs Composants <T>

Le modèle de dictionnaire présente quelques avantages par rapport au composant <T> :

1. Stockage centralisé : Les dictionnaires stockent tout le contenu traduisible dans un seul fichier, ce qui facilite sa gestion et sa mise à jour.
2. Précédent historique : Le modèle de dictionnaire est un modèle de conception courant dans l'industrie et est utilisé par de nombreuses autres bibliothèques.

En même temps, il présente également quelques inconvénients :

1. Complexité : Les dictionnaires sont plus complexes à configurer et à utiliser que le composant <T>.
2. Lisibilité : Les dictionnaires sont moins lisibles que le composant <T> car le contenu n'est pas en ligne.
3. Maintenabilité : Les dictionnaires sont plus difficiles à maintenir que le composant <T> car le contenu n'est pas en ligne, mais est stocké séparément. Cela rend le débogage et la maintenance des traductions beaucoup plus difficiles.

Les deux modèles de conception sont pris en charge par notre bibliothèque et ne s'excluent pas mutuellement. Vous pouvez utiliser un dictionnaire aux côtés des composants <T>.

Notre conseil

Nous recommandons d'utiliser le composant <T> en raison de sa simplicité, surtout si vous débutez dans l'internationalisation (i18n). Nous offrons la prise en charge des dictionnaires pour ceux qui préfèrent ce modèle de conception basé sur des expériences passées ou pour faciliter l'intégration avec des bases de code existantes.

Comment utiliser les dictionnaires

Dans cette section, nous vous montrerons comment mettre en place une implémentation de base d'un dictionnaire dans votre application Next.js. Nous allons parcourir les étapes suivantes :

Étape 1 : Créer un dictionnaire

La première étape consiste à créer un dictionnaire. Il s'agit d'un fichier dictionary.js (.ts ou .json) qui contient tout le contenu que vous souhaitez traduire. Créez le dictionnaire dans votre répertoire src/.

Si vous n'utilisez pas de dossier src/, vous pouvez également spécifier le répertoire du dictionnaire dans le fichier next.config.js.

Ajoutez le contenu suivant à votre fichier dictionary.js :

const dictionary = {
  greetings: {
    goodbye: 'Goodbye, World!'
  },
}
export default dictionary;

{
  "greetings": {
    "goodbye": "Goodbye, World!"
  }
}

Étape 2 : Référencer le dictionnaire

Il existe plusieurs façons d'utiliser le dictionnaire, selon le contexte dans lequel vous essayez de l'utiliser. Par exemple, si vous êtes dans un composant côté client, utilisez le hook useDict() et pour les composants côté serveur, utilisez await getDict().

Voici un exemple d'utilisation du dictionnaire dans un composant côté client :

"use client";
import { useDict } from 'gt-next/client';
 
export default function MyComponent() {
 
  const d = useDict(); // côté client, vous utilisez le hook useDict
 
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

Et voici un exemple d'accès aux traductions dans un composant côté serveur :

import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
 
  const d = await getDict(); // côté serveur, vous devez attendre une promesse
 
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

Chargement des dictionnaires pour d'autres langues

Par défaut, les développeurs ne fournissent qu'un dictionnaire pour la langue par défaut.

General Translation génère automatiquement des dictionnaires pour d'autres langues et les charge avec la fonction loadTranslations.

Cependant, si vous migrez depuis une autre bibliothèque i18n ou si vous disposez déjà de dictionnaires pour d'autres langues, vous pouvez les transmettre à la fonction loadDictionary.

gt-next chargera automatiquement le dictionnaire correspondant à la locale demandée lors de l'utilisation du hook useDict() ou de la fonction getDict().

Consultez la Référence API pour plus d'informations.

Utilisation des dictionnaires

Variables

Vous pouvez ajouter des variables à votre dictionnaire en utilisant la syntaxe {variable} :

const dictionary = {
  greetings: {
    hello: 'Hello, {name}!',
    goodbye: 'Goodbye, {name}!'
  },
}
export default dictionary;

import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
  const d = await getDict();
 
  return (
    <div>
      {d('greetings.hello', { variables: { name: 'World' }})}
      {d('greetings.goodbye', { variables: { name: 'World' }})}
    </div>
  );
}

Lisez plus sur l'ajout de variables à votre dictionnaire dans le type DictionaryTranslationOptions.

Préfixes

De plus, avec useDict() et getDict(), vous pouvez passer un préfixe à la fonction pour spécifier un chemin partagé dans le dictionnaire. Ceci est utile si vous avez un chemin partagé dans votre dictionnaire que vous souhaitez utiliser dans plusieurs composants.

const dictionary = {
  greetings: {
    common: {
      hello: 'Hello, World!',
      goodbye: 'Goodbye, World!'
    },
  },
}
export default dictionary;

import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
  // Tous les chemins de traduction tels que 'hello' seront préfixés par 'greetings'
  const d = await getDict('greetings.common'); 
 
  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </div>
  );
}

Sous-ensembles avec <GTProvider>

Vous pouvez également spécifier un préfixe dans le composant <GTProvider>. Cela passera un sous-ensemble du dictionnaire au client, de sorte que le dictionnaire entier n'a pas besoin d'être chargé. Cela s'applique uniquement aux composants côté client.

import { GTProvider } from 'gt-next';
 
export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <body>
                <GTProvider id="nested.dictionary.key"> // [!code highlight]
                    {children}
                </GTProvider> // [!code highlight]
            </body>
        </html>
    );
}

Vous devez toujours spécifier le chemin complet lors de la référence à une clé dans le dictionnaire.

"use client";
 
import { useDict } from 'gt-next/client';
 
export default function MyComponent() {
  const d = useDict();
 
  return (
    <div>
      {d('nested.dictionary.key.greeting')} // [!code highlight]
    </div>
  );
}

Considérations pour la production

Déploiement en production

Assurez-vous d'exécuter la commande translate avant de déployer en production, afin que toutes les traductions soient disponibles au moment de l'exécution. Nous recommandons de l'ajouter à votre pipeline CD ou comme partie de votre script de build.

{
  "scripts": {
    "build": "npx gtx-cli translate --languages fr es ja && <YOUR_BUILD_COMMAND>",
  }
}

C'est tout ! Vous avez réussi à traduire votre application en français, espagnol et japonais.

Pour un guide plus détaillé sur le déploiement de votre application, veuillez consulter le guide de Déploiement. Pour plus d'informations sur la commande, veuillez consulter le guide de référence de l'Outil CLI.

Comportement : Développement vs Production

En développement, la fonction d() traduira les entrées du dictionnaire à la demande. Cela signifie que lorsque le composant est rendu, il effectuera une traduction immédiatement. Nous faisons cela par commodité pour faciliter le développement avec d'autres langues.

Pour activer ce comportement, ajoutez simplement une clé API Dev à votre environnement.

En production, la fonction d() traduira le contenu au moment de la compilation. Cela signifie que vous devez exécuter la commande de traduction avant de déployer votre application.

Notes

• Les dictionnaires sont une alternative au composant <T>. Ils peuvent être utilisés en conjonction avec des composants <T> ou de manière autonome.
• Les traductions de dictionnaire se produisent au moment de la construction, vous devez donc ajouter la commande translate à votre processus de construction.
• Les dictionnaires peuvent être utilisés avec des préfixes pour spécifier un sous-ensemble du dictionnaire.

Prochaines étapes

• Découvrez le composant <T> et comment l'utiliser dans votre application Next.js.
• Apprenez à déployer en production avec notre guide de déploiement.