Lingo.dev Docs

Appearance

Localizing Large Projects with GitHub Actions ​

Need to localize large projects efficiently? Here's how to use GitHub Actions with temporary branches for reliable, automated localization.

Quick Comparison ​

  • Local Workflow: Good for small projects, uses translation caching
  • GitHub Workflow: Better for large projects, uses automated CI/CD

Summary ​

In this workflow, you'll create a GitHub Action that runs on demand to translate your content. You'll make changes to a dedicated branch, manually trigger the translation process, and get translated files committed back to your branch automatically. This approach keeps translations separate from development until you're ready to merge them.

Setup Steps ​

1. Add the Workflow File to Main Branch ​

bash
git checkout main
git checkout -b setup/localization-workflow
mkdir -p .github/workflows

Create .github/workflows/localize.yml:

yaml
name: Lingo.dev Localization
on:
  workflow_dispatch:  # Manual trigger only
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 }}
bash
git add .github/workflows/localize.yml
git commit -m "ci: add localization workflow"
git push -u origin setup/localization-workflow

Create a PR and merge to main.

2. Add API Key to GitHub Secrets ​

  1. Go to repository → Settings → Secrets → Actions
  2. Add new secret: LINGODOTDEV_API_KEY (from ~/.lingodotdev/config.json)

3. Create and Use Localization Branch ​

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

4. Run the Workflow Manually ​

  1. Go to your GitHub repository
  2. Click on "Actions" tab
  3. Select "Lingo.dev Localization" from the workflows list
  4. Click "Run workflow" button
  5. Select the branch with your content changes (e.g., localize/content-update)
  6. Click "Run workflow" button

The action will:

  1. Translate your content
  2. Commit translations back to your branch

When done, create a PR to merge translations back to main.

Best Practices ​

  • Use clear branch naming (localize/feature-name)
  • Keep branches updated with main to avoid conflicts
  • Group content changes in meaningful batches
  • Always commit the i18n.lock file

For Very Large Projects ​

  • Split content into separate branches by sections
  • Use GitHub's Actions tab to monitor progress
  • Use local workflow with caching for quick iterations

For GitHub Actions details, see our complete guide.