# react-native: T 组件
URL: https://generaltranslation.com/zh/docs/react-native/guides/t.mdx
---
title: T 组件
description: 如何使用 T 组件实现 JSX 组件的国际化
---

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

[`<T>` 组件](/docs/react-native/api/components/t)是 React Native 应用中实现 JSX 内容国际化的核心工具。它会包裹你的 JSX 元素，并根据用户的区域设置自动完成翻译。

<Callout>
  **提示：** 启用[自动 JSX 注入](/docs/cli/features/auto-jsx-injection)后，编译器可以在构建时自动将你的 JSX 包裹在翻译组件中。
  在大多数情况下，你可能不需要手动添加 `<T>`。不过，当你需要更细粒度的控制时，例如设置特定的 `id` 或 `context`，手动使用 `<T>` 仍然很有用。
</Callout>

## 快速开始

将任意静态 JSX 内容用 [`<T>`](/docs/react-native/api/components/t) 包裹起来即可完成转换：

```jsx
import { T } from 'gt-react-native';

// 之前
function Greeting() {
  return <p>Hello, world!</p>;
}

// 之后
function Greeting() {
  return <T><p>Hello, world!</p></T>;
}
```

对于 [`<T>`](/docs/react-native/api/components/t) 中的动态内容，请使用 [变量组件](/docs/react-native/guides/variables) 和 [分支组件](/docs/react-native/guides/branches)。


## 基本用法

[`<T>` 组件](/docs/react-native/api/components/t)可接受任意 JSX 内容作为子元素：

```jsx
// 简单文本
<T>Welcome to our app</T>

// HTML 元素
<T><h1>Page Title</h1></T>

// 复杂嵌套 JSX
<T>
  <div className="alert">
    <span>Important:</span> Please read carefully.
  </div>
</T>
```


## 配置选项

### 添加 context

为有歧义的术语提供翻译上下文：

```jsx
<T context="notification popup, not bread">
  Click the toast to dismiss
</T>
```


## 何时使用 T

仅在**静态内容**中使用 [`<T>`](/docs/react-native/api/components/t)：

```jsx
// ✅ 静态内容可正常使用
<T>
  <button>Click here</button>
  <h1>Welcome to our site</h1>
</T>

// ❌ 动态内容会出错
<T>
  <p>Hello {username}</p>
  <p>Today is {new Date()}</p>
</T>

// ✅ 对动态内容使用变量组件
<T>
  <p>Hello <Var>{username}</Var></p>
</T>
```

<Callout>
  变量组件和分支组件专为在 [`<T>`](/docs/react-native/api/components/t) 内使用而设计，用于处理动态内容。
  详情请参阅 [变量组件](/docs/react-native/guides/variables) 和 [分支组件](/docs/react-native/guides/branches) 指南。
</Callout>


## 示例

### 简单元素

```jsx
// 基本文本
<T>Hello, world!</T>

// 带文本的按钮
<T><Button>Submit Form</Button></T>

// 带样式的标题
<T><h1 className="text-2xl font-bold">Welcome</h1></T>
```


### 复杂组件

```jsx
// 导航菜单
<T>
  <nav className="navbar">
    <a href="/about">About Us</a>
    <a href="/contact">Contact</a>
  </nav>
</T>

// 警告消息
<T>
  <div className="alert alert-warning">
    <AlertIcon className="w-5 h-5" />
    <span>Your session expires in 5 minutes</span>
  </div>
</T>
```


### 使用变量

你可以使用变量组件进行本地化格式化。

```jsx
// 将静态文本与动态值结合使用
<T>
  <p>Welcome back, <Var>{user.name}</Var>!</p>
  <p>You have <Num>{user.friends.length}</Num> friends online</p>
  <p>Your birthday is <DateTime>{user.birthday}</DateTime></p>
  <p>Your balance is <Currency>{user.balance}</Currency></p>
</T>
```

<Callout>
  在[变量组件指南](/docs/react-native/guides/variables)中进一步了解[`<Var>` 组件](/docs/react-native/api/components/var)。
</Callout>


## 生产环境配置

### 构建流程

