CI/CD Integration

Integrate Tongues into your continuous integration and deployment pipelines

Overview

Tongues can be integrated into any CI/CD pipeline to automatically validate your i18n translation files. This ensures translation consistency and prevents missing keys from reaching production.

🚀Quick Start

Choose your platform below to get started with Tongues CI/CD integration:

⚙️GitHub Actions

Use our official GitHub Action or install manually

View GitHub Actions setup →

🦊GitLab CI

Configure GitLab CI pipelines with Docker or native installation

View GitLab CI setup →

🔷Bitbucket Pipelines

Set up Bitbucket Pipelines with caching and parallel checks

View Bitbucket setup →

🍵Gitea Actions

GitHub Actions-compatible workflows for Gitea

View Gitea setup →

GitHub Actions

Using the Official Action

The easiest way to integrate Tongues with GitHub Actions:

name: i18n Check

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  i18n-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Check translations
        uses: infobits-io/tongues@v1
        with:
          directory: './i18n'
          reference: 'en'
          strict: true
          check-empty: true
          check-extra: false

Manual Installation

Install Tongues manually for more control:

name: i18n Check

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  i18n-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.21'
      
      - name: Install Tongues
        run: go install github.com/infobits-io/tongues@latest
      
      - name: Check translations
        run: tongues -d ./i18n -r en --strict

Auto-fix Missing Keys

Automatically fix missing keys and commit changes:

name: i18n Auto-Fix

on:
  push:
    branches: [ develop ]

jobs:
  i18n-fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Check and fix translations
        uses: infobits-io/tongues@v1
        with:
          directory: './i18n'
          reference: 'en'
          fix: true
          clean: true
          placeholder: 'TODO: Translate'
      
      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: 'Auto-fix: Update translation files'
          file_pattern: 'i18n/*.json'

GitLab CI

Basic Configuration

Add to your .gitlab-ci.yml:

stages:
  - test

i18n-check:
  stage: test
  image: golang:1.21
  script:
    - go install github.com/infobits-io/tongues@latest
    - tongues -d ./i18n -r en --strict
  only:
    - merge_requests
    - main
    - develop

Using Docker

Use a pre-built Docker image:

stages:
  - test

i18n-check:
  stage: test
  image: infobits/tongues:latest
  script:
    - tongues -d ./i18n -r en --strict --check-empty
  only:
    - merge_requests
    - main

With Artifacts and Reports

Generate and save reports:

i18n-check:
  stage: test
  image: golang:1.21
  script:
    - go install github.com/infobits-io/tongues@latest
    - tongues -d ./i18n -r en --strict -f json > tongues-report.json
    - tongues -d ./i18n -r en --strict || true
  artifacts:
    reports:
      junit: tongues-report.json
    paths:
      - tongues-report.json
    expire_in: 1 week
  only:
    - merge_requests

Auto-fix in GitLab

Automatically fix and commit changes:

i18n-autofix:
  stage: test
  image: golang:1.21
  before_script:
    - apt-get update && apt-get install -y git
    - git config --global user.email "[email protected]"
    - git config --global user.name "GitLab CI"
  script:
    - go install github.com/infobits-io/tongues@latest
    - tongues -d ./i18n -r en --fix --clean --placeholder "TODO: Translate"
    - |
      if [[ -n $(git status --porcelain) ]]; then
        git add i18n/
        git commit -m "Auto-fix: Update translation files"
        git push https://oauth2:${GITLAB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git HEAD:${CI_COMMIT_REF_NAME}
      fi
  only:
    - develop

Bitbucket Pipelines

Basic Configuration

Add to your bitbucket-pipelines.yml:

image: golang:1.21

pipelines:
  default:
    - step:
        name: i18n Check
        script:
          - go install github.com/infobits-io/tongues@latest
          - tongues -d ./i18n -r en --strict
  
  pull-requests:
    '**':
      - step:
          name: Validate Translations
          script:
            - go install github.com/infobits-io/tongues@latest
            - tongues -d ./i18n -r en --strict --check-empty --extra

With Caching

Speed up builds by caching Go modules:

image: golang:1.21

definitions:
  caches:
    gopath: /go

pipelines:
  default:
    - step:
        name: i18n Check
        caches:
          - gopath
        script:
          - go install github.com/infobits-io/tongues@latest
          - tongues -d ./i18n -r en --strict

Parallel Checks

Run multiple language checks in parallel:

image: golang:1.21

