Phrase Strings CLI workflows with Hyperlocalise

Use hyperlocalise phrase to push source files, wait for uploads, and pull translations from Phrase Strings using supported .phrase.yml settings. Phrase Strings workflows share one executable with local AI translation, checks, and other TMS commands in the all-in-one localization CLI. This command family targets Phrase Strings. It does not establish compatibility with Phrase TMS projects or every product in the Phrase suite.

Start with a Phrase Strings push and pull

Install Hyperlocalise, set PHRASE_ACCESS_TOKEN in your shell or CI secret manager, and prepare .phrase.yml with source and target mappings. Replace a literal access_token secret in the config with $PHRASE_ACCESS_TOKEN. Use a project where your token can upload and download files.

hyperlocalise phrase config validate --config .phrase.yml
hyperlocalise phrase push --config .phrase.yml --wait
# Translate the target locales in Phrase Strings before pulling.
hyperlocalise phrase pull --config .phrase.yml

Push waits for the upload to finish processing, not for translations to be completed. Pull writes the configured target files. Review the output before committing. Follow reuse an existing .phrase.yml for a complete configuration and compatibility checks.

Hyperlocalise vs the official Phrase Strings CLI

Hyperlocalise is a Phrase Strings CLI alternative for supported file workflows. Both use push and pull with .phrase.yml; Hyperlocalise adds other TMS commands and local translation under one executable. Supported configuration is a subset, so validate behavior as well as syntax when migrating.

Task	Official Phrase Strings CLI	Hyperlocalise
Push configured files	`phrase push`	`hyperlocalise phrase push`
Wait for processing	`phrase push --wait`	`hyperlocalise phrase push --wait`
Pull configured files	`phrase pull`	`hyperlocalise phrase pull`
List project locales	`phrase locales list`	`hyperlocalise phrase locales list`
Full API commands and automatic cleanup	Consult the official command/config reference	See the gap inventory below; automatic push cleanup is unsupported

See official Phrase Strings CLI documentation for operations outside this command family.

Command reference

hyperlocalise phrase init [--project-id <id>] [--format <format>] [--file <path>] [--host <url>] [--source-locale <id>] [--token-env <name>] [--force]
hyperlocalise phrase config validate [--config <path>]
hyperlocalise phrase push [--config <path>] [--project-id <id>] [--source-locale <id>] [--file <path>] [--format <format>] [--wait] [--wait-timeout <duration>] [--dry-run]
hyperlocalise phrase pull [--config <path>] [--project-id <id>] [--target-locale <id>] [--format <format>] [--output <path>] [--dry-run]
hyperlocalise phrase locales list [--config <path>] [--project-id <id>] [--branch <name>] [--output text|json]
hyperlocalise phrase uploads cleanup --id <upload_id> [--config <path>] [--project-id <id>] [--dry-run]
hyperlocalise phrase upload sources [--config <path>] [--project-id <id>] [--source-locale <id>] [--file <path>] [--format <format>] [--branch <name>] [--tag <tag>] [--token-env <name>] [--api-base-url <url>] [--update-translations] [--skip-upload-tags] [--wait] [--wait-timeout <duration>] [--dry-run]
hyperlocalise phrase download sources --project-id <id> --source-locale <locale> --format <format> [--output <path>] [--branch <name>] [--tag <tag>] [--token-env <name>] [--api-base-url <url>] [--force] [--dry-run]
hyperlocalise phrase download translations [--config <path>] [--project-id <id>] [--target-locale <locale>] [--format <format>] [--output <path>] [--branch <name>] [--tag <tag>] [--token-env <name>] [--api-base-url <url>] [--force] [--dry-run]
hyperlocalise phrase glossary download --account-id <id> --glossary-id <id> [--language <locale>] [--output <path>] [--token-env <name>] [--api-base-url <url>] [--force] [--dry-run]
hyperlocalise phrase tm download --tm-id <id> --source-language <code> --target-language <code> [--format csv|tmx] [--output <path>] [--token-env <name>] [--api-base-url <url>] [--force] [--dry-run]

tm also accepts the alias translation-memory.

What this command family does

These commands operate on Phrase Strings file mode with .phrase.yml (or explicit flags). They are separate from Hyperlocalise native i18n.yml and sync push / sync pull workflows. Use shared TMS sync when you want Hyperlocalise-managed entry sync through the Phrase adapter. Use this surface when you want a closer replacement for Phrase Strings CLI file workflows. Use them for:

