diff --git a/docs/en-US/node/api/get-translations.mdx b/docs/en-US/node/api/get-translations.mdx new file mode 100644 index 0000000..6844cde --- /dev/null +++ b/docs/en-US/node/api/get-translations.mdx @@ -0,0 +1,150 @@ +--- +title: getTranslations +description: API reference for the getTranslations dictionary translation function +--- + +## Overview + +`getTranslations` returns a translation function `t` that resolves entries from a [dictionary](/docs/next/guides/dictionaries). +Use it to translate pre-defined strings by their dictionary key. + +```js +import { getTranslations } from 'gt-node'; + +const t = await getTranslations(); +t('greeting.hello'); // "Hello!" +``` + + + **Request context required:** + `getTranslations` must be called within a [`withGT`](/docs/node/api/with-gt) callback so it knows which locale to use. + + +## Reference + +### Parameters + +None. + +### Returns + +A promise that resolves to a translation function `t`: + +```ts +Promise +``` + +The `t` function accepts a dictionary key and optional interpolation options: + +| Name | Type | Description | +| --- | --- | --- | +| `id` | `string` | The dot-separated path to a dictionary entry. | +| `options?` | `DictionaryTranslationOptions` | Variables for interpolation. | + +**Returns:** `string` — the translated (or source-language fallback) text. + +If the key does not exist in the source dictionary, `t()` throws an error. +If the key exists in the source dictionary but has no translation for the current locale, `t()` returns the source text. + +### `t.obj()` + +Returns an entire subtree of the dictionary as an object instead of a single string. + +```ts +t.obj(id: string): DictionaryObjectTranslation +``` + +| Name | Type | Description | +| --- | --- | --- | +| `id` | `string` | The dot-separated path to a dictionary subtree. | + +**Returns:** A nested object matching the dictionary structure, with translated values where available and source-language fallbacks elsewhere. + +--- + +## Setup + +### Automatic (recommended) + +Create a `dictionary.json` file in your project root: + +```json title="dictionary.json" +{ + "greeting": { + "hello": "Hello!" + }, + "user": { + "welcome": "Welcome, {name}!" + } +} +``` + +When you run `npx gtx translate`, the CLI automatically detects `dictionary.json` and translates it for your configured locales. + +Then initialize GT with the dictionary: + +```ts +import { initializeGT } from 'gt-node'; +import dictionary from './dictionary.json'; + +initializeGT({ + dictionary, + defaultLocale: 'en-US', + locales: ['en-US', 'es', 'fr'], +}); +``` + +### Custom dictionary loader + +If you manage your own translated dictionaries, pass a `loadDictionary` function to [`initializeGT`](/docs/node/api/initialize-gt): + +```ts +import { initializeGT } from 'gt-node'; +import dictionary from './dictionary.json'; + +initializeGT({ + dictionary, + loadDictionary: async (locale) => { + const dict = await import(`./locales/${locale}.json`); + return dict.default; + }, +}); +``` + +Translations loaded via `loadDictionary` take precedence over GT-generated translations. + +--- + +## Examples + +### Basic usage + +```ts +import { getTranslations } from 'gt-node'; + +const t = await getTranslations(); +t('greeting.hello'); // "Hello!" +``` + +### Variable interpolation + +```ts +const t = await getTranslations(); +t('user.welcome', { name: 'Alice' }); // "Welcome, Alice!" +``` + +### Object lookup with `t.obj()` + +```ts +const t = await getTranslations(); + +const errors = t.obj('errors'); +// { notFound: "Page not found", unauthorized: "Access denied" } +``` + +--- + +## Notes + +- `getTranslations` is the dictionary-based counterpart to [`getMessages`](/docs/node/api/get-messages), which is used for inline `msg()` strings. +- For the Next.js equivalent, see [`getTranslations` in gt-next](/docs/next/api/dictionary/get-translations). diff --git a/docs/en-US/node/api/initialize-gt.mdx b/docs/en-US/node/api/initialize-gt.mdx index a246f6f..af708d9 100644 --- a/docs/en-US/node/api/initialize-gt.mdx +++ b/docs/en-US/node/api/initialize-gt.mdx @@ -20,7 +20,7 @@ initializeGT({ **Required setup:** - `initializeGT` must be called before using `withGT`, `getGT`, `getMessages`, or any other translation function. + `initializeGT` must be called before using `withGT`, `getGT`, `getMessages`, `getTranslations`, or any other translation function. Call it once during your server's initialization (e.g., at the top of your entry file). @@ -55,6 +55,14 @@ initializeGT({ type: 'string | null', optional: true, }, + "dictionary?": { + type: 'Dictionary', + optional: true, + }, + "loadDictionary?": { + type: 'DictionaryLoader', + optional: true, + }, "loadTranslations?": { type: 'TranslationsLoader', optional: true, @@ -84,6 +92,8 @@ initializeGT({ | `devApiKey` | API key for development environment on-demand translations. | | `cacheUrl` | URL of the GT cache service. Set to `null` to disable. | | `runtimeUrl` | URL of the GT runtime translation service. Set to `null` to disable. | +| `dictionary` | A source-language dictionary object for use with [`getTranslations`](/docs/node/api/get-translations). | +| `loadDictionary` | An async function that loads a translated dictionary for a given locale. Requires `dictionary` to be set. | | `loadTranslations` | A custom function to load translations from your own source. | | `customMapping` | A mapping of custom locale codes to standard locale codes or locale properties. | | `enableI18n` | Whether to enable i18n features. | @@ -135,4 +145,5 @@ initializeGT({ ## Next steps - See [`withGT`](/docs/node/api/with-gt) to provide locale context for each request. -- See [`getGT`](/docs/node/api/get-gt) and [`getMessages`](/docs/node/api/get-messages) for translating strings. +- See [`getGT`](/docs/node/api/get-gt) and [`getMessages`](/docs/node/api/get-messages) for translating inline strings. +- See [`getTranslations`](/docs/node/api/get-translations) for dictionary-based translations. diff --git a/docs/en-US/node/api/meta.json b/docs/en-US/node/api/meta.json index 5dd3291..50ddf14 100644 --- a/docs/en-US/node/api/meta.json +++ b/docs/en-US/node/api/meta.json @@ -6,6 +6,7 @@ "./with-gt", "./get-gt", "./get-messages", + "./get-translations", "./strings", "---Helpers---", "./get-locale",