Installation

Install the gt-react and gtx-cli packages:

npm i gt-react
npm i -D 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

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';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations'; // local translations

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

And create a loadTranslations function to load translations from your public directory:

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 {};
  }
}

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 .env.local 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

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

   Never publicly expose your GT_API_KEY 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.