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 vous montrerons comment configurer une implémentation de dictionnaire de base dans votre application Next.js. Nous passerons en revue 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 dans la racine de votre projet ou le répertoire src.

Étape 2 : Référencer le dictionnaire

Vous pouvez accéder aux entrées du dictionnaire avec le hook useTranslations() ou la fonction getTranslations(). Utilisez simplement la fonction retournée par le hook pour accéder aux entrées du dictionnaire par clé.

import { useTranslations } from 'gt-next';

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

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

export default async function MyComponent() {
  const d = await getTranslations();
  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 avez déjà des dictionnaires pour d'autres langues, vous pouvez les passer à la fonction loadDictionary.

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

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 { useTranslations } from 'gt-next';

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

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

Les chaînes de dictionnaire dans gt-next prennent en charge le format de message ICU, qui vous permet également de formater vos variables.

Préfixes

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

export default function MyComponent() {
  // Tous les chemins de traduction tels que 'hello' seront préfixés avec 'greetings.common.'
  const d = useTranslations('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 dans le cadre 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 vous référer au guide Deployment. Pour plus d'informations sur la commande, veuillez vous référer au guide de référence CLI Tool.

Comportement : Développement vs Production

En développement, la fonction retournée par le hook useTranslations() 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 de développement à 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.