React Quickstart

This guide describes how to add gt-react to a React.js project. It assumes that all components are client-rendered.

Create a secret key for gt-update

Because gt-react is entirely server-rendered, you will be using the CLI tool, gt-update to translate your dictionaries. For this you will need a API Key and a Project ID.

An API key is a 36-character string beginning gtx- which is used to authenticate gt-update with our cloud translation service. Create one on the API Keys page.

Your Project ID is a public identifier for your project. It can also be found on the Dashboard:

Store these variables safely, and make sure not to write your API key anywhere where it could be sent to the client.

Install the library

To install gt-react, navigate to your project's root directory and run:

npm i gt-react

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, plus a dictionary from which to load content. projectID is used to access the General Translation global cache, which serves translations around the world at millisecond speeds.

Other useful <GTProvider> props include locales, which specifies the approved languages for your app, and defaultLocale, which specifies the application's default language.

import dictionary from './dictionary'
import MyApp from './MyApp'
 
export default function App() {
 
    // Initialize i18n with a dictionary
    // The app's default language is US English
    // Approved languages are US English, French, Spanish, and Japanese
 
    return (
        <GTProvider
            projectID='abc-123'
            dictionary={dictionary}
            defaultLocale='en-US'
            locales={['en-US', 'fr', 'es', 'ja']}
        >
            <MyApp />
        </GTProvider>
    )
}

See a full list of <GTProvider> props here.

Inline translation

To mark JSX for translation, pass it as the children of your <T> component. Every <T> component you need translated should have a unique id prop:

import { T } from 'gt-react'
 
export default function Page() {
    return (
        <T id='my_id'>
            Hello, world
        </T>
    )
}

The text and structure of the tags inside your <T> component should be static. Attributes like className can be dynamic. To include dynamic variables inside your <T> component, use the <Var> component:

import { T, Var } from 'gt-react'
 
export default function Page() {
 
    const name = "Alice"; // or "Bob", "Charlie", etc.
 
    return (
        <T id='my_other_id'>
            Hello, <Var value={name}/>
        </T>
    )
}

The children (and the fallback value prop) of a <Var> component will never be translated and will remain private.

Learn how to include:

• Plural forms with the <Plural> component
• Formatted variables like numbers, currencies, and dates
• Context for the AI model to use while translating

gt-update

Now that content is loading in your defaultLocale (usually English), you can use the CLI tool to create translations.

Install gt-update globally or as a developer dependency, so it doesn't increase your app's production bundle size.

npm i -g gt-update

To run a script that will scan through your project and send each item for translation, run npx i18n. This script requires your API key and projectID, but gt-update automatically reads your environment variables for GT_API_KEY and GT_PROJECT_ID, so you usually don't have to include them:

npx i18n --languages fr es ja

Or, with projectID and apiKey:

npx i18n --apiKey YOUR_API_KEY --projectID YOUR_PROJECT_ID --languages fr es ja

If the script is successful, you should see the following message in the console:

Remote dictionary "default" updated: true. Languages: ["French", "Japanese", "Spanish"]. Translations are usually live within a minute. Check status: www.generaltranslation.com/dashboard.

Translations are usually ready within a minute, but could take up to five minutes in periods of high demand. When translations are ready should be able to access them via the cache in both your local and production projects.

Learn more about gt-update here.

Congratulations! Your app is now multilingual! 🥳

Next steps

• Learn more about the <T> component, or dictionaries with useGT()
• Set up your app so that the UI is mirrored for languages like Arabic and Hebrew, which are written right-to-left.