Traduction des chaînes

Aperçu

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

Nous aborderons 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 réside dans le moment où il faut les utiliser.

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

Utilisez la fonction getGT() dans les composants serveur, et le hook useGT() dans les composants client.

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>;
}

src/app/page.tsx

'use client';
import { useGT } from 'gt-next/client';
export function MyComponent() {
  const translate = useGT();
  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, il suffit de passer la chaîne directement à la fonction retournée par le hook.

import { useGT } from 'gt-next/client';
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. À la place, la chaîne de caractères est transmise 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 côté serveur, elle peut être utilisée dans des composants serveur et n'a pas besoin d'être appelée à l'intérieur du <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 aurez besoin de traduire des chaînes qui contiennent des variables.

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

Pour ajouter des variables, il suffit d'ajouter la variable à la chaîne comme un espace réservé avec {variable}, et de passer un objet en second argument à la fonction retournée par le hook.

const price = 100;
const translate = useGT();
translate('There are {count} items in the cart', { variables: { 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 de l'API.

Exemples

Traduction d'une chaîne dans un composant

import { useGT } from 'gt-next/client';

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>
  )
}

Traduction d'une chaîne avec des variables

import { useGT } from 'gt-next/client';

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

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

Traduction de parties d'un objet

import { useGT } from 'gt-next/client';

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>
  )
}

Traduction de constantes partagées

src/llms.ts

import { useGT } from 'gt-next/client';
// Custom hook to get LLM data with translations
export function useLLMData() {
  const t = useGT();
  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 { useLLMData } from './llms';

export default function MyComponent() {
  const llms = useLLMData();
  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>
  )
}

Soyez prudent ! Dans ce dernier exemple, vous devez être très attentif à la façon dont vous utilisez le hook useGT(). Assurez-vous qu'il ne viole pas les règles de React.

De plus, assurez-vous que le hook useGT() est appelé dans le contexte React. Si vos constantes sont définies en dehors d'un composant React, il vous faudra probablement créer un hook personnalisé pour accéder à vos données avec les traductions.

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