Tableau de bord

Chaînes partagées

Comment internationaliser des chaînes utilisées dans plusieurs composants et fichiers

Les chaînes partagées sont des valeurs textuelles utilisées à plusieurs endroits dans votre application — comme des libellés de navigation, des messages de formulaire ou des données de configuration. Plutôt que de dupliquer la logique de traduction partout, utilisez msg pour marquer les chaînes à traduire et useMessages pour les décoder.

Le problème du contenu partagé

Prenez par exemple cette configuration de navigation utilisée dans l’ensemble de votre application :

// navData.ts
export const navData = [
  {
    label: 'Accueil',
    description: 'La page d\'accueil',
    href: '/'
  },
  {
    label: 'À propos', 
    description: 'Informations sur l\'entreprise',
    href: '/about'
  }
];

Pour l’internationaliser, vous auriez généralement besoin de :

  1. Le transformer en une fonction qui accepte une fonction de traduction
  2. Mettre à jour chaque utilisation pour appeler la fonction avec t
  3. Gérer la complexité à l’échelle de votre codebase

Cela crée une surcharge de maintenance et rend votre code moins lisible. La fonction msg règle ce problème en vous permettant de marquer les chaînes à traduire directement dans le code, puis de les décoder au besoin.

Démarrage rapide

Utilisez msg pour baliser les chaînes et useMessages pour les décoder :

// navData.ts - Marquer les chaînes pour la traduction
import { msg } from 'gt-next';

export const navData = [
  {
    label: msg('Accueil'),
    description: msg('La page d\'accueil'), 
    href: '/'
  },
  {
    label: msg('À propos'),
    description: msg('Informations sur l\'entreprise'),
    href: '/about'
  }
];
// Utilisation du composant - Décoder les chaînes marquées
import { useMessages } from 'gt-next';
import { navData } from './navData';

function Navigation() {
  const m = useMessages();
  
  return (
    <nav>
      {navData.map((item) => (
        <a key={item.href} href={item.href} title={m(item.description)}>
          {m(item.label)}
        </a>
      ))}
    </nav>
  );
}

Fonctionnement des chaînes partagées

Le système de chaînes partagées fonctionne en deux phases :

  1. Phase de marquage : msg encode des chaînes avec des métadonnées de traduction
  2. Phase de décodage : useMessages ou getMessages décodent et traduisent les chaînes
// msg() encode la chaîne avec des métadonnées
const encoded = msg('Hello, world!');
console.log(encoded); // "Hello, world!:eyIkX2hhc2giOiJkMjA3MDliZGExNjNlZmM2In0="

// useMessages() décode et traduit
const m = useMessages();
const translated = m(encoded); // "Hello, world!" dans la langue de l'utilisateur

Les encoded strings issues de msg ne peuvent pas être utilisées directement : elles doivent être décodées avec useMessages ou getMessages.

Utilisation côté client et côté serveur

Composants clients

Utilisez le hook useMessages :

import { useMessages } from 'gt-next';

const encodedString = msg('Bonjour le monde !');

function MyComponent() {
  const m = useMessages();
  return <div>{m(encodedString)}</div>;
}

Composants serveur

Utilisez la fonction getMessages :

import { getMessages } from 'gt-next/server';

const encodedString = msg('Bonjour le monde !');

async function MyServerComponent() {
  const m = await getMessages();
  return <div>{m(encodedString)}</div>;
}

Récupérer les chaînes d’origine avec decodeMsg

Il arrive que vous ayez besoin d’accéder à la chaîne source sans traduction, par exemple pour la journalisation, le débogage ou des comparaisons. Utilisez decodeMsg pour extraire le texte d’origine :

import { decodeMsg } from 'gt-next';

const encoded = msg('Bonjour, le monde !');
const original = decodeMsg(encoded); // "Bonjour, le monde !" (original)
const translated = m(encoded); // "Bonjour, le monde !" (dans la langue de l'utilisateur)

