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 della tua 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 impostazioni locali per il tuo progetto. Consulta le impostazioni locali supportate per le opzioni.

Variabili d’ambiente

Aggiungi al file delle variabili d’ambiente per l’hot reloading 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 le tue chiavi API gratuite su dash.generaltranslation.com oppure esegui:

npx gtx-cli auth

Utilizzo

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

Contenuto JSX con <T>

Racchiudi 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 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 utilizzare 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 email')}
    />
  );
}

Consulta 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 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 caricamento). In produzione, tutto è pretradotto.

Risoluzione dei problemi

Distribuzione

In produzione è necessario pre‑tradurre i contenuti, perché 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- (diversamente 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 le chiavi di produzione con il prefisso pubblico delle variabili del tuo framework (come VITE_, REACT_APP_, ecc.): devono rimanere lato server.

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

   npx gtx-cli translate

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

   Consulta la guida di riferimento allo 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 passaggi

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