<T> 组件
如何使用 <T> 组件为 JSX 内容实现国际化
<T> 组件 是在 Next.js 应用中为 JSX 内容实现国际化的主要工具。它会包裹你的 JSX 元素，并根据用户的 locale 自动进行翻译。
快速开始
将任意静态 JSX 内容用 <T> 包裹以进行转换：
import { T } from 'gt-next';
// 之前
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 && <...您的构建命令...>"
}
}开发环境 vs 生产环境的行为
- 开发环境：使用 Dev API key 时，组件渲染会按需触发翻译；你将在开发过程中实时看到翻译结果。
- 生产环境：所有翻译都会在构建阶段预先生成，并在应用上线后可见。
在开发环境中将 Dev API key 配置为环境变量，以启用开发期间的实时翻译。你可以在 dashboard 的 API Keys 中创建一个。
隐私注意事项
<T> 组件中的内容会发送至 GT API 进行翻译。对于敏感数据，请使用 Variable Components 以将隐私信息保留在本地：
// 安全 - 敏感数据保持本地
<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 组件指南 - 在 JSX 翻译中处理动态内容
- 分支组件指南 - 为你的翻译添加条件逻辑
这份指南怎么样？