Que sont les traductions locales ?

Les traductions locales sont conservées dans le bundle de votre application, plutôt que récupérées depuis un CDN (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 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 au moment de l’exécution

Par défaut, gt-react 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 réduits : Les traductions locales sont servies directement par votre application, et se chargent plus rapidement que celles diffusées via un réseau de distribution de contenu (CDN)
• Aucune dépendance à des services externes : La capacité de votre application à charger les traductions ne dépend pas de la disponibilité du CDN. Si aucune traduction n’est trouvée pour un locale, l’application bascule automatiquement vers la langue par défaut
• Fonctionne hors ligne : Les traductions sont embarquées avec votre application

Inconvénients des traductions locales

• Taille du bundle accrue : 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 version à chaque changement

Configuration

É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 t = await import(`./_gt/${locale}.json`);
  return t.default;
}

Étape 2 : Configurer GTProvider

Passez loadTranslations comme prop au composant <GTProvider> :

import { GTProvider } from 'gt-react';
import loadTranslations from './loadTranslations';

export default function App() {
  return (
    <GTProvider loadTranslations={loadTranslations} locales={['es', 'fr']}>
      <YourApp />
    </GTProvider>
  );
}

Étape 3 : Configurer la CLI

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

npx gtx-cli configure

Lorsque vous y êtes invité :

• Enregistrer sur le CDN (réseau de diffusion de contenu) ? Sélectionnez « No »
• Répertoire de traduction : La CLI (interface en ligne de commande) utilisera automatiquement ./src/_gt

Vous pouvez également 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 4 : 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 base de code :

npx gtx-cli translate

Les traductions seront stockées dans src/_gt/ et intégrées à votre application.

Intégration à la build

Processus de build React

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 compilation :

# ❌ 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

Faites correspondre votre structure de répertoires dans la fonction load :

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

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

Poids de bundle élevé

Envisagez le découpage du code (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(`./_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

Prochaines étapes

• Guide des langues - Configurer les langues prises en charge