Prismy Documentation

Use prismy push and prismy pull when you use Prismy Hosted without native GitHub/GitLab. You upload source files to Prismy and download translated files (locally or in CI).

Using GitHub or GitLab with Prismy? Use prismy generate instead.

Authentication

The CLI looks for an API token in this order:

--api-token (flag)
PRISMY_API_TOKEN environment variable
Stored key from prismy auth (only when not in CI)

In CI, you must set --api-token or PRISMY_API_TOKEN; the CLI will not prompt. Get your token from Prismy Settings.

prismy push

Upload a local translation file to Prismy.

prismy push <filePath> --repo-id <repoId> --language <lang> --bundle-name <bundle>

Required: --repo-id, --language, --bundle-name Example:

prismy push ./locales/en/common.json \
  --repo-id 25060c5dfa \
  --language en-US \
  --bundle-name common

Push options

Option	Description
`--override`	Replace the file entirely; otherwise only new keys are merged
`--no-auto-translate`	Do not auto-translate new keys to other languages
`--wait-for-translations`	Wait for translations to finish before exiting (useful in CI)
`--branch`	Target branch (Prismy may create it from main)
`--user`	Author username/email for the change
`--tags`	Static tags for new/edited keys

File formats

JSON, .arb, .xcstrings: Parsed and sent as structured JSON.
Other (.yaml, .po, .resx, .xml, .ts, .js): Sent as raw content with format metadata.

prismy pull

Download a translation file from Prismy. The CLI writes JSON to the path you give.

prismy pull <filePath> --repo-id <repoId> --language <lang> --bundle-name <bundle>

Example:

prismy pull ./locales/en/common.json \
  --repo-id 25060c5dfa \
  --language en-US \
  --bundle-name common

Options: --repo-id, --language, --bundle-name (required); --branch (default: main); --api-token. The file is created or overwritten. If the file does not exist on Prismy, you get an empty object {}. For non-JSON formats (e.g. YAML, PO), use the CDN URL from your Prismy Hosted configuration.

CI setup

Use a pipeline to push the source file, wait for translations, then pull translated files.

Secret / variable

Name	Description	Secret
`PRISMY_API_TOKEN`	API token from Prismy	Yes

Optional: PRISMY_REPO_ID, PRISMY_BUNDLE_NAME (or pass --repo-id / --bundle-name in the script).

GitHub Actions

.github/workflows/prismy-sync.yml

name: Prismy sync

on:
  push:
    branches: [main]
  workflow_dispatch:

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

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install Prismy CLI
        run: npm install -g prismy-cli

      - name: Push source and wait for translations
        env:
          PRISMY_API_TOKEN: ${{ secrets.PRISMY_API_TOKEN }}
        run: |
          prismy push src/i18n/en.json \
            --repo-id "${{ vars.PRISMY_REPO_ID }}" \
            --language en-US \
            --bundle-name "${{ vars.PRISMY_BUNDLE_NAME }}" \
            --wait-for-translations

      - name: Pull translated files
        env:
          PRISMY_API_TOKEN: ${{ secrets.PRISMY_API_TOKEN }}
        run: |
          prismy pull src/i18n/en.json --repo-id "${{ vars.PRISMY_REPO_ID }}" --language en-US --bundle-name "${{ vars.PRISMY_BUNDLE_NAME }}"
          prismy pull src/i18n/es.json --repo-id "${{ vars.PRISMY_REPO_ID }}" --language es-ES --bundle-name "${{ vars.PRISMY_BUNDLE_NAME }}"
          prismy pull src/i18n/fr.json --repo-id "${{ vars.PRISMY_REPO_ID }}" --language fr-FR --bundle-name "${{ vars.PRISMY_BUNDLE_NAME }}"

      - name: Commit and push changes
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add src/i18n/
          git diff --staged --quiet || git commit -m "chore(i18n): sync translations from Prismy"
          git push

Add PRISMY_API_TOKEN in Settings → Secrets and variables → Actions. Optionally add variables PRISMY_REPO_ID and PRISMY_BUNDLE_NAME, or hardcode them in the YAML.

GitLab CI

Add a job (or merge into .gitlab-ci.yml):

prismy-sync:
  image: node:20
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"
    - if: $CI_PIPELINE_SOURCE == "web"
  variables:
    PRISMY_REPO_ID: "YOUR_REPO_ID"
    PRISMY_BUNDLE_NAME: "common"
  before_script:
    - npm install -g prismy-cli
  script:
    - prismy push src/i18n/en.json --repo-id "${PRISMY_REPO_ID}" --language en-US --bundle-name "${PRISMY_BUNDLE_NAME}" --wait-for-translations
    - prismy pull src/i18n/en.json --repo-id "${PRISMY_REPO_ID}" --language en-US --bundle-name "${PRISMY_BUNDLE_NAME}"
    - prismy pull src/i18n/es.json --repo-id "${PRISMY_REPO_ID}" --language es-ES --bundle-name "${PRISMY_BUNDLE_NAME}"
    - prismy pull src/i18n/fr.json --repo-id "${PRISMY_REPO_ID}" --language fr-FR --bundle-name "${PRISMY_BUNDLE_NAME}"
    - |
      git config user.name "GitLab CI"
      git config user.email "ci@gitlab"
      git add src/i18n/
      git diff --staged --quiet || git commit -m "chore(i18n): sync translations from Prismy"
      git push "https://oauth2:${CI_JOB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" HEAD:${CI_COMMIT_REF_NAME}

Add PRISMY_API_TOKEN in Settings → CI/CD → Variables (masked). Adjust git push if you use a deploy token or project access token.

Bitbucket Pipelines

Use a step that installs the CLI, runs prismy push with --wait-for-translations, then prismy pull for each language, and finally commits and pushes. Set PRISMY_API_TOKEN, PRISMY_REPO_ID, and PRISMY_BUNDLE_NAME as repository variables.

Run only when i18n changes

GitHub Actions: Under on.push, add paths: ["src/i18n/en.json"].
GitLab CI: In rules, use changes: ["src/i18n/en.json"].

Adjust paths and branch names to match your project. Reference: prismy-cli — PRISMY_PUSH_PULL_CI, CI_SETUP

Get Started

Plug to your codebase

AI configuration

Technical doc & features

API Reference

Prismy Hosted — push & pull

Authentication

prismy push

Push options

File formats

prismy pull

CI setup

Secret / variable

GitHub Actions

GitLab CI

Bitbucket Pipelines

Run only when i18n changes

​Authentication

​prismy push

​Push options

​File formats

​prismy pull

​CI setup

​Secret / variable

​GitHub Actions

​GitLab CI

​Bitbucket Pipelines

​Run only when i18n changes

Authentication

prismy push

Push options

File formats

prismy pull

CI setup

Secret / variable

GitHub Actions

GitLab CI

Bitbucket Pipelines

Run only when i18n changes