Dictionnaires

Aperçu

Dans ce guide, nous allons vous présenter les dictionnaires. N'hésitez pas à parcourir cette page selon vos besoins. Nous aborderons les points suivants :

Qu'est-ce qu'un 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. Ils peuvent être stockés dans un fichier .ts, .js ou .json.

gt-next vous permet d'utiliser des dictionnaires seuls, ou en conjonction avec des 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.
2. Anté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 i18n.

En même temps, il présente plusieurs inconvénients majeurs :

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 et est stocké séparément. Cela rend la maintenance et la mise à jour des traductions beaucoup plus difficiles.
4. Débogabilité : Pour la même raison, les dictionnaires sont plus difficiles à déboguer que le composant <T>. Lorsque vous essayez de déboguer un composant React, vous devrez retrouver où le contenu du dictionnaire est utilisé, plutôt que de simplement rechercher directement dans votre base de code.

Les deux modèles de conception sont pris en charge par notre bibliothèque et ne sont pas mutuellement exclusifs. Vous pouvez utiliser un dictionnaire en parallèle des composants <T>.

Notre conseil

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

Comment utiliser les dictionnaires

Dans cette section, nous allons vous montrer comment mettre en place une implémentation de dictionnaire minimaliste 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|json] qui contient tout le contenu que vous souhaitez traduire.

Ajoutez le contenu suivant à votre fichier dictionary :

const dictionary = {
  greetings: {
    hello: 'Hello, World!'
  },
}

export default dictionary;

{
  "greetings": {
    "hello": "Hello, World!"
  }
}

La fonction withGTConfig() détectera automatiquement le fichier dictionnaire à la racine de votre projet ou dans le répertoire src.

Étape 2 : Référencer le dictionnaire

Vous pouvez accéder aux entrées du dictionnaire avec le hook useDict() ou la fonction getDict(). Il suffit d'utiliser la fonction retournée par le hook pour accéder aux entrées du dictionnaire par clé.

import { useDict } from 'gt-next';

export default function MyComponent() {
  const d = useDict();
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

import { getDict } from 'gt-next';

export default async function MyComponent() {
  const d = await getDict();
  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 les 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}!',    // -> Hello, Alice!
    goodbye: 'Goodbye, {name}!' // -> Goodbye, Bob!
  },
}
export default dictionary;

import { useDict } from 'gt-next';

export default async function MyComponent() {
  const d = useDict();
  return (
    <div>
      {d('greetings.hello', { variables: { name: 'Alice' }})}
      {d('greetings.goodbye', { variables: { name: 'Bob' }})}
    </div>
  );
}

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

Préfixes

De plus, avec useDict(), 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 { useDict } from 'gt-next';

export default async function MyComponent() {
  // Tous les chemins de traduction comme 'hello' seront préfixés par 'greetings.common.'
  const d = useDict('greetings.common'); 

  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </div>
  );
}

Considérations de 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 à 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 && <YOUR_BUILD_COMMAND>",
  }
}

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

Comportement : Développement vs Production

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

Pour activer ce comportement, il suffit d'ajouter une clé API Dev à votre environnement.

En production, la fonction d() traduira le contenu au moment du build. 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 complément des composants <T> ou de manière autonome.
• Les traductions des dictionnaires ont lieu lors de la construction, vous devez donc ajouter la commande translate à votre processus de build.
• 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 grâce à notre guide de déploiement.