SPS Phrase CLI

Ensures translation keys and values in your application are not out of sync with translations Phrase (formerly known as PhraseApp) project

Dependencies and prerequisites

Prior to using this CLI locally or as a plugin, it is expected you:

• Have access to Phrase
• Have access to a Phrase project; you'll need the project id.
• Have access to a Phrase user token that has access to the desired project.

Plugin is built using node:22

Published to NPM as @spscommerce/phrase-cli

Running SPS-Phrase-CLI Locally:

Install it globally with

npm install -g @spscommerce/phrase-cli

After you have it installed you can run any command with the following syntax:

sps-phrase-cli <command>

If you don't want to install it globally you can also use npx:

npx @spscommerce/phrase-cli <command>

The init command must be the first command run before any CLI steps are taken. This will do the initial setup in your repo. These translation files will live in your repo. Authentication will happen through your phraseApp project's ACCESS_KEY. This will need to be set as an environment variable in a .env file defined as:

PHRASE_ACCESS_KEY=tokenValue

In light of security concerns, make sure the .env file is not committed. Once this initial setup is complete you will not need to do it again.

Another way to use this command is to pass in the Phrase Access Key with the command: PHRASE_ACCESS_KEY=<ACCESS KEY HERE> npx @spscommerce/phrase-cli init -p <PROJECT ID HERE>

BDP Usage

AzP configuration

This repo can be configured as an AzP task. The following will need to be added to your azure-pipelines.yaml file:

Check Translation Types

- task: DockerCmd@7
  displayName: 'Phrase CLI'
  inputs:
    imageSource: PublicRepo
    dockerImage: 'node:22'
    dockerEnvVars: 'PHRASE_ACCESS_KEY=$(PhraseAccessKey),MERGE_TO_MAIN=$(variables.isDefaultBranch),PHRASE_TAG=$(Build.SourceVersion)'
    dockerCmd: 'npx @spscommerce/phrase-cli runCheck'
    mountSourceVolume: true
    mountCustomVolume: false

In your AzP project configuration, set a secret variable for PhraseAccessKey with the api key for your project. Then inject the secret into the env vars for the task as shown above. The plugin will not be able to communicate with your phrase project without this set! The MERGE_TO_MAIN env var controls which check should run. It will default to checkPR and no new keys will be pushed to Phrase. If you set it to true it will execute checkBuild instead and new keys will be pushed to Phrase. Only set this env var to true if you're merging to the default branch (usually main). The PHRASE_TAG env var allows you to tag the uploads to phrase. This should be set to the commit SHA, but you have freedom to change it.

Plugin API (NPM Commands)

The following CLI commands can be run with npx @spscommerce/phrase-cli <command> locally or integrate them into alternative CI systems if not using AzP.

Authentication will happen through the Phrase project's ACCESS_KEY. This will need to live as an environment variable in a .env file defined as:

PHRASE_ACCESS_KEY=tokenValue

init

CLI command to setup your i18n.json file and /public/locales->languageCode(for example 'en-US') directory with translation.json files at the root of your app directory. The projectID will need to be accompanied as a flag --project_id, -p

1. Creates a new i18n.json directory containing your Phrase projectId and all locale ID's:

{ "projectId": "ID", "en-US": "locale ID", ... }

2. Creates/updates the locales translation.json files with all verified translations from your Phrase project

3. Sets the default locale(en-US) Proofreading booleans to true for:

• Unverify new translations

• Unverify updated translations

4. Creates a Phrase Configuration file at the root of your repository

• The .phrase.yml file sets up the repo side of the Phrase repo sync. Additional setup is required in the Phrase app

checkPR

CLI command that will check for new keys and updated keys in your en-US->translation.json locale file.

1. New Keys will pass check as these will be pushed to en-US(Unverified) on verifyBuild step/command

2. Updated keys will cause a failure and stop the PR from proceeding until the conflict is resolved. Phrase will either need updating, or the update to the key will need to be removed for the PR to proceed to merge.

checkBuild

CLI command that will check for new keys and updated keys in your en-US->translation.json locale file.

1. New keys will be posted to your projects en-US locale as Unverified

2. Updated keys will cause a failure and stop the Build from proceeding until the conflict is resolved. Phrase will either need updating, or the update to the key will need to be removed for the Build to succeed.

updateTranslations

CLI command that will update your locales directory with all translations from phraseApp in their proper langauge coded folders

addPhraseConfig

CLI command that creates a Phrase Configuration file at the root of your repository. This command is part of the init command but can be used separately for apps that are already setup. The values are configured to work with file paths defined in the init command, make sure to review the values to make sure they are correct for your project setup.

Publishing

This plugin is published to NPM automatically when a PR is merged to the main branch

Useful links

• Application that is using the new system: https://github.com/SPSCommerce/cp-home
• Phrase Pipeline in cp-home: https://github.com/SPSCommerce/cp-home/blob/main/phrase-pipeline.yml
• Phrase sync scripts om cp home: https://github.com/SPSCommerce/cp-home/tree/main/scripts
• Usage of the localize function to setup the application: https://github.com/SPSCommerce/cp-home/blob/main/src/index.tsx#L54
• Usage of the t function to do a translation: https://github.com/SPSCommerce/cp-home/blob/main/src/App.tsx#L141
• i18n packages in design system (based off i18next): https://github.com/SPSCommerce/woodland/tree/main/packages/i18n
• What the i18n uses under the hood: https://react.i18next.com/