项目结构

了解 .lingo/ 目录及其内容。

目录概览

首次运行编译器时，会在项目根目录下创建一个 .lingo/ 目录：

your-project/
├── .lingo/
│   ├── metadata.json
│   ├── locale-resolver.server.ts (optional)
│   └── locale-resolver.client.ts (optional)
├── src/
├── package.json
└── ...

metadata.json

包含所有翻译数据的核心文件。

结构

{
  "version": "1",
  "sourceLocale": "en",
  "targetLocales": ["es", "de", "fr"],
  "translations": {
    "abc123def456": {
      "source": "Welcome to our app",
      "context": {
        "file": "app/page.tsx",
        "line": 12,
        "component": "HomePage"
      },
      "locales": {
        "es": "Bienvenido a nuestra aplicación",
        "de": "Willkommen in unserer App",
        "fr": "Bienvenue dans notre application"
      },
      "metadata": {
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    }
  }
}

关键字段

Version：元数据格式版本。当前版本："1"

Source/Target Locales：已配置的语言环境

Translations：所有可翻译字符串的哈希映射：

  • Hash（abc123def456）：基于源文本和上下文的稳定标识符
  • source：原始英文文本
  • context：文本出现的位置（文件、行、组件）
  • locales：每个目标语言环境的翻译
  • metadata：翻译创建/更新的时间

哈希生成

哈希是确定性的：

  • 基于源文本和组件上下文
  • 相同文本在不同位置 = 不同哈希
  • 支持上下文相关的翻译

示例：

// app/home/page.tsx
<button>Submit</button> // Hash: abc123

// app/checkout/page.tsx
<button>Submit</button> // Hash: def456 (different context)

自定义语言环境解析器

用于自定义语言环境检测和持久化的可选文件。

locale-resolver.server.ts

服务端语言环境检测（仅限 Next.js）：

// .lingo/locale-resolver.server.ts
export async function getServerLocale(): Promise<string> {
  // Your custom logic
  return "en";
}

locale-resolver.client.ts

客户端语言环境检测与持久化：

// .lingo/locale-resolver.client.ts
export function getClientLocale(): string {
  // Detect locale
  return "en";
}

export function persistLocale(locale: string): void {
  // Save locale preference
}

如果这些文件不存在，编译器将采用默认的基于 cookie 的行为。

详情请参见 自定义语言环境解析器。

版本控制

是否应该提交 .lingo/?

应该提交。 .lingo/ 目录应纳入版本控制：

需要提交：

  • metadata.json — 包含所有翻译内容
  • 自定义语言环境解析器（如有创建）

不需要提交：

  • 无——.lingo/ 中的所有文件都应提交

为什么要提交翻译文件？

  1. 版本控制 — 跟踪翻译内容与代码的变更
  2. 团队协作 — 团队成员间共享翻译内容
  3. CI/CD — 生产环境构建使用已提交的翻译
  4. 审计追踪 — 了解翻译变更的时间和原因

Git 集成

将 .lingo/ 添加到你的仓库：

git add .lingo/
git commit -m "chore: update translations"
git push

当发生以下情况时，编译器会自动更新 .lingo/metadata.json：

  • 新增可翻译文本
  • 修改现有文本
  • 生成翻译内容

请定期提交这些更新。

文件大小

metadata.json 会随着你的应用增长：

  • 小型应用（50 条字符串）：约 10 KB
  • 中型应用（500 条字符串）：约 100 KB
  • 大型应用（5000 条字符串）：约 1 MB

这在版本控制中是正常且可接受的。

清理

移除未使用的翻译

随着时间推移，你可能会积累未使用的翻译（来自已删除的组件）。

手动清理：

  1. 在代码库中搜索哈希值
  2. 如果未找到，则从 metadata.json 中删除

自动清理（即将推出）：

npx @lingo.dev/compiler clean

这将自动移除未使用的翻译内容。

重置翻译

要从头重新生成所有翻译：

# Backup current translations
cp .lingo/metadata.json .lingo/metadata.backup.json

# Delete metadata
rm .lingo/metadata.json

# Regenerate
npm run dev # or npm run build

迁移

从旧编译器迁移

旧编译器使用了不同的文件结构：

旧版：

lingo/
├── dictionary.js
├── meta.json
└── [locale]/
    └── *.json

新版：

.lingo/
└── metadata.json

迁移过程不自动化。详情请参见 迁移指南。

检查翻译

在编辑器中查看

在你的编辑器中打开 .lingo/metadata.json：

{
  "translations": {
    "abc123": {
      "source": "Welcome",
      "locales": {
        "es": "Bienvenido"
      }
    }
  }
}

搜索翻译

通过源文本查找翻译：

grep -r "Welcome" .lingo/metadata.json

通过哈希查找

grep -r "abc123" .lingo/metadata.json

美化输出

cat .lingo/metadata.json | jq '.'

常见问题

我可以手动编辑 metadata.json 吗？ 可以，但不推荐。请使用 data-lingo-override，这样更安全，并且可以在源码中进行版本控制。

如果我删除 metadata.json 会怎样？ 编译器会在下次构建时重新生成它。所有翻译将会被重新生成（会消耗 API 配额）。

我可以将 .lingo/ 移动到其他目录吗？ 可以。请通过 lingoDir 选项进行配置：

{
  lingoDir: "translations"
}

metadata.json 是否包含敏感数据？ 不会。它只包含源文本和翻译内容——不包含 API 密钥或机密信息。

我可以合并来自多个分支的 metadata.json 吗？ 可以。Git 会自动处理合并。冲突很少见（哈希值是唯一的）。

如果两个分支添加了相同的翻译怎么办？ Git 会自动合并。如果哈希值不同（上下文不同），则会保留两者。

后续步骤