Fai tradurre la tua app React in pochi minuti.

Prerequisiti: React, conoscenze di base di JavaScript

Installazione

Installa i pacchetti gt-react e gtx-cli:

npm i gt-react
npm i gtx-cli

yarn add gt-react
yarn add --dev gtx-cli

bun add gt-react
bun add --dev gtx-cli

pnpm add gt-react
pnpm add --save-dev gtx-cli

Configurazione

GTProvider

Il componente GTProvider fornisce il contesto di traduzione ai componenti React. Gestisce lo stato della lingua/locale, le traduzioni e abilita gli hook useGT e useTranslations.

Aggiungi il GTProvider al componente radice dell’app:

import { GTProvider } from 'gt-react';

export default function App() {
  return (
    <GTProvider>
      <YourAppContent />
    </GTProvider>
  );
}

Crea un file gt.config.json nella directory principale del progetto:

{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}

Personalizza le lingue locali per il tuo progetto. Consulta le lingue locali supportate per le opzioni.

Variabili d'ambiente

Aggiungi al file delle variabili d'ambiente per l'hot reload in sviluppo:

VITE_GT_API_KEY="your-dev-api-key"
VITE_GT_PROJECT_ID="your-project-id"

REACT_APP_GT_API_KEY="your-dev-api-key"
REACT_APP_GT_PROJECT_ID="your-project-id"

GATSBY_GT_API_KEY="your-dev-api-key"
GATSBY_GT_PROJECT_ID="your-project-id"

REDWOOD_ENV_GT_API_KEY="your-dev-api-key"
REDWOOD_ENV_GT_PROJECT_ID="your-project-id"

Ottieni gratuitamente le tue chiavi API su dash.generaltranslation.com o esegui:

npx gtx-cli auth

Utilizzo

Ora puoi iniziare a internazionalizzare i contenuti. Esistono due approcci principali:

Contenuto JSX con <T>

Avvolgi gli elementi JSX per tradurli usando il componente <T>:

import { T } from 'gt-react';

function Welcome() {
  return (
    <T>
      <h1>Benvenuto nella nostra app!</h1>
    </T>
  );
}

Per i contenuti dinamici, usa i componenti variabili come <Var>:

import { T, Var } from 'gt-react';

function Greeting({ user }) {
  return (
    <T>
      <p>Ciao, <Var>{user.name}</Var>!</p>
    </T>
  );
}

Consulta la guida su come usare il componente <T> per ulteriori informazioni.

Stringhe semplici con useGT

Per attributi, etichette e testo semplice, utilizzando l’hook useGT:

import { useGT } from 'gt-react';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('Inserisci la tua email')}
      aria-label={t('Campo di input per email')}
    />
  );
}

Vedi la guida sulla traduzione delle stringhe per ulteriori informazioni.

Test dell'app

Verifica le traduzioni cambiando lingua:

1. Aggiungi un menu a discesa per la selezione della lingua/locale usando <LocaleSelector>:

   import { LocaleSelector } from 'gt-react';
   
   function App() {
     return <LocaleSelector />;
   }

2. Avvia il server di sviluppo:

   npmyarnbunpnpm

   npm run dev 

   yarn run dev 

   bun run dev 

   pnpm run dev 

3. Apri localhost:3000 e cambia lingua tramite il menu a discesa di selezione della locale.

In sviluppo, le traduzioni avvengono on demand (vedrai un breve tempo di caricamento). In produzione, tutto è pre-tradotto.

Risoluzione dei problemi

Distribuzione

In produzione è necessario pre‑tradurre i contenuti, poiché la traduzione a runtime è disabilitata (fa eccezione per le funzioni <Tx> e tx).

1. Ottieni una chiave API di produzione da dash.generaltranslation.com.

   Le chiavi di produzione iniziano con gtx-api- (diverse dalle chiavi di sviluppo, che iniziano con gtx-dev-). Scopri di più sulle differenze tra ambienti.

2. Aggiungila al tuo ambiente CI/CD:

   GT_PROJECT_ID=your-project-id
   GT_API_KEY=gtx-api-your-production-key

   Non anteporre mai alle chiavi di produzione il prefisso per variabili pubbliche del tuo framework (come VITE_, REACT_APP_, ecc.): devono rimanere solo lato server.

3. Esegui il comando di traduzione per tradurre i contenuti:

   npx gtx-cli translate

   Puoi configurare il comportamento del comando con il file gt.config.json.

   Consulta la guida di riferimento dello strumento CLI per maggiori informazioni.

4. Aggiorna lo script di build per eseguire la traduzione prima della build:

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

Prossimi passi

• Guida al componente <T> - Approfondimento sul componente <T> e sulla traduzione in JSX
• Guida alla traduzione di stringhe - Uso di useGT per tradurre le stringhe
• Componenti variabili - Gestisci contenuti dinamici con <Var>, <Num>, ecc.