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

title: T
description: 使用 General Translation gt-react 原地翻译 JSX 子元素。T 的 API 参考。

---

`gt-react` 中的 `<T>` 组件是主要的翻译方式。它会将其 JSX 子元素 (包括纯文本和嵌套标记) 原地翻译为当前生效的区域设置。

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

## 概览 [#overview]

将任何静态 JSX 包裹在 `<T>` 中，它就会被翻译成当前区域设置所对应的语言。对于动态值，请使用变量组件，例如 [`<Var>`](/docs/react/reference/components/var) 和 [`<Num>`](/docs/react/reference/components/num)。

```tsx
<T>
  Today, I went to
  <p>
    the <b>store</b> to buy some <i>groceries</i>.
  </p>
</T>
```

*注意：`<T>` 必须在 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 内渲染，才能访问翻译内容。对于独立的字符串，请改用 [`useGT`](/docs/react/reference/hooks/use-gt)。*

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

* **构建时翻译。** 在生产环境中，`<T>` 内的内容会在构建 (或部署) 阶段完成翻译，也就是在用户加载应用之前。这样可以保证运行时足够快，但只有在构建时已知的内容才能被翻译。生成的译文会通过 CDN 或应用的构建产物提供；如果缺少翻译，则会回退到原始内容。
* **开发环境中按需翻译。** 设置开发 API 密钥后，`<T>` 会按需进行翻译，因此你可以在原型开发时预览不同区域设置下的效果。翻译加载期间，`<T>` 会返回 `undefined` (除非源语言和目标语言属于同一种语言，例如 `en-US` 和 `en-GB`) ；如果出错，则会返回原始内容。生产构建中不会出现这种延迟。
* **翻译后代内容，而不是动态子元素。** `<T>` 只会翻译字面写在其标签之间的 JSX。通过变量传入的内容 (例如 `{greeting}`) 无法翻译，并且会导致错误——请将动态值包裹在变量组件中。一个简单的经验法则是：凡是直接写在两个 `<T>` 标签之间的内容，都会被翻译。避免嵌套 `<T>` 组件。

## Props [#props]

| Prop                                  | 描述              | Type        | 可选 | 默认值 |
| ------------------------------------- | --------------- | ----------- | -- | --- |
| [`children`](#children)               | 要翻译的 JSX 内容。    | `ReactNode` | 否  | —   |
| [`$context`](#context)                | 供译者消歧的上下文。      | `string`    | 是  | —   |
| [`$id`](#id)                          | 条目的稳定标识符。       | `string`    | 是  | —   |
| [`$maxChars`](#max-chars)             | 翻译的最大长度。        | `number`    | 是  | —   |
| [`$requiresReview`](#requires-review) | 将该翻译标记为使用前需先审批。 | `boolean`   | 是  | —   |

### `children` [#children]

**类型** `ReactNode` · **必填**

要翻译的内容。它可以是纯文本，也可以是 JSX 结构，包括变量组件和分支组件。内容必须是静态的；动态值必须封装在变量组件中。

### `$context` [#context]

**类型** `string` · **可选**

用于细化翻译的附加上下文信息。可用于消除含义不明确的短语，帮助译者准确传达预期意思。

### `$id` [#id]

**类型** `string` · **可选**

translation entry 的稳定标识符，用于保持翻译一致性，并让该条目易于在 Translation Editor 中查找。

### `$maxChars` [#max-chars]

**类型** `number` · **可选**

译文的最大字符数。该库会严格执行此限制，超出长度的输出将被截断。

### `$requiresReview` [#requires-review]

**类型** `boolean` · **可选**

将已翻译内容标记为在使用前需要先获批准，因此不会被自动提供，而是会先保留供审核。

## 示例 [#examples]

```tsx title="Greeting.tsx"
import { T } from 'gt-react';

export default function Greeting() {
  return (
    <T>
      Hello, world! // [!code highlight]
    </T>
  );
}
```

```tsx title="DynamicGreeting.tsx"
import { T, Var } from 'gt-react';

export default function DynamicGreeting({ user }) {
  return (
    <T>
      Hello, <Var>{user.name}</Var>! // [!code highlight]
    </T>
  );
}
```

```tsx title="ItemCount.tsx"
import { T, Plural } from 'gt-react';

export default function ItemCount({ count }) {
  return (
    <T>
      <Plural
        n={count} // [!code highlight]
        one={<>You have an item.</>}
        other={<>You have items.</>}
      />
    </T>
  );
}
```

```tsx title="DynamicContent.tsx"
import { T } from 'gt-react';

export default function DynamicContent({ greeting }) {
  return (
    <T>
      {greeting} // ❌ 动态子元素无法翻译 — 请用 <Var> 包裹 // [!code highlight]
    </T>
  );
}
```

```tsx title="Descendants.tsx"
import { T } from 'gt-react';

const ValidTranslation = ({ children }) => <div><b>{children}</b></div>;
const InvalidTranslation = () => <div><b>No translation</b></div>;

export default function Example() {
  return (
    <T>
      <div><b>This is valid!</b></div> {/* 已翻译 */}

      <ValidTranslation>
        Hello, world! {/* 已翻译 */}
      </ValidTranslation>

      <InvalidTranslation /> {/* 未翻译 — 此处内容非字面量 */}
    </T>
  );
}
```

## 注意事项 [#notes]

* `<T>` 用于翻译内容，适用于纯文本或 JSX 结构，包括变量和复数处理。
* 必须将其包裹在 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 中，才能访问翻译上下文。
* 如需翻译占位符、标签等独立字符串，请使用 [`useGT`](/docs/react/reference/hooks/use-gt)。