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

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

## Quick setup

Run `npx gtx-cli init` to use the wizard to set up your project.
Then follow [the instructions for adding the provider](#provider) to your root layout.

## Manual setup

### 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 `GT_API_KEY` to the browser or commit it 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

You can use the `loadTranslations` function to load translations from a custom source.
This is useful when you need to load translations from a different source, such as a custom API.

```tsx title="loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  try {
    const t = await import(`../public/_gt/${locale}.json`);
    return t.default;
  } catch (error) {
    console.warn(`Failed to load translations for locale ${locale}:`, error);
    return {};
  }
}
```

### `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="main.tsx"
import { GTProvider } from 'gt-react-native';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations.ts';

createRoot(document.getElementById('root')!).render(
  <GTProvider
    config={gtConfig}
    loadTranslations={loadTranslations}
    projectId='your-project-id'
    devApiKey='your-dev-api-key'
  >
    <App />
  </GTProvider>
);
```

Create a [`gt.config.json`](/docs/cli/reference/config) file in your project root:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}
```

Customize the locales for your project. See [supported locales](/docs/platform/supported-locales) for options.

### Polyfills

### Babel plugin

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

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"
import gtPlugin from 'gt-react-native/plugin';

export default function (api) {
  return {
    plugins: [
      [
        gtPlugin,
        {
          locales: [gtConfig.defaultLocale, ...gtConfig.locales],
          // for expo - entryPointFilePath: require.resolve('expo-router/entry')
          entryPointFilePath: path.resolve(__dirname, 'index.jsx'),
        },
      ],
    ],
  };
}
```

### 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 { T } from 'gt-react-native';

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

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

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

function Greeting({ user }) {
  return (
    <T>
      <p>
        Hello, <Var>{user.name}</Var>!
      </p>
    </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 { useGT } from 'gt-react-native';

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

  return (
    <input
      placeholder={gt('Enter your email')}
      aria-label={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 dev server**:

   <Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
      <Tab value="npm">
      ```bash
      npm run dev
      ```
      </Tab>
      <Tab value="yarn">
      ```bash
      yarn run dev
      ```
      </Tab>
      <Tab value="bun">
      ```bash
      bun run dev
      ```
      </Tab>
      <Tab value="pnpm">
      ```bash
      pnpm run dev
      ```
      </Tab>
   </Tabs>

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="My app's language is not changing, even though I've changed my browser's language.">
    **Browser Cookies**

    If you are deciding to test different languages by changing your browser's language, this issue may occur.

    Check your browser's cookies for your app.
    General translation uses cookies to store the user's language preference.
    The cookie is called `generaltranslation.locale`, and all you need to do is delete it.
    Then, just double check you are using the desired perferred language and then
    refresh the page.

    How to check cookies:
    * [Chrome](https://support.google.com/chrome/answer/95647)
    * [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored)
    * [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0)
    * [Edge](https://support.microsoft.com/en-us/microsoft-edge/delete-cookies-in-microsoft-edge-63947406-40ac-c3b8-57b9-2a946a29ae09)

  </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 website 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), [`useGT`](/docs/react-native/api/strings/use-gt) functions all 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.