Traduire le JSX

Aperçu

Ce guide vous expliquera comment utiliser le composant <T> pour internationaliser le contenu JSX.

À la fin de ce guide, vous connaîtrez la syntaxe correcte pour utiliser le composant <T> et ce qu'il faut éviter.

Nous aborderons les points suivants :

Si vous cherchez comment utiliser les Variable Components ou les Branching Components, veuillez consulter leurs guides respectifs.

Comment utiliser le composant <T>

Supposons que vous ayez du contenu HTML que vous souhaitez traduire.

function Greeting() {
  return <p>Hello, world!</p>;
}

Tout ce que vous avez à faire, c'est d'entourer le contenu avec un composant <T>.

import { T } from 'gt-next';

function Greeting() {
  return <T><p>Hello, world!</p></T>;
}

Selon la langue actuellement sélectionnée par votre utilisateur, cela affichera la traduction appropriée. Consultez la page changer de langue pour plus d'informations sur la façon de permettre à vos utilisateurs de changer de langue.

Options supplémentaires

Contexte

Dans certains cas, vous pouvez vouloir fournir un contexte supplémentaire à la traduction. Cela peut être fait en passant une prop context au composant <T>.

<T context="toast, as in a pop-up notification">
  Click on the toast to dismiss it.
</T>

Ceci est utile dans les cas où des mots peuvent avoir plusieurs significations selon le contexte. Par exemple, "toast" peut désigner l'aliment ou une notification contextuelle.

La prop context aide l'IA à comprendre l'intention de la traduction.

id

Vous pouvez également passer une prop id au composant <T>. Ceci est utile à des fins de débogage et facilite la modification de la traduction.

<T id="toast">
  Click on the toast to dismiss it.
</T>

Quand utiliser le composant <T>

Bien que le composant <T> soit très flexible, il n'est pas toujours la meilleure solution.

Vous devriez toujours essayer d'utiliser le composant <T> lorsque vous avez du contenu HTML ou JSX statique.

Quand ne pas utiliser le composant <T>

NE PAS utiliser le composant <T> lorsque vous avez du contenu dynamique non sécurisé.

Ici, le contenu dynamique signifie tout contenu qui pourrait changer à l'exécution. Cette règle ne s'applique pas si vous utilisez des Variable Components ou des Branching Components.

Les exemples suivants montrent une utilisation incorrecte du composant <T> :

<T>
  <p>Your username is {username}</p>
</T>

<T>
  <p>Current date: {new Date().toLocaleDateString()}</p>
</T>

<T>
  <p>Logical Expressions: {username === 'admin' ? 'Yes' : 'No'}</p>
</T>

<T>
  <p>Conditional Rendering: {isAdmin ? 'Yes' : 'No'}</p>
</T>

const chatMessage = getChatMessageFromServer();
<T>
  <p>{chatMessage}</p>
</T>

Exemples

Voici quelques exemples d'utilisation du composant <T>. Tous ces exemples sont corrects.

1. Contenu HTML

<T>
  <p>Bonjour, monde&nbsp;!</p>
</T>

<p>Hello, world!</p>

2. Contenu JSX simple

<T>
  <Button>Cliquez-moi&nbsp;!</Button>
</T>

<Button>Click me!</Button>

3. Contenu JSX complexe

<T>
  <Tooltip>
    <TooltipTrigger>
      <div className="flex items-center gap-2 rounded-full bg-destructive px-3 py-1.5 text-sm text-destructive-foreground">
        <AlertCircle className="h-4 w-4" />
        <span>Utilisation gratuite</span>
      </div>
    </TooltipTrigger>
    <TooltipContent>
      <p>
        Vous approchez de votre limite mensuelle gratuite. Veuillez
        mettre à niveau votre abonnement pour éviter toute interruption
        de service.
      </p>
    </TooltipContent>
  </Tooltip>
</T>

