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). 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 pour qu’elles puissent être utilisées.

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 à l’exécution

Par défaut, gt-next récupère les traductions depuis le CDN de General Translation. Lorsque vous traduisez votre application via 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 rapidement que celles servies depuis un CDN (Content Delivery Network)
• 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 avec votre application

Inconvénients des local translations

• Taille du bundle accrue : Les local translations augmentent la taille du bundle de votre application, ce qui peut ralentir le chargement initial
• Gestion des contenus : Pour modifier une traduction, vous devez redéployer votre application avec la nouvelle traduction à chaque changement

Configuration

Étape 1 : Créer une 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 et choisissez le stockage local :

npx gtx-cli configure

Lorsque vous y êtes invité·e :

• Enregistrer sur le CDN ? 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 du CLI pour en savoir plus.

É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 incluses 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 && <...VOTRE_COMMANDE_DE_BUILD...>"
  }
}

Pipeline CI/CD

# .github/workflows/deploy.yml
- name: Générer les traductions
  run: npx gtx-cli translate
  
- name: Construire 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 :

# ❌ Construire 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 dans 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`);

Taille de bundle volumineuse

Envisagez le découpage du code pour les applications prenant en charge de nombreuses langues :

// Charger les traductions uniquement quand 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 :