Qu’est-ce que 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, cela génère des traductions au format JSON. La dernière étape 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-react 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 réduits : Les traductions locales sont servies directement depuis votre application et se chargent plus vite que celles délivrées via un CDN (Content Delivery/Distribution Network)
• Aucune dépendance à des services externes : Le chargement des traductions par votre application 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 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 du contenu : Pour modifier une traduction, vous devez redéployer votre application avec la nouvelle traduction à chaque modification

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 en 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 et choisissez le stockage local :

npx gtx-cli configure

Lorsque vous y êtes invité :

• Enregistrer sur le CDN ? Sélectionnez « Non »
• Répertoire de traduction : la CLI 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 en savoir plus.

É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 intégrées à votre codebase :

npx gtx-cli translate

Les traductions seront stockées dans src/_gt/ et regroupées avec 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 && <...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 construction :

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

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

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

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

Grosse taille de bundle

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(`./_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

Prochaines étapes

• Guide des langues - Configurer les langues prises en charge