// Utile pour les logs ou le débogage
console.log('Chaîne originale :', decodeMsg(encoded));
console.log('Chaîne traduite :', m(encoded));

Cas d’usage de decodeMsg

  • Développement et débogage : journaliser les chaînes originales pour le diagnostic
  • Gestion du secours : utiliser le texte original lorsque les traductions échouent
  • Comparaison de chaînes : comparer aux valeurs originales connues
  • Analytique : suivre l’utilisation des chaînes originales
// Exemple : Gestion du secours
function getDisplayText(encodedStr) {
  const m = useMessages();
  try {
    return m(encodedStr);
  } catch (error) {
    console.warn('Échec de la traduction, utilisation de l\'original :', decodeMsg(encodedStr));
    return decodeMsg(encodedStr);
  }
}

Utilisation des variables

Pour les chaînes à contenu dynamique, utilisez des placeholders et transmettez des variables :

// Marquer une chaîne avec des variables
const items = 100;
export const pricing = [
  {
    name: 'De base',
    price: 100,
    description: msg('Le forfait de base inclut {items} éléments', { items })
  }
];
// Utilisation dans le composant
function PricingCard() {
  const m = useMessages();
  
  return (
    <div>
      <h3>{pricing[0].name}</h3>
      <p>{m(pricing[0].description)}</p>
    </div>
  );
}

Format de message ICU

Pour des mises en forme avancées, utilisez la syntaxe ICU :

const count = 10;
const message = msg('Il y a {count, plural, =0 {aucun article} =1 {un article} other {{count} articles}} dans le panier', { count });

Pour en savoir plus sur le format de message ICU, consultez la documentation d’Unicode.

Exemples

Configuration de la navigation

// config/navigation.ts
import { msg } from 'gt-next';

export const mainNav = [
  {
    label: msg('Accueil'),
    href: '/',
    icon: 'home'
  },
  {
    label: msg('Produits'),
    href: '/products', 
    icon: 'package'
  },
  {
    label: msg('À propos de nous'),
    href: '/about',
    icon: 'info'
  }
];

export const footerLinks = [
  {
    title: msg('Entreprise'),
    links: [
      { label: msg('À propos'), href: '/about' },
      { label: msg('Carrières'), href: '/careers' },
      { label: msg('Contact'), href: '/contact' }
    ]
  },
  {
    title: msg('Assistance'), 
    links: [
      { label: msg('Centre d\'aide'), href: '/help' },
      { label: msg('Documentation'), href: '/docs' },
      { label: msg('Référence de l\'API'), href: '/api' }
    ]
  }
];
// components/Navigation.tsx
import { useMessages } from 'gt-next';
import { mainNav } from '../config/navigation';

function Navigation() {
  const m = useMessages();
  
  return (
    <nav>
      {mainNav.map((item) => (
        <a key={item.href} href={item.href}>
          <Icon name={item.icon} />
          {m(item.label)}
        </a>
      ))}
    </nav>
  );
}

Configuration du formulaire

// config/forms.ts
import { msg } from 'gt-next';

export const formMessages = {
  placeholders: {
    email: msg('Saisissez votre adresse e-mail'),
    password: msg('Saisissez votre mot de passe'),
    message: msg('Tapez votre message ici...')
  },
  actions: {
    send: msg('Envoyer le message'),
    save: msg('Enregistrer les modifications'),
    cancel: msg('Annuler')
  },
  validation: {
    required: msg('Ce champ est obligatoire'),
    email: msg('Veuillez saisir une adresse e-mail valide'),
    minLength: msg('Doit contenir au moins {min} caractères', { min: 8 }),
    maxLength: msg('Ne peut pas dépasser {max} caractères', { max: 100 })
  },
  success: {
    saved: msg('Modifications enregistrées avec succès'),
    sent: msg('Message envoyé avec succès'),
    updated: msg('Profil mis à jour')
  },
  errors: {
    network: msg('Erreur réseau - veuillez réessayer'),
    server: msg('Erreur serveur - veuillez contacter le support'),
    timeout: msg('Délai d\'attente dépassé - veuillez réessayer')
  }
};
// components/ContactForm.tsx
import { useMessages } from 'gt-next';
import { formMessages } from '../config/forms';

