Use the Crowdin CLI to automate localization in Azure Pipelines

Use Azure Pipelines with Crowdin CLI to automate your frequent localization tasks such as uploading source files, downloading translations or anything else you can do with Crowdin CLI.

Azure Pipelines can be connected with Crowdin through the Crowdin CLI.

Example pipeline configuration:

trigger:
  branches:
    include:
      - refs/heads/*
  paths:
    include:
      - locales/en/*.json
 
variables:
  BRANCH_NAME: $[replace(variables['Build.SourceBranch'], 'refs/heads/', '')]
 
jobs:
  - job: Crowdin
    pool:
      vmImage: ubuntu-latest
    steps:
      - task: NodeTool@0
        displayName: 'Install Node.js'
        inputs:
          versionSpec: '22.x'

      - script: npm install -g @crowdin/cli

      - script: |
          crowdin push --no-progress -b $(BRANCH_NAME) \
                       -T $(CROWDIN_TOKEN) \
                       -i $(PROJECT_ID) \
                       -s "locales/en/*json" \
                       -t "locales/%two_letters_code%/%original_file_name%" \
                       /

In this example, the pipeline will be triggered on branch push filtering by file path. Then you need to set up Node and install Crowdin CLI NPM package globally. After the CLI installation, you can execute any CLI command.

Use your Crowdin Project ID, and access token, and specify source and translation files. To securely store your Crowdin Personal Access Token and Project ID, you need to configure it as a Secret Variables in your pipeline.

More information about Crowdin CLI commands.

crowdin.yml configuration file example:

"project_id_env": "PROJECT_ID"
"api_token_env": "CROWDIN_TOKEN"
"base_path": "."

"preserve_hierarchy": true

"files": [
  {
    "source": "*.md",
    "translation": "%two_letters_code%.md"
  }
]

See Configuration File for more information.

Automate Azure Pipelines on translation updates

Notify your Azure Pipeline when there are new translations and that the build is required. This section describes setting up a Crowdin webhook to trigger the pipeline automatically.

To trigger an Azure Pipeline, you need to send a POST request to the Azure DevOps REST API:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic BASE64_ENCODED_PAT" \
  https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=7.1 \
  -d '{"definition": {"id": pipelineId}}'

Where:

{organization} - your Azure DevOps organization name
{project} - your project name
pipelineId - the ID of your pipeline (you can find it in the URL when viewing your pipeline: https://dev.azure.com/{organization}/{project}/_build?definitionId={pipelineId})
BASE64_ENCODED_PAT - Base64-encoded string in format :YOUR_PERSONAL_ACCESS_TOKEN

To get the Base64-encoded PAT, run:

echo -n ":YOUR_PERSONAL_ACCESS_TOKEN" | base64

Info

Make sure to create a Personal Access Token (PAT) in Azure DevOps with the scope Build (Read & Execute) to allow Crowdin to trigger your pipeline.

We will configure Crowdin to send this request without any middleware, just by setting up the webhook on a needed event (e.g. File is 100% translated).

Depending on a Crowdin Edition you use, please check the documentation on how to create a webhook in crowdin.com and Crowdin Enterprise.

Below is an example of a fully configured Crowdin webhook:

URL: https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=7.1
HTTP Method: POST
Content Type: application/json
Headers: Authorization: Basic {BASE64_ENCODED_PAT}
Payload:

{
  "definition": {
    "id": pipelineId
  },
  "templateParameters": {
    "fileName": "{{fileName}}",
    "language": "{{targetLanguageId}}",
    "projectId": "{{projectId}}"
  }
}

Info

Replace pipelineId with your actual pipeline ID number (e.g., 42), not as a string.
The templateParameters field allows you to pass data from Crowdin's webhook payload to your pipeline. Crowdin will automatically replace the placeholders (e.g., {{fileName}}, {{targetLanguageId}}) with actual values from the event payload. See the Webhooks documentation for available payload fields.
You can omit templateParameters if you don't need to pass any data to your pipeline.

Pipeline example for webhook-triggered builds:

trigger: none  # Disable automatic triggers

parameters:
  - name: fileName
    type: string
    default: ''
  - name: language
    type: string
    default: ''
  - name: projectId
    type: number
    default: 0

jobs:
  - job: Crowdin
    pool:
      vmImage: ubuntu-latest
    steps:
      - task: NodeTool@0
        displayName: 'Install Node.js'
        inputs:
          versionSpec: '22.x'

      - script: npm install -g @crowdin/cli
        displayName: 'Install Crowdin CLI'

      - script: |
          echo "File translated: ${{ parameters.fileName }}"
          echo "Language: ${{ parameters.language }}"
          echo "Project ID: ${{ parameters.projectId }}"
        displayName: 'Display webhook data'

      - script: |
          crowdin download --no-progress \
                           -T $(CROWDIN_TOKEN) \
                           -i $(PROJECT_ID) \
                           -l ${{ parameters.language }} \
        displayName: 'Download translations from Crowdin'

Localize your product with Crowdin

Automate content updates, boost team collaboration, and reach new markets faster.

Free 14-day Trial

Crowdin is a platform that helps you manage and translate content into different languages. Integrate Crowdin with your repo, CMS, or other systems. Source content is always up to date for your translators, and translated content is returned automatically.

Learn More