构建模式

@lingo.dev/compiler 支持两种构建模式，用于控制翻译生成的时机和方式。

模式概览

模式适用场景API 调用行为
translate开发、CI是使用已配置的 LLM 生成缺失翻译
cache-only生产构建否仅从 .lingo/metadata.json 读取缓存翻译

translate 模式

用途： 在构建期间按需生成翻译。

{
  buildMode: "translate"
}

行为：

  • 扫描代码中的可翻译文本
  • 检查 .lingo/metadata.json 是否已有翻译
  • 通过已配置的 LLM 提供方生成缺失翻译
  • 用新翻译更新 .lingo/metadata.json
  • 若翻译生成失败则构建失败

适用场景：

  • 本地开发（配合 usePseudotranslator: true 使用）
  • CI/CD 流水线（配合真实 LLM 提供方）
  • 初始设置及翻译生成

要求：

  • 已配置提供方的有效 API 密钥（或启用伪翻译器）
  • 可连接 LLM 提供方的网络环境

cache-only 模式

用途： 仅使用预生成的翻译进行构建。

{
  buildMode: "cache-only"
}

行为：

  • 从 .lingo/metadata.json 读取翻译
  • 不进行任何 API 调用
  • 若任一语言缺少翻译则构建失败
  • 构建速度快且结果可复现

适用场景：

  • 生产构建
  • 无 API 密钥的部署
  • 网络受限环境

要求：

  • .lingo/metadata.json 包含所有语言的翻译
  • 在 CI 或开发阶段预生成翻译

推荐工作流

1. 本地开发

使用伪翻译器可获得即时反馈：

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: true,
  }
}

优势：

  • 即时伪翻译
  • 无 API 成本
  • 精确查看哪些内容被翻译
  • 可测试 UI 在不同文本长度下的表现

2. CI/CD 流水线

在 CI 中生成真实翻译：

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}

在 CI 中设置：

# GitHub Actions example
- name: Install dependencies
  run: pnpm install

- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: pnpm run build

- name: Commit translations
  run: |
    git config user.name "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

优势：

  • 每次部署时生成真实翻译
  • 提交到版本控制
  • 生产构建无需 API key

3. 生产构建

仅使用缓存翻译：

{
  buildMode: "cache-only",
}

优势：

  • 无需 API key
  • 构建速度快
  • 结果确定性高——相同输入始终产生相同输出
  • 无外部网络依赖

环境变量覆盖

通过环境变量覆盖构建模式：

# Force cache-only mode
LINGO_BUILD_MODE=cache-only npm run build

# Force translate mode
LINGO_BUILD_MODE=translate npm run build

这对于需要强制使用 cache-only 而不修改配置的部署环境非常有用。

处理缺失翻译

在 translate 模式下

如果翻译失败：

Error: Failed to generate translation for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - Provider: lingo.dev
  - Reason: API key invalid

**解决方案：**修复 API key，重新运行构建。

在 cache-only 模式下

如果缺少翻译：

Error: Missing translations for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - File: app/page.tsx:12

Run with buildMode: "translate" to generate missing translations.

**解决方案：**使用 translate 模式运行构建以生成缺失翻译，然后提交 .lingo/。

增量翻译

编译器使用内容哈希来判断哪些内容需要翻译：

  1. 每个可翻译字符串都会生成一个稳定的哈希值
  2. 哈希值基于源文本和上下文生成
  3. 如果哈希值已存在于 .lingo/metadata.json 中，则复用翻译
  4. 只有新增或变更的文本才会触发重新翻译

**结果：**每段文本只需支付一次翻译费用，后续构建会复用缓存的翻译。

CI 配置示例

GitHub Actions

name: Generate Translations

on:
  push:
    branches: [main]
  pull_request:

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - name: Install dependencies
        run: pnpm install

      - name: Generate translations
        env:
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
        run: pnpm run build

      - name: Commit translations
        if: github.event_name == 'push'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add .lingo/
          git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
          git push

GitLab CI

stages:
  - translate

generate-translations:
  stage: translate
  script:
    - pnpm install
    - pnpm run build
    - git config user.name "GitLab CI"
    - git config user.email "[email protected]"
    - git add .lingo/
    - git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
    - git push origin HEAD:$CI_COMMIT_REF_NAME
  only:
    - main

常见问题

生产环境需要 API key 吗？ 不需要。生产环境请使用 buildMode: "cache-only"。翻译会在 CI 阶段预生成。

如果我忘记在 CI 中生成翻译怎么办？ 生产构建会失败，并清晰列出缺失的翻译。请在 CI 中生成翻译、提交并重新部署。

可以在生产环境使用 translate 模式吗？ 可以，但不推荐。这样会导致构建结果不确定，并且生产环境需要 API key。建议在 CI 阶段生成翻译。

如何在本地测试仅缓存模式？

  1. 使用 translate 模式生成翻译
  2. 切换到 cache-only 模式
  3. 运行构建——应能成功使用缓存翻译

如果源文本发生变化怎么办？ 哈希值会变化，因此会生成新的翻译（在 translate 模式下）。旧翻译会保留在 .lingo/metadata.json 中以供历史查阅。

需要将 .lingo/ 提交到 git 吗？ 需要。.lingo/ 目录应纳入版本控制，其中包含翻译缓存。

下一步