By the end of this guide, your React app will display content in multiple languages, with a language switcher your users can interact with.

Prerequisites:

• A React app (Vite, Create React App, or similar)
• Node.js 18+

Step 1: Install the packages

gt-react is the library that powers translations in your app. gt is the CLI tool that prepares translations for production.

npm i gt-react
npm i -D gt

yarn add gt-react
yarn add --dev gt

bun add gt-react
bun add --dev gt

pnpm add gt-react
pnpm add --save-dev gt

Step 2: Create a translation config file

Create a gt.config.json file in your project root. This tells the library which languages you support:

{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": {
    "gt": {
      "output": "public/_gt/[locale].json"
    }
  }
}

• defaultLocale — the language your app is written in (your source language).
• locales — the languages you want to translate into. Pick any from the supported locales list.
• files — tells the CLI where to save translation files. The output path should match the import path in your loadTranslations function (Step 3).

Step 3: Create a translation loader

gt-react runs entirely on the client, so it needs a function to load translation files at runtime. Create a loadTranslations file:

export default async function loadTranslations(locale: string) {
  try {
    const translations = await import(`../public/_gt/${locale}.json`);
    return translations.default;
  } catch (error) {
    console.warn(`No translations found for ${locale}`);
    return {};
  }
}

This function loads JSON translation files from your public/_gt/ directory. The CLI generates these files when you run npx gt translate.

Step 4: Add the GTProvider to your app

The GTProvider component gives your entire app access to translations. Wrap your app at the root level:

import { GTProvider } from 'gt-react';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

export default function App() {
  return (
    <GTProvider config={gtConfig} loadTranslations={loadTranslations}>
      {/* Your app content */}
    </GTProvider>
  );
}

GTProvider takes your config and translation loader as props. It manages locale state and makes translations available to all child components.

Step 5: Mark content for translation

Now, wrap any text you want translated with the <T> component. <T> stands for "translate":

import { T } from 'gt-react';

export default function Welcome() {
  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}

You can wrap as much or as little JSX as you want inside <T>. Everything inside it — text, nested elements, even formatting — gets translated as a unit.

Step 6: Add a language switcher

Drop in a <LocaleSelector> so users can change languages:

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

export default function Welcome() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}

LocaleSelector renders a dropdown populated with the languages from your gt.config.json.

Step 7: Set up environment variables (optional)

To see translations in development, you need API keys from General Translation. These enable on-demand translation — your app translates content in real time as you develop.

Create a .env.local file with the correct prefix for your bundler:

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"

Get your free keys at dash.generaltranslation.com or by running:

npx gt auth

Step 8: See it working

Start your dev server:

npm run dev

yarn dev

bun dev

pnpm dev

Open your app and use the language dropdown to switch languages. You should see your content translated.

Step 9: Translate strings (not just JSX)

For plain strings — like placeholder attributes, aria-label values, or alt text — use the useGT hook:

import { useGT } from 'gt-react';

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

  return (
    <form>
      <input
        placeholder={gt('Enter your email')}
        aria-label={gt('Email input field')}
      />
      <button type="submit">{gt('Send')}</button>
    </form>
  );
}

Step 10: Deploy to production

In production, translations are pre-generated at build time (no real-time API calls). Add the translate command to your build script:

{
  "scripts": {
    "build": "npx gt translate && <YOUR_BUILD_COMMAND>"
  }
}

Set your production environment variables in your hosting provider (Vercel, Netlify, etc.):

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

That's it — your app is now multilingual. 🎉

Troubleshooting

Next steps

• <T> Component Guide — Learn about variables, plurals, and advanced translation patterns
• String Translation Guide — Deep dive into useGT
• Variable Components — Handle dynamic content with <Var>, <Num>, <Currency>, and <DateTime>
• Pluralization — Handle plural forms with the <Plural> component
• Deploying to Production — CI/CD setup, caching, and performance optimization
• Shared Strings — Translate text in arrays, config objects, and shared data with msg()