CI/CD Integration

Run PolyCLI automatically in GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines, Vercel, and Netlify.

PolyCLI is a plain Node.js binary with no daemon, no interactive prompts, and no watch mode. It reads buildtranslator.json, translates only changed strings, writes files to disk, and exits with code 0 on success or 1 on failure. This makes it a first-class citizen in any CI/CD pipeline that can run Node.js.

Prerequisites for all platforms

Add your PolyCLI API key as a secret named POLYCLI_API_KEY in your CI/CD settings.
Commit buildtranslator.json to your repository.
Commit .translator-lock.json (and .polycli-md-cache.json if using Markdown). Without these, every run re-translates everything from scratch.

GitHub Actions

Add a workflow step before your build step. The translated files are committed back to the branch or simply passed to the subsequent build step (if your build consumes them).

.github/workflows/translate.yml

name: Translate

on:
  push:
    branches: [main]
    paths:
      - 'locales/en.json'   # only run when source locale changes
      - 'docs/en/**'        # or when source Markdown changes

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Translate
        run: npx @polycli/cli run
        env:
          POLYCLI_API_KEY: ${{ secrets.POLYCLI_API_KEY }}

      - name: Commit translated files
        run: |
          git config user.name "PolyCLI Bot"
          git config user.email "bot@polycli.io"
          git add locales/ docs/ .translator-lock.json .polycli-md-cache.json
          git diff --staged --quiet || git commit -m "chore: update translations"
          git push

GitLab CI

.gitlab-ci.yml

translate:
  image: node:20-alpine
  stage: build
  only:
    changes:
      - locales/en.json
      - docs/en/**
  script:
    - npx @polycli/cli run
  artifacts:
    paths:
      - locales/
      - docs/
      - .translator-lock.json
      - .polycli-md-cache.json

Set POLYCLI_API_KEY under Settings → CI/CD → Variables in your GitLab project.

CircleCI

.circleci/config.yml

version: 2.1

jobs:
  translate:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Translate
          command: npx @polycli/cli run

workflows:
  build:
    jobs:
      - translate

Set POLYCLI_API_KEY under Project Settings → Environment Variables in CircleCI.

Bitbucket Pipelines

bitbucket-pipelines.yml

pipelines:
  branches:
    main:
      - step:
          name: Translate
          image: node:20-alpine
          script:
            - npx @polycli/cli run
          artifacts:
            - locales/**
            - docs/**
            - .translator-lock.json
            - .polycli-md-cache.json

Set POLYCLI_API_KEY under Repository Settings → Repository variables in Bitbucket.

Vercel

Run PolyCLI as part of your Vercel build command. Translated files are generated before next build (or your framework's build command) runs, so they are always up to date in production.

package.json (scripts)

{
  "scripts": {
    "build": "npx @polycli/cli run && next build"
  }
}

Or set it directly in Vercel → Project Settings → Build & Output Settings → Build Command:

bash

npx @polycli/cli run && next build

Add POLYCLI_API_KEY under Project Settings → Environment Variables.

Netlify

Set the build command in netlify.toml or in the Netlify UI. PolyCLI runs before your site build, producing up-to-date translated files.

netlify.toml

[build]
  command = "npx @polycli/cli run && npm run build"
  publish = ".next"

[build.environment]
  NODE_VERSION = "20"

Add POLYCLI_API_KEY under Site Configuration → Environment Variables in Netlify.

All examples use npx @polycli/cli — no global install required. npx always fetches the latest published version automatically.

Always commit .translator-lock.json and .polycli-md-cache.json. Without them, PolyCLI has no delta baseline and will re-translate every string on every CI run, consuming all your credits.