Overview

The useGT function is a hook for translating strings at build time.

const t = useGT();

<p>{  t('This text will be translated')  }</p>;

Reference

Parameters

None

Returns

A callback function, t, that translates the provided content.

(content: string, options?: InlineTranslationOptions) => string

Behaviour

Production

During the CD process, any content inside a t function will be translated before your application is deployed. This ensures fast load times for all locales, but it can only translate content known at build time.

Once generated, translations are either (1) stored on the CDN or (2) included in your app’s build output, according to your configuration. From there, the translated content is served to your users. If a translation isn’t found, it will fall back to the original content.

Make sure to follow the deployment guide here.

Development

During development, the t function will translate content on demand. This is useful for prototyping what your app will look like in different languages. Remember to add a Dev API key to your environment to enable this behaviour.

You will see a delay during on‑demand translation in development. This will not occur during production builds unless content is explicitly being translated on demand, i.e., using tx or <Tx>.

Example

Basic usage

You can use useGT to translate strings.

import { useGT } from 'gt-next';

export default function TranslateGreeting() {
  const t = useGT();

  return (
    <p>
      {t('Hello, Alice!')}
    </p>
  );
}

Note: "Alice" will be translated into the user's preferred language.

Using variables

You can pass variables to dictionary translations.

import { useGT } from 'gt-next';

export default function TranslateGreeting() {
  const t = useGT();

  return (
    <p>
      {t('Hello, {name}!', { name: 'Alice'  })}
    </p>
  );
}

Note: "Alice" will not be translated into the user's preferred language because it is a variable.

Using ICU message format

gt-next supports the ICU message format, which lets you format your variables as well.

import { useGT } from 'gt-next';

export default function TranslateGreeting() {
  const t = useGT();
  return (
    <p>
      {t('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the basket', { count: 10 })}
    </p>
  );
}

Importing from gt-next/client

If you’re using the "use client" directive, import from gt-next/client rather than gt-next.

"use client";
import { useGT } from 'gt-next/client';

export default function TranslateGreeting() {
  const t = useGT();

  return (
    <p>
      {t('Hello, Alice!')}
    </p>
  );
}

Notes

• The useGT function is a hook that translates strings.
• Translating strings with useGT happens before runtime, during the build process (unless in development).

Next steps

• See getGT for async string translations at build time.
• For runtime translations, see tx and <Tx>.