Bonnes pratiques

Ces bonnes pratiques s’appuient sur des approches qui donnent des résultats fiables et rentables avec le Compiler de Lingo.dev. Elles couvrent le pipeline de build, l’organisation du code, la qualité des traductions et les tests.

Pipeline de build#

Adopter la stratégie en trois modes#

{
  buildMode: "translate",
  dev: { usePseudotranslator: true },
}

LINGO_BUILD_MODE=translate npm run build

LINGO_BUILD_MODE=cache-only npm run build

Contrôle de version#

Commiter .lingo/ dans votre dépôt#

Le fichier .lingo/metadata.json fait foi pour toutes les traductions en cache. Les builds de production en mode cache-only en dépendent.

# .gitignore - do NOT ignore .lingo/
node_modules/
dist/
.env

Relire les diffs de traduction#

Lorsque la CI commit des traductions mises à jour, relisez le diff de .lingo/metadata.json dans les pull requests. Vous pourrez ainsi repérer les problèmes de traduction avant qu’ils n’arrivent en production, comme pour une relecture de modifications de code.

Organisation du code#

Placer le texte traduisible directement dans le JSX#

Le Compiler analyse le JSX à la recherche de contenu traduisible. Le texte stocké dans des variables JavaScript, des constantes ou des fichiers externes n’est pas détecté :

// Good - compiler detects this text
export function Header() {
  return <h1>Welcome to our app</h1>;
}

// Bad - compiler cannot detect text in a variable
const title = "Welcome to our app";
export function Header() {
  return <h1>{title}</h1>;
}

Utiliser useDirective pour les grandes bases de code#

Dans les grands projets, analyser chaque fichier augmente le temps de build. Activez useDirective: true et ajoutez 'use i18n' uniquement aux fichiers qui contiennent du texte visible par l’utilisateur :

{
  useDirective: true,
}

'use i18n';

// Only this file is scanned for translations
export function PublicPage() {
  return <h1>Welcome</h1>;
}

Limiter sourceRoot au strict nécessaire#

Définissez sourceRoot sur le plus petit répertoire contenant vos composants traduisibles. Un sourceRoot trop large analyse des fichiers inutiles :

Qualité de traduction#

Utiliser des overrides manuels pour les termes de marque#

Les noms de marque, les noms de produits et les textes juridiques doivent utiliser des manual overrides plutôt que de s’appuyer sur une traduction par IA :

<h1 data-lingo-override={{ es: "Motor de Localizacion", de: "Lokalisierungs-Engine" }}>
  Localization Engine
</h1>

Utiliser le mapping des paires de langues pour optimiser les coûts#

Les modèles n’ont pas tous les mêmes points forts ni les mêmes tarifs. Réservez les modèles les plus coûteux aux langues qui en ont besoin et utilisez des modèles plus économiques ailleurs :

{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",      // Fast, cost-effective default
    "*:ja": "anthropic:claude-3-5-sonnet",       // Higher quality for Japanese
    "*:zh-Hans": "anthropic:claude-3-5-sonnet",  // Higher quality for Chinese
  },
}

Utiliser le moteur Lingo.dev pour le glossaire et la voix de marque#

Lorsque vous avez besoin d’une terminologie cohérente dans toute votre application, configurez un moteur de localisation sur Lingo.dev avec un glossaire et une voix de marque. Ils s’appliquent automatiquement à chaque demande de traduction.

Pluralisation#

Désactiver la pluralisation si elle n’est pas nécessaire#

Si votre application n’affiche pas de valeurs numériques à côté du texte, désactivez la pluralisation pour réduire la complexité du build :

{
  pluralization: { enabled: false },
}

Rédiger naturellement les textes qui dépendent d’un nombre#

Lorsque la pluralisation est activée, rédigez naturellement le texte avec des variables numériques. Le Compiler se charge de la conversion en ICU MessageFormat :

// Good - the compiler detects and pluralizes this
<p>You have {count} items in your cart</p>

// Also good - works with any numeric expression
<p>{unreadCount} unread messages</p>

Tests#

Tester d’abord avec le pseudotranslator#

Avant de générer de vraies traductions, exécutez avec le pseudotranslator pour vérifier que la couverture est complète :

1. Activer dev.usePseudotranslator: true
2. Parcourir chaque page et chaque composant
3. Tout texte sans marqueurs [!!! ... !!!] n’est pas traduit
4. Corriger les problèmes d’emplacement du texte (déplacer le texte dans le JSX, ajuster sourceRoot, ajouter des directives 'use i18n')

Tester avec de vraies traductions avant la mise en production#

Désactivez le pseudotranslator et générez de vraies traductions pour au moins une langue cible avant la mise en production :

{
  dev: { usePseudotranslator: false },
}

Vérifiez les débordements de mise en page, les troncatures de texte et les problèmes de texte bidirectionnel que les pseudotraductions ne peuvent pas révéler.

Étapes suivantes#