# react-native: React Native Quickstart
URL: https://generaltranslation.com/en-US/docs/react-native/tutorials/quickstart.mdx
---
title: React Native Quickstart
description: Easily internationalize your React Native App with gt-react-native
---

<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'>
  **Quick Setup:** Try `npx gtx-cli@latest` for automatic configuration. See the
  [Setup Wizard](/docs/cli/init) guide or use our [AI tools
  integration](/docs/overview/ai-tools).
</Callout>

## Installation

Install the `gt-react-native` and `gtx-cli` packages:

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

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

## Setup

### Configuration

Create a `gt.config.json` file in your project root.
This will contain your project's configuration.

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

Here we have specified that we will translate our project into French and Spanish, and we want to save our translations to the `content/[locale].json` file.


### Environment variables

Add to your `.env` file for development hot-reloading and on-demand translations:

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

<Callout type="warn">
  **Dev vs prod keys:** Use a `gtx-dev-` key locally. Use a `gtx-api-` key in CI/CD if you run `gtx-cli translate` during deploy.
  Never expose production API keys in your app bundle or commit them to source control.
</Callout>

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

```bash
npx gtx-cli auth
```

<Accordions>
  <Accordion title="What if I don't want to use the General Translation platform?">
  `gt-react-native` is an i18n library that can work standalone without any environment variables.
  Without them, the library will act very similarly to other i18n libraries, and will still have core internationalization functionality.

However, `gt-react-native` also offers a native integration with the General Translation platform.
This integration unlocks additional functionality in the library, such as:

- Translation Hot Reloading in Development
- Automatic AI translations
- Syncing translations with the General Translation platform
- Native integration with our translation CDN

To avoid using the General Translation platform, just don't set any environment variables.

  </Accordion>
</Accordions>

### Loading translations

Next, create a `loadTranslations.ts` file in your project root.
This will handle pulling translations from the `content/[locale].json` files.

```tsx title="loadTranslations.ts"
// Metro does not support dynamic imports,
// so we must specify the translations for each locale manually.
const translations: Record<string, any> = {
  fr: require("@/content/fr.json"),
  zh: require("@/content/zh.json"),
};

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

You can also use the `loadTranslations` function to load translations from a custom source, such as a remote API.

### `GTProvider` [#provider]

The [`GTProvider`](/docs/react-native/api/components/gtprovider) component provides translation context to client-side components. It manages locale state, translations, and enables the [`useGT`](/docs/react-native/api/strings/use-gt) and [`useTranslations`](/docs/react-native/api/dictionary/use-translations) hooks.

Add the [`GTProvider`](/docs/react-native/api/components/gtprovider) to your root component:

```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='your-project-id'
      devApiKey='your-dev-api-key' // only needed for development
    >
      {/* your app content */}
    </GTProvider>
  );
}
```
### Polyfills

Because the React Native JS runtime does not automatically polyfill the `Intl` object, you need to polyfill it manually.
You can either use the babel plugin or polyfill manually.

#### Babel plugin

For the babel plugin, under `entryPointFilePath` just specify the entry point of your app (can often be found in the `"main"` field of 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'),
      },
    ],
  ],
};

```

#### Manual polyfilling

If you run into issues with the babel plugin, you can polyfill manually.
You will need to npm install and then polyfill the base imports as well as locale-specific imports.