pipelines:
  default:
    - parallel:
      - step:
          name: Check Spanish Translations
          script:
            - go install github.com/infobits-io/tongues@latest
            - tongues -d ./i18n -r en --strict --check-empty
      - step:
          name: Check French Translations
          script:
            - go install github.com/infobits-io/tongues@latest
            - tongues -d ./i18n -r en --strict --check-empty
      - step:
          name: Check German Translations
          script:
            - go install github.com/infobits-io/tongues@latest
            - tongues -d ./i18n -r en --strict --check-empty

With Auto-commit

Automatically fix and commit changes:

image: golang:1.21

pipelines:
  branches:
    develop:
      - step:
          name: Auto-fix Translations
          script:
            - go install github.com/infobits-io/tongues@latest
            - tongues -d ./i18n -r en --fix --clean --placeholder "TODO: Translate"
            - git add i18n/
            - git commit -m "Auto-fix: Update translation files" || true
            - git push

Gitea Actions

Basic Configuration

Create .gitea/workflows/i18n.yml:

name: i18n Check

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  i18n-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.21'
      
      - name: Install Tongues
        run: go install github.com/infobits-io/tongues@latest
      
      - name: Check translations
        run: tongues -d ./i18n -r en --strict

With Docker

Use Docker containers for isolation:

name: i18n Check

on:
  push:
    branches: [ main, develop ]
  pull_request:

jobs:
  i18n-check:
    runs-on: ubuntu-latest
    container:
      image: golang:1.21
    steps:
      - uses: actions/checkout@v3
      
      - name: Install and run Tongues
        run: |
          go install github.com/infobits-io/tongues@latest
          tongues -d ./i18n -r en --strict --check-empty

Matrix Testing

Test multiple language configurations:

name: i18n Matrix Check

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        reference: [en, es, fr]
        check: [strict, permissive]
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.21'
      
      - name: Install Tongues
        run: go install github.com/infobits-io/tongues@latest
      
      - name: Check translations
        run: |
          if [ "${{ matrix.check }}" = "strict" ]; then
            tongues -d ./i18n -r ${{ matrix.reference }} --strict --check-empty --extra
          else
            tongues -d ./i18n -r ${{ matrix.reference }}
          fi

Configuration Options

Command Line Options

Option	Description	Default
`-d, --dir`	Directory containing translation files	`./i18n`
`-r, --reference`	Reference language code	`en`
`--strict`	Exit with error code 1 if issues found	`false`
`--check-empty`	Check for empty values	`true`
`--extra`	Check for extra keys not in reference	`false`
`--fix`	Automatically fix missing keys	`false`
`--clean`	Clean and sort translation files	`false`
`--placeholder`	Add placeholder text for missing keys	`""`
`-f, --format`	Output format (text, json, yaml)	`text`

Exit Codes

0: No issues found
1: Issues found (when using --strict)
2: Error in execution

Environment Variables

Configure Tongues using environment variables:

export TONGUES_DIR="./translations"
export TONGUES_REFERENCE="en-US"
export TONGUES_STRICT="true"

Docker Image

Use the official Docker image in any CI/CD platform:

FROM infobits/tongues:latest
COPY ./i18n /app/i18n
RUN tongues -d /app/i18n -r en --strict

Best Practices

1. Run on Pull/Merge Requests

Always validate translations before merging code to prevent issues in production.

2. Use Strict Mode

Enable --strict to catch all issues and fail the build when problems are found.

3. Cache Dependencies

Cache Go modules or Docker images to speed up your CI/CD builds.

4. Generate Reports

Use JSON output format to generate detailed reports for tracking and analysis.

5. Auto-fix on Development

Consider automatically fixing missing keys on development branches while requiring manual review on main branches.

6. Pre-commit Hooks

For local development, add a pre-commit hook:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/infobits-io/tongues
    rev: v1.0.0
    hooks:
      - id: tongues
        args: ['-d', './i18n', '-r', 'en', '--strict']

Tip: Combine multiple checks (empty values, extra keys, descriptions) to ensure comprehensive validation of your translation files.

Troubleshooting

Permission Denied

Ensure the CI runner has read permissions for translation files
Check file permissions in the repository

Command Not Found

Verify Go is installed and in PATH
Use full path: $(go env GOPATH)/bin/tongues

Exit Code 1 Despite No Issues

Check if --strict is enabled
Review the output for warnings treated as errors

Auto-commit Fails

Verify CI has write permissions to the repository
Check authentication tokens are properly configured