# gt-next: General Translation Next.js SDK: T
URL: https://generaltranslation.com/zh/docs/next/api/components/t.mdx
---
title: T
description: T 组件 API 参考
---

## 概述

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

```jsx
<T>
    Today, I went to
    {" the store"}
    <p>
        to <b>buy</b> some <i>groceries</i>.
    </p>
</T>
```

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

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

***


## 参考

### 属性

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

### 说明

| 属性         | 说明                              |
| ---------- | ------------------------------- |
| `children` | 要翻译的内容，可包含纯文本或 JSX 结构。          |
| `id`       | 翻译字符串的可选唯一标识符。如果未提供，则会在构建时自动生成。 |
| `context`  | 用于优化翻译的附加上下文，有助于消除歧义。           |

### 返回值

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

***

## 行为

### 生产环境

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

生成后，翻译会根据你的配置以以下两种方式之一存储： (1) 存储在 CDN 中，或 (2) 存储在应用的构建输出中。
之后，这些翻译后的内容会提供给用户。
如果未找到翻译，则会回退到原始内容。

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

### 开发环境

在开发期间，`<T>` 函数会按需翻译内容。
这有助于你在原型设计阶段预览应用在不同语言下的显示效果。
请记得在环境变量中添加 Dev API key，以启用此行为。

加载过程中，`<T>` 会返回 undefined，除非语言较为接近 (例如 en-US 和 en-GB) ；不过，你也可以通过渲染设置自定义这一行为。
如果发生错误，`<T>` 会返回原始内容。

在开发环境中按需翻译时，你会看到一定延迟。
在生产构建中，除非内容被明确设为按需翻译，
即使用 [`<Tx>`](/docs/next/api/components/tx) 或 [`tx`](/docs/next/api/strings/tx)，否则不会出现这种延迟。

***

## 示例

### 基本用法

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

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

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


### 使用变量

你可以使用 `<Var>` 组件将其子内容标记为变量。
这样可以标记不应被翻译的内容。
通常，`<Var>` 组件用于包裹动态内容。

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

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


### 复数形式

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

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

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


### 限制

`<T>` 组件无法翻译动态内容。

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

export default function DynamicContent({greeting}) {
    return (
        <T>
            {greeting} {/* 将会报错 */}
        </T>
    );
}
```

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

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

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

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

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

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

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

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

***


## 注意事项

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

## 后续步骤

* 如需按需翻译，请参阅 [`<Tx>`](/docs/next/api/components/tx) 组件。
* 如需使用更高级的功能，请参阅 [`<T>` 参考文档](/docs/next/guides/t)。
* 如需翻译字符串，请参阅 [`tx`](/docs/next/api/strings/tx)、[`getGT`](/docs/next/api/strings/get-gt) 和 [`useGT`](/docs/next/api/strings/use-gt)。