# react-native: Démarrage rapide React Native avec Expo
URL: https://generaltranslation.com/fr/docs/react-native/tutorials/quickstart-expo.mdx
---
title: Démarrage rapide React Native avec Expo
description: Ajoutez plusieurs langues à votre application Expo en moins de 10 minutes
---

À la fin de ce guide, votre application Expo affichera du contenu en plusieurs langues, avec un sélecteur de langue que vos utilisateurs pourront utiliser.

**Prérequis :**

* Un projet Expo (SDK 49+)
* Node.js 18+

<Callout type="warn">
  `gt-react-native` est toujours expérimental et peut ne pas fonctionner sur tous les projets.
  N&#39;hésitez pas à nous le signaler si vous rencontrez des problèmes en [ouvrant une issue sur GitHub](https://github.com/generaltranslation/gt/issues).
</Callout>

<Callout type="info">
  **Vous voulez une configuration automatique ?** Exécutez `npx gt@latest` pour tout configurer avec l&#39;[assistant de configuration](/docs/cli/init). Ce guide couvre la configuration manuelle.
</Callout>

<Callout type="info">
  Vous cherchez un projet React Native CLI sans Expo ? Consultez le [démarrage rapide React Native](/docs/react-native/tutorials/quickstart).
</Callout>

***

## Étape 1 : Installez les paquets

`gt-react-native` est la bibliothèque qui gère les traductions dans votre application. `gt` est l’outil CLI qui prépare les traductions pour la production.

<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>

***

## Étape 2 : Créez un fichier de configuration de traduction

Créez un fichier **`gt.config.json`** à la racine de votre projet. Cela indique à la bibliothèque quelles langues sont prises en charge :

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

* **`defaultLocale`** — la langue dans laquelle votre application est écrite (votre langue source).
* **`locales`** — les langues dans lesquelles vous voulez traduire votre application. Choisissez-en dans la [liste des paramètres régionaux pris en charge](/docs/platform/supported-locales).
* **`files.gt.output`** — l’emplacement où la CLI enregistre les fichiers de traduction. `[locale]` est remplacé par chaque code de langue (par exemple, `content/es.json`).

***


## Étape 3 : Configurer les polyfills

L’environnement d’exécution JavaScript de React Native n’inclut pas les API `Intl` nécessaires à `gt-react-native`. Le plus simple est d’utiliser le plugin Babel fourni.

