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

title: msg
description: 在模块作用域中标记并编码字符串，以供 General Translation 翻译。msg 的 API 参考。

---

注册一个字符串 (或字符串数组) 以供翻译。将 `msg` 与 [`getMessages`](/docs/node/reference/functions/get-messages) 搭配使用，可注册字符串 (通常在模块作用域中) ，并在运行时解析其译文。

## 概览 [#overview]

用字符串调用 `msg`。不传入任何 options 时，它会原样返回该字符串；传入 options (插值变量或元数据) 时，它会返回一个携带这些 options 的编码后的字符串。将结果传给 [`getMessages`](/docs/node/reference/functions/get-messages) 即可获取翻译。

```ts
const registered = msg('Hello, world!');
console.log(registered); // "Hello, world!"（不变）

const withVars = msg('Hello, {name}!', { name: 'Brian' });
console.log(withVars); // "Hello, Brian:<encoded-options>"
```

签名：

```ts
msg<T extends string | string[]>(message: T): T;
msg<T extends string | string[]>(message: T, options?: GTTranslationOptions): T extends string ? string : string[];
```

*注意：`msg` 在未传入选项时会原样返回消息。只有传入选项时，它才会生成编码后的字符串。要从编码后的字符串中还原原始文本，请使用 [`decodeMsg`](/docs/node/reference/functions/decode-msg) 进行解码。*

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

* **注册。** `msg` 会标记内容，以便 [`gt` CLI](/docs/cli/quickstart) 发现并翻译。实际翻译结果会在稍后由 [`getMessages`](/docs/node/reference/functions/get-messages) 解析。
* **生产环境。** `msg` 调用中的内容会在部署前完成翻译。翻译会根据你的配置存储在 CDN 或应用的构建产物中，并从那里提供服务。如果找不到翻译，则回退到原始内容。
* **开发环境。** 配合 `projectId` 和 `devApiKey` 使用时，`msg` 中的内容会按需翻译，这很适合用来预览不同语言版本。预计会有一定延迟，而这种延迟在生产构建中不会出现。
* **编码。** 提供 options 时，返回值为 `interpolatedContent:encodedOptions`——即插值后的内容、一个冒号，以及经过 base64 编码的 options。你可以使用 [`getMessages`](/docs/node/reference/functions/get-messages) 对其进行解析，或使用 [`decodeMsg`](/docs/node/reference/functions/decode-msg) 进行解码。
* **数组。** 传入 `string[]` 会注册其中的每个 entry。使用 `$id` 时，每个 entry 都会获得一个唯一 id，格式为 `${$id}.${index}`。

## 参数 [#parameters]

| 参数                    | 描述             | 类型                     | 可选 | 默认值 |
| --------------------- | -------------- | ---------------------- | -- | --- |
| [`message`](#message) | 待注册的字符串或字符串数组。 | `string \| string[]`   | 否  | —   |
| [`options`](#options) | 翻译选项和插值变量。     | `GTTranslationOptions` | 是  | —   |

### `message` [#message]

**类型** `string | string[]` · **必填**

要注册为待翻译内容的字符串，或由多个字符串组成的数组，以便一次注册多个字符串。

### `options` [#options]

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

翻译选项以及插值变量：

* `$context?: string` — 用于帮助消除翻译歧义的额外上下文。
* `$id?: string` — translation entry 的自定义 ID (array 会生成 `${$id}.${index}`) 。
* `$format?: string` — 消息格式。默认为 `'ICU'`。
* `$maxChars?: number` — 翻译的最大字符数。
* `$requiresReview?: boolean` — 翻译在使用前是否需要审批。
* 其他任何键都会被视为要使用 `{key}` 语法插值到 string 中的值。

## 返回值 [#returns]

**类型** `string | string[]`

未传入 options 时，消息保持不变；传入 options 时，则返回编码后的字符串 (已对变量完成插值) 。如果输入是数组，则返回形状相同的数组。

## 解码 [#decoding]

要从编码后的消息中还原原始的插值字符串，请使用 [`decodeMsg`](/docs/node/reference/functions/decode-msg) 进行解码。

```ts
import { msg, decodeMsg } from 'gt-node';

const encoded = msg('Hello, {name}!', { name: 'Brian' });
const decoded = decodeMsg(encoded);
console.log(decoded); // "Hello, Brian"
```

## 示例 [#examples]

```ts
// 基本用法 — 将字符串标记为待翻译
import { msg, getMessages } from 'gt-node';

const greeting = msg('Hello, world!');

const m = await getMessages();
const translated = m(greeting);
console.log(translated); // "Hello, world!"（已翻译为用户的首选语言）
```

```ts
// 使用变量 — "Alice" 是一个变量，不会被翻译
import { msg, getMessages } from 'gt-node';

const greeting = msg('Hello, {name}!', { name: 'Alice' });

const m = await getMessages();
const translated = m(greeting);
console.log(translated); // "Hello, Alice!"（已翻译）
```

```ts
// 使用 ICU message format 格式化变量
import { msg, getMessages } from 'gt-node';

const encodedString = msg(
  'There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the cart',
  { count: 10 }
);

const m = await getMessages();
const translated = m(encodedString);
console.log(translated);
```

*注意：[ICU message format](https://unicode-org.github.io/icu/userguide/format_parse/messages/) 是一种功能强大的变量格式化方式。*

## 注意事项 [#notes]

* `msg` 用于标记可翻译内容；翻译会在运行时之前的构建过程中完成 (开发环境除外) 。
* 不传 options 时，`msg` 会原样返回输入内容；传入 options 时，则会返回一个编码后的字符串。
* 使用 [`getMessages`](/docs/node/reference/functions/get-messages) 解析编码后的字符串，或使用 [`decodeMsg`](/docs/node/reference/functions/decode-msg) 还原原始文本。