useElement()

Overview

The useElement() method allows you to access jsx content from your translation dictionary.

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

useElement() supports:

• Jsx translation only (no string support, use getGT(), useGT(), or tx() for string translations).
• Variable insertion and conditional logic within translations.
• Optional id prefixing.
• Identical syntactic implementation on both client and server side.

Despite its name, useElement() is not always a hook. When used on the client side, it is implemented as a hook. When used on the server side, it synchonously resolves the translations and streams the result.

useElement() excludes strings as this allows for identical syntax in both client and server side components. For accessing both strings and jsx content, use getGT() or useGT().

Reference

Props

Description

Returns

A translation function t with the following signature:

(key: string) => React.ReactElement

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

Examples

Basic Usages

Every entry in your dictionary gets translated. useElement() can only resolve jsx entries. Strings are forbidden.

const dictionary = {
  greeting: <>Hello, Alice</>, 
};
export default dictionary;

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

import { useElement } from 'gt-next';
 
export default async function translateGreeting() {
  const t = useElement(); 
  return (
    <p>
      {t('greeting')}
    </p>
  );
}

Using variables

You can pass variables to dictionary translations. Just use a variable component.

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> to pass a variable to the translation.

In the dictionary, we assign <Var> the identifier name="userName".

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

In the component, we pass the value by invoking the identifier userName: "Alice".

import { useElement } from 'gt-next';
 
export default async function translateGreeting() {
  const t = useElement();
 
  return (<p> {t('greeting', { userName: "Alice" })} </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-next';
 
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>
  </>,
};

import { useElement } from 'gt-next';
 
export default function HairColor() {
  const t = useElement();
  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: { 
      greeting: <>Hello, Alice</>,
    }
  }
};
export default dictionary;

Because we added the value 'prefix1.prefix2' to the useElement() method, all of the keys are prefixed with prefix1.prefix2:

import { useElement } from 'gt-next';
 
export default function UserDetails() {
  const t = useElement('prefix1.prefix2'); 
  return (
    <div>
      <p>{t('greeting')}</p> {/* greeting1 => prefix1.prefix2.greeting1 */}
    </div>
  );
}

Notes

• useElement() only translates JSX content from the dictionary. No strings.
• useElement() is "platform agnostic", meaning it can be used in both client-side and server-side components.
• For string-based translations, consider using useGT(), getGT(), or tx().

Next Steps

• Read more about the dictionary design pattern.
• Combine useElement() with Variable Components and Branching Components for advanced translation scenarios.