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, 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"]
}

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

Environment Variables

Add 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

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

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

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

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('Enter your email')}
      aria-label={t('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';
   
   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 change 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 <Tx> and tx functions).

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

   Never prefix production keys with your framework's public variable prefix (like 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 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 for string translation
• Variable Components - Handle dynamic content with <Var>, <Num>, etc.