# gt-react: General Translation React SDK: T
URL: https://generaltranslation.com/zh/docs/react/api/components/t.mdx
---
title: T
description: T 组件的 API 参考文档
---

{/* 自动生成：请勿直接编辑。请改为编辑 content/docs-templates/ 下的模板。 */}


## 概述

`<T>` 组件是 `gt-react` 中主要的翻译方法。

```jsx
<T id="example"> // [!code highlight]
    Today, I went to
    {" the store"}
    <p>
        to <b>buy</b> some <i>groceries</i>.
    </p>
</T> // [!code highlight]
```

`<T>` 组件既支持翻译纯文本，也支持翻译复杂的 JSX 结构。
此外，它还支持处理变量、复数形式以及特定上下文的翻译。

<Callout>
  **构建时翻译：**
  `<T>` 的翻译在构建时进行。
  这意味着翻译会在部署前完成，从而降低延迟。
  请务必遵循[此处的部署指南](/docs/react/tutorials/quickdeploy)。
</Callout>


## 参考

### 属性

<TypeTable
  type={{
  "children": {
      type: 'any',
      optional: false,
  },
  "id": {
      type: 'string',
      optional: false,
  },
  "context?": {
      type: 'string',
      optional: true,
      default: 'undefined',
  },
}}
/>

### 说明

| Prop       | 描述                            |
| ---------- | ----------------------------- |
| `children` | 要翻译的内容，可包含纯文本或 JSX 结构。        |
| `id`       | 翻译字符串的唯一标识符。这可确保整个应用中的翻译保持一致。 |
| `context`  | 用于优化翻译的附加上下文。有助于消除含义不明确的短语。   |

### 返回值

`React.JSX.Element|undefined`，包含根据所提供配置渲染的译文或回退内容。

***

## 行为

### 生产环境

在 CD 过程中，`<T>` 中的任何子内容都会在应用部署前完成翻译。
这样可以确保所有区域设置下都具备较快的加载速度，但它只能翻译在构建时已知的内容。

翻译生成后，会根据你的配置选择 (1) 存储在 CDN 中，或 (2) 存储在应用的构建输出中。
随后，这些翻译内容会被提供给用户。
如果未找到翻译，则会回退到原始内容。

请务必遵循[此处的部署指南](/docs/react/tutorials/quickdeploy)。

### 开发

在开发过程中，`<T>` 函数会按需翻译内容。
这对于快速原型设计，或查看应用在不同语言下的显示效果很有帮助。
请记得在环境变量中添加 Dev API key 以启用此行为。

加载期间，除非语言相近 (如 en-US 与 en-GB) ，否则 `<T>` 会返回 undefined；不过，你也可以通过渲染设置自定义此行为。
如果发生错误，`<T>` 会返回原始内容。

在开发环境中按需翻译时，你会注意到一定延迟。
这种延迟不会出现在生产构建中，因为所有内容都已提前翻译完成。

***

## 示例

### 基本用法

`<T>` 组件可以通过 `id` 及其子内容来翻译简单字符串。
请注意，`<T>` 组件必须在 [`<GTProvider>`](/docs/react/api/components/gtprovider) 内使用，才能访问翻译内容。

```jsx title="SimpleTranslation.jsx" copy
import { T } from 'gt-react';

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


### 使用变量

`<T>` 组件支持在翻译中使用变量来插入动态内容。

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

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


### 处理复数形式

`<T>` 组件也支持通过 `<Plural>` 组件处理复数形式。

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

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


### 限制

`<T>` 组件不会翻译动态生成的内容。

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

export default function DynamicContent({greeting}) {
    return (
        <T>
            {greeting} // 将会报错 // [!code highlight]
        </T>
    );
}
```

`<T>` 函数会翻译其子内容。

```jsx title="Example.jsx" copy
import { T } from 'gt-react';

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

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

export default function Example() {
    return (
        <T>
            <div><b>This is valid!</b></div> // 将被翻译 // [!code highlight]

            <ValidTranslation> // 将被翻译 // [!code highlight]
                Hello, world! // [!code highlight]
            </ValidTranslation> // [!code highlight]

            <InvalidTranslation /> // 不会被翻译
        </T>
    );
}
```

<Callout>
  **注意：** 一个很实用的经验法则是：文件中两个 `<T>` 之间 *原封不动* 写出的任何内容都会被翻译。
  如果有内容没有被翻译，你随时都可以再添加一个 `<T>` 来翻译它，不过不建议嵌套 `<T>` 组件。
</Callout>

***


## 注意事项

* `<T>` 组件用于翻译应用中的内容，是 `gt-react` 中实现本地化的主要方式。
* 使用 `<T>` 组件可以翻译纯文本或 JSX 结构，包括变量和复数形式。
* 确保 `<T>` 组件包裹在 [`<GTProvider>`](/docs/react/api/components/gtprovider) 中，以访问翻译上下文。

## 后续步骤

* 如需了解按需翻译、变量、上下文和复数形式处理等更高级功能，请参阅 [`<T>` 设计模式](/docs/react/guides/t) 文档。
* 如需翻译字符串，请参阅 [`useGT`](/docs/react/api/strings/use-gt) 文档。