Quickstart

Overview

This quickstart guide will walk you through internationalizing your React app with gt-react.

By the end of this guide, you will have a fully internationalized React app.

In this guide, we will cover the following:

Installation

Configuration

Usage

Testing Your App

Deployment

Prerequisites

A React project using a supported framework (Next.js, Vite, etc.)
Basic knowledge of React and JavaScript

Installation

Install the gt-react and gtx-cli packages:

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

Automatic Setup: We have an experimental Setup Wizard that can help you setup your project with gt-react.

Try it out by running npx gtx-cli@latest. You'll still need to manually internationalize strings, but it will help you get started.

See the Setup Wizard reference guide for more information.

Alternatively, if you would like your AI tool like Claude Code, Cursor, or Windsurf to automatically setup your project, you can use our mcp server.

Configuration

`GTProvider`

The core of gt-react is the GTProvider component.

It is responsible for:

Managing the user's current locale
Providing relevant translations to your application
Providing context to hooks for accessing translations
Providing context to hooks for changing the user's locale

First, add the GTProvider component to your application. It should be placed as high up in your component tree as possible.

src/App.tsx

import { GTProvider } from 'gt-react';

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

Next, create a gt.config.json file in the root of your project. This file is used to configure both the gtx-cli tool and the gt-react library.

gt.config.json

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

You should customize the defaultLocale and locales to match your project. See the list of supported locales for more information.

Lastly, spread the gt.config.json file into the provider's props.

import gtConfig from './gt.config.json';

<GTProvider {...gtConfig}>
  <App />
</GTProvider>

Spreading the gt.config.json file makes the config consistent across your application and CLI tool.

Alternatively, you can individually specify each prop in the GTProvider component.

<GTProvider
  defaultLocale="en"
  locales={["fr", "es"]}
>

Environment Variables

Set the following environment variables:

VITE_GT_API_KEY="" # Your General Translation Developer API key
VITE_GT_PROJECT_ID="" # Your General Translation project ID

GATSBY_GT_API_KEY="" # Your General Translation Developer API key
GATSBY_GT_PROJECT_ID="" # Your General Translation project ID

REDWOOD_ENV_GT_API_KEY="" # Your General Translation Developer API key
REDWOOD_ENV_PROJECT_ID="" # Your General Translation project ID

NEXT_PUBLIC_GT_API_KEY="" # Your General Translation Developer API key
NEXT_PUBLIC_GT_PROJECT_ID="" # Your General Translation project ID

REACT_APP_GT_API_KEY="" # Your General Translation Developer API key
REACT_APP_GT_PROJECT_ID="" # Your General Translation project ID

Many react frameworks each have a unique way of exporting environment variables to the client. In development environments, both GT_API_KEY and GT_PROJECT_ID need to be exported to the client.

We have added support for a few libraries so far, but please let us know if your framework is not listed by creating an issue on our GitHub repository.

Make sure your API key variable is only set in your development environment! It should not be set in production.

You can get a free API key and project ID by creating a General Translation account.

After creating an account, navigate to the Development API Keys page to get your Dev API key and project ID.

Alternatively, you can also use the CLI tool command npx gtx-cli auth to generate an API key and project ID for your project, saved to your .env.local file.

Usage

Great! If you've followed the steps above, your React project is now setup to use gt-react.

The next step is to internationalize your content. Here, we'll give a brief overview of the different ways to translate content in your application.

`<T>` Component

The <T> component is the main component for translating JSX content in your application.

To use it, simply wrap the JSX you want to translate in the <T> component.

import { T } from 'gt-react';
<T>
  <div>Your content</div>
</T>

If you have dynamic content, you'll need to use variable components to pass in the dynamic values.

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

<T>
  <div>Hello, <Var>{name}</Var>!</div>
</T>

See the Translating JSX guide for more information.

`useGT` Hook

The useGT hook is a React hook that returns a function that can be used to translate strings.

import { useGT } from 'gt-react';

const translate = useGT();
translate('Hello, world!');

See the Translating Strings guide for more information.

Utilizing the hot-reload translation functionality will be helpful for internationalizing your application.

To enable this, make sure you have the GT_API_KEY and GT_PROJECT_ID environment variables set in your development environment.

Testing Your App

Congratulations! 🥳 If you've followed the steps above, your app is now multilingual! Let's see it in action.

See Your App in a Different Language

Add the <LocaleSelector> component to your app. This will allow you to select a different language for your app.

Tip: You can also skip this step and just change your language in your browser settings.

Start your React app in development mode.

npm run dev

yarn run dev

bun run dev

pnpm run dev

Open up your app in your preferred browser (usually at http://localhost:3000).

Troubleshooting

Deployment

Great! If you're satisfied with your translations and the functionality of your app, you can now deploy your application.

The behavior of gt-react in production is slightly different from development. Specifically, no translations will be performed at runtime.

This means that you'll need to translate your content before deploying your application, in the build process.

Luckily, the gtx-cli tool has a translate command that can be used to automatically translate your content.

First, you'll need to get a Production API key from the General Translation platform.

Please note that this key is different from your Development API key, and begins with gtx-api-, instead of gtx-dev-.

Read about the difference between Development and Production keys here.

Add this environment variable to your CI/CD pipeline.

GT_PROJECT_ID=<your-project-id>
GT_API_KEY=<your-production-api-key>

Make sure that GT_API_KEY is NOT prefixed with NEXT_PUBLIC_ or VITE_, depending on your framework!

If it is, you'll risk exposing your API key to the public.

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.

Add the translate command to your build process.

package.json

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

Summary

In this guide, we covered how to setup your React project with gt-react
We briefly covered the different ways to translate content in your application.
We also covered how to deploy your application after you've internationalized your content.

Next Steps

Learn about how to translate JSX content with the <T> component: Translating JSX
Learn about how to translate strings with the useGT hook: Translating Strings
Learn how to use local translations: Local Translations

Quickstart

What if I don't want to use the General Translation platform?

My app's language is not changing, even though I've changed my browser's language.

Why do new languages take a long time to load?

Why are some things translating and others not?

Why are some translations inaccurate?

What if I'm not using the General Translation platform?

On this page