# gt-node: General Translation Node.js SDK: getTranslations
URL: https://generaltranslation.com/zh/docs/node/reference/functions/get-translations.mdx
---

title: getTranslations
description: 获取当前请求区域设置的 General Translation 词典解析器。getTranslations 的 API 参考。

---

这是一个异步函数，会返回一个 `t` 函数，用于按 id 解析词典条目。将它与通过 [`initializeGT`](/docs/node/reference/functions/initialize-gt) 配置的词典配合使用，即可按请求翻译集中管理的键值文案。

## 概览 [#overview]

在 [`withGT`](/docs/node/reference/functions/with-gt) 的作用域中 await `getTranslations`，即可获取一个同步的 `t(id, options?)` 函数，然后按 id 查找词典条目。

```ts
import { getTranslations } from 'gt-node';

const t = await getTranslations();
const title = t('page.title');
```

签名：

```ts
getTranslations(rootId?: string): Promise<TFunctionType>

type TFunctionType = ((id: string, options?: TranslationVariables) => string) & {
  obj: (id: string) => DictionaryObjectTranslation;
};
```

*注意：`getTranslations` 必须在 [`withGT`](/docs/node/reference/functions/with-gt) 的回调中调用，这样它才能知道应使用哪个区域设置；并且还要求在 [`initializeGT`](/docs/node/reference/functions/initialize-gt) 中配置 `dictionary` (或 [`loadDictionary`](/docs/react/reference/functions/load-dictionary)) 。*

## 工作原理 [#how-it-works]

* **词典查找。** `t(id)` 会查找词典中 `id` 对应的条目，并返回其在当前区域设置下的翻译；如果缺少翻译，则回退到源条目。
* **未知 id 会抛出错误。** 如果源词典中没有 `id` 对应的条目，`t(id)` 会抛出 `Dictionary entry <id> cannot be found`。这是 `gt-node` 中唯一会抛出错误、而不是回退到源字符串的翻译路径。
* **根作用域限定。** 传入 `rootId` 可将所有查找限定在某个前缀下，因此 `getTranslations('page')` 让你可以调用 `t('title')`，而不是 `t('page.title')`。
* **插值。** 在选项对象中传入变量，即可使用 `{key}` 语法将变量插入条目中。
* **对象子树。** `t.obj(id)` 会将词典中嵌套的子树作为一个由已翻译字符串组成的普通对象返回。

## 参数 [#parameters]

`getTranslations` 接受一个可选的 `rootId`。返回的 `t` 函数接受以下参数：

| 参数                    | 说明              | 类型                     | 可选 | 默认值  |
| --------------------- | --------------- | ---------------------- | -- | ---- |
| [`rootId`](#root-id)  | 应用于每个查找 id 的前缀。 | `string`               | 是  | —    |
| [`id`](#id)           | 要解析的词典条目 id。    | `string`               | 否  | —    |
| [`options`](#options) | 要插入条目中的变量值。     | `TranslationVariables` | 是  | `{}` |

### `rootId` [#root-id]

**类型** `string` · **可选**

会为传给 `t` 的每个 id 添加一个前缀。设置后，`t('title')` 会解析为 `rootId.title`。

### `id` [#id]

**类型** `string` · **必填**

要解析的 词典条目 的 `id`；对于嵌套 entries，使用点表示法 (例如 `'page.title'`) 。

### `options` [#options]

**类型** `TranslationVariables` · **可选**

一组变量值记录，用于通过 `{key}` 语法插入到已解析的 条目 中。

## 返回值 [#returns]

**类型** `Promise<TFunctionType>`

该 Promise 会解析为 `t` 函数。调用 `t(id, options?)` 会返回翻译后的字符串；`t.obj(id)` 会返回翻译后的对象子树。

## 示例 [#examples]

```ts title="server.js"
// 在启动时配置词典
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'],
  dictionary: {
    page: { title: 'Welcome', greeting: 'Hello, {name}!' },
  },
});
```

```ts title="handler.js"
// 解析请求区域设置的词典条目
import { withGT, getTranslations } from 'gt-node';

function handleRequest(locale) {
  return withGT(locale, async () => {
    const t = await getTranslations();
    return {
      title: t('page.title'),
      greeting: t('page.greeting', { name: 'Alice' }),
    };
  });
}
```

```ts title="handler.js"
// 使用 rootId 限定查找范围
const t = await getTranslations('page');
const title = t('title'); // 解析为 'page.title'
```

## 注意事项 [#notes]

* 未知的 词典 id 会抛出错误；请确保 source 与代码中的 词典 键保持同步。
* 对于内联字符串，请使用 [`getGT`](/docs/node/reference/functions/get-gt)；对于模块层级的常量，请使用 [`msg`](/docs/node/reference/functions/msg) 并配合 [`getMessages`](/docs/node/reference/functions/get-messages)。