scaffold a non-interactive .phrase.yml with phrase init
source-file upload from phrase.push.sources (push is an alias of upload sources)
translation download into phrase.pull.targets (pull is an alias of download translations)
locale listing from the Phrase project
source download with explicit flags (no config-file mode)
glossary and translation-memory download (CSV/TMX)
config validation against .phrase.yml

phrase init refuses to overwrite an existing .phrase.yml unless you pass --force. When --project-id is set and PHRASE_ACCESS_TOKEN or PHRASE_API_TOKEN is available, init calls Phrase to set phrase.push.sources[].params.locale_id to the project default locale; otherwise it falls back to en. Pass --source-locale to override. Do not commit a generated config that contains secrets.

Config lookup

If --config is omitted, Hyperlocalise checks PHRASEAPP_CONFIG, then .phrase.yml in the current directory, then $HOME/.phrase.yml. In config mode, Hyperlocalise resolves the token in this order:

phrase.access_token as a literal value, or as $VAR / ${VAR} from that named environment variable
PHRASE_ACCESS_TOKEN, then PHRASE_API_TOKEN, only when phrase.access_token is omitted or empty

If phrase.access_token is an environment reference ($VAR / ${VAR}), Hyperlocalise uses that variable only. An unset or empty reference does not fall through to PHRASE_ACCESS_TOKEN or PHRASE_API_TOKEN. Set the referenced variable, or omit access_token so the default env vars apply. Manual flag commands (and config mode when you pass --token-env) read --token-env (default PHRASE_API_TOKEN). If you set a custom --token-env and it is empty, Hyperlocalise then tries PHRASE_API_TOKEN. --api-base-url overrides phrase.host. upload sources and download translations use config mode when you pass --config, or when a config file resolves and you do not set --project-id, --format, or (for upload) --file / (for download) --output. download sources, glossary download, and tm download are flag-only.

Supported config fields

These drive Hyperlocalise Phrase file mode under the phrase: key:

access_token
project_id
file_format
host
locale_mapping
push.sources[].file
push.sources[].project_id
push.sources[].params.locale_id
push.sources[].params.file_format
push.sources[].params.branch
push.sources[].params.tags
push.sources[].params.update_translations
push.sources[].params.update_translation_keys
push.sources[].params.update_descriptions
push.sources[].params.skip_upload_tags
push.sources[].params.skip_unverification
push.sources[].params.file_encoding
push.sources[].params.locale_mapping
push.sources[].params.format_options
push.sources[].params.autotranslate
push.sources[].params.mark_reviewed
pull.targets[].file
pull.targets[].project_id
pull.targets[].params.locale_id
pull.targets[].params.file_format
pull.targets[].params.branch
pull.targets[].params.tags
pull.targets[].params.include_empty_translations
pull.targets[].params.exclude_empty_zero_forms
pull.targets[].params.include_translated_keys
pull.targets[].params.keep_notranslate_tags
pull.targets[].params.encoding
pull.targets[].params.include_unverified_translations
pull.targets[].params.use_last_reviewed_version
pull.targets[].params.fallback_locale_id
pull.targets[].params.format_options
pull.targets[].params.source_locale_id
pull.targets[].params.translation_key_prefix
pull.targets[].params.filter_by_prefix
pull.targets[].params.use_locale_fallback
pull.targets[].params.skip_unverified_translations

Path placeholders in file values: <locale_name>, <locale_code>, <tag>, <tags>. Unlike Crowdin file mode, unknown top-level YAML keys under .phrase.yml are silently dropped. Only fields listed above are applied. These push.sources[].params and pull.targets[].params values apply in config mode only. Manual flag mode exposes a smaller set (--update-translations, --skip-upload-tags, --branch, --tag). --dry-run with locale placeholders in config may require --source-locale or --target-locale because dry-run cannot call Phrase to enumerate locales.

Strings CLI gap inventory

Official Strings CLI	Hyperlocalise today
`phrase init`	Supported (non-interactive scaffold; no wizard; resolves default `locale_id` when token is set)
`phrase push`	Supported (`upload sources` alias, same config resolution)
`phrase push --wait`	Supported (also `upload sources --wait`; polls until `success` or `error`/`failed`; unknown states fail closed; `--wait-timeout` default 10m; still prints `upload_id` if wait fails)
`phrase pull`	Supported (`download translations` alias, same config resolution)
`phrase locales list`	Supported (`--output text\|json`)
`phrase uploads cleanup --id`	Supported (deletes keys unmentioned in that upload, not translations only; `--dry-run` lists and does not delete; refuses non-`success` uploads)
`delete_unmentioned_keys` in `.phrase.yml` / `push --cleanup`	Unsupported (do not auto-run cleanup from `push`)
Push param `translation_key_prefix`	Unsupported (parsed on pull only)
Full API CLI (`keys`, `translations`, `jobs`, `locales create`)	Out of scope
Glossary/TM upload	Out of scope (download is Hyperlocalise-shaped CSV/TMX)
`phrase status`	Out of scope