将翻译集成到构建流程中：

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && <...YOUR_BUILD_COMMAND...>"
  }
}
```


### 开发环境与生产环境的行为差异

* **开发环境**：使用开发 API 密钥时，组件会在渲染时按需翻译。你在开发过程中可以看到实时翻译效果。
* **生产环境**：所有翻译都会在构建阶段预先生成，并在应用上线后生效。

在环境变量中设置开发 API 密钥，即可在开发期间启用实时翻译。你可以在仪表板中的 [API Keys](https://dash.generaltranslation.com/en-US/project/api-keys) 页面创建一个。

### 隐私注意事项

[`<T>`](/docs/react-native/api/components/t) 组件中的内容会发送到 GT API 进行翻译。对于敏感数据，请使用 [变量组件](/docs/react-native/guides/variables) 将敏感信息保留在本地：

```jsx
// 安全 - 敏感数据保留在本地
<T>
  Welcome back, <Var>{username}</Var>
</T>
```


## 单个 `<T>` 应包裹多少内容

应包裹**逻辑上的内容块**——也就是译者通常会作为一个整体阅读并翻译的内容。

```jsx
// ✅ 好 — 将相关内容包裹在一起，为译者提供完整的上下文
<T>
  <h1>Welcome to Our Platform</h1>
  <p>Get started in minutes with our simple setup process.</p>
</T>

// ✅ 好 — 每张卡片是独立的翻译单元
{features.map((feature) => (
  <T key={feature.id}>
    <h3><Var>{feature.title}</Var></h3>
    <p><Var>{feature.description}</Var></p>
  </T>
))}

// ❌ 粒度过细 — 翻译被碎片化，丢失上下文
<T><h1>Welcome to Our Platform</h1></T>
<T><p>Get started in minutes with our simple setup process.</p></T>

// ❌ 粒度过粗 — 将整个页面包裹在一起会增加维护难度
<T>
  {/* ...数百行 JSX... */}
</T>
```

**经验法则：**如果文本在视觉上或语义上有关联，就把它们包在同一个 `<T>` 中。只有当内容确实彼此独立时才拆分 (例如页眉和页脚) 。

把更多内容包在单个 `<T>` 中，能为译者提供更充分的上下文，从而产出更自然的译文——有些语言会重组句子结构，或者需要参照附近的内容。


## 常见问题

### 组件边界

[`<T>`](/docs/react-native/api/components/t) 仅翻译其直接子元素，不会翻译其他组件内部的内容：

```jsx
// ❌ 错误 - 组件内部的内容不会被翻译
function MyComponent() {
  return <p>这不会被翻译</p>;
}

<T>
  <h1>这会被翻译</h1>
  <MyComponent /> {/* 内部内容不会被翻译 */}
</T>

// ✅ 正确 - 单独包裹每个组件
function MyComponent() {
  return <T><p>这会被翻译</p></T>;
}

<T><h1>这会被翻译</h1></T>
<MyComponent />
```


### 嵌套 T 组件

```jsx
// ❌ 不要嵌套 <T> 组件
<T>
  <T>Hello world</T> {/* 不要这样做 */}
</T>
```


### 动态内容错误

如果 [`<T>`](/docs/react-native/api/components/t) 中包含动态内容，CLI 会报错。请使用变量组件包裹动态值：

```jsx
// ❌ 错误 - 动态内容会导致报错
<T><p>Hello {username}</p></T>

// ✅ 正确 - 使用变量组件
<T><p>Hello <Var>{username}</Var></p></T>
```

<Callout>
  如需处理动态值，请参阅[变量组件指南](/docs/react-native/guides/variables)；如需处理条件内容，请参阅[分支组件指南](/docs/react-native/guides/branches)。
</Callout>


## 后续步骤

<Callout>
  **查看实际效果：**查看 [`<T>` 组件基础示例应用](https://github.com/gt-examples/t-component-basics)，体验可运行的演示 — [实时预览](https://t-component-basics.generaltranslation.dev)。
</Callout>

* [变量组件指南](/docs/react-native/guides/variables) - 处理 JSX 翻译中的动态内容
* [分支组件指南](/docs/react-native/guides/branches) - 在翻译中添加条件逻辑