Panoramica

gt-react/browser ora supporta l'hot reload delle traduzioni in sviluppo. In precedenza, ogni volta che modificavi il codice in un'app GT lato browser, dovevi eseguire di nuovo il comando di traduzione per vedere le traduzioni aggiornate. Con questa release, le traduzioni vengono precalcolate a runtime durante lo sviluppo, senza bisogno di ripetere manualmente la traduzione.

Questo porta gt-react/browser allo stesso livello del flusso di traduzione standard di gt-react. Tieni presente che gt-react/browser è solo per single-page application (SPA) — se usi un framework con rendering lato server, usa gt-react (non gt-react/browser). Questa funzionalità è inoltre solo per lo sviluppo — le build di produzione continuano a usare traduzioni precalcolate come prima.

Come funziona

Il plugin del compilatore inserisce chiamate di traduzione runtime a livello di modulo. L'esecuzione del rendering viene sospesa finché non vengono risolte.

Quando devHotReload è abilitato, il compilatore aggiunge le chiamate GtInternalRuntimeTranslateString e GtInternalRuntimeTranslateJsx, che preriscaldano la cache delle traduzioni al caricamento del modulo. Per JSX, le traduzioni possono anche essere risolte tramite una chiamata a Suspense all'interno del componente <T> stesso, anziché essere caricate a livello di modulo.

Poiché le traduzioni avvengono a runtime, viene tradotta solo la lingua verso cui l'utente naviga effettivamente — a differenza degli approcci build-time, che devono generare traduzioni per ogni lingua configurata a ogni build di sviluppo, anche se poi non le visualizzi mai.

Le traduzioni recuperate a runtime vengono memorizzate nella cache di localStorage, quindi persistono tra un aggiornamento della pagina e l'altro.

Configurazione

1. Aggiungi il plugin del compilatore

L'hot reload in fase di sviluppo richiede il plugin del compilatore GT. Se non l'hai già fatto, aggiungilo alla configurazione del bundler — ad esempio, il plugin Vite:

// vite.config.ts
import { vite as gtCompiler } from "@generaltranslation/compiler"
import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
import gtConfig from "./gt.config.json"

export default defineConfig({
  plugins: [react(), gtCompiler({ gtConfig })]
})

Per gli altri bundler, consulta le docs di setup di gt-react.

2. Abilita il ricaricamento automatico in sviluppo in gt.config.json

{
  "files": {
    "gt": {
      "parsingFlags": {
        "devHotReload": true
      }
    }
  }
}

Per impostazione predefinita, devHotReload: true abilita l'hot reload per le stringhe, ma non per JSX. JSX è disattivato perché il componente <T> gestisce già la traduzione del JSX a runtime tramite Suspense, quindi non è necessario bloccare il caricamento del modulo in attesa che venga completata. Se necessario, puoi configurare queste opzioni separatamente:

{
  "files": {
    "gt": {
      "parsingFlags": {
        "devHotReload": {
          "strings": true,
          "jsx": false
        }
      }
    }
  }
}

3. Passa le credenziali a bootstrap()

Devi anche passare direttamente l'ID del progetto e la chiave API di sviluppo alla chiamata bootstrap(), insieme a una funzione loadTranslations. Si tratta di una particolarità dell'implementazione attuale che prevediamo di semplificare in una release futura.

await bootstrap({
  ...gtConfig,
  loadTranslations,
  projectId: import.meta.env.VITE_GT_PROJECT_ID,
  devApiKey: import.meta.env.VITE_GT_DEV_API_KEY
})

Link

• Dev log precedente: abbandono del React context (gt-react@10.12.0)
• PR #1217