# General Translation React SDKs (gt-react, gt-next): msg
URL: https://generaltranslation.com/zh/docs/react/reference/functions/msg.mdx
---

title: msg
description: 在模块作用域中使用 General Translation gt-react 注册并编码用于翻译的字符串。msg 的 API 参考。

---

`msg` 函数会标记并编码一个字符串以供翻译。你可以用它在模块作用域中 (即组件外) 注册字符串，然后在运行时通过 [`useMessages`](/docs/react/reference/hooks/use-messages) 解析它们。

*可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。示例从 `gt-react` 导入；请改为从你所用框架对应的包中导入。*

## 概览 [#overview]

用字符串调用 `msg` 会得到一个编码后的字符串。将该编码后的值传给 [`useMessages`](/docs/react/reference/hooks/use-messages) 以获取翻译。

```tsx
const encodedString = msg('Hello, world!');
```

*注意：`msg` 会对输入内容进行编码，因此不能直接渲染。要恢复原始字符串，请使用 [`decodeMsg`](/docs/node/reference/functions/decode-msg) 进行解码。*

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

* **注册以便提取。** `msg` 会标记该字符串，以便 CLI 将其提取出来进行翻译，并让 [`useMessages`](/docs/react/reference/hooks/use-messages) 能在运行时解析它。不带选项时，它会原样返回该字符串；带选项时，则会返回一个携带这些选项的编码后的字符串。
* **构建时翻译。** 在生产环境中，已注册的字符串会在构建期间完成翻译。缺失的翻译会回退到原文。在开发环境中，翻译会按需进行，并会有轻微延迟。
* **解码。** `decodeMsg` 会从编码消息中提取原始的插值字符串。[`decodeOptions`](/docs/node/reference/functions/decode-options) 会提取这些选项。
* **数组。** `msg` 也接受字符串数组；提供 `$id` 时，每个条目都会分配一个唯一的 id，即 `${id}.${index}`。

```tsx
import { msg, decodeMsg } from 'gt-react';

const encoded = msg('Hello, world!');
const decoded = decodeMsg(encoded);
console.log(decoded); // "Hello, world!"
```

## 参数 [#parameters]

| 参数                    | 描述                           | 类型                                                                                   | 可选 | 默认值 |
| --------------------- | ---------------------------- | ------------------------------------------------------------------------------------ | -- | --- |
| [`message`](#message) | 要注册的字符串 (或字符串数组) 。           | `string \| string[]`                                                                 | 否  | —   |
| [`options`](#options) | 插值变量以及 `$context`、`$id` 等选项。 | [`InlineTranslationOptions`](/docs/react/reference/types/inline-translation-options) | 是  | —   |

### `message` [#message]

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

要注册并编码的字符串内容。数组可一次注册多个字符串。

### `options` [#options]

**类型** [`InlineTranslationOptions`](/docs/react/reference/types/inline-translation-options) · **可选**

插值变量，以及 `$context`、`$id` 和 `$maxChars` 等选项。解析该字符串时，这些变量会被插入其中。

## 返回 [#returns]

**类型** `string`

返回一个已应用所有插值变量的编码后的字符串。对于数组输入，则返回编码后的字符串数组。请使用 [`useMessages`](/docs/react/reference/hooks/use-messages) 解析结果。

## 示例 [#examples]

```tsx
import { msg, useMessages } from 'gt-react';

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

export default function TranslateGreeting() {
  const m = useMessages();
  return <p>{m(encodedString)}</p>;
}
```

```tsx
import { msg, useMessages } from 'gt-react';

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

export default function TranslateGreeting() {
  const m = useMessages();
  return <p>{m(encodedString)}</p>;
}
// "Alice" 是变量，不会被翻译。
```

```tsx
import { msg } from 'gt-react';

// 使用 $context 消除歧义
const LABEL = msg('Bank', { $context: 'a bank of a river' });
```

`gt-react` 支持 [ICU message format](https://unicode-org.github.io/icu/userguide/format_parse/messages/)，用于在已注册的字符串中格式化变量。

## 说明 [#notes]

* `msg` 用于标记可翻译内容；翻译会在构建时进行 (开发环境中也可按需进行) 。
* 通过 [`useMessages`](/docs/react/reference/hooks/use-messages) 解析编码后的字符串。