GitHub Actions Integration
Quick Setup
Add the Lingo.dev GitHub Action to your workflow with this simple configuration:
yaml
- uses: lingodotdev/lingo.dev@main
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
Required Permissions
Your workflow must have these permissions:
yaml
permissions:
contents: write
pull-requests: write # Only if using pull request mode
Authentication Setup
- Store your Lingo.dev API key as a repository secret named
LINGODOTDEV_API_KEY
- For pull request mode, provide the GitHub token:
yaml
- uses: lingodotdev/lingo.dev@main
env:
GH_TOKEN: ${{ github.token }}
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
pull-request: true
- Enable "Allow GitHub Actions to create and approve pull requests" in repository Settings → Actions → General
Complete Workflow Example
This example automatically translates new content whenever you push to feature branches:
yaml
name: Lingo.dev i18n
on:
push:
branches:
- feat/*
permissions:
contents: write
pull-requests: write
jobs:
i18n:
name: Run i18n
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: lingodotdev/lingo.dev@main
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
Security for Fork-Based Workflows
When working with external forks, use this selective checkout approach to maintain security:
yaml
jobs:
i18n:
name: Run i18n
runs-on: ubuntu-latest
permissions:
actions: write
contents: write
pull-requests: write
steps:
- uses: actions/checkout@v4
- run: find apps/web/public/static/locales/** -name "common.json" | xargs git checkout ${{ github.event.pull_request.head.sha }} --
shell: bash
- uses: lingodotdev/lingo.dev@main
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
This approach:
- Only checks out translation files from the fork
- Prevents exposure of sensitive code
- Maintains necessary write permissions
How the Action Works
The GitHub Action follows this process:
- Runs the translation engine to process new or changed content
- Stages all translation changes
- Either commits directly to your branch or creates a pull request
- Handles conflicts automatically through rebasing
Customization Options
Parameter | Description | Default |
---|---|---|
version | Specify CLI version to use | latest |
pull-request | Create PR instead of direct push | false |
pull-request-title | Custom PR title | feat: update translations via @lingodotdev |
commit-message | Custom commit message | feat: update translations via @lingodotdev |
working-directory | Custom working directory | . |
process-own-commits | Process this action's commits | false |
Example with Custom Options
yaml
- uses: lingodotdev/lingo.dev@main
env:
GH_TOKEN: ${{ github.token }}
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
pull-request: true
pull-request-title: "feat: update translations"
commit-message: "feat: update translations"
working-directory: "apps/web"
process-own-commits: true
Note: When using process-own-commits: true
, add persist-credentials: false
to your checkout step.
Versioning
You can specify which version of the Lingo.dev CLI to use with the version
parameter:
yaml
- uses: lingodotdev/lingo.dev@main
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
version: "1.2.3" # Pin to specific version
In most cases, it's not recommended to pin versions, as that would prevent receiving updates and improvements to the CLI.