# react-native: Guida rapida a React Native
URL: https://generaltranslation.com/it/docs/react-native/tutorials/quickstart.mdx
---
title: Guida rapida a React Native
description: Aggiungi più lingue alla tua app React Native in meno di 10 minuti
---

Alla fine di questa guida, la tua app React Native mostrerà contenuti in più lingue, con un selettore della lingua con cui gli utenti potranno interagire.

**Prerequisiti:**

* Un'app React Native CLI (non Expo — per i progetti Expo, consulta la [guida rapida di Expo](/docs/react-native/tutorials/quickstart-expo))
* Node.js 18+

<Callout type="warn">
  `gt-react-native` è ancora sperimentale e potrebbe non funzionare con tutti i progetti.
  Se riscontri problemi, faccelo sapere [aprendo una issue su GitHub](https://github.com/generaltranslation/gt/issues).
</Callout>

<Callout type="info">
  **Vuoi una configurazione automatica?** Esegui `npx gt@latest` per configurare tutto con il [Wizard di setup](/docs/cli/init). Questa guida illustra la configurazione manuale.
</Callout>

***

## Passaggio 1: Installa i pacchetti

`gt-react-native` è la libreria che gestisce le traduzioni nella tua app. `gt` è lo strumento CLI che prepara le traduzioni per l&#39;ambiente di produzione.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-react-native
    npm i -D gt
    cd ios && pod install
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-react-native
    yarn add --dev gt
    cd ios && pod install
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-react-native
    bun add --dev gt
    cd ios && pod install
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-react-native
    pnpm add --save-dev gt
    cd ios && pod install
    ```
  </Tab>
</Tabs>

***

## Passaggio 2: Crea un file di configurazione per la traduzione

Crea un file **`gt.config.json`** nella directory principale del progetto. Questo indica alla libreria quali lingue supporta il progetto:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": {
    "gt": {
      "output": "content/[locale].json"
    }
  }
}
```

* **`defaultLocale`** — la lingua in cui è scritta la tua app (la lingua di origine).
* **`locales`** — le lingue in cui vuoi tradurre. Scegline una dall&#39;[elenco delle impostazioni regionali supportate](/docs/platform/supported-locales).
* **`files.gt.output`** — dove la CLI salva i file di traduzione. `[locale]` viene sostituito con ogni codice lingua (ad esempio, `content/es.json`).

***


## Passaggio 3: Configura i polyfill

Il runtime JavaScript di React Native non include le API `Intl` necessarie a `gt-react-native`. La soluzione più semplice è usare il plugin Babel incluso.

Aggiungilo alla configurazione Babel, impostando `entryPointFilePath` sul file di ingresso della tua app (controlla il campo `"main"` nel tuo `package.json`):

```js title="babel.config.js"
const path = require('path');
const gtPlugin = require('gt-react-native/plugin');
const gtConfig = require('./gt.config.json');

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    [
      gtPlugin,
      {
        locales: [gtConfig.defaultLocale, ...gtConfig.locales],
        entryPointFilePath: path.resolve(__dirname, 'App.tsx'),
      },
    ],
  ],
};
```

<Accordions>
  <Accordion title="Il plugin Babel non funziona? Applica invece i polyfill manualmente">
    Installa i polyfill di FormatJS e importali all&#39;inizio del file di ingresso. Ti servono i polyfill di base, più i dati specifici dell&#39;impostazione regionale per ogni lingua supportata.

    Consulta la [documentazione sui polyfill di FormatJS](https://formatjs.github.io/docs/polyfills) per l&#39;elenco completo. Come minimo, ti servono:

    ```tsx title="index.js"
    import '@formatjs/intl-getcanonicallocales/polyfill';
    import '@formatjs/intl-locale/polyfill';
    import '@formatjs/intl-pluralrules/polyfill-force';
    import '@formatjs/intl-numberformat/polyfill';
    import '@formatjs/intl-datetimeformat/polyfill';
    import '@formatjs/intl-datetimeformat/add-all-tz';

    // Aggiungi i dati dell'impostazione regionale per ogni lingua:
    import '@formatjs/intl-pluralrules/locale-data/en';
    import '@formatjs/intl-pluralrules/locale-data/es';
    import '@formatjs/intl-numberformat/locale-data/en';
    import '@formatjs/intl-numberformat/locale-data/es';
    // ... ripeti per ogni impostazione regionale e polyfill
    ```
  </Accordion>
</Accordions>

***

## Passaggio 4: Crea un loader delle traduzioni

Metro (il bundler di React Native) non supporta gli import dinamici, quindi devi associare esplicitamente ogni impostazione regionale al relativo file di traduzione:

```ts title="loadTranslations.ts"
const translations: Record<string, any> = {
  es: require("./content/es.json"),
  fr: require("./content/fr.json"),
  ja: require("./content/ja.json"),
};

export function loadTranslations(locale: string) {
  return translations[locale] ?? {};
}
```

Questi file vengono generati dalla CLI quando esegui `npx gt translate`.

***


## Passaggio 5: aggiungi GTProvider alla tua app

Il componente **`GTProvider`** fornisce all&#39;intera app l&#39;accesso alle traduzioni. Avvolgi la tua app nel componente radice:

```tsx title="App.tsx"
import { GTProvider } from 'gt-react-native';
import gtConfig from './gt.config.json';
import { loadTranslations } from './loadTranslations';

export default function App() {
  return (
    <GTProvider
      config={gtConfig}
      loadTranslations={loadTranslations}
      projectId={process.env.GT_PROJECT_ID}
      devApiKey={process.env.GT_API_KEY}
    >
      {/* Il contenuto della tua app */}
    </GTProvider>
  );
}
```

`GTProvider` gestisce lo stato dell&#39;impostazione regionale e rende le traduzioni disponibili per tutti i componenti figli. La prop `devApiKey` abilita la traduzione on-demand durante lo sviluppo.

***


## Passaggio 6: Contrassegna i contenuti da tradurre

Racchiudi nel componente **`<T>`** tutto il testo che vuoi tradurre:

```tsx title="screens/Home.tsx"
import { Text, View } from 'react-native';
import { T } from 'gt-react-native';

export default function Home() {
  return (
    <View>
      <T>
        <Text>Welcome to my app</Text>
      </T>
      <T>
        <Text>This content will be translated automatically.</Text>
      </T>
    </View>
  );
}
```

Tutto ciò che è incluso in `<T>` viene tradotto come un&#39;unica unità.

***


## Passaggio 7: Aggiungi un selettore della lingua

Usa l&#39;hook **`useLocaleSelector`** per creare un selettore della lingua. A differenza di `gt-react`, `gt-react-native` non esporta un componente `<LocaleSelector>` già pronto: devi creare tu l&#39;interfaccia con l&#39;hook:

```tsx title="screens/Home.tsx"
import { Text, View, Pressable } from 'react-native';
import { T, useLocaleSelector } from 'gt-react-native';

export default function Home() {
  const { locales, locale, setLocale } = useLocaleSelector();

  return (
    <View>
      <View style={{ flexDirection: 'row', gap: 8, marginBottom: 16 }}>
        {locales.map((l) => (
          <Pressable key={l} onPress={() => setLocale(l)}>
            <Text style={{ fontWeight: l === locale ? 'bold' : 'normal' }}>{l}</Text>
          </Pressable>
        ))}
      </View>
      <T>
        <Text>Welcome to my app</Text>
      </T>
    </View>
  );
}
```

`useLocaleSelector` restituisce le impostazioni regionali disponibili, l&#39;impostazione regionale corrente e un setter, offrendoti il controllo completo dell&#39;interfaccia utente.

***

## Passaggio 8: Configura le variabili d&#39;ambiente (facoltativo)

Per vedere le traduzioni in fase di sviluppo, ti servono le chiavi API di General Translation. Queste abilitano la **traduzione on-demand**: la tua app traduce i contenuti in tempo reale mentre lavori allo sviluppo.

Crea un file **`.env`**:

```bash title=".env"
GT_API_KEY="your-api-key"
GT_PROJECT_ID="your-project-id"
```

Ottieni le chiavi gratuite su [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) oppure eseguendo:

```bash
npx gt auth
```

<Callout type="warn">
  Per lo sviluppo, usa una chiave che inizi con `gtx-dev-`. Le chiavi di produzione (`gtx-api-`) sono solo per CI/CD.

  Non esporre mai le chiavi API di produzione nel bundle della tua app e non salvarle nel controllo di versione.
</Callout>

<Accordions>
  <Accordion title="Posso usare gt-react-native senza chiavi API?">
    Sì. Senza chiavi API, `gt-react-native` funziona come una normale libreria i18n. Non avrai la traduzione on-demand in sviluppo, ma puoi comunque:

    * Fornire manualmente i file di traduzione
    * Usare tutti i componenti (`<T>`, `<Var>`, `LocaleSelector`, ecc.)
    * Eseguire `npx gt generate` per creare modelli di file di traduzione e poi tradurli tu stesso
  </Accordion>
</Accordions>

***


## Passaggio 9: Verifica che funzioni

Compila ed esegui la tua app:

```bash
npx react-native run-ios
# oppure
npx react-native run-android
```

Usa il selettore della lingua per passare da una lingua all&#39;altra. Dovresti vedere i contenuti tradotti.

<Callout type="info">
  In fase di sviluppo, le traduzioni avvengono on-demand: la prima volta che passi a una nuova lingua potresti vedere un breve caricamento. In produzione, le traduzioni vengono pre-generate e si caricano istantaneamente.
</Callout>

***


## Passaggio 10: Traduci le stringhe (non solo JSX)

Per le stringhe normali, come gli attributi `placeholder` o i valori di `accessibilityLabel`, usa l&#39;hook **`useGT`**:

```tsx title="screens/Contact.tsx"
import { TextInput, View } from 'react-native';
import { useGT } from 'gt-react-native';

export default function Contact() {
  const gt = useGT();

  return (
    <View>
      <TextInput
        placeholder={gt('Enter your email')}
        accessibilityLabel={gt('Email input field')}
      />
    </View>
  );
}
```

***


## Passaggio 11: Esegui il deploy in produzione

In produzione, le traduzioni vengono generate in anticipo durante la fase di build (senza chiamate API in tempo reale). Aggiungi il comando `translate` allo script di build:

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && <YOUR_BUILD_COMMAND>"
  }
}
```

Imposta le variabili d&#39;ambiente di **produzione** nel tuo sistema CI/CD:

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

<Callout type="warn">
  Le chiavi di produzione iniziano con `gtx-api-` (non `gtx-dev-`). Puoi ottenerne una da [dash.generaltranslation.com](https://dash.generaltranslation.com). Non esporre mai le chiavi di produzione nel bundle della tua app.
</Callout>

Fatto: la tua app ora è multilingue. 🎉

***


## Risoluzione dei problemi

<Accordions>
  <Accordion title="Impossibile trovare 'GtReactNative'">
    ```
    ERROR  [Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'GtReactNative' could not be found.]
    ```

    Significa che il modulo nativo non è stato collegato. Esegui `cd ios && pod install` e ricompila l&#39;app.
  </Accordion>

  <Accordion title="Errore: codici di impostazione regionale non validi">
    ```
    Error: You are using invalid locale codes in your configuration.
    ```

    In genere significa che i polyfill non sono configurati correttamente. Assicurati che il plugin Babel sia configurato (oppure che i polyfill manuali siano importati) e svuota la cache di Metro:

    ```bash
    npx react-native start --reset-cache
    ```
  </Accordion>

  <Accordion title="Le traduzioni sono lente in sviluppo">
    È previsto. In sviluppo, le traduzioni avvengono on-demand (i contenuti vengono tradotti in tempo reale tramite l&#39;API). Questo ritardo **non esiste in produzione** — tutte le traduzioni vengono pre-generate da `npx gt translate`.
  </Accordion>

  <Accordion title="Alcune traduzioni non sono corrette">
    Un testo ambiguo può portare a traduzioni imprecise. Ad esempio, &quot;apple&quot; potrebbe indicare il frutto o l&#39;azienda. Aggiungi una prop `context` per chiarire:

    ```jsx
    <T context="the technology company">Apple</T>
    ```

    Sia `<T>` sia `useGT()` supportano l&#39;opzione `context`.
  </Accordion>
</Accordions>

***

## Prossimi passi

* [**Guida al componente `<T>`**](/docs/react-native/guides/t) — Scopri variabili, plurali e schemi di traduzione avanzati
* [**Guida alla traduzione delle stringhe**](/docs/react-native/guides/strings) — Approfondisci `useGT`
* [**Componenti variabili**](/docs/react-native/guides/variables) — Gestisci i contenuti dinamici con `<Var>`, `<Num>`, `<Currency>` e `<DateTime>`
* [**Deploy in produzione**](/docs/react-native/tutorials/quickdeploy) — Configurazione CI/CD, caching e ottimizzazione delle prestazioni