GitHub Actions

What is GitHub Actions?

GitHub Actions is a CI/CD and automation platform built into GitHub. It lets users define workflows in YAML files to build, test, and deploy code or automate tasks triggered by repository events.

What is Lingo.dev CI/CD?

Lingo.dev CI/CD is an AI-powered tool for localizing apps and content in CI/CD, ensuring translations never fall out of date. It's built on top of Lingo.dev CLI and available via the ci command:

npx lingo.dev@latest ci --help

About this guide

This guide explains how to set up Lingo.dev CI/CD with GitHub Actions and Lingo.dev Engine.

Step 1. Set up Lingo.dev CLI

To begin, follow the Quickstart for Lingo.dev CLI.

You should end up with:

• an API key for Lingo.dev
• an i18n.json file that configures the behavior of a translation pipeline
• the ability to translate content with npx lingo.dev@latest run

Step 2. Configure a repository secret

1. Navigate to Settings > Secrets and variables > Actions.
2. Click New repository secret.
3. In the Name field, enter LINGODOTDEV_API_KEY.
4. In the Secret field, enter a Lingo.dev API key.
5. Click Add secret.

Step 3. Choose a workflow

You can set up Lingo.dev CI/CD in different ways to support different workflows. These are some of the workflows that we recommend (and provide examples for):

• When content is merged into main, commit translations to main
• When content is merged into main, create a pull request from main
• When content is merged into a feature branch, commit translations to the branch
• When content is merged into a feature branch, create a pull request from the branch

But there is no "best" workflow. They all have trade-offs. If you're not sure where to begin, we recommend starting with with the first option. It's the simplest, most invisible workflow.

Step 4. Set up the workflow

1. In the repo, create a .github/workflows directory:

   mkdir -p .github/workflows
   

   Be sure to include the . at the start of .github.

2. In the .github/workflows directory, create a YAML file:

   touch .github/workflows/translate.yml
   

   The name of the file is not important.

3. Copy one of the example workflows into the file.

4. If the workflow creates pull requests:

   1. Navigate to Settings > Actions > General.
   2. Enable Allow GitHub Actions to create and approve pull requests.
   3. Click Save.

5. Commit and push the changes to the main branch:

   git add  .github/workflows/translate.yml
   git commit -m "feat: GitHub action for Lingo.dev"
   git push
   

(Optional) Step 5. Customize the workflow

Lingo.dev CI/CD has default values that, in most cases, don't need to be customized. You can, however, override them using the CLI flags of the ci command,

npx lingo.dev@latest ci --api-key "$LINGODOTDEV_API_KEY" --commit-message "My custom commit message!"

To view all of the available options, see CLI commands.

Example workflows

Commit to main

When content is merged into main, commit translations to main.

name: Translate

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Lingo.dev
        run: npx lingo.dev@latest ci --api-key "$LINGODOTDEV_API_KEY"
        env:
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}

View on GitHub

Pull request from main

When content is merged into main, create a pull request from main.

name: Translate

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Lingo.dev
        run: npx lingo.dev@latest ci --pull-request --api-key "$LINGODOTDEV_API_KEY"
        env:
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

View on GitHub

Commit to feature branch

When content is merged into a feature branch, commit translations to the branch.

name: Translate

on:
  push:
    branches-ignore: [main]

permissions:
  contents: write

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Lingo.dev (commit to non-main)
        run: npx lingo.dev@latest ci --api-key "$LINGODOTDEV_API_KEY"
        env:
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}

View on Github

Pull request from feature branch

When content is merged into a feature branch, create a pull request from the branch.

name: Translate

on:
  push:
    branches-ignore: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Lingo.dev
        run: npx lingo.dev@latest ci --pull-request --api-key "$LINGODOTDEV_API_KEY"
        env:
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

View on GitHub