Traduction des chaînes

Aperçu

Ce guide vous expliquera comment internationaliser les chaînes de caractères dans votre application Next.js en utilisant le hook useGT() et la fonction getGT().

Nous couvrirons les points suivants :

Quand utiliser le hook useGT()

Comment utiliser le hook useGT()

Utilisation des variables

Exemples

Pièges courants

Dans ce guide, lorsque nous faisons référence au hook useGT(), nous faisons également référence à la fonction getGT().

La seule différence entre les deux est quand les utiliser.

La fonction getGT() est une fonction asynchrone qui retourne une fonction promise, tandis que le hook useGT() retourne la fonction directement.

Utilisez la fonction getGT() dans les composants synchrones, et le hook useGT() dans les composants asynchrones.

src/app/page.tsx

import { useGT } from 'gt-next';
export function MyComponent() {
  const translate = useGT();
  const translatedString = translate('Hello, world!');
  return <div>{translatedString}</div>;
}

src/app/page.tsx

import { getGT } from 'gt-next/server';
export async function MyComponent() {
  const translate = await getGT();
  const translatedString = translate('Hello, world!');
  return <div>{translatedString}</div>;
}

Quand utiliser le hook `useGT()`

Le hook useGT() est un hook React qui peut être utilisé pour traduire des chaînes de caractères.

Dans la plupart des cas, vous pouvez utiliser le composant <T>. Cependant, dans les cas où le JSX n'est pas approprié, le hook useGT() peut être utilisé.

Voici quelques cas où le hook useGT() pourrait être plus approprié :

Dans des propriétés qui attendent strictement des chaînes de caractères, comme les attributs placeholder ou title.
Lorsque la chaîne fait partie d'un objet plus large, par exemple :

const user = {
  title: 'Mr.',
  name: 'John',
  description: 'John is a software engineer at General Translation',
}

Ici, seule la propriété description doit être traduite.

Dans la mesure du possible, vous devriez utiliser le composant <T>. Le composant <T> vous permet de traduire du contenu JSX, et c'est la méthode recommandée pour traduire des chaînes de caractères.

Comment utiliser le hook `useGT()`

Le hook useGT() doit être appelé à l'intérieur du <GTProvider>.

Pour traduire une chaîne de caractères, passez simplement la chaîne directement à la fonction retournée par le hook.

import { useGT } from 'gt-next';
export function MyComponent() {
  const translate = useGT();
  return <div>{translate('Hello, world!')}</div>;
}

Contrairement aux bibliothèques i18n traditionnelles, le hook useGT() ne nécessite pas de passer une key à la fonction. Au lieu de cela, la chaîne est passée directement à la fonction.

Cela signifie que vous n'avez pas besoin d'utiliser de dictionnaires !

Comment utiliser la fonction `getGT()`

D'autre part, puisque la fonction getGT() est une fonction asynchrone, elle peut être utilisée dans des composants async, et n'a pas besoin d'être appelée dans le <GTProvider>.

Le contexte pour getGT() est géré par la fonction withGTConfig dans votre fichier next.config.ts.

import { getGT } from 'gt-next/server';
export async function MyComponent() {
  const translate = await getGT();
  return <div>{translate('Hello, world!')}</div>;
}

Utilisation des variables

Souvent, vous devrez traduire des chaînes qui contiennent des variables.

Par exemple, vous pourriez avoir besoin de traduire une chaîne qui contient des valeurs numériques.

Pour ajouter des variables, ajoutez simplement la variable à la chaîne comme un espace réservé avec {variable}, et passez un objet comme second argument à la fonction retournée par le hook.

const price = 100;
const translate = useGT();
translate('There are {count} items in the cart', { count: 10 });

L'espace réservé {count} sera remplacé par la valeur de la variable count.

Cela vous permet d'afficher des valeurs dynamiques dans vos traductions.

Pour plus d'informations sur l'API, consultez la référence API.

gt-next prend en charge le format de message ICU, qui vous permet également de formater vos variables.

const price = 100;
const translate = useGT();
translate('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the cart', { count: 10 });

Le format de message ICU est un moyen puissant de formater vos variables. Pour plus d'informations, consultez la documentation du format de message ICU.

Exemples

Traduire une chaîne de caractères dans un composant

import { useGT } from 'gt-next';

export default function MyComponent() {
  const t = useGT();
  return (
    <div>
      <h1>{t('Hello, world!')}</h1>
    </div>
  )
}

