GitHub Crowdin Action

The GitHub Crowdin Action allows you to easily integrate the localization of your Crowdin project into the workflow you’ve set up on your repo with help of GitHub Actions. Using GitHub Crowdin Action, you can automate the synchronization of localization resources with your Crowdin project.

With this action you can do the following things:

• Upload sources to Crowdin.
• Upload translations to Crowdin.
• Download translations from Crowdin.

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 how to create and set up custom workflows.

name: Crowdin Action

on:
  push:
    branches: [ master ]

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

    steps:

    - name: Checkout
      uses: actions/checkout@v2

    - name: crowdin action
      uses: crowdin/github-action@1.0.4
      with:
        upload_translations: true
        download_translations: true
      env:
        GITHUB_TOKEN: $
        CROWDIN_PROJECT_ID: $
        CROWDIN_PERSONAL_TOKEN: $

Supported Options

The default action is to upload sources. Though, you can set different actions through the with options. If you don’t want to upload your sources to Crowdin, just set the upload_sources option to false.

By default sources and translations are being uploaded to the root of your Crowdin project. Still, if you use branches, you can set the preferred source branch.

You can also specify what GitHub branch you’d like to download your translations to (default translation branch is l10n_crowdin_action).

In case you don’t want to download translations from Crowdin (download_translations: false), localization_branch_name and create_pull_request options aren’t required either.

- name: crowdin action
  with:
    # upload options
    upload_sources: true
    upload_translations: true

    # download options
    download_translations: true
    language: 'uk'
    push_translations: true

    # This is the name of the git branch that Crowdin will create when opening a pull request. 
    # This branch does NOT need to be manually created. It will be created automatically by the action.
    localization_branch_name: l10n_crowdin_action
    create_pull_request: true

    # global options
    
    # This is the name of the top-level directory that Crowdin will use for files.
    # Note that this is not a "branch" in the git sense, but more like a top-level directory in your Crowdin project.
    # This branch does NOT need to be manually created. It will be created automatically by the action.
    crowdin_branch_name: l10n_branch
    identity: '/path/to/your/credentials/file'
    config: '/path/to/your/crowdin.yml'
    dryrun_action: true

    # config options
    
    # This is a project numeric id
    project_id: $ 
    # This is a personal access token
    token: $
    source: '/path/to/your/file'
    translation: 'file/export/pattern'
    base_url: 'https://crowdin.com'
    base_path: '/project-base-path'

For more detailed descriptions of these options, see action.yml.

Crowdin Configuration File

If your workflow file contains the config property, you’ll need to add the following to your Crowdin configuration file (e.g., crowdin.yml):

project_id_env: CROWDIN_PROJECT_ID
api_token_env: CROWDIN_PERSONAL_TOKEN

When the workflow runs, the real values of your token and project ID will be injected into the config using the secrets in the environment.

Q&A

What is the difference between localization_branch_name and pull_request_base_branch_name?

To better understand the purpose of each option, let’s consider two possible scenarios.

Prerequisites:

• GitHub repository that has two branches with source files that require localization: branch_1 and branch_2
• GitHub Crowdin Action is configured to upload source files from GitHub and download translations from Crowdin.

Scenario #1:
GitHub Crowdin Action has a configured localization_branch_name option with a l10n_crowdin_action value and pull_request_base_branch_name isn’t used at all. Once you execute the GitHub Crowdin Action on the branch_1 branch, the sources are pushed to Crowdin, then Crowdin creates a new l10n_crowdin_action branch with translations on GitHub and a pull request to merge into branch_1. Once you merge this pull request, the translations from the l10n_crowdin_action branch will be merged into branch_1.

Scenario #2:
GitHub Crowdin Action has a configured localization_branch_name option with a l10n_crowdin_action value and pull_request_base_branch_name option with a branch_2 value. Once you execute the GitHub Crowdin Action on the branch_1 branch, the sources are pushed to Crowdin, then Crowdin creates a new l10n_crowdin_action branch with translations on GitHub and a pull request to merge into branch_2. Once you merge this pull request, the translations from the l10n_crowdin_action branch will be merged into branch_2, unlike Scenario #1.

So if you need to merge translations into the same branch you executed the GitHub Crowdin Action on, you can do without using the pull_request_base_branch_name option.

But if you need to merge translations into a branch different from the one you executed the GitHub Crowdin Action on, you can specify the target branch the translations should be merged to using the pull_request_base_branch_name option.

What is GITHUB_TOKEN, and where does it come from?

Every time you run the workflow, the GITHUB_TOKEN secret is automatically created by GitHub to be used in the workflow. Also, GITHUB_TOKEN is used by Crowdin for pull request creation on GitHub.

Read more about GITHUB_TOKEN.