Skip to content

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

License

Notifications You must be signed in to change notification settings

crowdin/github-action

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

GitHub Crowdin Action Tweet GitHub Repo stars

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

What does this action do?

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.

Usage

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.

Sample workflow

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 }}

Enter the CROWDIN_PROJECT_ID and CROWDIN_PERSONAL_TOKEN secrets under the Repository settings -> Secrets and variables -> Actions > Repository secrets.

Sample crowdin.yml configuration file

"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.

Supported options

Upload options

Option Description Example value
upload_sources Specifies whether or not to upload sources to Crowdin true
upload_translations Specifies whether or not to upload existing translations to Crowdin false
upload_language Upload translations for a single specified language uk
auto_approve_imported Automatically approve added translations true
import_eq_suggestions Add translations even if they match the source strings true
upload_sources_args Allows passing any supported arguments of the upload sources command --no-auto-update label=web
upload_translations_args Allows passing any supported arguments of the upload translations command --translate-hidden

Download options

Option Description Example value
download_sources Specifies whether to download sources from Crowdin true
download_translations Specifies whether to download translations from Crowdin true
download_bundle The numeric ID of the Bundle you want to download translations from 1
download_language Download translations for a single specified language uk
skip_untranslated_strings Skip untranslated strings when downloading translations true
skip_untranslated_files Skip untranslated files when downloading translations true
export_only_approved Include only approved translations in exported files true
download_sources_args Allows passing any supported arguments of the download sources command --reviewed
download_translations_args Allows passing any supported arguments of the download translations command --all --skip-untranslated-strings

Git and Pull Request options

Option Description Example value
push_translations Push downloaded translations to the branch true
push_sources Push downloaded sources to the branch true
localization_branch_name The name of the git branch that Crowdin will create when pushing translations or sources l10n_crowdin_action
commit_message The commit message for the pushed changes New Crowdin translations by GitHub Action
create_pull_request Specifies whether to create a pull request with the translations true
pull_request_title The pull request title New Crowdin translations
pull_request_body The pull request body New Crowdin pull request with translations
pull_request_labels The pull request labels localization, l10n
pull_request_assignees The pull request assignees crowdin-bot
pull_request_reviewers The pull request reviewers user-reviewer
pull_request_team_reviewers The pull request team reviewers team-reviewer
pull_request_base_branch_name The git branch name to with pull request will be created. If not specified, the default branch is used main
skip_ref_checkout Skip the default git checkout on GITHUB_REF if you need to checkout multiple branches in a single workflow false

Global options

Option Description Example value
crowdin_branch_name Option to upload or download files to the specified version branch in your Crowdin project l10n_branch
config Option to specify a path to the configuration file (without / at the beginning) path/to/your/crowdin.yml
dryrun_action Defines whether to run the action in the dry-run mode false

GitHub (Enterprise) configuration

Option Description Example value
github_base_url Option to configure the base URL of GitHub server, if using GitHub Enterprise github.com
github_api_base_url Options to configure the base URL of GitHub server for API requests, if using GHE and different from api.github_base_url api.[github_base_url]
github_user_name Option to configure GitHub user name on commits Crowdin Bot
github_user_email Option to configure GitHub user email on commits support+bot@crowdin.com
gpg_private_key GPG private key in ASCII-armored format ${{ secrets.GPG_PRIVATE_KEY }}
gpg_passphrase The passphrase for the ASCII-armored key ${{ secrets.GPG_PASSPHRASE }}

Note For signed commits, add your ASCII-armored key and export gpg --armor --export-secret-key GPG_KEY_ID

Ensure that all emails are the same: for account profile that holds private key, the one specified during key generation, and for commit author (github_user_email parameter)

CLI config options

Option Description Example value
token Crowdin Personal Access Token ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
project_id The numeric project ID (Tools > API section in your Crowdin project) ${{ secrets.CROWDIN_PROJECT_ID }}
source Path to the source files (without / at the beginning) sources/pattern
translation Path to the translation files translations/pattern
base_url Base URL of Crowdin server for API requests execution https://api.crowdin.com
base_path The project base path .

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

Note The base_url is required For Crowdin Enterprise and should be passed in the following way: base_url: 'https://{organization-name}.api.crowdin.com'

Crowdin CLI command

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.

Outputs

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

Permissions

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.

Contributing

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

Seeking Assistance

If you find any problems or would like to suggest a feature, please feel free to file an issue on GitHub at Issues Page.

License

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.