useGT()

Overview

useGT() is used to access translations from the translation dictionary. It must be used within a component wrapped by a <GTProvider>.

const t = useGT(); // Get the translation function
t('greeting.hello'); // pass the id to get a translation

useGT() supports:

• Translation of string and jsx content.
• Variable insertion and conditional logic within translations.
• Optional id prefixing.

Reference

Parameters

Description

Returns

A translation function t with the following signature:

(key: string) => React.ReactNode

• key: The identifier of the translation to fetch.
• Returns: The translated value as a React.ReactNode.

Examples

Basic Usages

Every entry in your dictionary gets translated. Entries can be either JSX or a string.

const dictionary = {
  greeting1: <>Hello, Alice</>, 
  greeting2: "Hello, Bob", 
};
export default dictionary;

When we want to access these entries, we call useGT(). This returns a function that accepts the key of a translation from the dictionary.

"use client";
import { useGT } from 'gt-react';
 
export default async function translateGreeting() {
  const t = useGT(); 
  return (
    <p>
      {t('greeting1')}
      {t('greeting2')}
    </p>
  );
}

Using variables

You can pass variables to dictionary translations. For jsx content, just use a variable component. For string content, add curley braces {} to the string.

In order to pass values, you must (1) assign an identifier and (2) reference the identifier when calling the t() function. In this example, we use <Var> and {} to pass variables to the translations. In the dictionary, we assign identifiers name="userName" and {userName}.

const dictionary = {
  greeting1: <>Hello, <Var name="userName"/> !</>, 
  greeting2: "Hello, {userName}!", 
};
export default dictionary;

In the component, we pass the values userName: "Alice" and userName: "Bob".

"use client";
import { useGT } from 'gt-react';
 
export default async function translateGreeting() {
  const t = useGT();
  
  // Hello Alice!
  const greetingAlice = t('greeting1', { userName: "Alice" }); 
  // Hello Bob!
  const greetingBob = t('greeting2', { userName: "Bob" }); 
 
  return (
    <p>
      {greetingAlice}
      {greetingBob}
    </p>
  );
}

Using branches

Branching components, such as <Branch> and <Plural>, can be used to handle control logic in a translation.

In order to pass values, you must (1) assign an identifier and (2) reference the identifier when calling the t() function. In this example, we see that hairColor is passed to both <Branch> and <Var> components.

import { Branch, Var } from 'gt-react';
 
const dictionary = {
  hairColor: <>
    <Branch name="hairColor"
      black={<>Their hair is dark.</>}
      brown={<>Their hair is in the middle.</>}
      blonde={<>Their hair is light.</>}
      >
        {/* fallback incase no branch is matched */}
        <p>Unhandled hair color: <Var name="hairColor"/></p>
      </Branch>
  </>,
};

"use client";
import { useGT } from 'gt-react';
 
export default function HairColor() {
  const t = useGT();
  return (
    <div>
      { t('hairColor', { hairColor: 'brown' }) }
    </div>
  );
}

Using prefixes

We can use prefixes to only translate a subset of the dictionary.

const dictionary = {
  prefix1: { 
    prefix2: { 
      greeting1: <>Hello, Alice</>,
      greeting2: "Hello, Bob",
    }
  }
};
export default dictionary;

Because we added the value 'prefix1.prefix2' to the useGT hook, all of the keys are prefixed with prefix1.prefix2:

"use client";
import { useGT } from 'gt-react';
 
export default function UserDetails() {
  const t = useGT('prefix1.prefix2'); 
  return (
    <div>
      <p>{t('greeting1')}</p> {/* greeting1 => prefix1.prefix2.greeting1 */}
      <p>{t('greeting2')}</p> {/* greeting2 => prefix1.prefix2.greeting2 */}
    </div>
  );
}

Notes

• The useGT() function allows you to access dictionary translations.
• The useGT() hook can only be used within a component wrapped by a <GTProvider> component.
• Supports dynamic behavior and variable insertion with Branching and Variable Components respectively.

Next Steps

• Learn more about using dictionaries in the dictionaries reference.
• See useElement() for rendering jsx content.
• Enhance server-side locale routing with i18n Routing and locale management with i18n Configuration.