构建模式

Alpha

Lingo.dev Compiler 目前处于 alpha 阶段，尚不稳定，不建议在生产环境中使用，且 API 可能会在不同版本之间发生变化。

Lingo.dev Compiler 支持两种构建模式，用于控制是否在构建过程中生成新的翻译。想要搭建可靠的开发、CI 和生产流水线，理解这两种模式至关重要。

两种模式#

模式	行为	适用场景
`"translate"`	调用已配置的 LLM 提供商生成缺失翻译，并复用已有缓存翻译。	开发和 CI——适用于新增或变更文本需要翻译时。
`"cache-only"`	仅使用 `.lingo/metadata.json` 中的翻译。只要有任何翻译缺失，构建就会失败。	生产构建——输出结果可预测，且不会调用外部 API。

translate mode 如何工作#

在 translate 模式下，Compiler 会将每个可翻译字符串与 .lingo/metadata.json 进行比对。如果缓存翻译已存在且源文本未发生变化，就直接使用缓存版本；如果字符串是新增或已修改，Compiler 会调用已配置的翻译提供商生成翻译，并更新缓存。

{
  buildMode: "translate",
}

这是默认模式，既支持 pseudotranslator（用于即时生成伪翻译），也支持真实的 LLM 提供商。

cache-only mode 如何工作#

在 cache-only 模式下，Compiler 只会从 .lingo/metadata.json 读取翻译，不会发起任何 LLM 调用。如果缓存中缺少任意可翻译字符串，构建将失败，并在错误信息中列出缺失的字符串。

.lingo/metadata.json 必须提交到版本控制中。生产环境下使用 cache-only 模式进行构建时，依赖该文件存在于仓库中，而不只是本地生成。

{
  buildMode: "cache-only",
}

这种模式可生成可预测的构建结果——相同的源代码和缓存，始终会得到相同的输出。同时，它也消除了生产构建期间对外部 API 的依赖。

环境变量覆盖#

LINGO_BUILD_MODE 环境变量会覆盖 buildMode 配置项，让你能够在不同环境中共用同一份配置文件：

bash

# Override in any environment
LINGO_BUILD_MODE=cache-only npm run build

环境变量的优先级高于配置文件中的值。

CI 示例#

yaml

# .github/workflows/translate.yml
name: Generate Translations
on:
  push:
    branches: [main]

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

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - run: npm run build
        env:
          LINGO_BUILD_MODE: translate
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}

      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: update translations"
          file_pattern: ".lingo/metadata.json"

务必将 .lingo/metadata.json 提交到版本控制中。生产构建在 cache-only 模式下依赖这个文件；如果文件缺失或内容不完整，构建就会失败。

下一步#

翻译提供商

为 translate mode 配置 LLM 提供商

开发工具

pseudotranslator 与翻译服务器