Ajoutez-le à votre configuration 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="Le plugin Babel ne fonctionne pas ? Ajoutez les polyfills manuellement à la place">
    Installez les polyfills FormatJS et importez-les en haut de votre fichier d’entrée. Vous avez besoin des polyfills de base, ainsi que des données propres au paramètre régional pour chaque langue prise en charge.

    Consultez [la documentation des polyfills de FormatJS](https://formatjs.github.io/docs/polyfills) pour obtenir la liste complète. Au minimum, il vous faut :

    ```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';

    // Ajoutez les données de paramètre régional pour chaque langue :
    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';
    // ... répétez l’opération pour chaque paramètre régional et polyfill
    ```
  </Accordion>
</Accordions>

***

## Étape 4 : Créer un chargeur de traductions

Metro (le bundler d’Expo) ne prend pas en charge les imports dynamiques. Vous devez donc associer explicitement chaque paramètre régional à son fichier de traduction :

```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] ?? {};
}
```

Ces fichiers sont générés par la CLI lorsque vous exécutez `npx gt translate`.

***


## Étape 5 : Ajouter GTProvider à votre layout

Le composant **`GTProvider`** permet à toute votre application d’accéder aux traductions. Ajoutez-le à votre layout racine :

```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` gère l’état du paramètre régional et met les traductions à la disposition de tous les composants enfants. La prop `devApiKey` permet la traduction à la demande pendant le développement.

***


## Étape 6 : Marquez le contenu à traduire

Entourez de **`<T>`** tout texte que vous souhaitez traduire :

```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>
  );
}
```

Tout ce qui se trouve dans `<T>` est traduit d’un seul bloc.

***


## Étape 7 : Ajouter un sélecteur de langue

Utilisez le hook **`useLocaleSelector`** pour créer un sélecteur de langue. Contrairement à `gt-react`, `gt-react-native` n’exporte pas de composant `<LocaleSelector>` prêt à l’emploi : vous devez créer votre propre interface utilisateur à l’aide du 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` renvoie les paramètres régionaux disponibles, le paramètre régional actuel et une fonction de mise à jour — ce qui vous donne un contrôle total sur l’interface utilisateur.

***

## Étape 8 : Configurer les variables d’environnement (facultatif)

Pour voir les traductions en développement, vous avez besoin de clés API General Translation.

Créez un fichier **`.env.local`**. Expo exige que les variables d’environnement publiques soient préfixées par `EXPO_PUBLIC_` :

```bash title=".env.local"
EXPO_PUBLIC_GT_DEV_API_KEY="your-dev-api-key"
EXPO_PUBLIC_GT_PROJECT_ID="your-project-id"
```

Obtenez gratuitement vos clés sur [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) ou en exécutant :

```bash
npx gt auth
```

<Callout type="warn">
  Pour le développement, utilisez une clé commençant par `gtx-dev-`. Les clés de production (`gtx-api-`) sont réservées au CI/CD.

  N’exposez jamais de clés d’API de production dans le bundle de votre application et ne les versionnez jamais.
</Callout>

<Accordions>
  <Accordion title="Puis-je utiliser gt-react-native sans clés d’API ?">
    Oui. Sans clés d’API, `gt-react-native` fonctionne comme une bibliothèque d’i18n standard. Vous n’aurez pas la traduction à la demande en développement, mais vous pouvez quand même :

    * Fournir manuellement vos propres fichiers de traduction
    * Utiliser tous les composants (`<T>`, `<Var>`, `LocaleSelector`, etc.)
    * Exécuter `npx gt generate` pour créer des modèles de fichiers de traduction, puis les traduire vous-même
  </Accordion>
</Accordions>

***


## Étape 9 : Vérifiez que cela fonctionne

Démarrez votre build de développement :

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

<Callout type="warn">
  **Expo Go ne fonctionne pas** avec `gt-react-native`, car il inclut un module natif. Vous avez besoin d’une [build de développement](https://docs.expo.dev/develop/development-builds/introduction/) :

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

Utilisez le sélecteur de langue pour passer d’une langue à l’autre. Votre contenu devrait alors s’afficher traduit.

<Callout type="info">
  En développement, les traductions se font à la demande : vous pouvez voir un bref chargement la première fois que vous passez à une nouvelle langue. En production, les traductions sont pré-générées et se chargent instantanément.
</Callout>

***


## Étape 10 : Traduire les chaînes de caractères (pas seulement le JSX)

Pour les chaînes de caractères simples — comme les attributs `placeholder` ou les valeurs `accessibilityLabel` — utilisez le 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>
  );
}
```

***


## Étape 11 : Déployer en production

En production, les traductions sont pré-générées au moment du build (sans appel d’API en temps réel). Ajoutez la commande translate à votre script de build :

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

Définissez vos variables d’environnement de **production** dans votre pipeline CI/CD (elles sont uniquement côté serveur, et non `EXPO_PUBLIC_`) :

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

<Callout type="warn">
  Les clés de production commencent par `gtx-api-` (et non `gtx-dev-`). Récupérez-en une sur [dash.generaltranslation.com](https://dash.generaltranslation.com). N’exposez jamais de clés de production dans le bundle de votre application.
</Callout>

C&#39;est tout — votre application est désormais multilingue. 🎉

***


## Dépannage

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

    Cela signifie que le module natif n&#39;a pas été correctement lié. Causes fréquentes :

    1. **Vous utilisez Expo Go** au lieu d&#39;une version de développement. Passez à un build de développement :

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

    2. **Les Pods ne sont pas à jour (iOS).** Essayez de les réinstaller :

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

  <Accordion title="Erreur de codes de langue invalides">
    ```
    Error: You are using invalid locale codes in your configuration.
    ```

    Cela signifie généralement que les polyfills ne sont pas correctement configurés. Assurez-vous que le plugin Babel est bien configuré (ou que les polyfills manuels sont importés), puis videz le cache :

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

  <Accordion title="Les traductions sont lentes en développement">
    C&#39;est normal. En développement, les traductions se font à la demande (votre contenu est traduit en temps réel via l&#39;API). Ce délai **n&#39;existe pas en production** : toutes les traductions sont pré-générées par `npx gt translate`.
  </Accordion>

  <Accordion title="Certaines traductions sont inexactes">
    Un texte ambigu peut entraîner des traductions inexactes. Par exemple, &quot;apple&quot; peut désigner le fruit ou l&#39;entreprise. Ajoutez une prop `context` pour lever l&#39;ambiguïté :

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

    `<T>` et `useGT()` prennent tous deux en charge l&#39;option `context`.
  </Accordion>
</Accordions>

***

## Étapes suivantes

* [**Guide du composant `<T>`**](/docs/react-native/guides/t) — Découvrez les variables, les pluriels et les schémas de traduction avancés
* [**Guide de traduction des chaînes**](/docs/react-native/guides/strings) — Explorez `useGT` en profondeur
* [**Composants variables**](/docs/react-native/guides/variables) — Gérez le contenu dynamique avec `<Var>`, `<Num>`, `<Currency>` et `<DateTime>`
* [**Déploiement en production**](/docs/react-native/tutorials/quickdeploy) — Configuration CI/CD, mise en cache et optimisation des performances