Examples

hyperlocalise phrase init --project-id abc123 --format json --file ./locales/en.json
hyperlocalise phrase config validate
hyperlocalise phrase push --dry-run
hyperlocalise phrase push --wait
hyperlocalise phrase locales list --output json
hyperlocalise phrase pull
hyperlocalise phrase uploads cleanup --id <upload_id> --dry-run

Upload one source file with flags:

hyperlocalise phrase upload sources \
  --project-id project-uuid \
  --source-locale en-US \
  --file ./locales/en.json \
  --format json \
  --tag app \
  --update-translations

Download a source locale to a file:

hyperlocalise phrase download sources \
  --project-id project-uuid \
  --source-locale en-US \
  --format json \
  --output ./locales/en.json \
  --force

download sources does not read .phrase.yml. Credentials come from --token-env (default PHRASE_API_TOKEN) or PHRASE_API_TOKEN. Download one locale with flags. Use %locale% in --output when you pass more than one --target-locale:

hyperlocalise phrase download translations \
  --project-id project-uuid \
  --target-locale fr-FR \
  --format json \
  --output ./locales/%locale%.json \
  --force

Or configure the same workflow in .phrase.yml:

phrase:
  access_token: $PHRASE_ACCESS_TOKEN
  project_id: project-uuid
  file_format: json
  host: https://api.phrase.com/v2
  locale_mapping:
    fr-FR: fr
  push:
    sources:
      - file: ./locales/en.json
        params:
          locale_id: en-US
          tags: app,source
          update_translations: true
  pull:
    targets:
      - file: ./locales/<locale_name>.json
        params:
          locale_id: fr-FR
          include_unverified_translations: false

Download a glossary:

hyperlocalise phrase glossary download \
  --account-id account-uuid \
  --glossary-id glossary-uuid \
  --output ./glossary.csv \
  --force

Download translation memory as TMX:

hyperlocalise phrase tm download \
  --tm-id tm-uuid \
  --source-language en \
  --target-language fr \
  --format tmx \
  --output ./memory.tmx \
  --force

Live smoke (throwaway Phrase project)

Use a dedicated throwaway Strings project, not production. Cleanup deletes keys, not only translations.

In Phrase, create a Strings project with source locale en and at least one target (for example fr).
Create an access token (read/write). Do not commit it. In PowerShell:

$env:PHRASE_ACCESS_TOKEN = "<token>"

On bash: export PHRASE_ACCESS_TOKEN=<token>.

In an empty temp directory (set the token first so init can resolve the project default locale):

go run ./apps/cli phrase init --project-id <project_id> --format json --file ./locales/en.json
mkdir -p locales
cat > locales/en.json <<'EOF'
{
  "hello": { "message": "Hello" },
  "unused": { "message": "drop me" }
}
EOF
go run ./apps/cli phrase config validate
go run ./apps/cli phrase locales list
go run ./apps/cli phrase push --dry-run
go run ./apps/cli phrase push --wait

If no token is set at init time, locale_id defaults to en; edit .phrase.yml or rerun init --force after exporting PHRASE_ACCESS_TOKEN. Use Phrase JSON ({"key":{"message":"..."}}) when the project expects structured JSON, not flat {"key":"value"}. Confirm the last command prints upload_id=... and state=success (not processing). Copy the upload id.

Pull:

go run ./apps/cli phrase pull --force

Confirm a target file appears under locales/ (or the path in .phrase.yml).

Cleanup dry-run, then skip or run for real only if this project is disposable:

go run ./apps/cli phrase uploads cleanup --id <upload_id> --dry-run
# deletes keys not present in that upload — do not run on a shared project
# go run ./apps/cli phrase uploads cleanup --id <upload_id>

Do not commit .phrase.yml. Official phrase CLI is optional for comparison (phrase push --wait); Hyperlocalise’s commands are go run ./apps/cli phrase ....

​Start with a Phrase Strings push and pull

​Hyperlocalise vs the official Phrase Strings CLI

​Command reference

​What this command family does

​Config lookup

​Supported config fields

​Strings CLI gap inventory

​Examples

​Live smoke (throwaway Phrase project)

​Related workflows