Get your React app translating content in minutes.

Prerequisites: React, basic JavaScript knowledge

Installation

Install the gt-react and gtx-cli packages:

npm i gt-react
npm i gtx-cli

yarn add gt-react
yarn add --dev gtx-cli

bun add gt-react
bun add --dev gtx-cli

pnpm add gt-react
pnpm add --save-dev gtx-cli

Configuration

GTProvider

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

Add the GTProvider to your root app component:

import { GTProvider } from 'gt-react';

export default function App() {
  return (
    <GTProvider>
      <YourAppContent />
    </GTProvider>
  );
}

Create a gt.config.json file in your project root:

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

Customise the locales for your project. See supported locales for options.

Environment variables

Add the following to your environment file for development hot reloading:

VITE_GT_API_KEY="your-dev-api-key"
VITE_GT_PROJECT_ID="your-project-id"

REACT_APP_GT_API_KEY="your-dev-api-key"
REACT_APP_GT_PROJECT_ID="your-project-id"

GATSBY_GT_API_KEY="your-dev-api-key"
GATSBY_GT_PROJECT_ID="your-project-id"

REDWOOD_ENV_GT_API_KEY="your-dev-api-key"
REDWOOD_ENV_GT_PROJECT_ID="your-project-id"

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

npx gtx-cli auth

Usage

You can now start internationalising 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';

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

For dynamic content, use variable components such as <Var>:

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

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

See the guide on using the <T> component for further information.

Plain strings with useGT

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

import { useGT } from 'gt-react';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('Enter your email address')}
      aria-label={t('Email address input field')}
    />
  );
}

See the guide to 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';
   
   function App() {
     return <LocaleSelector />;
   }

2. Start your dev server:

   npmyarnbunpnpm

   npm run dev 

   yarn run dev 

   bun run dev 

   pnpm run dev 

3. Visit localhost:3000 and switch languages via the locale selection dropdown.

In development, translations happen on demand (you’ll see a brief loading time). In production, everything is pre-translated.

Troubleshooting

Deployment

For production, you need to pre-translate content since runtime translation is disabled (except for the <Tx> and tx functions).

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

   Production keys begin with gtx-api- (unlike 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

   Never prefix production keys with your framework’s public variable prefix (such as VITE_, REACT_APP_, etc.) — they should remain server-side only.

3. Run the translate command to translate your content:

   npx gtx-cli translate

   You can configure the behaviour 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 - A deep dive into the <T> component and JSX translation
• String translation guide - Using useGT for string translation
• Variable components - Handle dynamic content with <Var>, <Num>, etc.