大型项目

Lingo.dev CLI 针对拥有数十万翻译键、多语言和复杂内容结构的大型本地化项目，提供了性能优化和工作流策略。

对于内容量庞大的项目，CLI 提供并行处理和 CI/CD 集成，能够高效地大规模处理翻译任务。

并行处理

Lingo.dev CLI 通过并行 worker 同时处理多个翻译任务，从而加快大型项目的处理速度。

启用并行处理：

npx lingo.dev@latest run

这会将翻译任务分配到多个 worker 上，显著缩短大型项目的处理时间。

控制 worker 并发数：

npx lingo.dev@latest run --concurrency 16

默认并发数为 10 个 worker。更高的数值可以同时处理更多任务，但可能会触发 API 速率限制。

并行处理的工作原理

CLI 会创建一个 worker 池，并发处理翻译任务，同时防止文件损坏：

  1. 任务分发 — 按语言和文件将本地化拆分为单独任务
  2. worker 分配 — 通过负载均衡将任务分配给可用 worker
  3. 竞争条件预防 — 使用文件系统锁防止多个 worker 同时访问同一文件时发生冲突
  4. 进度跟踪 — 实时报告所有 worker 的进度

大型项目示例：

// Project with 50 files across 10 languages = 500 translation tasks
{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja", "zh", "ko", "pt", "it", "ru", "ar"]
  },
  "buckets": {
    "json": {
      "include": ["src/locales/[locale]/*.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

通过并行处理，这 500 个任务会分配给多个 worker，而不是顺序处理。

定向处理

对于大型项目，可以只处理特定部分，无需一次性全部处理：

处理特定语言：

npx lingo.dev@latest run --target-locale es --target-locale fr

处理特定文件类型：

npx lingo.dev@latest run --bucket json

处理特定文件：

npx lingo.dev@latest run --file components/header

这种选择性处理对于开发过程中的增量更新非常有用。

CI/CD 集成

大型项目可以通过使用 GitHub Actions 或其他 CI/CD 系统实现自动化翻译流程，从而受益。

GitHub Actions 工作流：

name: Lingo.dev Localization
on:
  workflow_dispatch:
permissions:
  contents: write
  pull-requests: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

该工作流在专用分支上处理翻译任务，使翻译工作与开发工作分离。

基于分支的工作流

对于大型项目，建议为翻译工作使用专用分支：

创建翻译分支：

git checkout main
git checkout -b localize/content-update
# Make content changes
git push -u origin localize/content-update

通过 GitHub Actions 触发翻译：

  1. 进入仓库的 Actions 标签页
  2. 选择 "Lingo.dev Localization" 工作流
  3. 在翻译分支上运行工作流
  4. 审核并合并已翻译内容

这种方法可以清晰地分离内容变更与翻译处理。

性能考量

系统资源：

  • 并行处理会占用更多 CPU 和内存
  • 在高并发设置下需监控系统性能
  • 云端 CI/CD 运行器可高效处理并行任务

API 速率限制：

  • 更高的并发可能触发速率限制
  • 建议先使用默认设置，根据性能再做调整
  • Lingo.dev Engine 会自动处理速率限制

文件系统：

  • 大型项目会生成大量翻译文件
  • 如有需要，可使用 .gitignore 忽略临时文件
  • 提交 i18n.lock 文件以进行内容追踪

项目组织

分桶管理：

{
  "buckets": {
    "app": {
      "include": ["src/locales/[locale].json"]
    },
    "marketing": {
      "include": ["marketing/[locale]/*.json"]
    },
    "docs": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

分桶可以针对不同内容区域进行有针对性的处理。

文件结构：

project/
  src/locales/           # Application content
  marketing/             # Marketing content
  docs/                  # Documentation
  i18n.json             # Configuration
  i18n.lock             # Content tracking

有条理的结构让大型项目易于管理，并支持有选择地处理内容。

扩展策略

增量处理：

  • 使用 lockfile 仅处理变更内容
  • 按需更新特定语言或分组
  • 结合 CI/CD 实现自动化增量更新

团队工作流：

  • 采用基于分支的翻译方式以便协作
  • 将内容变更与翻译工作分离
  • 在合并到生产环境前先审核翻译

资源优化：

  • 根据系统能力调整并发数
  • 针对高负载处理任务使用云端 runner
  • 监控处理时长并优化分组配置