# gt-react: General Translation React SDK: t
URL: https://generaltranslation.com/zh/docs/react/api/strings/t-function.mdx
---
title: t
description: t() 同步字符串翻译函数的 API 参考
---
## 概述
`t` 函数是一个同步的模块级字符串翻译函数，适用于 React 客户端应用。
```jsx
import { t } from 'gt-react/browser';
const greeting = t('Hello, world!');
```
`t` 也可以用作标签模板字面量：
```jsx
import { t } from 'gt-react/browser';
const greeting = t`Hello, ${name}!`;
```
与 `useGT` (需要 React 上下文) 或 `msg` (将字符串编码以便后续解析) 不同，`t()` 会直接返回翻译后的字符串。它可以在浏览器代码中的任何位置调用——包括模块作用域中，以及 React 组件之外。
**实验性：** `t()` 是一项实验性功能。它专为纯客户端 React 应用设计，目前尚未与 React 上下文 (例如 ``、`useGT`) 集成。如果在服务器端调用，它会记录一条警告，并返回原始字符串。
***
## 设置
`t()` 依赖 `bootstrap()` 在应用渲染之前加载翻译。你需要修改应用的入口文件，先运行 `bootstrap()`。
入口文件通常是 `main.tsx`。你需要新建一个文件 (例如 `bootstrap.tsx`) ，然后让 `index.html` 改为指向这个文件。
### 1. 创建 bootstrap 入口文件
```tsx
// bootstrap.tsx
import gtConfig from '../gt.config.json';
import { bootstrap } from 'gt-react/browser';
async function loadTranslations(locale: string) {
return (await import(`./_gt/${locale}.json`)).default;
}
await bootstrap({
...gtConfig,
loadTranslations,
});
await import('./main.tsx');
```
默认情况下，`bootstrap()` 会自动更新 `` 元素的 `lang` 和 `dir` 属性，使其与当前区域设置保持一致。
你可以通过 `htmlTagOptions` 配置这一行为：
```tsx
await bootstrap({
...gtConfig,
loadTranslations,
htmlTagOptions: {
updateHtmlLangTag: true, // 默认值：true
updateHtmlDirTag: false, // 默认值：true
},
});
```
你也可以随时借助 `gt-react/browser` 中的 `updateHtmlTagLang` 和 `updateHtmlTagDir` 辅助函数，手动更新这些属性。
### 2. 更新 `index.html`
在 `index.html` 中，将模块入口更新为指向新的 bootstrap 文件，而不是 `main.tsx`：
```
src="/src/bootstrap.tsx"
```
### 3. 在任意位置使用 `t()`
```tsx
import { t } from 'gt-react/browser';
// 模块级别 — 在导入时执行
const navItems = [
{ label: t('Home'), path: '/' },
{ label: t('About'), path: '/about' },
{ label: t('Contact'), path: '/contact' },
];
export default function Nav() {
return (
);
}
```
**独立セットアップ：** `t()` 目前尚未与 `gt-react` 系统的其他部分 (如 ``、`useGT`) 集成。你需要使用上文所述的 bootstrap セットアップ。
***
## 标签模板字面量
`t` 可以作为标签模板字面量使用，语法更自然：
```tsx
import { t } from 'gt-react/browser';
// 以下两种写法等价：
t('Hello, {name}!', { name: 'Alice' });
t`Hello, ${name}!`;
```
tagged template 形式无需再使用 ICU 风格的占位符和选项对象——变量会通过模板表达式直接插值。
### 全局注册
无需在每个文件中导入 `t`，你可以将其注册为全局可用：
```tsx
// 在应用的入口文件中
import "gt-react/macros";
```
这会设置 `globalThis.t`，使标签模板字面量无需显式导入即可在任何位置使用：
```tsx
// 无需导入
const labels = {
save: t`Save`,
cancel: t`Cancel`,
};
```
***
## 参考
### 参数
| 名称 | 类型 | 说明 |
| ---------- | -------- | ----------------- |
| `message` | `string` | 要翻译的字符串。 |
| `options?` | `object` | 可选。包含用于插值的变量值的对象。 |
### 返回值
`string` — 当前区域设置下的翻译后字符串；如果没有可用译文，则返回源字符串。
***
## 变量
你可以使用花括号语法来传递变量：
```tsx
import { t } from 'gt-react/browser';
const message = t('Hello, {name}!', { name: 'Alice' });
// → "Hola, Alice!"（西班牙语）
```
或者使用标签模板字面量写法，它会自动处理插值：
```tsx
import { t } from 'gt-react/browser';
const message = t`Hello, ${name}!`;
// → "Hola, Alice!"（西班牙语，当 name = 'Alice' 时）
```
变量值不会被翻译——只有外层的字符串模板会被翻译。
***
## 行为
### 工作方式
`bootstrap()` 会在导入应用模块之前，异步加载当前区域设置的所有翻译。加载完成后，`t()` 会同步从翻译数据中读取内容，不会产生额外开销。
由于翻译是在模块加载时解析的：
* **切换区域设置需要完全重新加载页面。** 浏览器必须重新执行所有模块，才能应用新的翻译。
* **这仅适用于客户端应用。** 模块级代码在浏览器中加载时会重新执行，这正是这种模式之所以可行的原因。
### 服务端行为
如果在服务端环境中 (即 `window` 为 `undefined`) 调用 `t()`，它会输出一条警告，并返回原始字符串。若要在服务端进行翻译，请使用基于 React 上下文的 Hook，例如 `useGT`。
***
## 示例
### 常量文件
```tsx
// constants.ts
import { t } from 'gt-react/browser';
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
// routes.ts
import { t } from 'gt-react/browser';
export const routes = [
{ path: '/', label: t('Home') },
{ path: '/dashboard', label: t('Dashboard') },
{ path: '/settings', label: t('Settings') },
];
```
***
## 说明
* `t()` 从 `gt-react/browser` 导入，而不是直接从 `gt-react` 导入。
* 必须先调用 `bootstrap()`，再加载任何使用 `t()` 的模块。
* **实验性功能。** 目前尚未与 `` 或 `gt-react` 中其他基于上下文的功能集成。
* 切换区域设置需要重新加载整个页面。
## 开发日志
* [gt-react@10.12.0](/devlog/gt-react_v10_12_0) — 引入 `t()` 函数
* [gt-react@10.13.0](/devlog/gt-react_v10_13_0) — 支持标签模板字面量
## 后续步骤
* 如需在 React 组件中翻译字符串，请参阅 [`useGT`](/docs/react/api/strings/use-gt)。
* 如需对字符串进行编码以便稍后翻译，请参阅 [`msg`](/docs/react/api/strings/msg)。