Installation

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

npm i gt-react-native
npm i -D gtx-cli
cd ios && pod install

yarn add gt-react-native
yarn add --dev gtx-cli
cd ios && pod install

bun add gt-react-native
bun add --dev gtx-cli
cd ios && pod install

pnpm add gt-react-native
pnpm add --save-dev gtx-cli
cd ios && pod install

Quick setup

Run npx gtx-cli init to use the wizard to set up your project. Then follow the instructions for adding the provider to your root layout.

Manual setup

Environment variables

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

GT_API_KEY="your-dev-api-key"
GT_PROJECT_ID="your-project-id"

Get your free API keys at dash.generaltranslation.com or run:

npx gtx-cli auth

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.

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

The GTProvider component provides translation context to client-side components. It manages locale state, translations, and enables the useGT and useTranslations hooks.

Add the GTProvider to your root component:

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 file in your project root:

{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}

Customize the locales for your project. See 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).

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.

// 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> component:

import { T } from 'gt-react-native';

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

For dynamic content, use variable components like <Var>:

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 for more information.

Plain strings with useGT

For attributes, labels, and plain text using the useGT hook:

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 for more information.

Testing your app

Test your translations by switching languages:

1. Add a locale selection dropdown using <LocaleSelector>:

   import { LocaleSelector } from 'gt-react-native';
   
   function App() {
     return <LocaleSelector />;
   }

2. Start your dev server:

   npmyarnbunpnpm

   npm run dev

   yarn run dev

   bun run dev

   pnpm run dev

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

Deployment

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

1. Get a production API key from dash.generaltranslation.com.

   Production keys begin with gtx-api- (different from dev keys which start with gtx-dev-). Learn more about environment differences.

2. Add to your CI/CD environment:

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

3. Run the translate command to translate your content:

   npx gtx-cli translate

   You can configure the behavior of the translate command with the gt.config.json file.

   See the CLI Tool reference guide for more information.

4. Update your build script to translate before building:

   {
     "scripts": {
       "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
     }
   }

Next steps

• <T> Component Guide - Deep dive into the <T> component and JSX translation
• String Translation Guide - Using useGT
• Variable Components - Handle dynamic content with <Var>, <Num>, etc.