Configure Lokalise CI/CD integration with GitHub Actions and automated sync.
Use when setting up automated translation sync, configuring CI pipelines,
or integrating Lokalise into your build process.
Trigger with phrases like "lokalise CI", "lokalise GitHub Actions",
"lokalise automated sync", "CI lokalise", "lokalise pipeline".
Automate the full translation lifecycle through GitHub Actions: upload source strings when code is pushed, download translations during builds, block PRs with missing translations, and manage branch-based translation workflows that mirror your Git branching strategy. The goal is zero manual translation file management — developers write code, translators work in Lokalise, and CI keeps everything in sync.
Prerequisites
Lokalise project with Project ID (Settings > General > Project ID)
Lokalise API token with read/write permissions (Profile > API Tokens), stored as LOKALISE_API_TOKEN GitHub secret
LOKALISE_PROJECT_ID stored as GitHub secret (or variable)
Lokalise CLI v2 (lokalise2) — installed in CI via curl -sfL https://raw.githubusercontent.com/nicktomlin/lokalise-cli-2-install/master/install.sh | sh
Source locale files committed to the repository (e.g., src/locales/en.json)
Instructions
Step 1: Upload Source Strings on Push
Create .github/workflows/lokalise-upload.yml to push source strings to Lokalise whenever the default locale file changes on :
main
name: Upload translations to Lokalise
on:
push:
branches: [main]
paths:
- 'src/locales/en.json' # Adjust to your source locale path
jobs:
upload:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Lokalise CLI
run: |
curl -sfL https://raw.githubusercontent.com/lokalise/lokalise-cli-2-go/master/install.sh | sh
sudo mv ./bin/lokalise2 /usr/local/bin/lokalise2
- name: Upload source strings
run: |
lokalise2 file upload \
--token "${{ secrets.LOKALISE_API_TOKEN }}" \
--project-id "${{ secrets.LOKALISE_PROJECT_ID }}" \
--file "src/locales/en.json" \
--lang-iso "en" \
--replace-modified \
--include-path \
--distinguish-by-file \
--poll \
--poll-timeout 120s
# --replace-modified updates existing keys with new values
# --poll waits for the async upload to complete before exiting
Step 2: Download Translations During Build
Create .github/workflows/lokalise-build.yml or add a step to your existing build workflow:
name: Build with translations
on:
push:
branches: [main, staging]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Lokalise CLI
run: |
curl -sfL https://raw.githubusercontent.com/lokalise/lokalise-cli-2-go/master/install.sh | sh
sudo mv ./bin/lokalise2 /usr/local/bin/lokalise2
- name: Download translations
run: |
lokalise2 file download \
--token "${{ secrets.LOKALISE_API_TOKEN }}" \
--project-id "${{ secrets.LOKALISE_PROJECT_ID }}" \
--format json \
--original-filenames=true \
--directory-prefix="" \
--export-empty-as=base \
--unzip-to "src/locales/"
# --export-empty-as=base falls back to source language for untranslated keys
# --original-filenames preserves the file structure from Lokalise
- name: Build application
run: npm run build
Step 3: PR Check for Missing Translations
Add a workflow that comments on PRs when new translation keys lack translations in required locales:
name: Translation coverage check
on:
pull_request:
paths:
- 'src/locales/**'
jobs:
check-translations:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check translation coverage
run: |
#!/bin/bash
set -euo pipefail
REQUIRED_LOCALES=("en" "de" "fr" "es" "ja")
SOURCE_FILE="src/locales/en.json"
MISSING=0
REPORT=""
source_keys=$(jq -r '[paths(scalars)] | map(join(".")) | .[]' "$SOURCE_FILE" | sort)
for locale in "${REQUIRED_LOCALES[@]}"; do
locale_file="src/locales/${locale}.json"
if [[ ! -f "$locale_file" ]]; then
REPORT+="- **${locale}**: File missing entirely\n"
MISSING=1
continue
fi
locale_keys=$(jq -r '[paths(scalars)] | map(join(".")) | .[]' "$locale_file" | sort)
missing_keys=$(comm -23 <(echo "$source_keys") <(echo "$locale_keys"))
if [[ -n "$missing_keys" ]]; then
count=$(echo "$missing_keys" | wc -l)
REPORT+="- **${locale}**: ${count} missing keys\n"
MISSING=1
fi
done
if [[ $MISSING -eq 1 ]]; then
echo "## Translation Coverage Report" >> "$GITHUB_STEP_SUMMARY"
echo "" >> "$GITHUB_STEP_SUMMARY"
echo -e "$REPORT" >> "$GITHUB_STEP_SUMMARY"
echo "" >> "$GITHUB_STEP_SUMMARY"
echo "Run \`lokalise2 file download\` to pull latest translations." >> "$GITHUB_STEP_SUMMARY"
exit 1
fi
echo "All locales have complete translation coverage." >> "$GITHUB_STEP_SUMMARY"
Step 4: Integration Tests for Key Coverage
Add a test that validates translation files have all required keys at build time:
