<T> 组件
如何使用 <T> 组件为 JSX 组件实现国际化
<T> 组件 是在 React 应用中为 JSX 内容实现国际化的主要工具。它用于包裹 JSX 元素，并会根据用户的 locale 自动完成翻译。
快速开始
将任意静态 JSX 内容用 <T> 包裹以进行转换：
import { T } from 'gt-react';
// 之前
function Greeting() {
return <p>Hello, world!</p>;
}
// 之后
function Greeting() {
return <T><p>Hello, world!</p></T>;
}在 <T> 中处理动态内容时，请使用 Variable 组件 和 Branching 组件。
基本用法
<T> 组件 可将任意 JSX 内容作为 children 传入：
// 简单文本
<T>欢迎使用我们的应用</T>
// HTML 元素
<T><h1>页面标题</h1></T>
// 复杂嵌套 JSX
<T>
<div className="alert">
<span>重要提示：</span>请仔细阅读。
</div>
</T>配置选项
添加上下文
为含义模糊的术语提供翻译上下文：
<T context="notification popup, not bread">
点击提示框以关闭
</T>设置翻译 ID
使用显式 ID，确保翻译一致：
<T id="welcome-message">
欢迎回来，用户！
</T>何时使用 <T>
将 <T> 用于仅限静态内容的场景：
// ✅ 静态内容可以正常工作
<T><button>点击这里</button></T>
<T><h1>欢迎来到我们的网站</h1></T>
// ❌ 动态内容会出现问题
<T><p>你好 {username}</p></T>
<T><p>今天是 {new Date()}</p></T>
// ✅ 对动态内容使用 Variable 组件
<T>
<p>你好 <Var>{username}</Var></p>
</T>Variable 和 Branching 组件旨在配合用于动态内容的 <T> 一起使用。详见 Variable Components 与 Branching Components 指南。
示例
基本元素
// 基本文本
<T>你好，世界！</T>
// 带文本的按钮
<T><Button>提交表单</Button></T>
// 带样式的标题
<T><h1 className="text-2xl font-bold">欢迎</h1></T>复杂组件
// 导航菜单
<T>
<nav className="navbar">
<a href="/about">关于我们</a>
<a href="/contact">联系我们</a>
</nav>
</T>
// 提示消息
<T>
<div className="alert alert-warning">
<AlertIcon className="w-5 h-5" />
<span>您的会话将在 5 分钟后过期</span>
</div>
</T>搭配变量
// 将静态文本与动态值结合
<T>
<p>欢迎回来，<Var>{user.name}</Var>！</p>
</T>
// 包含混合内容的表单
<T>
<label>
邮箱：<input type="email" placeholder="请输入您的邮箱" />
</label>
</T>生产环境配置
构建流程
将翻译加入到你的构建管道中：
{
"scripts": {
"build": "npx gtx-cli translate && <...您的构建命令...>"
}
}开发环境与生产环境的行为差异
- 开发环境：使用 Dev API key 时，组件在渲染时会按需触发翻译。你在开发过程中可以实时看到翻译效果。
- 生产环境：所有翻译都会在构建阶段预先生成，并在应用上线后呈现。
在本地环境中配置你的开发用 API key，以在开发期间启用实时翻译。你可以在 Dashboard 的 API Keys 下创建一个。
隐私注意事项
<T> 组件中的内容会发送至 GT API 进行翻译。对于敏感数据，请使用变量组件以将私人信息保留在本地：
// 安全 - 敏感数据保持本地
<T>
欢迎回来，<Var>{username}</Var>
</T>常见问题
组件边界
<T> 只会翻译其直接子级内容，而不会翻译其他组件内部的内容：
// ❌ 错误 - 组件内部的内容不会被翻译
function MyComponent() {
return <p>这不会被翻译</p>;
}
<T>
<h1>这将被翻译</h1>
<MyComponent /> {/* 内部内容不会被翻译 */}
</T>
// ✅ 正确 - 单独包装每个组件
function MyComponent() {
return <T><p>这将被翻译</p></T>;
}
<T><h1>这将被翻译</h1></T>
<MyComponent />嵌套 <T> 组件
// ❌ 不要嵌套 <T> 组件
<T>
<T>Hello world</T> {/* 不要这样做 */}
</T>动态内容错误
CLI 会对 <T> 中的动态内容抛出错误。请使用 Variable 组件包裹动态值：
// ❌ 错误 - 动态内容会出错
<T><p>Hello {username}</p></T>
// ✅ 正确 - 使用 Variable 组件
<T><p>Hello <Var>{username}</Var></p></T>请参阅Variable 组件指南以处理动态值，以及Branching 组件指南以处理条件内容。
后续步骤
- Variable Components 指南 - 在 JSX 翻译中处理动态内容
- Branching Components 指南 - 为你的翻译添加条件逻辑
这份指南怎么样？