# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<T>`
URL: https://generaltranslation.com/zh/docs/react/reference/components/t.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 原地翻译 JSX 子元素。`<T>` 组件的 API 参考。

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

*可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。*

## 概览 [#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>
```

*注意：服务器端渲染的 `gt-react` 和 TanStack Start 应用通过 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 提供区域设置和翻译，而 `gt-next` 和 `gt-react-native` 应用使用其框架的 provider，无需这些属性。使用 [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) 初始化的 React SPA 不需要 provider。*

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

* **构建时翻译。** 在生产环境中，`<T>` 内的内容会在构建 (或部署) 阶段完成翻译，也就是在用户加载应用之前。这样可以保证运行时足够快，但只有在构建时已知的内容才能被翻译。生成翻译会通过 CDN 或应用的构建产物提供；如果缺少翻译，则会回退到原始内容。
* **开发环境中按需翻译。** 配置开发热重载后，`<T>` 会在你进行原型开发时请求缺失的翻译。在客户端渲染的组件中，它会先展示源内容，直到译文可用为止，并且可以在更新期间保留先前的翻译。被拒绝的客户端运行时请求会被记录下来，重复的错误会去重。服务器组件则会等待其翻译查找完成。生产环境的渲染使用生成翻译，缺少翻译时会回退到源内容。
* **翻译后代内容，而不是动态子元素。** `<T>` 只会翻译字面写在其标签之间的 JSX。通过变量传入的内容 (例如 `{greeting}`) 无法翻译，并且会导致错误——请将动态值包裹在变量组件中。一个简单的经验法则是：凡是直接写在两个 `<T>` 标签之间的内容，都会被翻译。避免嵌套 `<T>` 组件。

## Props [#props]

| Prop                                  | 描述              | 类型        | 可选 | 默认值 |
| ------------------------------------- | --------------- | ----------- | -- | --- |
| [`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]

*示例从 `gt-react` 导入；请改为从你的框架对应的 package 导入。*

```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 结构，包括变量和复数处理。
* 基于 Provider 的设置会在 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 下渲染 `<T>`。React SPA 和 `gt-next` 同步服务器组件无需使用它，但 `gt-next` 客户端组件需要。
* 如需翻译占位符、标签等独立字符串，请使用 [`useGT`](/docs/react/reference/hooks/use-gt)。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.