export default function MyComponent() {
  return (
    <div>
      <h1>Hello, world!</h1>
    </div>
  )
}

Traduire une chaîne de caractères avec des variables

import { useGT } from 'gt-next';

export default function MyComponent() {
  const t = useGT();
  const count = 10;
  return (
    <div>
      <h1>{t('There are {count} items in the cart', { count })}</h1>
    </div>
  )
}

export default function MyComponent() {
  const count = 10;
  return (
    <div>
      <h1>There are {count} items in the cart</h1>
    </div>
  )
}

Traduire des parties d'un objet

import { useGT } from 'gt-next';

export default function MyComponent() {
  const t = useGT();
  const users = [
    {
      name: 'John',
      description: t('John is a software engineer at General Translation'),
    },
    {
      name: 'Jane',
      description: t('Jane is a software engineer at Google'),
    },
  ]
  return (
    <div>
      {users.map((user) => (
        <div key={user.name}>
          <h1>{user.name}</h1>
          <p>{user.description}</p>
        </div>
      ))}
    </div>
  )
}

export default function MyComponent() {
  const users = [
    {
      name: 'John',
      description: 'John is a software engineer at General Translation',
    },
    {
      name: 'Jane',
      description: 'Jane is a software engineer at Google',
    },
  ]
  return (
    <div>
      {users.map((user) => (
        <div key={user.name}>
          <h1>{user.name}</h1>
          <p>{user.description}</p>
        </div>
      ))}
    </div>
  )
}

Traduire des constantes partagées

src/llms.ts

// Custom function to get LLM data with translations
export function getLLMData(t: (content: string) => string) {
  return [
    {
      name: 'GPT-4.1',
      id: 'gpt-4.1',
      description: t('GPT-4.1 is a large language model developed by OpenAI'),
    },
    {
      name: 'Claude 3.7 Sonnet',
      id: 'claude-3-7-sonnet',
      description: t('Claude 3.7 Sonnet is a large language model developed by Anthropic'),
    },
  ]
}

import { getLLMData } from './llms';
import { useGT } from 'gt-next';

export default function MyComponent() {
  const t = useGT();
  const llms = getLLMData(t);
  return (
    <div>
      {llms.map((llm) => (
        <div key={llm.id}>
          <h1>{llm.name}</h1>
          <p>{llm.description}</p>
        </div>
      ))}
    </div>
  )
}

src/llms.ts

export const llms = [
  {
    name: 'GPT-4.1',
    id: 'gpt-4.1',
    description: 'GPT-4.1 is a large language model developed by OpenAI',
  },
  {
    name: 'Claude 3.7 Sonnet',
    id: 'claude-3-7-sonnet',
    description: 'Claude 3.7 Sonnet is a large language model developed by Anthropic',
  },
]

import { llms } from './llms';

export default function MyComponent() {
  return (
    <div>
      {llms.map((llm) => (
        <div key={llm.id}>
          <h1>{llm.name}</h1>
          <p>{llm.description}</p>
        </div>
      ))}
    </div>
  )
}

Dans ce dernier exemple, nous avons transformé le tableau llms en une fonction qui retourne les données avec les traductions. Nous avons passé la fonction t à la fonction qui retourne les données.

Alternativement, vous pourriez aussi transformer le tableau llms en un hook personnalisé. Cependant, ceci n'est pas recommandé, car vous devrez être très prudent sur la façon dont vous utilisez le hook useGT(), afin de ne pas violer les règles de React.

Pièges courants

Traduction de contenu dynamique

Toutes les chaînes doivent être connues au moment de la construction.

Cela signifie que vous ne pouvez pas traduire du contenu dynamique qui est généré ou récupéré à l'exécution.

Cela inclut les variables, même si ce sont des chaînes.

export default function MyComponent() {
  const [dynamicContent, setDynamicContent] = useState('Hello, world!');
  const t = useGT();
  return (
    <div>
      <h1>{t(dynamicContent)}</h1> {/* This will not work */}
    </div>
  )
}

L'outil CLI vous avertira si vous essayez de traduire du contenu dynamique avec le hook useGT().

Prochaines étapes

Découvrez comment traduire du contenu JSX à la demande.
En savoir plus sur le composant <T>.
Consultez la référence API pour useGT().

Traduction des chaînes

Pourquoi ne puis-je pas importer directement le tableau `llms` ?

Que faire si j'ai besoin de traduire du contenu dynamique ?

Sur cette page