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

title: getGT
description: 获取适用于当前请求区域设置的 General Translation 函数，用于翻译内联字符串。getGT 的 API 参考。

---

一个异步函数，返回适用于当前请求区域设置的翻译函数。它会解析由 General Translation 编译器在构建时注册的翻译；如果找不到翻译，则回退到源字符串。

## 概览 [#overview]

在 [`withGT`](/docs/node/reference/functions/with-gt) 作用域内对 `getGT` 使用 await，以获取一个同步的 `gt(message, options?)`` 函数，然后用它翻译字符串。

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

const gt = await getGT();
const greeting = gt('Hello, world!');
```

签名：

```ts
getGT(): Promise<GTFunctionType>

type GTFunctionType = (message: string, options?: GTTranslationOptions) => string;
```

*注意：`getGT` 必须在 [`withGT`](/docs/node/reference/functions/with-gt) 的回调函数中调用，这样它才能知道应使用哪个区域设置。它还接受一个内部 `_messages` 参数，供 编译器 在开发时进行 hot reload；你无需直接传入它。*

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

* **构建时翻译。** `getGT` 会返回一个构建时翻译函数。字符串会在部署前的 CD 过程中完成翻译，因此 Production 环境中的请求会直接返回缓存的译文，无需网络往返。
* **开发环境。** 在开发环境中，翻译按需进行，并且需要 Dev API Key。
* **后备内容。** 如果找不到翻译，则返回原始的 (已插值的) 源字符串。
* **插值。** 在字符串中使用 `{variableName}` 占位符，并在选项对象中传入值。`gt-node` 支持 [ICU message format](https://unicode-org.github.io/icu/userguide/format_parse/messages/)，可用于高级格式化。

## 参数 [#parameters]

`getGT` 不接受任何参数。返回的 `gt` 函数接受：

| 参数                    | 描述         | Type                   | 可选 | 默认值  |
| --------------------- | ---------- | ---------------------- | -- | ---- |
| [`message`](#message) | 要翻译的字符串。   | `string`               | 否  | —    |
| [`options`](#options) | 插值变量和翻译选项。 | `GTTranslationOptions` | 是  | `{}` |

### `message` [#message]

**类型** `string` · **必需**

要翻译的字符串。它可以包含用于 ICU 插值的 `{variable}` 占位符。

### `options` [#options]

**类型** `GTTranslationOptions` · **可选**

翻译选项及插值变量：

* `$context?: string` — 用于帮助消除翻译歧义的附加上下文。
* `$id?: string` — 翻译条目的自定义 ID。
* `$locale?: string` — 覆盖此次调用的请求区域设置。
* `$format?: string` — 消息格式。默认为 `'ICU'`。
* `$maxChars?: number` — 翻译的最大字符数。
* `$requiresReview?: boolean` — 翻译在使用前是否需要审批。
* 其他任何键都会被视为要通过 `{key}` 语法插入字符串的值。

## 返回值 [#returns]

**类型** `Promise<GTFunctionType>`

该 Promise 会解析为 `gt` 翻译函数。调用 `gt(message, options?)` 会返回翻译后的字符串；如果找不到翻译，则返回原始的 (插值后的) 字符串。

## 示例 [#examples]

```ts title="handler.js"
// 简单翻译
import { withGT, getGT } from 'gt-node';

function handleRequest(locale) {
  return withGT(locale, async () => {
    const gt = await getGT();
    return gt('Hello, world!');
  });
}
```

```ts title="handler.js"
// 使用变量——在字符串中使用 {name}，并在 options object 中传入对应的值
import { withGT, getGT } from 'gt-node';

function handleGreeting(locale, name) {
  return withGT(locale, async () => {
    const gt = await getGT();
    return gt('Hello, {name}!', { name });
  });
}
```

```ts title="handler.js"
// 使用 ICU message format
const gt = await getGT();
const balance = gt(
  'Your balance: {amount, number, ::currency/USD}',
  { amount: 1234.56 }
);
```

## 注意事项 [#notes]

* `getGT` 返回一个构建时翻译函数；字符串会在部署前的 CD 流程中完成翻译。
* 在开发环境中，翻译按需进行，并且需要 Dev API Key。
* 如果找不到翻译，则返回原始字符串作为后备内容。
* 对于仅在运行时才能确定的字符串，使用 [`tx`](/docs/node/reference/functions/tx)；对于在模块作用域中注册的字符串，使用 [`msg`](/docs/node/reference/functions/msg) 和 [`getMessages`](/docs/node/reference/functions/get-messages)。