Build your CI/CD pipeline

​

Quickstart

curl --request GET \
  --url https://api.phrase.com/v2/projects/<PROJECT_ID> \
  --header 'Authorization: Bearer <JWT_TOKEN>'

​

Prerequisites

1. Authentication set up. See the Authentication guide, and store the API token as a CI secret. The pipeline exchanges it for the short-lived JWT the calls below send as Bearer <JWT_TOKEN>.
2. Phrase Strings command-line interface (CLI) installed. It provides phrase push and phrase pull.
3. A project ID, the project code taken from the project in Phrase.
4. A .phrase.yml config file. Run phrase init to scaffold one; it holds push.sources and pull.targets.
5. A CI platform such as GitHub Actions or GitLab CI. You author the pipeline YAML.

​

How-to

1. Push source strings on every change. Run phrase push in the job that reacts to a code change; the command-line interface uploads each source file. The direct API call is the multipart upload below. Processing is asynchronous: the response returns 201 with an upload id, so poll the upload status until state reads success. Prefer this file upload over a per-key loop. A 422 means the request has a bad field, usually the file format or an unknown language code; the errors array names it, so correct it and retry. To get translations back sooner, set autotranslate on the upload so machine translation (MT) fills them in as the file imports.
   curl --request POST \
     --url https://api.phrase.com/v2/projects/<PROJECT_ID>/uploads \
     --header 'Authorization: Bearer <JWT_TOKEN>' \
     --form file=@locales/en.json \
     --form file_format=json \
     --form locale_id=<SOURCE_LOCALE_ID>
   
2. Pull finished translations before the build. Translation runs inside Phrase, by people or machine translation, and is outside the pipeline. Run phrase pull, or call the two-step download below: start the download, then poll the status until it reads completed and fetch result.url, which is valid for 15 minutes. If the status stays processing, keep polling on a short interval rather than firing many parallel requests.
   # 1. Start the download
   curl --request POST \
     --url https://api.phrase.com/v2/projects/<PROJECT_ID>/locales/<LOCALE_ID>/downloads \
     --header 'Authorization: Bearer <JWT_TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{"file_format":"json"}'
   
   # 2. Poll, then fetch result.url
   curl --request GET \
     --url https://api.phrase.com/v2/projects/<PROJECT_ID>/locales/<LOCALE_ID>/downloads/<DOWNLOAD_ID> \
     --header 'Authorization: Bearer <JWT_TOKEN>'
   

​

When it breaks: common errors

​

Troubleshooting

​

Next steps

1. Review the reference pages this pipeline calls: Upload a new file, and Initiate a locale download.
2. Wire the delivery half: Push translation fixes without a release, and Auto-sync translation keys on code push.