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

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

**Prérequis :**

* Une application React Native CLI (pas Expo — consultez le [démarrage rapide Expo](/docs/react-native/tutorials/quickstart-expo) pour les projets Expo)
* Node.js 18+

<Callout type="warn">
  `gt-react-native` est encore expérimental et peut ne pas fonctionner avec tous les projets.
  Si vous rencontrez des problèmes, veuillez nous en informer en [ouvrant une issue sur GitHub](https://github.com/generaltranslation/gt/issues).
</Callout>

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

***

## Étape 1 : Installez les packages

`gt-react-native` est la bibliothèque qui gère les traductions dans votre application. `gt` est l’outil en ligne de commande 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
    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>

***

## É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 les langues 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 vers lesquelles vous souhaitez traduire. Choisissez-les dans la [liste des paramètres régionaux pris en charge](/docs/platform/supported-locales).
* **`files.gt.output`** — l’emplacement où le CLI enregistre les fichiers de traduction. `[locale]` est remplacé par chaque code de langue (par exemple, `content/es.json`).

***


## Étape 3 : Configurer les polyfills

Le runtime JavaScript de React Native n&#39;inclut pas les API `Intl` requises par `gt-react-native`. La solution la plus simple consiste à utiliser le plugin Babel fourni.

Ajoutez-le à votre configuration Babel en faisant pointer `entryPointFilePath` vers le fichier d&#39;entrée de votre application (vérifiez le champ `"main"` dans votre `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="Le plugin Babel ne fonctionne pas ? Utilisez plutôt un polyfill manuel">
    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 à chaque 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 chaque polyfill
    ```
  </Accordion>
</Accordions>

***

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

Metro (le bundler de React Native) 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 lancez `npx gt translate`.

***


## Étape 5 : Ajoutez GTProvider à votre application

Le composant **`GTProvider`** donne à l’ensemble de votre application accès aux traductions. Enveloppez votre application à la racine :

```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}
    >
      {/* Le contenu de votre application */}
    </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` active la traduction à la demande en développement.

***


## Étape 6 : Marquez le contenu à traduire

Encapsulez tout texte que vous souhaitez traduire dans le composant **`<T>`** :

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

Tout ce qui se trouve dans `<T>` est traduit en 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="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` renvoie les paramètres régionaux disponibles, le paramètre régional actuel et un setter, ce qui vous donne un contrôle total sur l’interface utilisateur.

***

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

Pour afficher les traductions en développement, vous avez besoin de clés API General Translation. Elles activent la **traduction à la demande** : votre application traduit le contenu en temps réel pendant que vous développez.

Créez un fichier **`.env`** :

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

Obtenez vos clés gratuites sur [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) ou en lançant :

```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 ajoutez jamais au contrôle de version.
</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 de 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 tout fonctionne

Compilez et lancez votre application :

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

Utilisez le sélecteur de langue pour passer d’une langue à l’autre. Vous devriez voir votre contenu traduit.

<Callout type="info">
  En développement, les traductions se font à la demande — un bref chargement peut apparaître 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 des chaînes de caractères (pas seulement du JSX)

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

***


## Étape 11 : Déployer en production

En production, les traductions sont pré-générées au build (aucun appel à l’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 :

```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 par `gtx-dev-`). Obtenez-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’est tout — votre application est maintenant 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’a pas été lié. Exécutez `cd ios && pod install`, puis recompilez votre application.
  </Accordion>

  <Accordion title="Erreur : 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 configurés correctement. Assurez-vous que le plugin Babel est configuré (ou que les polyfills manuels sont importés), puis videz le cache Metro :

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

  <Accordion title="Les traductions sont lentes en développement">
    C’est normal. En développement, les traductions se font à la demande (votre contenu est traduit en temps réel via l’API). Ce délai **n’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, « apple » peut désigner le fruit ou l’entreprise. Ajoutez une prop `context` pour préciser le sens :

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

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

***

## Prochaines étapes

* [**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) — Approfondissez `useGT`
* [**Composants de variables**](/docs/react-native/guides/variables) — Gérez le contenu dynamique avec `<Var>`, `<Num>`, `<Currency>` et `<DateTime>`
* [**Déployer en production**](/docs/react-native/tutorials/quickdeploy) — Configuration CI/CD, mise en cache et optimisation des performances