<Tooltip>
  <TooltipTrigger>
    <div className="flex items-center gap-2 rounded-full bg-destructive px-3 py-1.5 text-sm text-destructive-foreground">
      <AlertCircle className="h-4 w-4" />
      <span>Free Usage</span>
    </div>
  </TooltipTrigger>
  <TooltipContent>
    <p>
      You are nearing your free monthly limit. Please
      upgrade your plan to avoid any disruptions to your
      service.
    </p>
  </TooltipContent>
</Tooltip>

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 tutoriel 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, le composant <T> traduira le contenu à la demande. Cela signifie que lorsque le composant est rendu, il effectue immédiatement une traduction. La bibliothèque fait 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, toutes les traductions utilisées par le composant <T> sont réalisées au moment du build. Cela signifie que vous devez exécuter la commande de traduction avant de déployer votre application.

Problèmes de confidentialité

À quelques exceptions près, tout contenu enveloppé dans un composant <T> est envoyé à l’API de traduction générale pour être traduit. Cela peut ne pas être souhaitable pour l’affichage de données sensibles, telles que des noms d’utilisateur, des numéros de compte, etc.

Pour contourner ce problème, utilisez les Variable Components pour gérer les informations privées. Cela garantit qu’aucune donnée sensible n’est envoyée à l’API de traduction générale. La localisation de tout contenu enveloppé dans un composant variable est gérée localement.

Pièges courants

Descendants directs uniquement

Le composant <T> ne traduit que le texte passé directement en tant qu’enfant. Cela signifie que si vous avez du contenu à l’intérieur d’un composant qui n’est pas directement passé à <T>, il ne sera pas traduit.

Illustrons cela avec un exemple :

function UntranslatedContent() {
  return (
    <p>This content is not translated</p>
  );
}

export default function DisplayGreetings() {
  return (
    <T>
      <h1>Hello, this text will be translated</h1>
      <UntranslatedContent />
    </T>
  );
}

Dans cet exemple, le contenu à l’intérieur de <UntranslatedContent> ne sera pas traduit. Seul le contenu directement à l’intérieur de <T> sera traduit, comme la balise <h1> et ses enfants.

Quelle est la solution ?

Enveloppez le texte directement dans le composant <T>, comme ceci :

function TranslatedContent() {
  return (
    <T>
      <p>This content <b>IS</b> translated</p>
    </T>
  );
}

export default function DisplayGreetings() {
  return (
    <>
      <T>
        <h1>Hello, this text will be translated</h1>
      </T>
      <TranslatedContent />
    </>
  );
}

Composants <T> imbriqués

L’imbrication des composants <T> n’est pas autorisée. En raison du système de rendu de React, cela peut entraîner un comportement inattendu et des problèmes de performance.

Voici un exemple de ce qu’il ne faut pas faire :

function SomeComponent() {
  return (
    <T>
      Hello, friend!
    </T>
  );
}

export default function NestedTranslation() {
  return (
    <T>
      <T> {/* Don't do this! */} 
        Hello, world! 
      </T>
      <SomeComponent /> {/* This still counts. Don't do this! */}
    </T>
  );
}

La solution ici est de supprimer le composant <T> le plus externe.

Traduction de contenu dynamique

Si vous essayez d’envelopper du contenu dynamique avec le composant <T>, l’outil CLI renverra une erreur.

Par exemple, ce qui suit provoquera une erreur :

const username = 'John Doe';
<T>
  <p>Your username is {username}</p>
</T>

Pour contourner ce problème, essayez d’utiliser les Variable Components ou les Branching Components pour envelopper le contenu dynamique.

Sinon, si votre contenu est vraiment dynamique et doit être traduit à la demande, vous pouvez utiliser le composant <Tx>.

Résumé

• Les composants <T> sont utilisés pour internationaliser du contenu JSX arbitraire.
• Les composants <T> ne doivent pas être utilisés pour du contenu dynamique, sans utiliser de composants de variable ou de composants conditionnels.
• En développement, le composant <T> traduira le contenu à la demande.
• En production, toutes les traductions utilisées par le composant <T> sont réalisées lors de la phase de build.

Prochaines étapes

• Lisez à propos de l'API pour le composant <T>.
• Explorez les composants de variables et les composants de branchement.
• Découvrez comment traduire des chaînes.