# react-native: React Native Quickstart
URL: https://generaltranslation.com/en-US/docs/react-native/tutorials/quickstart.mdx
---
title: React Native Quickstart
description: Add multiple languages to your React Native app in under 10 minutes
---

By the end of this guide, your React Native app will display content in multiple languages, with a language switcher your users can interact with.

**Prerequisites:**
- A React Native CLI app (not Expo — see the [Expo quickstart](/docs/react-native/tutorials/quickstart-expo) for Expo projects)
- Node.js 18+

<Callout type='warn'>
  `gt-react-native` is still experimental and may not work for all projects.
  Please let us know if you encounter any issues by [opening an issue on GitHub](https://github.com/generaltranslation/gt/issues).
</Callout>

<Callout type='info'>
  **Want automatic setup?** Run `npx gt@latest` to configure everything with the [Setup Wizard](/docs/cli/init). This guide covers manual setup.
</Callout>

---

## Step 1: Install the packages

`gt-react-native` is the library that powers translations in your app. `gt` is the CLI tool that prepares translations for 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>

---

## Step 2: Create a translation config file

Create a **`gt.config.json`** file in your project root. This tells the library which languages you support:

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

- **`defaultLocale`** — the language your app is written in (your source language).
- **`locales`** — the languages you want to translate into. Pick any from the [supported locales list](/docs/platform/supported-locales).
- **`files.gt.output`** — where the CLI saves translation files. `[locale]` is replaced with each language code (e.g., `content/es.json`).

---

## Step 3: Set up polyfills

React Native's JavaScript runtime doesn't include the `Intl` APIs that `gt-react-native` needs. The easiest fix is the included Babel plugin.

Add it to your Babel config, pointing `entryPointFilePath` to your app's entry file (check the `"main"` field in your `package.json`):

```js title="babel.config.js"
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: require.resolve(__dirname, 'App.tsx'),
      },
    ],
  ],
};
```

<Accordions>
  <Accordion title="Babel plugin not working? Polyfill manually instead">
    Install the FormatJS polyfills and import them at the top of your entry file. You need base polyfills plus locale-specific data for each language you support.

    See [FormatJS's polyfill documentation](https://formatjs.github.io/docs/polyfills) for the full list. At minimum you need:

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

    // Add locale data for each language:
    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';
    // ... repeat for each locale and polyfill
    ```
  </Accordion>
</Accordions>

---

## Step 4: Create a translation loader

Metro (React Native's bundler) doesn't support dynamic imports, so you need to explicitly map each locale to its translation file:

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

These files are generated by the CLI when you run `npx gt translate`.

---

## Step 5: Add the GTProvider to your app

The **`GTProvider`** component gives your entire app access to translations. Wrap your app at the root level:

```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}
    >
      {/* Your app content */}
    </GTProvider>
  );
}
```

`GTProvider` manages locale state and makes translations available to all child components. The `devApiKey` prop enables on-demand translation during development.

---

## Step 6: Mark content for translation

Wrap any text you want translated with the **`<T>`** component:

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

Everything inside `<T>` gets translated as a unit.

---

## Step 7: Add a language switcher

Drop in a **`<LocaleSelector>`** so users can change languages:

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

export default function Home() {
  return (
    <View>
      <LocaleSelector />
      <T>
        <Text>Welcome to my app</Text>
      </T>
    </View>
  );
}
```

`LocaleSelector` renders a picker populated with the languages from your `gt.config.json`.

---

## Step 8: Set up environment variables (optional)

To see translations in development, you need API keys from General Translation. These enable **on-demand translation** — your app translates content in real time as you develop.

Create a **`.env`** file:

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

Get your free keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) or by running:

```bash
npx gt auth
```

<Callout type="warn">
  For development, use a key starting with `gtx-dev-`. Production keys (`gtx-api-`) are for CI/CD only.

  Never expose production API keys in your app bundle or commit them to source control.
</Callout>

<Accordions>
  <Accordion title="Can I use gt-react-native without API keys?">
    Yes. Without API keys, `gt-react-native` works as a standard i18n library. You won't get on-demand translation in development, but you can still:
    - Provide your own translation files manually
    - Use all components (`<T>`, `<Var>`, `LocaleSelector`, etc.)
    - Run `npx gt generate` to create translation file templates, then translate them yourself
  </Accordion>
</Accordions>

---

## Step 9: See it working

Build and run your app:

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

Use the language picker to switch languages. You should see your content translated.

<Callout type="info">
  In development, translations happen on-demand — you may see a brief loading state the first time you switch to a new language. In production, translations are pre-generated and load instantly.
</Callout>

---

## Step 10: Translate strings (not just JSX)

For plain strings — like `placeholder` attributes or `accessibilityLabel` values — use the **`useGT`** hook:

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

---

## Step 11: Deploy to production

In production, translations are pre-generated at build time (no real-time API calls). Add the translate command to your build script:

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

Set your **production** environment variables in your CI/CD:

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

<Callout type="warn">
  Production keys start with `gtx-api-` (not `gtx-dev-`). Get one from [dash.generaltranslation.com](https://dash.generaltranslation.com). Never expose production keys in your app bundle.
</Callout>

That's it — your app is now multilingual. 🎉

---

## Troubleshooting

<Accordions>
  <Accordion title="'GtReactNative' could not be found">
    ```
    ERROR  [Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'GtReactNative' could not be found.]
    ```
    This means the native module hasn't been linked. Run `cd ios && pod install` and rebuild your app.
  </Accordion>
  <Accordion title="Invalid locale codes error">
    ```
    Error: You are using invalid locale codes in your configuration.
    ```
    This typically means polyfills aren't set up correctly. Make sure the Babel plugin is configured (or manual polyfills are imported) and clear the Metro cache:
    ```bash
    npx react-native start --reset-cache
    ```
  </Accordion>
  <Accordion title="Translations are slow in development">
    This is expected. In development, translations happen on-demand (your content is translated in real time via the API). This delay **does not exist in production** — all translations are pre-generated by `npx gt translate`.
  </Accordion>
  <Accordion title="Some translations are inaccurate">
    Ambiguous text can lead to inaccurate translations. For example, "apple" could mean the fruit or the company. Add a `context` prop to help:

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

    Both `<T>` and `useGT()` support the `context` option.
  </Accordion>
</Accordions>

---

## Next steps

- [**`<T>` Component Guide**](/docs/react-native/guides/t) — Learn about variables, plurals, and advanced translation patterns
- [**String Translation Guide**](/docs/react-native/guides/strings) — Deep dive into `useGT`
- [**Variable Components**](/docs/react-native/guides/variables) — Handle dynamic content with `<Var>`, `<Num>`, `<Currency>`, and `<DateTime>`
- [**Deploying to Production**](/docs/react-native/tutorials/quickdeploy) — CI/CD setup, caching, and performance optimization