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

title: t
description: 使用 General Translation gt-react 在模块作用域中同步翻译字符串。t 的 API 参考。

---

`t` 函数是一个同步的、模块级的字符串翻译函数，适用于客户端 `gt-react` 应用。不同于 [`useGT`](/docs/react/reference/hooks/use-gt) (它需要 React 上下文) 或 [`msg`](/docs/react/reference/functions/msg) (它会对字符串进行编码，以便后续解析) ，`t` 会直接返回翻译后的字符串，并且可以在浏览器代码中的任何位置调用，包括 React 组件外部。

*可用于 `gt-react` 和 `gt-tanstack-start`。示例从 `gt-react` 导入；如果使用 TanStack Start，请从 `gt-tanstack-start` 导入。*

*注意：`gt-next` 和 `gt-react-native` 不导出此函数。在 `gt-next` 中，请在同步组件中使用 [`useGT`](/docs/react/reference/hooks/use-gt)，或在异步 App Router 组件中使用 [`getGT`](/docs/react/nextjs/reference/functions/get-gt)。*

## 概览 [#overview]

从 `gt-react` 导入 `t`，然后传入一个字符串进行调用。

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

const greeting = t('Hello, world!');
```

也可作为标签模板字面量使用：

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

const greeting = t`Hello, ${name}!`;
```

*注意：`t` 会从由 [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) 填充的客户端缓存中读取翻译。请确保在任何在模块作用域调用 `t` 的模块执行之前，初始化已完成。在服务器端渲染应用中，禁止在模块作用域调用 `t`：开发环境下会直接抛出错误，生产环境下则会记录错误日志，并回退到默认区域设置的值。*

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

* **同步的模块作用域翻译。** 为当前区域设置加载翻译后，`t` 会同步读取这些翻译，没有额外开销。由于它不使用 React 上下文，因此既可在模块作用域 (常量、路由表) 使用，也可在组件内部使用。
* **在加载时解析。** 翻译会在模块求值时解析，因此**切换区域设置需要完整刷新页面**——浏览器必须重新执行模块，才能应用新的区域设置。此模式仅适用于客户端应用。
* **变量不会被翻译。** 插值后的值会被插入到已翻译的字符串中，但本身永远不会被翻译。
* **服务端行为。** 当渲染策略为 `server-render` 时，在模块作用域调用 `t` 是被禁止的——也就是在按请求初始化条件存储之前。在开发环境中，这会抛出错误；在生产环境中，它会记录错误日志并回退到 `defaultLocale` 的值。对于服务端翻译，请使用基于上下文的钩子，例如 [`useGT`](/docs/react/reference/hooks/use-gt)。

## 标签模板字面量 [#tagged-template]

`t` 可以用作标签模板，语法更自然。以下两种写法等价：

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

t('Hello, {name}!', { name: 'Alice' });
t`Hello, ${name}!`;
```

带标签的形式会直接从模板中插值变量，因此不需要 ICU 风格的占位符或 `options object`。

### 全局注册 [#macros]

无需在每个文件中都导入 `t`，只需在应用的入口文件中一次性导入 `macros` 入口，即可将其全局注册：

```tsx
import 'gt-react/macros';
```

这会设置 `globalThis.t`，让这个标签模板无需显式导入即可在任何地方使用：

```tsx
// 无需导入
const labels = {
  save: t`Save`,
  cancel: t`Cancel`,
};
```

## 参数 [#parameters]

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

### `message` [#message]

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

要翻译的字符串。用作标签模板时，这里则是模板字符串。

### `options` [#options]

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

插值变量和选项，如 `$context` 和 `$id` 等。参见 [`InlineTranslationOptions`](/docs/react/reference/types/inline-translation-options)。

## 返回值 [#returns]

**类型** `string`

当前区域设置对应的翻译字符串；如果没有可用译文，则返回源字符串。

## 示例 [#examples]

```tsx title="constants.ts"
import { t } from 'gt-react';

export const ERROR_MESSAGES = {
  notFound: t('Page not found'),
  unauthorized: t('You do not have permission to view this page'),
  serverError: t('Something went wrong. Please try again later.'),
};
```

```tsx title="routes.ts"
import { t } from 'gt-react';

export const routes = [
  { path: '/', label: t('Home') },
  { path: '/dashboard', label: t('Dashboard') },
  { path: '/settings', label: t('Settings') },
];
```

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

const message = t('Hello, {name}!', { name: 'Alice' });
// 变量值会被插入，而非翻译。
```

## 注意事项 [#notes]

* `t` 是同步的，可在模块作用域调用；它不使用 React 上下文。
* 切换区域设置需要重新加载整个页面。
* 要翻译组件内的字符串，请使用 [`useGT`](/docs/react/reference/hooks/use-gt)；要将字符串编码以便后续解析，请使用 [`msg`](/docs/react/reference/functions/msg)。