Alpha
Lingo.dev Compiler 目前仍处于 alpha 阶段。功能尚不稳定，不建议用于生产环境，且 API 可能会在不同版本之间发生变动。
Lingo.dev Compiler 会在项目根目录下创建并维护一个 .lingo/ 目录，用于存放翻译元数据和缓存。理解这个目录结构，有助于你在版本控制中管理翻译、排查缺失翻译，并优化构建性能。
.lingo/ 目录#
编译器会在首次构建时自动创建该目录，其中包含构建流程所需的全部翻译元数据：
.lingo/
metadata.json # Translation cache and content hashes
locale-resolver.server.ts # Optional: custom server-side locale resolver
locale-resolver.client.ts # Optional: custom client-side locale resolvermetadata.json#
这是 .lingo/ 目录中的核心文件，存储内容包括：
- 内容哈希 - 每条可翻译字符串对应的稳定哈希标识符
- 缓存翻译 - 为每个语言环境组合生成的翻译结果
- 源文本快照 - 翻译生成时的源文本，用于检测变更
编译器会在每次构建开始时读取该文件。哈希匹配的字符串会直接复用缓存翻译；哈希已变更或缺失的字符串，则会发送给已配置的翻译提供方。
提交到版本控制
请务必将 .lingo/metadata.json 提交到代码仓库。生产构建在 cache-only 模式下只会从该文件读取翻译；如果没有提交，生产构建将直接失败。
.gitignore 注意事项#
不要把 .lingo/ 加入 .gitignore。这个目录应该纳入版本控制。以下是使用该编译器的项目中常见的 .gitignore 配置：
# Do NOT ignore .lingo/ - it contains translation cache
node_modules/
dist/
.envsourceRoot#
sourceRoot 选项用于指定编译器扫描哪个目录，以查找可翻译的 React 组件：
{
sourceRoot: "./app", // Next.js App Router
// or
sourceRoot: "src", // Vite + React
}编译器会递归扫描 sourceRoot 下所有 .tsx、.ts、.jsx 和 .js 文件，提取其中可翻译的 JSX 内容。该目录之外的文件不会被处理。
| sourceRoot 值 | 扫描范围 |
|---|---|
"./app" | 扫描 app/ 目录下的所有文件（Next.js 约定） |
"src" | 扫描 src/ 目录下的所有文件（Vite 约定） |
"." | 扫描项目根目录下的所有文件（适用于带共享包的 monorepo） |
更大的 sourceRoot 范围意味着要扫描更多文件，也会拉长构建时间。因此应尽量收窄范围。如果只有部分文件需要翻译，请改用 useDirective 选项。
使用“use i18n”的按需启用模式#
默认情况下，编译器会翻译 sourceRoot 中的所有 JSX 文本。若要切换为按需启用模式，请设置 useDirective: true：
{
useDirective: true,
}在按需启用模式下，只有以 'use i18n' 指令开头的文件才会被处理：
'use i18n';
export function Welcome() {
return <h1>Welcome to our app</h1>;
// This text IS translated
}未包含该指令的文件会被跳过：
export function InternalAdmin() {
return <h1>Admin Dashboard</h1>;
// This text is NOT translated
}何时使用按需启用模式#
| 场景 | 推荐模式 |
|---|---|
| 所有内容都需要翻译的小型应用 | 默认（useDirective: false） |
| 只有部分用户页面需要翻译的大型代码库 | 按需启用（useDirective: true） |
| 同时包含内部与外部共享组件的 monorepo | 按需启用（useDirective: true） |
| 渐进式接入——为现有应用添加 i18n | 按需启用（useDirective: true） |
lingoDir#
lingoDir 选项可用于更改元数据目录的位置：
{
lingoDir: ".lingo", // Default
// or
lingoDir: ".translations", // Custom location
}如果 .lingo/ 与项目中已有目录发生冲突，这个选项会很有帮助。
