A GitHub action to manage and synchronize localization resources with your Crowdin project

This action allows you to easily integrate and automate the localization of your Crowdin project into the GitHub Actions workflow.

• Upload sources to Crowdin.
• Upload translations to Crowdin.
• Downloads translations from Crowdin.
• Download sources from Crowdin.
• Creates a PR with the translations.
• Run any Crowdin CLI command.

Set up a workflow in .github/workflows/crowdin.yml (or add a job to your existing workflows).

Read the Configuring a workflow article for more details on creating and setting up GitHub workflows.

name: Crowdin Action

on:
  push:
    branches: [ main ]

jobs:
  synchronize-with-crowdin:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: crowdin action
        uses: crowdin/github-action@v2
        with:
          upload_sources: true
          upload_translations: false
          download_translations: true
          localization_branch_name: l10n_crowdin_translations
          create_pull_request: true
          pull_request_title: 'New Crowdin Translations'
          pull_request_body: 'New Crowdin translations by [Crowdin GH Action](https://github.com/crowdin/github-action)'
          pull_request_base_branch_name: 'main'
        env:
          # A classic GitHub Personal Access Token with the 'repo' scope selected (the user should have write access to the repository).
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
          
          # A numeric ID, found at https://crowdin.com/project/<projectName>/tools/api
          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}

          # Visit https://crowdin.com/settings#api-key to create this token
          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

Create the CROWDIN_PROJECT_ID and CROWDIN_PERSONAL_TOKEN secrets in Repository settings -> Secrets and variables -> Actions > Repository secrets.

"project_id_env": "CROWDIN_PROJECT_ID"
"api_token_env": "CROWDIN_PERSONAL_TOKEN"
"base_path": "."

"preserve_hierarchy": true

"files": [
  {
    "source": "locales/en.yml",
    "translation": "locales/%two_letters_code%.yml"
  }
]

Replace the source and translation paths with the actual paths to your source and translation files.

By default, the action will look for the crowdin.yml file in the root of the repository. You can specify a different path using the config option.

The options above can be used in the No-crowdin.yml configuration mode.

You can also run any other Crowdin CLI command by specifying the command and command_args (optional) options. For example:

- name: crowdin action
  uses: crowdin/github-action@v2
  with:
    command: 'pre-translate'
    command_args: '-l uk --method tm --branch main'

To see the full list of available commands, visit the official documentation.

This action has the following outputs:

• pull_request_url: The URL of the pull request created by the workflow
• pull_request_number: The number of the pull request created by the workflow

In order to push translations and create pull requests, the Crowdin GitHub Action requires the GITHUB_TOKEN to have the write permission on the contents and pull-requests.

In case you want to use an automatic GitHub authentication token, you need to assign the write permission to your job and allow GH Actions to create Pull Requests.

If you are using the native GitHub integration, you can easily migrate to the GitHub Action. The main difference is that the GitHub Action requires a Crowdin Personal Access Token and a numeric project ID to be specified. Follow the steps below to migrate:

• If you're using a crowdin.yml file, you'll need to add preserve_hierarchy: true to keep the directory structure the same between Crowdin and GitHub (even if you weren't already using this setting in your existing OAuth integration).
• localization_branch_name should be set to the existing Git branch name you're using for Crowdin PRs.
• crowdin_branch_name should be set as well.

For example, if you have the following configuration file:

files:
  - source: /**/*.xml
    translation: /**/%two_letters_code%.xml

Add the credentials:

project_id_env: CROWDIN_PROJECT_ID
api_token_env: CROWDIN_PERSONAL_TOKEN

files:
  - source: /**/*.xml
    translation: /**/%two_letters_code%.xml

Then create the secrets CROWDIN_PROJECT_ID and CROWDIN_PERSONAL_TOKEN and finally, create the workflow. See Usage for more details.

If comparing the native GitHub integration and the GitHub Action, the GitHub Action provides more flexibility and control over the localization process.

If you would like to contribute, please read the Contributing guidelines.

If you find any problems or would like to suggest a feature, please feel free to file an issue on GitHub at the Issues Page. Please also check the Examples page for more use cases.

The Crowdin GitHub Action is licensed under the MIT License.
See the LICENSE file distributed with this work for additional
information regarding copyright ownership.

Except as contained in the LICENSE file, the name(s) of the above copyright
holders shall not be used in advertising or otherwise to promote the sale,
use or other dealings in this Software without prior written authorization.