Référence des Dictionnaires

Un aperçu du Modèle de Dictionnaire

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 ?

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 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 React. Nous allons parcourir les étapes suivantes :

Créer un dictionnaire

Référencer le dictionnaire

Étape 1 : Créer un dictionnaire

La première étape consiste à créer un dictionnaire. Il s'agit d'un fichier dictionary.js (.json) qui contient tout le contenu que vous souhaitez traduire.

Ajoutez le contenu suivant à votre fichier dictionary.js :

src/dictionary.js
const dictionary = {
  greetings: {
    hello: 'Hello, World!'
  },
}
 
export default dictionary;

Vous pouvez également utiliser un fichier dictionary.json pour stocker votre dictionnaire. C'est utile si vous migrez depuis une autre bibliothèque ou si vous préférez utiliser des fichiers JSON. Voici un exemple de fichier dictionary.json :

src/dictionary.json
{
  "greetings": {
    "hello": "Hello, World!"
  }
}

Ensuite, vous le transmettez à votre composant <GTProvider> :

index.js
import dictionary from "./dictionary.js";
 
createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider locales={['es', 'fr']} dictionary={dictionary}> // [!code highlight]
      <App />
    </GTProvider>
  </StrictMode>
);

Étape 2 : Référencer le dictionnaire

Vous pouvez accéder aux entrées du dictionnaire avec le hook useDict(). Utilisez simplement la fonction d() pour accéder aux entrées du dictionnaire par identifiant.

src/components/MyComponent.js
import { useDict } from 'gt-react';
 
export default function MyComponent() {
 
  const d = useDict(); 
 
  return (
    <div>
      {d('greetings.hello')} // [!code highlight]
    </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-react chargera automatiquement le dictionnaire correspondant pour 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} :

src/dictionary.js
const dictionary = {
  greetings: {
    hello: 'Hello, {name}!',    // -> Hello, Alice!
    goodbye: 'Goodbye, {name}!' // -> Goodbye, Bob!
  },
}
export default dictionary;
src/components/MyComponent.js
import { useDict } from 'gt-react';
 
export default async function MyComponent() {
  const d = useDict();
 
  return (
    <div>
      {d('greetings.hello', { variables: { name: 'Alice' }})}
      {d('greetings.goodbye', { variables: { name: 'Bob' }})}
    </div>
  );
}

Lisez 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.

src/dictionary.js
const dictionary = {
  greetings: {
    common: {
      hello: 'Hello, World!',
      goodbye: 'Goodbye, World!'
    },
  },
}
export default dictionary;
src/components/MyComponent.js
import { useDict } from 'gt-react';
 
export default async function MyComponent() {
  // Tous les chemins de traduction tels que 'hello' seront préfixés par 'greetings'
  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 de traduction 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 construction.

package.json
{
  "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 vous référer au guide de Déploiement. Pour plus d'informations sur la commande, veuillez vous référer au 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 pour plus de commodité afin de 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 de la construction. Cela signifie que vous devez exécuter la commande de traduction avant de déployer votre application.

Astuce : Si vous souhaitez simuler le comportement de production en développement, utilisez simplement une clé API de production dans votre build de développement.


Notes

  • Les dictionnaires sont une alternative au composant <T>. Ils peuvent être utilisés en conjonction avec les 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