The following is an example of polyfilling every possible import, but in reality, you may only need a subset of these.
For more information see [FormatJS's documentation on polyfilling](https://formatjs.github.io/docs/polyfills).

```tsx title="main.tsx"
// base polyfills:

import '@formatjs/intl-getcanonicallocales/polyfill';
import '@formatjs/intl-locale/polyfill';
import '@formatjs/intl-displaynames/polyfill';
import '@formatjs/intl-listformat/polyfill';
import '@formatjs/intl-pluralrules/polyfill-force'; // https://github.com/formatjs/formatjs/issues/4463
import '@formatjs/intl-numberformat/polyfill';
import '@formatjs/intl-relativetimeformat/polyfill';
import '@formatjs/intl-datetimeformat/polyfill';
import '@formatjs/intl-datetimeformat/add-all-tz';

// locale polyfills:

// en polyfills
import '@formatjs/intl-displaynames/locale-data/en';
import '@formatjs/intl-listformat/locale-data/en';
import '@formatjs/intl-pluralrules/locale-data/en';
import '@formatjs/intl-numberformat/locale-data/en';
import '@formatjs/intl-relativetimeformat/locale-data/en';
import '@formatjs/intl-datetimeformat/locale-data/en';

// zh polyfills
import '@formatjs/intl-displaynames/locale-data/zh';
import '@formatjs/intl-listformat/locale-data/zh';
import '@formatjs/intl-pluralrules/locale-data/zh';
import '@formatjs/intl-numberformat/locale-data/zh';
import '@formatjs/intl-relativetimeformat/locale-data/zh';
import '@formatjs/intl-datetimeformat/locale-data/zh';
```

---

## Usage

Now you can start internationalizing your content. There are two main approaches:

### JSX content with `<T>`

Wrap JSX elements to translate them using the [`<T>`](/docs/react-native/api/components/t) component:

```tsx
import { Text } from 'react-native';
import { T } from 'gt-react-native';

function Welcome() {
  return (
    <T>
      <Text>Welcome to our app!</Text>
    </T>
  );
}
```

For dynamic content, use [variable components](/docs/react-native/guides/variables) like [`<Var>`](/docs/react-native/api/components/var):

```tsx
import { Text } from 'react-native';
import { T, Var } from 'gt-react-native';

function Greeting({ user }) {
  return (
    <T>
      <Text>
        Hello, <Var>{user.name}</Var>!
      </Text>
    </T>
  );
}
```

See the guide on [using the `<T>` component](/docs/react-native/guides/t) for more information.

### Plain strings with `useGT`

For attributes, labels, and plain text using the [`useGT`](/docs/react-native/api/strings/use-gt) hook:

```tsx
import { TextInput } from 'react-native';
import { useGT } from 'gt-react-native';

function ContactForm() {
  const gt = useGT();

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

See the guide on [translating strings](/docs/react-native/guides/strings) for more information.

---

## Testing your app

Test your translations by switching languages:

1. **Add a locale selection dropdown** using [`<LocaleSelector>`](/docs/react-native/api/components/locale-selector):

   ```tsx
   import { LocaleSelector } from 'gt-react-native';

   function App() {
     return <LocaleSelector />;
   }
   ```

2. **Start your app**:

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

3. Visit your development app and change languages via the locale selection dropdown.

In development, translations happen on-demand (you'll see a brief loading time). In production, translations are pre-generated by the CLI.

### Troubleshooting

<Accordions>
  <Accordion title="'GtReactNative' could not be found">
    ```bash
    ERROR  [Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'GtReactNative' could not be found. Verify that a module by this name is registered in the native binary.]
    ```
    This error occurs when the `gt-react-native` module is not found in the native binary.
    This means that you will have to install (`cd ios && pod install`) and rebuild your app.
  </Accordion>
  <Accordion title="You are using invalid locale codes in your configuration.">
    ```text
    @generaltranslation/react-core: Error: You are using invalid locale codes in your configuration.
    You must either specify a list of valid locales or use "customMapping" to specify aliases for the following invalid locales: en, fr, zh. 
    ```
    This error typically occurs when locales are not being properly polyfilled. Make sure that you have either polyfilled the locales manually or are using the babel plugin correctly.

    If you make updates to the babel plugin, you need to clear the cache to make sure the changes are applied.

    ```bash
    npx react-native start --reset-cache
    ```
  </Accordion>
  <Accordion title="Why do languages take a long time to load in dev?">
    **On-Demand Translation**

    You may notice when loading languages in development, translations will take a few seconds to be displayed.
    This happens because your app is being translated in real time.
    We refer to this process as an "on-demand translation".

    This **only happens in dev** so you can easily prototype your app in different languages.
    All translations are preloaded in production, so there will be no delay.
    Follow our guide on [shipping to production](/docs/react-native/tutorials/quickdeploy).

  </Accordion>
  <Accordion title="Why are some translations inaccurate?">
    The most likely cause of an inaccurate translation is ambiguous wording.
    For example, "apple" can be a fruit or a technology company.

    To fix this, you can provide more context to the translation with the `context` prop.
    The [`<T>`](/docs/react-native/api/components/t) component and [`useGT`](/docs/react-native/api/strings/use-gt) hook both support a `context` prop.
    For example:
    ```jsx
    <T context="the technology company">Apple</T>
    ```

  </Accordion>
</Accordions>

---

## Deployment

For production, you need to pre-translate content since runtime translation is disabled.

1. **Get a production API key** from [dash.generaltranslation.com](https://dash.generaltranslation.com).

   Production keys begin with `gtx-api-` (different from dev keys which start with `gtx-dev-`). Learn more about [environment differences](/docs/react-native/concepts/environments).

2. **Add to your CI/CD environment**:

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

3. **Run the translate command** to translate your content:

   ```bash
   npx gtx-cli translate
   ```

   You can configure the behavior of the translate command with the [`gt.config.json`](/docs/cli/reference/config) file.

   See the [CLI Tool](/docs/cli/translate) reference guide for more information.

4. **Update your build script** to translate before building:
   ```json title="package.json"
   {
     "scripts": {
       "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
     }
   }
   ```

<Accordions>
  <Accordion title="What if I'm not using the General Translation platform?">
    If you're not using the General Translation platform, you can still use `gt-react-native` in production.

    However, you'll need to manually translate your content before deploying your application.

    Instead of running `translate`, run the `generate` command to generate JSON files containing all of your translation data (in your source language).

    ```bash
    npx gtx-cli generate
    ```

    Then, you'll need to manually edit / translate these files, and load them into your application with [`loadTranslations`](/docs/react-native/guides/local-tx).

  </Accordion>
</Accordions>

## Next steps

- [`<T>` Component Guide](/docs/react-native/guides/t) - Deep dive into the [`<T>`](/docs/react-native/api/components/t) component and JSX translation
- [String Translation Guide](/docs/react-native/guides/strings) - Using [`useGT`](/docs/react-native/api/strings/use-gt)
- [Variable Components](/docs/react-native/guides/variables) - Handle dynamic content with [`<Var>`](/docs/react-native/api/components/var), [`<Num>`](/docs/react-native/api/components/num), etc.