Cosa sono le traduzioni locali?

Le traduzioni locali vengono incluse nel bundle della tua app, invece di essere scaricate da una CDN (Content Delivery Network). Quando aggiungi il comando gtx-cli translate al processo di build, vengono generate le 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): recupera le traduzioni da una CDN a runtime

Per impostazione predefinita, gt-next recupera le traduzioni dalla CDN di General Translation. Quando traduci la tua app utilizzando la nostra API, le traduzioni vengono salvate automaticamente nella nostra CDN.

Trade-off

Vantaggi delle traduzioni locali

• Tempi di caricamento più rapidi: Le traduzioni locali vengono fornite direttamente dalla tua app, risultando più veloci rispetto a quelle distribuite tramite CDN
• Nessuna dipendenza da servizi esterni: La possibilità per la tua app di caricare le traduzioni non dipende dall’uptime del CDN. Se non sono disponibili traduzioni per una certa 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

• Aumento delle dimensioni del bundle: Le traduzioni locali aumentano le dimensioni del bundle della tua app, con il rischio di rallentare il caricamento iniziale
• Gestione dei contenuti: Per modificare una traduzione devi eseguire un nuovo deploy dell’app con la versione aggiornata ogni volta che apporti cambiamenti

Configurazione

Passaggio 1: creare la funzione di caricamento

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

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

withGTConfig rileva automaticamente il file loadTranslations.[js|ts] dalla directory src/ o dalla radice del progetto.

Passaggio 2: Configurare 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: Inserisci ./public/_gt

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

Passaggio 3: Genera le traduzioni

Ora, quando esegui il comando di traduzione, le traduzioni verranno scaricate automaticamente e aggiunte alla tua codebase:

npx gtx-cli translate

Le traduzioni verranno salvate in public/_gt/ e incluse nel bundle della tua app.

Integrazione della build

Processo di build di Next.js

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 importazione

Fai corrispondere la struttura delle directory nella funzione load:

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

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

Dimensione del bundle elevata

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

Prossimi passaggi

• Guida al middleware - Rilevamento della lingua e instradamento
• Guida alle lingue - Configurare le lingue supportate
• Riferimenti API: