React Quickstart

Overview

This guide describes how to internationalize an existing React project.

We will cover 4 simple steps:

1. Running the setup wizard

The setup wizard will walk you through the process of internationalizing your project.

npx gtx-cli@latest init

To manually setup your project, follow the manual setup guide.

The setup wizard will:

1. Install the required libraries.
2. Configure your project's supported locales.
3. Wrap your project's JSX components with the <T> component.
4. Generate a production API key and project ID for your project.

See the setup wizard docs for more information.

2. Adding the GTProvider

Add the <GTProvider> component to your app. Spread the config JSON object into the config prop.

import { GTProvider } from "gt-react";
import MyApp from "./MyApp";
import config from "./gt.config.json";
 
export default function App() {
  return (
    <GTProvider {...config}> 
      <MyApp />
    </GTProvider> 
  );
}

3. Adding environment variables

The setup wizard will create a .env.local file for you in the root of your project containing your production API key and project ID.

However, in order to use gt-react in development mode, you will need to add a development API key instead of a production one.

VITE_GT_API_KEY="YOUR_GT_DEV_API_KEY"
VITE_GT_PROJECT_ID="YOUR_GT_PROJECT_ID"

4. Cleaning up strings

The setup wizard will wrap all of your project's JSX components with the <T> component. However, you may notice that strings are unaffected.

For example, if you have a string constant like this:

export default function Example() {
  const greeting = "Hello, world!";
  return <p>{greeting}</p>;
}

The setup wizard will not touch this string.

To fix this, you can use the useGT() hook to translate the string.

import { useGT } from "gt-react";
export default function Example() {
  const t = useGT();
  return <p>{t("Hello, world!")}</p>;
}

Let's try it out!

Congratulations! 🥳 Your app is now multilingual! Let's see it in action.

See Your App in a Different Language

npm run dev 

Troubleshooting

Shipping to Production

Follow our guide on shipping to production.

Next steps

• See our React API reference for detailed information about the <T> component and other available components.

Manual Setup

If you prefer to do the setup manually, follow the steps below.

1. Install libraries

Install the gt-react and gtx-cli libraries.

npm i gt-react
npm i gtx-cli --save-dev

2. Select languages

<GTProvider> is used to configure the behavior of gt-react. It should be placed as high up in your app as possible, ideally at the root.

Just pass a list of locale codes to add them to your app.

import { GTProvider } from "gt-react";
import MyApp from "./MyApp";
 
export default function App() {
  return (
    // French and Chinese support 
    <GTProvider locales={['fr', 'zh']}> 
      <MyApp />
    </GTProvider> 
  );
}

For a full list of <GTProvider> props and extended documentation, see the API reference.

3. Add the <T> component

Wrap any nested JSX content in the <T> component to make it translatable. For more information, check out the guide on using <T> components.

import { T } from "gt-react";
 
export default function Example() {
  return (
    <T>
      <p>
        This gets translated.
      </p>
    </T>  
  );
}

Use the <Var> component to designate JSX content that should not be translated.

import { T, Var } from "gt-react";
 
export default function Example() {
  return (
    <T>
      <p>
        This gets translated. <Var>This does not.</Var>
      </p>
    </T>  
  );
}

For strings, you can use useGT() for translation.

import { useGT } from "gt-react";
 
export default function Example() {
  const t = useGT(); 
  return (
    <p>
      {t("This gets translated.")}
    </p>
  );
}

4. Add your environment variables

Add your API key and Project ID to your environment variables.

VITE_GT_API_KEY="YOUR_GT_DEV_API_KEY"
VITE_GT_PROJECT_ID="YOUR_GT_PROJECT_ID"