Skip to main content
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:
  1. --api-token (flag)
  2. PRISMY_API_TOKEN environment variable
  3. 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

OptionDescription
--overrideReplace the file entirely; otherwise only new keys are merged
--no-auto-translateDo not auto-translate new keys to other languages
--wait-for-translationsWait for translations to finish before exiting (useful in CI)
--branchTarget branch (Prismy may create it from main)
--userAuthor username/email for the change
--tagsStatic 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

NameDescriptionSecret
PRISMY_API_TOKENAPI token from PrismyYes
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