General Translation  

React Quickstart

Internationalize your React App in 5 minutes with General Translation

Overview

This guide describes how to internationalize an existing React project.

We will cover 4 simple steps:

Installing the required libraries

Run the CLI tool to setup your codebase

Set up your local environment

Add <GTProvider> to your app

This entire process should take under 5 minutes.

Setup

1. Install libraries

Install the gt-react and gt-react-cli libraries.

npm i gt-react gt-react-cli

2. Run our CLI tool

Run the gt-react-cli tool to setup your project for translation.

This will scan your codebase for translatable content and automatically wrap it in <T> components.

shell
npx gt-cli setup

See the CLI tool documentation for more information.

Experimental

This feature is currently experimental and may not work perfectly. If you run into any issues, please let us know by creating an issue on our GitHub repository. In particular, note that some manual edits may be required.

Example

The CLI tool will wrap any JSX elements containing translatable content in <T> components. Each component will be given a unique id prop.

See the <T> component documentation for more information.

app/page.js
import { T } from "gt-react"; 
import { Card, CardHeader, CardContent } from "@components/ui/Card";
 
export default function Page() {
  return (
    <T id="app.page.0">
      {/* This text will be translated */}
      <b>Shakespeare&apos;s</b> quotes
      {/* Any arbitrary components and their children will also be translated */}
      <Card>
        <CardHeader>Hamlet</CardHeader>
        <CardContent>
          <p>&quot;To be, or not to be: that is the question...&quot;</p>
        </CardContent>
      </Card>
    </T> 
  );
}

3. Set up your local environment

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

Navigate to your GT Dashboard.

  • Navigate to the Developer Keys page in the sidebar.

Click Create Dev API Key then copy the API key and Project ID to your clipboard.

Add the Project ID and API Key to your environment variables.

GT_API_KEY="YOUR_GT_API_KEY"
GT_PROJECT_ID="YOUR_GT_PROJECT_ID"

Protect Your API Keys!

All React environment variables are bundled into your application at build time and are publicly visible in the client-side code. For security reasons, you should:

  • Only use development API keys during local development
  • Never include production API keys in your environment variables
  • Use production API keys only with the CLI tool for deployment

4. Add <GTProvider>

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

To work out of the box, <GTProvider> needs the projectID you created earlier.

import MyApp from "./MyApp";
 
export default function App() {
  return (
    <GTProvider
      projectID="abc-123"
    >
      <MyApp />
    </GTProvider>
  );
}

In development, you should also pass your Development API key to the devApiKey prop.

<GTProvider
  projectID="abc-123"
  devApiKey={process.env.VITE_GT_DEV_API_KEY}
>

Make sure to remove this environment variable when shipping to production!

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

Let's Try It Out!

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

See Your App in a Different Language

Start by changing your preferred browser's language settings. This will change which language is displayed.

  • Change your language in Chrome
  • Change your language in Firefox
  • Change your language in Edge

Start your React app in development mode.

npm run dev

Open up your app in your preferred browser (usually at http://localhost:3000). If you want to switch languages, just select a different language in your browser settings and refresh the page.

Troubleshooting

Shipping to Production

CLI Tool

In order to ship your app to production, you will need to run our CLI tool to parse your codebase and validate your content.

Security

Due to the nature of client-sided rendering in React, you must pre-authorize your content with the CLI tool before it can be translated. This means that you must run the CLI tool before deploying to your production environment.

Run the following command in your deployment process:

npx gt-cli translate

The CLI tool expects a production API key and project ID. There are a few ways to set these:

  • Set the GT_API_KEY and GT_PROJECT_ID environment variables in your deployment environment.
  • Pass the --api-key and --project-id flags to the CLI tool.

For more information, see the CLI tool documentation.

For Production Only!

This CLI tool is meant to only be used for production deployments. Make sure you have the correct API key and project ID in your environment variables, and make sure that you are translating the same content that is being used for production (i.e., the branch you are on when you run this command is the branch used for production).

Next steps

Previous

Next.js Quickstart

Next

<T>

On this page

Overview
Setup
1. Install libraries
2. Run our CLI tool
3. Set up your local environment
4. Add <GTProvider>
Let's Try It Out!
See Your App in a Different Language
Troubleshooting
Shipping to Production
CLI Tool
Next steps