Terminology

Overview

Throughtout these docs, we use a variety of terminology to describe the different concepts used in the General Translation libraries.

This page highlights some of the key terminology we use.

Key Terminology

Locale

A locale is a code used to identify a specific language.

See the locale strings page for a more detailed explanation.

For example, en-US is the locale for English (United States).

Throughout these docs, we often use the term "locale" and "language code" interchangeably.

Language

When we refer to a language in the context of using it with code, we actually mean the locale. (Or the language code)

For example, when we say "provide the language in the call to setLocale", we actually mean "provide the locale in the call to setLocale".

If we say "French is a supported language", we actually mean "fr is a supported locale".

Dictionary

A dictionary is a JSON file that contains a set of (potentially nested) key-value pairs.

The keys are used as references, and the values are strings, either in the original language or in a translated language.

{
  "greeting": "Hello, World!",
  "farewell": "Goodbye, World!",
  "dashboard": {
    "title": "Dashboard",
    "description": "Welcome to the dashboard"
  }
}

The keys are human-readable references which are used to look up the translated content within your app.

These dictionaries are conventional in structure and usage, similar to translation files in other i18n libraries.

A source dictionary can also be a .js or .ts file, meaning it can import from other files. A dictionary containing translated content can only be a .json file.

Source Dictionary

A source dictionary is a dictionary that contains content in the default locale for your app.

Translated Dictionary

A translated dictionary is a dictionary that contains content in a specific locale that is different from the default locale.

The keys are the same as the source dictionary, and the values are the translated strings.

If you have your own translated dictionaries, you can load them using the loadDictionary() function.

In-line content

In-line content is content that is written directly in your app's code, and not stored separately in something like a JSON or dictionary file.

This includes:

<T> components
useGT hooks
getGT function

Source Content

Source content is the content in the default locale for your app. It includes anything written in your app's default language.

Specifically for gt-next, and gt-react, source content includes all of the translatable content for your app, including your app's source dictionary and any in-line content.

Source Template

Source template refers to the specific data format for storing source content.

{
  ["Unique identifier for the source content"]: "...Content..."
}

The unique identifier for the source content is either a hash of the source content, or a user-defined unique identifier.

Depending on the type of the source content, the corresponding value can be a string, array, or an object. (Strings and arrays for dictionaries, and objects for <T> components)

Translations

Throughout these docs, we use the noun "translations" to refer to the translated content obtained from translating source content.

Translations are generated directly from your source template.

The loadTranslations() function allows you to customize the location where these translations are stored. This function expects the JSONs to be of the same format as the source template.

Use the CLI generate command to generate these data files from your source content.

Note:

It's important to note that a translation is different from a translated dictionary. Dictionaries are potentially nested, and contain human-readable references as keys.

Translations, on the other hand, are flat, and likely contain non-human-readable hashes as keys.

Translations are what is stored on the GT CDN.

If we use translations in reference to JSON, MDX, or MD files, we are referring to the direct translations of the original source files.

Terminology

On this page