GitHub Action
crowdin-action
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 }}
Enter the CROWDIN_PROJECT_ID
and CROWDIN_PERSONAL_TOKEN
secrets under the 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.
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 |
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 |
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 |
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 |
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)
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'
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 workflowpull_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 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 Issues Page.
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.