GitLab CI/CD - Lingo.dev CI/CD

What is GitLab CI/CD?

GitLab CI/CD is a continuous integration and deployment platform built into GitLab. It lets users define pipelines 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 GitLab CI/CD 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. Get an access token

In GitLab CI/CD, an access token is required to perform certain actions within a pipeline.

There are two types of access tokens:

Either can be used, but only personal access tokens are available to non-paying users of GitLab.

Personal access tokens

On the left sidebar, select your avatar.
Select Edit profile.
On the left sidebar, select Access tokens.
Select Add new token.
In Token name, enter a name for the token (e.g., "Lingo.dev").
Enable the following scopes.
- api
- read_repository
- write_repository
Select Create personal access token.

Project access tokens

Navigate to a project in GitLab.
Select Settings > Access tokens.
Select Add new token.
In Token name, enter a name.
Select a role for the token.
Enable the following scopes.
- api
- read_repository
- write_repository
Select Create project access token.

Step 2. Configure CI/CD variables

In GitLab, CI/CD variables allow pipelines to access sensitive values. To use Lingo.dev in GitLab CI/CD, both the Lingo.dev API key and GitLab access token must be available as variables.

Warning: By default, CI/CD variables are only available on protected branches. If you're not using protected branches, disable the Protect variable option when creating variables.

Lingo.dev API key

Navigate to Settings > CI/CD.
Expand the Variables section.
Click Add variable.
In the Key field, enter LINGODOTDEV_API_KEY.
In the Value field, enter a Lingo.dev API key.
Select Visibility > Masked.
Click Add variable.

GitLab access token

Navigate to Settings > CI/CD.
Expand the Variables section.
Click Add variable.
In the Key field, enter GL_TOKEN.
In the Value field, enter a GitLab access token.
Select Visibility > Masked.
Click Add variable.

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 merge 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 merge 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 pipeline

In the repo root, create a .gitlab-ci.yml file:
```
touch .gitlab-ci.yml
```
Copy one of the example pipelines into the file.

Commit and push the changes to the main branch:

git add .gitlab-ci.yml
git commit -m "feat: GitLab CI pipeline for Lingo.dev"
git push

(Optional) Step 5. Customize the pipeline

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 pipelines

Commit to main

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

image:
  name: lingodotdev/ci-action:latest
  entrypoint: [""]

stages: [translate]

translate:
  stage: translate
  script:
    - npx lingo.dev@latest ci --api-key "$LINGODOTDEV_API_KEY"
  only:
    - main

Merge request from main

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

image:
  name: lingodotdev/ci-action:latest
  entrypoint: [""]

stages: [translate]

translate:
  stage: translate
  script:
    - npx lingo.dev@latest ci --pull-request --api-key "$LINGODOTDEV_API_KEY"
  only:
    - main

Commit to feature branch

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

image:
  name: lingodotdev/ci-action:latest
  entrypoint: [""]

stages: [translate]

translate:
  stage: translate
  script:
    - npx lingo.dev@latest ci --api-key "$LINGODOTDEV_API_KEY"
  only:
    - branches
  except:
    - main

Merge request from feature branch

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

image:
  name: lingodotdev/ci-action:latest
  entrypoint: [""]

stages: [translate]

translate:
  stage: translate
  script:
    - npx lingo.dev@latest ci --pull-request --api-key "$LINGODOTDEV_API_KEY"
  except:
    - main