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

Al termine di questa guida, la tua app Expo mostrerà contenuti in più lingue, con un selettore di lingua che gli utenti potranno usare.

**Prerequisiti:**

* Un progetto Expo (SDK 49+)
* 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 segnalazione su GitHub](https://github.com/generaltranslation/gt/issues).
</Callout>

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

<Callout type="info">
  Cerchi un progetto React Native CLI bare? Consulta la [Guida rapida a React Native](/docs/react-native/tutorials/quickstart).
</Callout>

***

## Passaggio 1: Installa i pacchetti

`gt-react-native` è la libreria che gestisce le traduzioni nella tua app. `gt` è lo strumento da riga di comando 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
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-react-native
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-react-native
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-react-native
    pnpm add --save-dev gt
    ```
  </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 supporti:

```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. Scegli quelle che ti servono 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 ciascun codice lingua (ad esempio, `content/es.json`).

***


## Passaggio 3: Configura i polyfill

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

Aggiungilo alla configurazione di Babel:

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

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: [
      [
        gtPlugin,
        {
          locales: [gtConfig.defaultLocale, ...gtConfig.locales],
          entryPointFilePath: require.resolve('expo-router/entry'),
        },
      ],
    ],
  };
};
```

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

    Consulta [la documentazione dei 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 Expo) non supporta gli import dinamici, quindi devi mappare 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 al layout

Il componente **`GTProvider`** consente all&#39;intera app di accedere alle traduzioni. Aggiungilo al layout principale:

```tsx title="app/_layout.tsx"
import { Slot } from 'expo-router';
import { GTProvider } from 'gt-react-native';
import gtConfig from '../gt.config.json';
import { loadTranslations } from '../loadTranslations';

export default function RootLayout() {
  return (
    <GTProvider
      config={gtConfig}
      loadTranslations={loadTranslations}
      projectId={process.env.EXPO_PUBLIC_GT_PROJECT_ID}
      devApiKey={process.env.EXPO_PUBLIC_GT_DEV_API_KEY}
    >
      <Slot />
    </GTProvider>
  );
}
```

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

***


## Passaggio 6: Contrassegna il contenuto da tradurre

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

```tsx title="app/index.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 si trova all&#39;interno di `<T>` viene tradotto come un unico blocco.

***


## Passaggio 7: Aggiungi un selettore di lingua

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

```tsx title="app/index.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, quella corrente e un setter, offrendoti il pieno controllo sull&#39;interfaccia utente.

***

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

Per vedere le traduzioni durante lo sviluppo, ti servono le chiavi API di General Translation.

Crea un file **`.env.local`**. Expo richiede che le variabili d&#39;ambiente pubbliche siano precedute dal prefisso `EXPO_PUBLIC_`:

```bash title=".env.local"
EXPO_PUBLIC_GT_DEV_API_KEY="your-dev-api-key"
EXPO_PUBLIC_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 inserirle nel controllo del codice sorgente.
</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 durante lo sviluppo, ma puoi comunque:

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

***


## Passaggio 9: Verifica che funzioni

Avvia la build di sviluppo:

```bash
npx expo start --dev-client
```

<Callout type="warn">
  **Expo Go non funziona** con `gt-react-native` perché include un modulo nativo. Ti serve una [build di sviluppo](https://docs.expo.dev/develop/development-builds/introduction/):

  ```bash
  npx expo run:ios
  # oppure
  npx expo run:android
  ```
</Callout>

Usa il selettore della lingua per cambiare lingua. 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 notare un breve caricamento. In produzione, le traduzioni vengono pregenerate e caricate istantaneamente.
</Callout>

***


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

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

```tsx title="app/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 deployment in produzione

In produzione, le traduzioni vengono generate in anticipo in fase di build (senza chiamate API in tempo reale). Aggiungi il comando di traduzione 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 CI/CD (sono solo lato server, non `EXPO_PUBLIC_`):

```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="'GtReactNative' non è stato trovato">
    ```
    ERROR  [Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'GtReactNative' could not be found.]
    ```

    Questo significa che il modulo nativo non è stato collegato. Cause comuni:

    1. **Stai usando Expo Go** invece di una build di sviluppo. Passa a una build di sviluppo:

    ```bash
    npx expo run:ios
    # or
    npx expo run:android
    ```

    2. **I pod non sono aggiornati (iOS).** Prova a reinstallarli:

    ```bash
    cd ios && rm -rf build Pods Podfile.lock && pod install && cd ..
    ```
  </Accordion>

  <Accordion title="Errore: codici locale 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:

    ```bash
    npx expo start --clear
    ```
  </Accordion>

  <Accordion title="Le traduzioni sono lente in fase di sviluppo">
    È normale. In fase di 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 pregenerate da `npx gt translate`.
  </Accordion>

  <Accordion title="Alcune traduzioni sono imprecise">
    Un testo ambiguo può portare a traduzioni imprecise. Per 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>

***

## Passaggi successivi

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