Overview

gt-i18n now supports dictionary-backed translations via getTranslations(). This brings gt-i18n in line with gt-next, gt-react, and other i18n libraries that use dictionaries as their primary translation pattern.

Setup

Create a dictionary.json file in the root of your project with your source (English) strings:

{
  "greeting": {
    "hello": "Hello!"
  },
  "user": {
    "welcome": "Welcome, {name}!"
  },
  "errors": {
    "notFound": "Page not found",
    "unauthorized": "Access denied"
  }
}

When you run the GT CLI (npx gtx translate), it will automatically detect dictionary.json in the project root and translate it for your configured locales.

Usage

Given the source dictionary above, call getTranslations() to get a t function that resolves entries from your dictionary:

import { getTranslations } from 'gt-i18n';

const t = await getTranslations();

t('greeting.hello'); // "Hello!"
t('user.welcome', { name: 'Alice' }); // "Welcome, Alice!"

Sub-dictionaries with t.obj()

t() returns a single string. t.obj() returns an entire subtree of the dictionary as an object:

const t = await getTranslations();

t('errors.notFound'); // "Page not found"

const errors = t.obj('errors');
// { notFound: "Page not found", unauthorized: "Access denied" }

When a translated dictionary is missing keys, the missing entries are filled in from the source dictionary. This means partial translations won't cause runtime errors — untranslated keys fall back to the source text.

Lookup behavior

Two rules govern how lookups resolve:

1. Missing translation → default locale fallback. If a key exists in the source dictionary but has no translation for the current locale, t() returns the source text.
2. Missing source entry → error. If a key doesn't exist in the source dictionary at all, t() throws. This is intentional — if a key isn't defined in your source, it's a bug, not a missing translation. This behavior will be applied across all GT libraries in an upcoming refactor.

The second rule assumes that translated dictionaries match the structure of your source dictionary, which is how GT generates translations automatically.

Links

• PR #1359
• getTranslations API reference
• Dictionaries guide