useDict()

Overview

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

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

useDict() uses a dictionary to store all content for translation. This is different from using the <T> component for translation. If you are interested in only using <T> components for translation, then this document is not relevant.

Reference

Parameters

Prop	Type	Default
`id??`	`string`	`undefined`

Description

Prop	Description
`id`	An optional prefix to prepend to all translation keys. This is useful for working with nested dictionary values.

Returns

A translation function d() that, given an id, will return the translated version of the corresponding entry

(id: string, options?: DictionaryTranslationOptions) => React.ReactNode

Name	Type	Description
`id`	`string`	The id of the entry to be translated
`options?`	`DictionaryTranslationOptions`	Translation options to customize the behavior of `d()`.

Examples

Basic Usages

Every entry in your dictionary gets translated.

dictionary.jsx

const dictionary = {
  greeting: "Hello, Bob", 
};
export default dictionary;

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

You must pass the dictionary to the GTProvider component.

TranslateGreeting.jsx

import { useDict } from 'gt-react';
import dictionary from "./dictionary.json"

export default async function TranslateGreeting() {
  const d = useDict(); 
  return (
    <GTProvider dictionary={dictionary}>
      <p>
        {d('greeting')} // [!code highlight]
      </p>
    </GTProvider>
  );
}

Using variables

In order to pass values, you must (1) assign an identifier and (2) reference the identifier when calling the d() function.

In this example, we use {} to pass variables to the translations. In the dictionary, we assign identifier {userName}.

dictionary.jsx

const dictionary = {
  greeting: "Hello, {userName}!", 
};
export default dictionary;

TranslateGreeting.jsx

import { useDict } from 'gt-react';

export default async function TranslateGreeting() {
  const d = useDict();
  
  // Hello Alice!
  const greetingAlice = d('greeting', { userName: "Alice" }); 

  return (
    <p>
      {greetingAlice} // Hello, Alice // [!code highlight]
    </p>
  );
}

Using prefixes

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

dictionary.jsx

const dictionary = {
  prefix1: { 
    prefix2: { 
      greeting: "Hello, Bob",
    }
  }
};
export default dictionary;

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

UserDetails.jsx

import { useDict } from 'gt-react';

export default function UserDetails() {
  const d = useDict('prefix1.prefix2'); 
  return (
    <div>
      <p>{d('greeting')}</p> // greeting => prefix1.prefix2.greeting // [!code highlight]
    </div>
  );
}

Notes

The useDict() function allows you to access dictionary translations.
The useDict() hook can only be used within a component wrapped by a <GTProvider> component.

Next Steps

Learn more about using dictionaries in the dictionaries reference.

useDict()

On this page