Scale Your Localization with GitHub Actions

Automate translations for large projects using GitHub Actions and dedicated branches - a powerful approach for teams managing extensive content across multiple languages.

Choose Your Workflow

Approach	Best For	Key Benefit
Local Workflow	Small projects, quick iterations	Uses translation caching for reliability
GitHub Workflow	Large projects, team collaboration	Automated CI/CD with clear separation of concerns

The GitHub Workflow Advantage

This approach lets you:

• Separate translation work from development
• Trigger translations on demand
• Automatically receive translated files as commits
• Review translations before merging to production

Implementation Guide

1. Set Up the Workflow File

First, add the workflow configuration to your main branch:

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

Create .github/workflows/localize.yml:

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 }}

Commit and create a PR:

git add .github/workflows/localize.yml
git commit -m "ci: add localization workflow"
git push -u origin setup/localization-workflow

Merge this PR to your main branch.

2. Configure Authentication

1. Navigate to your repository's Settings → Secrets → Actions
2. Add a new secret named LINGODOTDEV_API_KEY
3. Use the value from your local config file (~/.lingodotdev/config.json)

3. Create a Translation Branch

When you have content to translate:

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

4. Trigger the Translation Process

1. Go to your GitHub repository
2. Navigate to the Actions tab
3. Select Lingo.dev Localization
4. Click Run workflow
5. Select your content branch (e.g., localize/content-update)
6. Click Run workflow to start the process

The action automatically:

• Processes all translatable content
• Commits the translated files to your branch
• Updates the lockfile for tracking

When complete, create a PR to merge your translations into the main branch.

Best Practices

• Branch Naming: Use descriptive prefixes like localize/feature-name
• Sync Regularly: Keep translation branches updated with main
• Batch Logically: Group related content changes together
• Version Control: Always commit the i18n.lock file with your changes

Enterprise-Scale Tips

For very large localization projects:

• Divide and Conquer: Split content across multiple branches by section
• Monitor Progress: Use GitHub's Actions tab to track translation jobs
• Hybrid Approach: Use local workflow with caching for quick iterations between major releases

For complete GitHub Actions configuration options, see our detailed guide.