function ContactForm() {
  const m = useMessages();
  const [errors, setErrors] = useState({});
  
  return (
    <form>
      <input 
        type="email"
        placeholder={m(formMessages.placeholders.email)}
        required
      />
      {errors.email && <span>{m(formMessages.validation.email)}</span>}
      
      <button type="submit">
        {m(formMessages.actions.send)}
      </button>
    </form>
  );
}

Génération de contenu dynamique

// utils/productData.ts
import { msg } from 'gt-next';

function mockProducts() {
  return [
    { name: 'iPhone 15', company: 'Apple', category: 'Électronique' },
    { name: 'Galaxy S24', company: 'Samsung', category: 'Électronique' }
  ];
}

export function getProductData() {
  const products = mockProducts();
  
  return products.map(product => ({
    ...product,
    description: msg('{name} est un produit {category} de {company}', {
      name: product.name,
      category: product.category,
      company: product.company
    })
  }));
}
// components/ProductList.tsx
import { useMessages } from 'gt-next';
import { getProductData } from '../utils/productData';

function ProductList() {
  const m = useMessages();
  const products = getProductData();
  
  return (
    <div>
      {products.map(product => (
        <div key={product.name}>
          <h3>{product.name}</h3>
          <p>{m(product.description)}</p>
        </div>
      ))}
    </div>
  );
}

Problèmes fréquents

Utiliser des chaînes encodées directement

N'utilisez jamais directement la sortie de msg :

// ❌ Incorrect - chaîne encodée utilisée directement
const encoded = msg('Hello, world!');
return <div>{encoded}</div>; // Affiche la chaîne encodée, pas la traduction

// ✅ Correct - décoder d'abord la chaîne  
const encoded = msg('Hello, world!');
const m = useMessages();
return <div>{m(encoded)}</div>; // Affiche la traduction appropriée

Contenu dynamique dans msg()

Les chaînes doivent être connues à la compilation :

// ❌ Incorrect - littéral de modèle dynamique
const name = 'John';
const message = msg(`Hello, ${name}`); // Erreur au moment de la compilation

// ✅ Correct - utiliser variables  
const name = 'John';
const message = msg('Hello, {name}', { name });

Oubli du décodage

Chaque chaîne msg doit être décodée :

// ❌ Décodage manquant
const config = {
  title: msg('Tableau de bord'),
  subtitle: msg('Bon retour')
};

// Plus tard dans le composant - oublié de décoder
return <h1>{config.title}</h1>; // Affiche la chaîne encodée

// ✅ Correct - décoder lors de l'utilisation
const m = useMessages();
return <h1>{m(config.title)}</h1>; // Affiche le titre traduit

Prochaines étapes

Que pensez-vous de ce guide ?

Chaînes

Comment internationaliser des chaînes de texte simples avec useGT et getGT

Contenu dynamique

Comment traduire du contenu à l’exécution à l’aide des API de traduction côté serveur

Sur cette page

Le problème du contenu partagé
Démarrage rapide
Fonctionnement des chaînes partagées
Utilisation côté client et côté serveur
Composants clients
Composants serveur
Récupérer les chaînes d’origine avec decodeMsg
Cas d’usage de decodeMsg
Utilisation des variables
Format de message ICU
Exemples
Configuration de la navigation
Configuration du formulaire
Génération de contenu dynamique
Problèmes fréquents
Utiliser des chaînes encodées directement
Contenu dynamique dans msg()
Oubli du décodage
Prochaines étapes
Chaînes partagées