@kununu/phraseapp-cli

CLI for syncing translations between your project and Phrase. It downloads locale JSON files from a Phrase project, and can also check your source for missing or unused translation keys.

Installation

npm install @kununu/phraseapp-cli --save

Usage

1. Add the npm script

In your package.json:

"scripts": {
  "update-translations": "node ./node_modules/@kununu/phraseapp-cli/index.js"
}

2. Set the required environment variables

The CLI authenticates against Phrase with two env vars (set them in your .env locally, or as CI secrets):

| Variable | Description | |---|---| | PHRASEAPP_PROJECT_ID | Your Phrase project ID | | PHRASEAPP_ACCESS_TOKEN | Phrase API access token |

Keep the access token out of version control.

3. Add the configuration file

Create a .phraseapp.json in your project root:

{
  "path": "YOUR_TRANSLATIONS_PATH",
  "locales": [
    {
      "locale_id": "de_DE",
      "tags": ["TAG1", "TAG2", "TAG3"]
    },
    {
      "locale_id": "de_AT",
      "tags": ["TAG1"],
      "fallback_locale_id": "de_DE"
    }
  ]
}

| Field | Required | Description | |---|---|---| | path | yes | Output directory for the downloaded locale files (e.g. src/translations/) | | branch | no | Phrase branch to download from; omit to use the default branch | | locales[].locale_id | yes | Phrase locale identifier (e.g. de_DE) | | locales[].tags | yes | Only keys with these tags are downloaded | | locales[].fallback_locale_id | no | Locale to fall back to for untranslated keys | | locales[].filePrefix | no | Prefix for the output filename (<prefix>-<locale_id>.json); use it to split a locale's translations across multiple files | | dynamicKeys | no | Keys built at runtime; declare them so check-translations doesn't report them as missing or unused |

4. Run it

npm run update-translations

One <path><filePrefix?>-<localeId>.json file is written per locale.

Checking translations

To check your source for missing or unused keys, see README_CHECK_TRANSLATIONS.md.

Documentation

• CONTRIBUTING.md — dev setup, linting, releases, PR process
• AGENTS.md — entry points, conventions, and constraints (for both humans and AI agents)

License

Apache-2.0 © kununu