Introduction

The General Translation React SDK is an open-source internationalisation (i18n) library for React applications.

It provides a comprehensive set of tools to internationalise your React application in an easy, maintainable way, with feature parity to other popular i18n libraries.

The SDK can be used standalone, without the General Translation platform, and behaves similarly to other i18n libraries.

However, it also integrates with our platform for enhanced features:

• Translation hot reloading in development
• Automatic AI translations
• Syncing translations with the General Translation platform
• Native integration with our translation CDN

Concepts

There are five main concepts to understand about the SDK.

The <GTProvider> component

The <GTProvider> component provides translation context to your application, including the current language and corresponding translations.

import { GTProvider } from 'gt-react';

function App() {
  return (
    <GTProvider>
      <div>
        {/* Your application content */}
      </div>
    </GTProvider>
  );
}

Important: The provider should wrap your entire application and be placed as high in the component tree as possible, such as in your root App component.

See the GTProvider API reference for more information.

The <T> component

The <T> component is the recommended way to translate content in your application.

It’s a React component that can wrap any JSX element and will automatically render that element’s content in a supported language.

Examples

<T>
  <div>Hello, world!</div>
</T>

<T>
  <div>
    <h1> Here is an image </h1>
    <img src="https://example.com/image.png" alt="Example" />
  </div>
</T>

<T>
  Formatting can be done easily with the `<T>` component.
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency currency="USD">{1000}</Currency>
</T>

The <T> component works with variable components such as <Num>, <DateTime> and <Currency> for dynamic content formatting.

See the <T> component guide to learn about the different ways to use the <T> component.

The useGT hook

The useGT hook is a React hook that can be used similarly to the <T> component, with some trade-offs.

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

const t = useGT();

t('Hello, world!');

Compared with the <T> component, the useGT hook provides greater flexibility in your codebase.

For example, if you have a complex data structure with nested strings, a <T> component would be harder to use.

const t = useGT();
const data = {
  title: t('Hello, world!'),
  description: t('This is a description'),
};

See the strings guide to learn more about the useGT hook.

The msg function

The msg function is used to mark strings for translation that are used across multiple components or stored in configuration objects.

This is particularly useful for shared content such as navigation labels, form messages, or any text that appears in multiple places throughout your application.

// Mark strings for translation
import { msg } from 'gt-react';

const navItems = [
  { label: msg('Home'), href: '/' },
  { label: msg('About'), href: '/about' },
  { label: msg('Contact'), href: '/contact' }
];

// Decode and use the marked strings
import { useMessages } from 'gt-react';

function Navigation() {
  const m = useMessages();
  
  return (
    <nav>
      {navItems.map(item => (
        <a key={item.href} href={item.href}>
          {m(item.label)}
        </a>
      ))}
    </nav>
  );
}

The msg function encodes strings with translation metadata, and useMessages decodes them.

See the shared strings guide to learn more about the msg function.

The useTranslations hook

The useTranslations hook is a React hook that returns a function you can use to retrieve translations for a given key.

const dictionary = {
  hello: {
    world: 'Hello, world!',
  },
};

const translate = useTranslations();
translate('hello.world');

This behaviour is similar to other translation libraries, such as react-i18next and next-intl.

See the dictionaries guide to learn more about the useTranslations hook.

See the useTranslations API Reference for more information.

Next steps

• Learn how to set up your React project with the SDK: Quickstart
• Learn how to translate JSX content with the <T> component: JSX translation guide
• Learn how to translate strings with the useGT hook: String translation guide
• Learn about shared strings with the msg function: Shared strings guide