Dictionaries Reference

Overview

In this reference guide, we will introduce you to the dictionary pattern. Please feel free to skip around this page as needed. We will cover the following:

• What is a dictionary?
• How to use dictionaries
• Using dictionaries
• Production considerations

What is a dictionary?

General Translation allows translatable content to be stored in a dictionary file. A dictionary is a nested object with string values that can be used to store translatable content. This dictionary file (.ts, .js, or .json) is then used to generate a translation.

Dictionaries can be used standalone, or in conjunction with <T> components.

Dictionary vs <T> Components

The dictionary pattern has a few advantages over the <T> component:

1. Centralized Storage: Dictionaries store all translatable content in a single file, making it easier to manage and update.
2. Historical Precedent: The dictionary pattern is a common design pattern in the industry and is used by many other libraries.

At the same time, it has some disadvantages as well:

1. Complexity: Dictionaries are more complex to set up and use than the <T> component.
2. Readability: Dictionaries are less readable than the <T> component because the content is not inline.

Both design patterns are supported by our library and are not mutually exclusive. You can use a dictionary along side <T> components.

Our advice

We recommend using the <T> component because of its simplicity especially if you are new to internationalization (i18n). We offer dictionary support for those who prefer this design pattern from past experiences or for ease of integration with existing code bases.

How to use dictionaries

In this section, we will show you how to set up a bare-bones dictionary implementation in your React application. We will walk through the following steps:

Step 1: Create a dictionary

The first step is to create a dictionary. This is a dictionary.js (.json) file that contains all the content you want to translate.

Add the following content to your dictionary.js file:

const dictionary = {
  greetings: {
    hello: 'Hello, World!'
  },
}
 
export default dictionary;

Then you pass it to your <GTProvider> component:

import dictionary from "./dictionary.js";
 
createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider locales={['es', 'fr']} dictionary={dictionary}>
      <App />
    </GTProvider>
  </StrictMode>
);

Step 2: Reference the dictionary

You can access dictionary entries with the useDict() hook. Just use the d() function to access the dictionary entries by identifier.

import { useDict } from 'gt-react';
 
export default function MyComponent() {
 
  const d = useDict(); 
 
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

Using dictionaries

Variables

You can add variables to your dictionary by using the {variable} syntax:

const dictionary = {
  greetings: {
    hello: 'Hello, {name}!',    // -> Hello, Alice!
    goodbye: 'Goodbye, {name}!' // -> Goodbye, Bob!
  },
}
export default dictionary;

import { useDict } from 'gt-react';
 
export default async function MyComponent() {
  const d = useDict();
 
  return (
    <div>
      {d('greetings.hello', { variables: { name: 'Alice' }})}
      {d('greetings.goodbye', { variables: { name: 'Bob' }})}
    </div>
  );
}

Read more about adding variables to your dictionary in the DictionaryTranslationOptions type.

Prefixes

Additionally, with useDict(), you can pass in a prefix to the function to specify a shared path in the dictionary. This is useful if you have a shared path in your dictionary that you want to use in multiple components.

const dictionary = {
  greetings: {
    common: {
      hello: 'Hello, World!',
      goodbye: 'Goodbye, World!'
    },
  },
}
export default dictionary;

import { useDict } from 'gt-react';
 
export default async function MyComponent() {
  // All translation paths such as 'hello' will be prefixed with 'greetings'
  const d = useDict('greetings.common'); 
 
  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </div>
  );
}

Production considerations

Deploying to production

Make sure to run the translate command before deploying to production, so that all translations are available at runtime. We recommend adding it to your in your CD pipeline or as a part of your build script.

{
  "scripts": {
    "build": "npx gt-react-cli translate --languages fr es ja && <YOUR_BUILD_COMMAND>",
  }
}

That's it! You have successfully translated your application into French, Spanish, and Japanese.

For a more detailed guide on deploying your application, please refer to the Deployment guide. For more information on the command, please refer to the CLI Tool reference guide.

Behavior: Development vs Production

In development, the d() function will translate dictionary entries on-demand. This means that when the component is rendered, it will perform a translation immediately. We do this for convenience to make development with other languages easier.

To enable this behavior, just add a Dev API key to your environment.

In production, the d() function will translate content at build time. This means that you have to run the translation command before deploying your application.

Notes

• Dictionaries are an alternative to the <T> component. They can be used in conjunction with <T> components or standalone.
• Dictionary translations occur at build time, so you have to add the translate command to your build process.
• Dictionaries can be used with prefixes to specify a subset of the dictionary.

Next steps

• Learn about the <T> component and how to use it in your React application.
• Learn how to ship to production with our deployment guide.