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

title: tx
description: 使用 General Translation 在运行时按需翻译字符串。tx 的 API 参考。

---

在运行时翻译字符串。与用于处理 build-time 翻译的 [`getGT`](/docs/node/reference/functions/get-gt) 不同，`tx` 会将内容发送出去进行按需翻译，因此它可以翻译那些只有在运行时才会确定的字符串。

## 概览 [#overview]

在 [`withGT`](/docs/node/reference/functions/with-gt) 作用域内，对 `tx` 传入要翻译的字符串并使用 `await`。它会返回翻译后的字符串。

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

const translated = await tx('Hello, world!');
```

签名：

```ts
tx(content: string, options?: RuntimeTranslationOptions): Promise<string>
```

*注意：`tx` 会按需执行翻译，这意味着相比 build-time 翻译，需要发起网络请求，并且会有一定延迟。对于在构建时已知的字符串，请使用 [`getGT`](/docs/node/reference/functions/get-gt)；只有当内容是动态的，或无法提前确定时，才使用 `tx`。*

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

* **运行时翻译。** 发生缓存未命中时，翻译会在运行时通过网络请求完成，因此相比 build-time 翻译会有一定延迟。`tx` 请仅用于 dynamic content。
* **不支持 ICU 插值。** 与 [`getGT`](/docs/node/reference/functions/get-gt) 不同，`tx` 不会对 `{variable}` 占位符进行插值——它会将字符串视为 plain text。请使用 JavaScript template literal 嵌入变量，这样变量值就会包含在发送去翻译的内容中。
* **后备内容。** 如果无需翻译，则返回原始字符串。

## 参数 [#parameters]

| 参数                    | 描述            | 类型                          | 可选 | 默认 |
| --------------------- | ------------- | --------------------------- | -- | -- |
| [`content`](#content) | 要翻译的字符串。      | `string`                    | 否  | —  |
| [`options`](#options) | 用于自定义翻译行为的选项。 | `RuntimeTranslationOptions` | 是  | —  |

### `content` [#content]

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

要翻译的字符串。请使用模板字面量嵌入动态值，不要使用 `{variable}` 占位符。

### `options` [#options]

**类型** `RuntimeTranslationOptions` · **可选**

用于自定义运行时翻译的选项：

* `$context?: string` — 用于帮助消除翻译歧义的额外上下文。
* `$locale?: string` — 覆盖由 [`withGT`](/docs/node/reference/functions/with-gt) 设置的区域设置。
* `$maxChars?: number` — 翻译的最大字符数。
* `$requiresReview?: boolean` — 翻译在使用前是否需要审批。

*注意：`RuntimeTranslationOptions` 类似于 [`getGT`](/docs/node/reference/functions/get-gt) 的内联选项，但不包含 `$id`，且其 `$format` 默认是 plain-string (非 ICU) ，而不是 ICU。*

## 返回值 [#returns]

**类型** `Promise<string>`

解析结果为翻译后的字符串；如果不需要翻译，则返回原始字符串。

## 示例 [#examples]

```ts title="handler.js"
// 基本用法
import { withGT, tx } from 'gt-node';

function handleRequest(locale) {
  return withGT(locale, async () => {
    return await tx('Processing complete');
  });
}
```

```ts title="handler.js"
// 使用变量——通过模板字面量嵌入值，而非 {placeholders}
import { withGT, tx } from 'gt-node';

function handleStatus(locale, status) {
  return withGT(locale, async () => {
    return await tx(`Current status: ${status}`);
  });
}
```

```ts title="handler.js"
// 使用上下文消除翻译歧义
const translated = await tx('Spring', {
  $context: 'the season, not a coil',
});
```

```ts title="handler.js"
// 指定区域设置 — 覆盖 withGT 的区域设置
const translated = await tx('Hello, world!', { $locale: 'fr' });
```

## 注意事项 [#notes]

* `tx` 是异步的，会返回一个 promise。请始终使用 `await` 等待结果。
* Translations 通过网络请求在 运行时 执行，因此相比 build-time 翻译会有一定延迟。
* `tx` 不支持 ICU `{variable}` 插值。请使用模板字面量嵌入变量。
* 对于带有 ICU 变量插值的静态 strings，请使用 [`getGT`](/docs/node/reference/functions/get-gt) 或结合 [`getMessages`](/docs/node/reference/functions/get-messages) 使用 [`msg`](/docs/node/reference/functions/msg)。