# CircleCI

> Trigger a CircleCI build when new translations ready

URL: https://store.crowdin.com/circle-ci
Identifier: circle-ci
Category: Development
Type: Guide
Author: Community

Use [CircleCI](https://circleci.com/) 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.

### Preparing the repository

Push the `crowdin.yml` [configuration file](https://developer.crowdin.com/configuration-file/) to the repository.

Use [Environment Variables](https://developer.crowdin.com/configuration-file/#api-credentials-from-environment-variables) for API Credentials:

```yml
"project_id_env": "CROWDIN_PROJECT_ID"
"api_token_env": "CROWDIN_PERSONAL_TOKEN"
```

See the [Introduction to environment variables](https://circleci.com/docs/env-vars/) to learn more about defining variables in CircleCI.

### Pipeline configuration

```yml
version: 2

orbs:
  node: circleci/node@5.2.1

workflows:
  localization:
    environment:
      CROWDIN_PROJECT_ID: $CROWDIN_PROJECT_ID
      CROWDIN_PERSONAL_TOKEN: $CROWDIN_PERSONAL_TOKEN

    jobs:
      -  upload:
          executor: node/default
          steps:
            - checkout
            - run: npm install -g @crowdin/cli
            - run: crowdin push

      - download:
          executor: node/default
          steps:
            - checkout
            - run: npm install -g @crowdin/cli
            - run: crowdin pull --no-progress --keep-archive
            - store_artifacts:
                 path: CrowdinTranslations_*.zip

on:
  push:
    branches:
      - main
```

The localization workflow above has two jobs: `upload` and `download`. The `upload` job installs the `@crowdin/cli` npm package and then runs the` crowdin push` command to push the source files to Crowdin. The download job runs the `crowdin pull` command to download translations from Crowdin. The `download` job also stores the downloaded translations as the pipeline artifact.

For more information about Crowdin CLI commands visit the official [Crowdin CLI website](https://crowdin.github.io/crowdin-cli/).

## Triggering the pipeline

Notify your CircleCI when there are new translations and that the build is required. This guide describes setting up a Crowdin webhook to invoke the build.

[CircleCI' documentation](https://support.circleci.com/hc/en-us/articles/360050351292-How-to-trigger-a-workflow-via-CircleCI-API-v2) says we should send the following request to trigger the build. 

```bash
curl --request POST \
  --url https://circleci.com/api/v2/project/vcs-slug/org-name/repo-name/pipeline \
  --header 'Circle-Token: ***********************************' \
  --header 'content-type: application/json' \
  --data '{"parameters":{"run_workflow_build":false, "run_workflow_deploy":false}}'
```

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 how to create a webhook in [crowdin.com](https://support.crowdin.com/webhooks/#adding-webhooks) and [Crowdin Enterprise](https://support.crowdin.com/enterprise/webhooks/#adding-webhooks).

Below is an example of a fully configured Crowdin webhook.
![CircleCI Crowdin Integration](https://developers.app.crowdin.net/api/media/file/e52d21d4-fbda-43a4-9272-b7de5d3051c1.png)

Use the following template to create a webhook URL: `https://circleci.com/api/v2/project/<your-vcs-like-github>/<organization-name>/<repo-slug>/pipeline`.

For more advanced setup please refer to the [official documentation](https://support.circleci.com/hc/en-us/articles/360050351292-How-to-trigger-a-workflow-via-CircleCI-API-v2).