GitHub

Lingo.dev 支持以两种方式在 GitHub 上运行持续本地化：托管的 GitHub App，以及在 GitHub Actions 作业中运行 @lingo.dev/cli。

该选哪一种？

建议先使用 GitHub App——它在服务端运行，可自动响应 push 和拉取请求，无需 runner、无需 API 密钥 secret，也不用管理 lockfile。只有当你希望本地化与其他 CI 步骤一起在自有流水线中运行时，再选择 GitHub Actions。

GitHub App（推荐）#

GitHub App 是在 GitHub 上实现持续本地化最简单的方式。只需安装一次并指定引擎，它就会自动响应每一次 push 和拉取请求。

前往 GitHub App 页面安装应用，并授予它访问仓库的权限。
在仓库根目录提交一个 .lingo/config.json，说明你的 buckets 和 locales，并包含应用应使用引擎的 engineId。文件格式请参见 Configuration。
执行 push。应用会在服务端对变更内容进行本地化，并将结果提交回仓库（或创建拉取请求），自动保持 .lingo/lock.json 为最新状态。

由于应用运行在服务端，因此无需维护 runner、无需存储 LINGO_API_KEY secret，也无需执行任何 lockfile 命令。

GitHub Actions#

如果你希望在自有流水线中运行本地化，请在作业中安装 CLI 并运行 lingo push，然后用你现有的工具提交结果或创建拉取请求。

将你的 API 密钥保存为名为 LINGO_API_KEY 的仓库 secret（Settings > Secrets and variables > Actions）。CLI 会从环境变量中读取它。

提交到当前分支#

创建 .github/workflows/localize.yml：

yaml

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Lingo.dev CLI
        run: npm install -g @lingo.dev/cli
      - name: Localize
        run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Commit translations
        run: |
          git config user.name "Lingo.dev"
          git config user.email "support@lingo.dev"
          git add .
          git diff --staged --quiet || git commit -m "feat: update translations"
          git push

这会对变更内容执行本地化，并在每次 push 时将结果直接提交到当前分支。

创建拉取请求#

如果你希望通过代码审查合并翻译，而不是直接提交，可以先将结果推送到一个分支，再创建拉取请求。此示例使用 GitHub CLI，它已预装在 GitHub 托管的 runner 上：

yaml

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Lingo.dev CLI
        run: npm install -g @lingo.dev/cli
      - name: Localize
        run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Open pull request
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git config user.name "Lingo.dev"
          git config user.email "support@lingo.dev"
          branch="lingo/translations-${{ github.run_id }}"
          git checkout -b "$branch"
          git add .
          git diff --staged --quiet && exit 0
          git commit -m "feat: update translations"
          git push origin "$branch"
          gh pr create --fill --base "${{ github.ref_name }}" --head "$branch"

如果使用基于 PR 的工作流，请启用 Settings > Actions > General > Allow GitHub Actions to create and approve pull requests。

同一个作业也适用于功能分支——修改 on.push.branches 过滤条件（例如 branches-ignore: [main]）即可控制在哪些分支上运行本地化。

下一步#

GitHub App

托管式替代方案——无需 runner、secret 或 lockfile

Lingo.dev 支持以两种方式在 GitHub 上运行持续本地化：托管的 GitHub App，以及在 GitHub Actions 作业中运行 @lingo.dev/cli。

该选哪一种？

GitHub App（推荐）#

GitHub App 是在 GitHub 上实现持续本地化最简单的方式。只需安装一次并指定引擎，它就会自动响应每一次 push 和拉取请求。

前往 GitHub App 页面安装应用，并授予它访问仓库的权限。
在仓库根目录提交一个 .lingo/config.json，说明你的 buckets 和 locales，并包含应用应使用引擎的 engineId。文件格式请参见 Configuration。
执行 push。应用会在服务端对变更内容进行本地化，并将结果提交回仓库（或创建拉取请求），自动保持 .lingo/lock.json 为最新状态。

由于应用运行在服务端，因此无需维护 runner、无需存储 LINGO_API_KEY secret，也无需执行任何 lockfile 命令。

GitHub Actions#

如果你希望在自有流水线中运行本地化，请在作业中安装 CLI 并运行 lingo push，然后用你现有的工具提交结果或创建拉取请求。

将你的 API 密钥保存为名为 LINGO_API_KEY 的仓库 secret（Settings > Secrets and variables > Actions）。CLI 会从环境变量中读取它。

提交到当前分支#

创建 .github/workflows/localize.yml：

yaml

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Lingo.dev CLI
        run: npm install -g @lingo.dev/cli
      - name: Localize
        run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Commit translations
        run: |
          git config user.name "Lingo.dev"
          git config user.email "support@lingo.dev"
          git add .
          git diff --staged --quiet || git commit -m "feat: update translations"
          git push

这会对变更内容执行本地化，并在每次 push 时将结果直接提交到当前分支。

创建拉取请求#

yaml

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Lingo.dev CLI
        run: npm install -g @lingo.dev/cli
      - name: Localize
        run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Open pull request
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git config user.name "Lingo.dev"
          git config user.email "support@lingo.dev"
          branch="lingo/translations-${{ github.run_id }}"
          git checkout -b "$branch"
          git add .
          git diff --staged --quiet && exit 0
          git commit -m "feat: update translations"
          git push origin "$branch"
          gh pr create --fill --base "${{ github.ref_name }}" --head "$branch"

如果使用基于 PR 的工作流，请启用 Settings > Actions > General > Allow GitHub Actions to create and approve pull requests。

同一个作业也适用于功能分支——修改 on.push.branches 过滤条件（例如 branches-ignore: [main]）即可控制在哪些分支上运行本地化。

下一步#

GitHub App

托管式替代方案——无需 runner、secret 或 lockfile