Tableau de bord

Traduire les chaînes partagées

Comment internationaliser des chaînes partagées

Aperçu

Les chaînes partagées sont des chaînes ou des constantes utilisées à plusieurs endroits dans votre application.

Par exemple, vous pouvez avoir une chaîne utilisée dans plusieurs composants, ou une constante utilisée dans plusieurs fichiers.

Avec les bibliothèques i18n traditionnelles, vous devez créer un dictionnaire pour chaque chaîne partagée.

Ce guide vous expliquera comment internationaliser facilement les chaînes partagées dans votre application React à l’aide de la fonction msg() et du hook useMessages().

Nous aborderons les points suivants :

Quand utiliser la fonction msg()

Comment utiliser la fonction msg() et le hook useMessages()

Utilisation de variables

Exemples

Pièges courants

Quand utiliser la fonction msg()

La fonction msg() est une fonction simple qui sert à marquer des chaînes en vue de leur traduction.

Voyons un exemple d’objet partagé contenant des chaînes :

src/navData.ts
export const navData = {
  home: {
    label: 'Home',
    description: 'The home page',
    icon: 'home',
    href: '/',
  },
  about: {
    label: 'About',
    description: 'Information about the company',
    icon: 'info',
    href: '/about',
  },
}

Habituellement, pour internationaliser cet objet, vous devriez soit créer une entrée de dictionnaire pour chaque chaîne, soit refactoriser votre objet en une fonction qui renvoie les données avec leurs traductions.

Par exemple :

src/navData.ts
export const getNavData = (t: (content: string) => string) => ({
  home: {
    label: t('Home'),
    description: t('The home page'),
    icon: 'home',
    href: '/',
  },
  about: {
    label: t('About'),
    description: t('Information about the company'),
    icon: 'info',
    href: '/about',
  },
})

Partout ailleurs dans votre application où navData est importé, vous devrez appeler getNavData(t) à la place.

src/app/page.tsx
import { getNavData } from '@/navData';

export default function Home() {
  const t = useGT();
  const navData = getNavData(t);
  return <div>{navData.home.label}</div>;
}

Cela peut représenter beaucoup de travail. La solution consiste à utiliser la fonction msg().

Comment utiliser la fonction msg()

Pour utiliser la fonction msg(), passez la chaîne directement à la fonction. La fonction retourne une chaîne spéciale, encodée, qui peut être utilisée pour les traductions.

src/navData.ts
import { msg } from 'gt-react';

export const navData = [
  {
    label: msg('Home'), // Output has type `string`
    description: msg('The home page'),
    icon: 'home',
    href: '/',
  },
  {
    label: msg('About'),
    description: msg('Information about the company'),
    icon: 'info',
    href: '/about',
  },
]

Ensuite, transmettez simplement la chaîne encodée au hook useMessages().

src/app/page.tsx
import { useMessages } from 'gt-react';
import { navData } from '@/navData';

export default function Home() {
  const m = useMessages();
  return (
    <div>
      {navData.map((item) => (
        <div key={item.label}>{m(item.label)}</div>
      ))}
    </div>
  );
}

Attention ! La chaîne renvoyée par la fonction msg() est encodée et sera différente de la chaîne d’entrée d’origine. Si vous souhaitez retrouver la chaîne d’origine, vous devez la décoder avec decodeMsg()

Utilisation des variables

Si votre chaîne est une chaîne de modèle et qu’elle contient des variables, vous pouvez les transmettre à la fonction msg().

Remplacez simplement la notation ${} dans la chaîne de modèle par {variable}, puis passez un objet en deuxième argument à msg() avec le nom de la variable comme clé.

src/navData.ts
const items = 100;
export const pricing = [
  {
    name: 'Basic',
    price: 100,
    description: `The basic plan includes ${items} items`
  },
]

Doit être transformé en :

src/navData.ts
import { msg } from 'gt-react';

const items = 100;
export const pricing = [
  {
    name: 'Basic',
    price: 100,
    description: msg('The basic plan includes {items} items', { items })
  },
]

L’espace réservé {items} sera remplacé par la valeur de la variable items.

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

Pour en savoir plus sur l’API, consultez la référence de l’API.

gt-react prend en charge le format de messages ICU, qui permet également de formater vos variables.

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

Le format de messages ICU est un outil puissant pour formater vos variables. Pour plus d’informations, consultez la documentation du format de messages ICU.

Exemples

  1. Traduire un objet global partagé
src/llms.ts
import { msg } from 'gt-react';

