Que sont les traductions locales ?

Les traductions locales sont stockées dans le bundle de votre application, plutôt que d’être récupérées depuis un CDN (Content Delivery Network, réseau de diffusion de contenu). Lorsque vous ajoutez la commande gtx-cli translate à votre processus de build, des traductions au format JSON sont générées. L’étape finale consiste à intégrer ces traductions dans votre application afin de pouvoir les utiliser.

Il existe deux façons de procéder :

1. Dans le bundle de votre application (local) : enregistrez les traductions dans le bundle de votre application après leur génération
2. Dans un CDN (par défaut) : récupérez les traductions depuis un CDN au moment de l’exécution

Par défaut, gt-next récupère les traductions depuis le CDN de General Translation. Lorsque vous traduisez votre application à l’aide de notre API, les traductions sont automatiquement enregistrées sur notre CDN.

Arbitrages

Avantages des traductions locales

• Temps de chargement plus courts : Les traductions locales sont servies directement depuis votre application, et se chargent plus vite que celles diffusées via un CDN (réseau de diffusion de contenu)
• Aucune dépendance à des services externes : La capacité de votre application à charger des traductions ne dépend pas de la disponibilité du CDN. Si aucune traduction n’est trouvée pour un locale, l’application revient automatiquement à la langue par défaut
• Fonctionne hors ligne : Les traductions sont intégrées à votre application

Inconvénients des traductions locales

• Augmentation de la taille du bundle : Les traductions locales augmentent la taille du bundle de votre application, ce qui peut ralentir le chargement initial
• Gestion du contenu : Pour modifier une traduction, vous devez redéployer votre application avec la nouvelle traduction à chaque modification

Mise en place

Étape 1 : Créer la fonction de chargement

Ajoutez un fichier loadTranslations.[js|ts] dans ./src avec le contenu suivant :

export default async function loadTranslations(locale: string) {
  const translations = await import(`../public/_gt/${locale}.json`);
  return translations.default;
}

withGTConfig détecte automatiquement le fichier loadTranslations.[js|ts] dans votre répertoire src/ ou à la racine du projet.

Étape 2 : Configurer la CLI

Exécutez la commande de configuration, puis sélectionnez le stockage local :

npx gtx-cli configure

Lorsque vous y êtes invité :

• Enregistrer sur le CDN (réseau de diffusion de contenu) ? Sélectionnez « Non »
• Répertoire des traductions : Saisissez ./public/_gt

Vous pouvez aussi configurer manuellement le fichier gt.config.json pour utiliser des traductions locales. Consultez la documentation de configuration de la CLI pour plus d’informations.

Étape 3 : Générer les traductions

Désormais, lorsque vous exécutez la commande translate, les traductions sont automatiquement téléchargées et ajoutées à votre codebase :

npx gtx-cli translate

Les traductions seront stockées dans public/_gt/ et empaquetées avec votre application.

Intégration à la build

Processus de build Next.js

Ajoutez la génération des traductions à votre script de build :

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

Pipeline CI/CD

# .github/workflows/deploy.yml
- name: Générer les traductions
  run: npx gtx-cli translate
  
- name: Compiler l'application  
  run: npm run build

Problèmes fréquents

Fichiers de traduction manquants

Assurez-vous que les traductions sont générées avant la génération du build :

# ❌ Build sans traductions
<...YOUR_BUILD_COMMAND...>

# ✅ Générer les traductions d'abord
npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>

Erreurs de chemin d’importation

Alignez votre structure de répertoires avec la fonction load :

// ❌ Chemin incorrect
const t = await import(`../translations/${locale}.json`);

// ✅ Chemin correct pour public/_gt
const t = await import(`../public/_gt/${locale}.json`);

Poids de bundle élevé

Envisagez le code splitting pour les applications prenant en charge de nombreuses langues :

// Charger les traductions uniquement si nécessaire
export default async function loadTranslations(locale: string) {
  // Charger uniquement si la locale est active
  if (locale === getCurrentLocale()) {
    const translations = await import(`../public/_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

Prochaines étapes

• Guide du middleware - Détection de la langue et routage
• Guide des langues - Configurer les langues prises en charge
• Référence de l’API :