Cosa sono le traduzioni locali?

Le traduzioni locali sono incluse nel bundle della tua app, invece di essere caricate da una CDN (Content Delivery Network). Quando aggiungi il comando gtx-cli translate al processo di build, vengono generate traduzioni in formato JSON. L’ultimo passaggio è importare queste traduzioni nella tua app, dove potranno essere utilizzate.

Ci sono due modi per farlo:

1. Nel bundle della tua app (locale): salva le traduzioni nel bundle della tua app dopo la generazione
2. In una CDN (predefinito): carica le traduzioni da una CDN a runtime

Per impostazione predefinita, gt-react carica le traduzioni dalla CDN di General Translation. Quando traduci la tua app usando la nostra API, le traduzioni vengono salvate automaticamente sulla nostra CDN.

Compromessi

Vantaggi delle traduzioni locali

• Tempi di caricamento più rapidi: le traduzioni locali sono fornite direttamente dalla tua app e si caricano più velocemente rispetto a quelle distribuite tramite CDN
• Nessuna dipendenza da servizi esterni: la tua app non dipende dall'uptime di un CDN per caricare le traduzioni. Se non sono disponibili traduzioni per una determinata locale, l'app esegue automaticamente il fallback alla lingua predefinita
• Funziona offline: le traduzioni sono incluse nel pacchetto della tua app

Svantaggi delle traduzioni locali

• Maggiore dimensione del bundle: Le traduzioni locali aumentano la dimensione del bundle della tua app, con il rischio di rallentare il caricamento iniziale
• Gestione dei contenuti: Per modificare una traduzione, devi effettuare un nuovo deploy della tua app con la traduzione aggiornata ogni volta che apporti modifiche

Configurazione

Passaggio 1: Crea la funzione di caricamento

Aggiungi un file loadTranslations.[js|ts] in ./src con il seguente contenuto:

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

Passaggio 2: configura GTProvider

Passa loadTranslations come prop al componente <GTProvider>:

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

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

Passaggio 3: Configura la CLI

Esegui il comando di configurazione e seleziona l'archiviazione locale:

npx gtx-cli configure

Quando richiesto:

• Salvare su CDN? Seleziona «No»
• Directory delle traduzioni: La CLI utilizzerà automaticamente ./src/_gt

In alternativa, puoi configurare manualmente il file gt.config.json per usare traduzioni locali. Consulta la documentazione sulla configurazione della CLI per ulteriori informazioni.

Passaggio 4: Genera le traduzioni

Ora, quando esegui il comando di traduzione, le traduzioni verranno scaricate automaticamente e incluse nel tuo codebase:

npx gtx-cli translate

Le traduzioni verranno salvate in src/_gt/ e incluse nel bundling della tua app.

Integrazione della build

Processo di build di React

Aggiungi la generazione delle traduzioni allo script di build:

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

Pipeline CI/CD

# .github/workflows/deploy.yml
- name: Genera traduzioni
  run: npx gtx-cli translate
  
- name: Compila applicazione  
  run: npm run build

Problemi comuni

File di traduzione mancanti

Assicurati che le traduzioni siano generate prima della compilazione:

# ❌ Build senza traduzioni
<...YOUR_BUILD_COMMAND...>

# ✅ Genera prima le traduzioni
npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>

Errori nel percorso di import

Abbina la struttura delle tue directory nella funzione load:

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

// ✅ Percorso corretto per src/_gt
const t = await import(`./_gt/${locale}.json`);

Dimensioni del bundle elevate

Prendi in considerazione il code splitting per le app con molte lingue:

// Carica le traduzioni solo quando necessario
export default async function loadTranslations(locale: string) {
  // Carica solo se il locale è attivo
  if (locale === getCurrentLocale()) {
    const translations = await import(`./_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

Prossimi passaggi

• Guida alle lingue - Configura le lingue supportate