export const llmData = [
  {
    name: 'GPT-4.1',
    id: 'gpt-4.1',
    description: msg('GPT-4.1 is a large language model developed by OpenAI'),
  },
  {
    name: 'Claude 3.7 Sonnet',
    id: 'claude-3-7-sonnet',
    description: msg('Claude 3.7 Sonnet is a large language model developed by Anthropic'),
  },
];
src/app/page.tsx
import { llmData } from '@/llms';
import { useMessages } from 'gt-react';

export default function MyComponent() {
  const m = useMessages();
  return (
    <div>
      {llmData.map((llm) => (
        <div key={llm.id}>
          <h1>{llm.name}</h1>
          <p>{m(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',
  },
]
src/app/page.tsx
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>
  )
}
  1. Traduire la valeur de retour d’une fonction
src/llms.ts
import { msg } from 'gt-react';

function mockData() {
  return [
    {
      name: 'GPT-4.1',
      id: 'gpt-4.1',
      company: 'OpenAI',
    },
    {
      name: 'Claude 3.7 Sonnet',
      id: 'claude-3-7-sonnet',
      company: 'Anthropic',
    },
  ];
}

export function getData() {
  const data = mockData();
  const modifiedData = data.map((item) => ({
    ...item,
    description: msg('{name} est un grand modèle de langage développé par {company}', {
      name: item.name,
      company: item.company,
    }),
  }));
  return modifiedData;
}
src/app/page.tsx
import { getData } from '@/llms';
import { useMessages } from 'gt-react';

export default function MyComponent() {
  const m = useMessages();
  const data = getData();
  return (
    <div>
      {data.map((item) => (
        <div key={item.id}>
          <h1>{item.name}</h1>
          <p>{m(item.description)}</p>
        </div>
      ))}
    </div>
  )
}
src/llms.ts
import { msg } from 'gt-react';

function mockData() {
  return [
    {
      name: 'GPT-4.1',
      id: 'gpt-4.1',
      company: 'OpenAI',
    },
    {
      name: 'Claude 3.7 Sonnet',
      id: 'claude-3-7-sonnet',
      company: 'Anthropic',
    },
  ];
}

export function getData() {
  const data = mockData();
  const modifiedData = data.map((item) => ({
    ...item,
    description: `${item.name} est un grand modèle de langage développé par ${item.company}`,
  }));
  return modifiedData;
}
src/app/page.tsx
import { getData } from '@/llms';

export default function MyComponent() {
  const data = getData();
  return (
    <div>
      {data.map((item) => (
        <div key={item.id}>
          <h1>{item.name}</h1>
          <p>{item.description}</p>
        </div>
      ))}
    </div>
  )
}

Pièges courants

Oublier d’appeler useMessages()

msg() encode la chaîne passée en entrée ; vous ne pouvez donc pas l’utiliser directement dans du JSX ou ailleurs.

Si vous essayez d’utiliser la chaîne encodée telle quelle, vous obtiendrez une chaîne étrange qui ressemble à ceci :

const encodedString = msg('Hello, world!');
console.log(encodedString); // "Hello, world!:eyIkX2hhc2giOiJkMjA3MDliZGExNjNlZmM2In0="

Pour corriger cela, vous devez utiliser le hook useMessages() pour récupérer la chaîne traduite.

import { useMessages } from 'gt-react';

const encodedString = msg('Hello, world!');

export default function MyComponent() {
  const m = useMessages();
  return <div>{m(encodedString)}</div>; // 'Hello, world!' dans la langue actuelle
}

Sinon, si vous souhaitez retrouver la chaîne d’origine, vous pouvez utiliser la fonction decodeMsg().

import { decodeMsg } from 'gt-react';

const encodedString = msg('Hello, world!');
const decodedString = decodeMsg(encodedString);
console.log(decodedString); // "Hello, world!"

Envelopper du contenu dynamique dans msg()

Toutes les chaînes doivent être connues au moment de la build. Cela signifie que vous ne pouvez pas envelopper de contenu dynamique dans msg().

Par exemple, ceci est invalide :

const dynamicContent = msg(`Hello, ${name}`);

Pour corriger cela, fournissez le contenu dynamique en tant que variable, puis passez-la à msg().

const dynamicContent = msg('Hello, {name}', { name });

L’outil CLI vous avertira si vous essayez d’envelopper du contenu dynamique avec msg().

Prochaines étapes

Que pensez-vous de ce guide&nbsp;?

Modifier sur GitHub

Sur cette page

Aperçu
Quand utiliser la fonction msg()
Comment utiliser la fonction msg()
Utilisation des variables
Exemples
Pièges courants
Oublier d’appeler useMessages()
Envelopper du contenu dynamique dans msg()
Prochaines étapes
Traduire les chaînes partagées