CI/CD Integration

Three steps cover the full translation lifecycle in CI: push source strings on merge, audit key parity on pull requests, and pull finished translations before your build.

Add your token as a secret

Add a STRINGHIVE_TOKEN secret to your repository. Scope it to Write for push jobs and Read for pull and audit. Consider using separate secrets so read-only jobs can't accidentally modify your source strings.

GitHub Actions

Push on merge

When a branch lands on main, push new or updated source strings to Stringhive. --conflict-strategy keep leaves existing translations intact — only new strings start empty.

name: Stringhive Sync

on:
  push:
    branches: [main]

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

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

      - name: Install dependencies
        run: npm ci

      - name: Push source strings
        run: npx stringhive push my-app --conflict-strategy keep
        env:
          STRINGHIVE_TOKEN: ${{ secrets.STRINGHIVE_TOKEN }}

Audit on pull requests

Check key parity before a PR merges. --scan-source also scans your component files for t('key') and $t('key') calls, catching runtime translation misses before they reach production.

name: Translation Audit

on:
  pull_request:
    branches: [main]

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

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

      - run: npm ci

      - name: Audit translation keys
        run: npx stringhive audit my-app --fail-on-missing --scan-source 'src/**/*.{ts,tsx,vue}'
        env:
          STRINGHIVE_TOKEN: ${{ secrets.STRINGHIVE_TOKEN }}

--fail-on-missing exits with code 1 if any local keys are absent from the hive. Drop it if you want the report without blocking the PR.

Pull before build

Pull translations as an early step so your bundle always includes the latest strings:

- name: Pull translations
  run: npx stringhive pull my-app
  env:
    STRINGHIVE_TOKEN: ${{ secrets.STRINGHIVE_TOKEN }}

- name: Build
  run: npm run build

Using package.json scripts

Define the commands once so CI and local usage stay in sync:

{
  "scripts": {
    "i18n:push": "stringhive push --conflict-strategy keep",
    "i18n:pull": "stringhive pull",
    "i18n:audit": "stringhive audit --fail-on-missing --scan-source 'src/**/*.{ts,tsx,vue}'"
  }
}

Then reference them in your workflow steps:

- run: npm run i18n:push
  env:
    STRINGHIVE_TOKEN: ${{ secrets.STRINGHIVE_TOKEN }}

Complete workflow

A single file that pushes on merge and audits on PRs:

name: Stringhive

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

jobs:
  push-strings:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npm run i18n:push
        env:
          STRINGHIVE_TOKEN: ${{ secrets.STRINGHIVE_TOKEN }}

  audit:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npm run i18n:audit
        env:
          STRINGHIVE_TOKEN: ${{ secrets.STRINGHIVE_TOKEN }}

GitLab CI

stringhive-push:
  image: node:22
  stage: deploy
  only:
    - main
  script:
    - npm ci
    - npx stringhive push my-app --conflict-strategy keep
  variables:
    STRINGHIVE_TOKEN: $STRINGHIVE_TOKEN

stringhive-audit:
  image: node:22
  stage: test
  only:
    - merge_requests
  script:
    - npm ci
    - npx stringhive audit my-app --fail-on-missing
  variables:
    STRINGHIVE_TOKEN: $STRINGHIVE_TOKEN

Set STRINGHIVE_TOKEN in Settings > CI/CD > Variables with the Masked flag.

Token scoping

Use a Write token for the push job and a separate Read token for pull and audit. A compromised Read token can't modify your source strings.