Setup a Crowdin Project

What is Crowdin?

Crowdin is an agile translation tool, which provides a modern web interface to propose and review translations with ease, without the need of any prerequisites you normally need, when working with Jenkins views.

This guide aims to provide guidance for project maintainers, how to prepare and setup their project, in order to use crowdin.jenkins.io. This guide is not needed for people, who want to translate plugins only and aren’t plugin maintainers. Refer to this document if you want to learn more about using Crowdin as a translator.

Prerequisites

Your plugin is internationalized

Before integrating your project with Crowdin, you should have internationalized it. Internationalization documentation for Jelly, Java and Groovy can be found here.

Setting up a new project

Request the creation of a new project

To request the creation of a new project, fill out a crowdin issue on the infrastructure helpdesk.

Integrating your GitHub plugin repository with Crowdin

The workflow file

On GitHub, open the repository you want to integrate. Navigate to "Actions" → "New workflow" and select "By Jenkins" → "Crowdin integration" → "Configure".

The default workflow requires one modification in order to work.
Change CROWDIN_PROJECT_ID: # to the actual project ID. You can find it in the URL if you edit the project settings on crowdin.jenkins.io, for example https://jenkins.crowdin.com/u/projects/4/crowdsource, in this case, the project ID is 4. You can find your project ID in your helpdesk issue too, if your project has been created.

Authenticating the action

To let the GitHub action access the project, you need to create a personal access token (PAT) on https://jenkins.crowdin.com/u/user_settings/access-tokens/create
Give the PAT a name, select the scope "Projects" and "Create" the token. You may have to confirm your credentials again. Copy the token, it’ll never be shown again.
Return to your GitHub repository and select "Settings" → "Security" → "Secrets" → "Actions" → "New repository secret" in the upper right corner. For the name of the secret set CROWDIN_PERSONAL_TOKEN, for the value you insert the token you generated on crowdin. Hit "Add secret" and you are done.

The crowdin.yml file

Create a crowdin.yml in the root directory of your plugin using the following setup:

files:
  - source: '/src/main/resources/path/to/your/translations/**/*.properties'
    ignore:
      - '/src/main/resources/path/to/your/translations/**/%file_name%_%two_letters_code%.properties'
    translation: '/src/main/resources/path/to/your/translations/**/%file_name%_%two_letters_code%.properties'
    escape_quotes: 0
    escape_special_characters: 0

project_id_env: CROWDIN_PROJECT_ID
api_token_env: CROWDIN_PERSONAL_TOKEN

Replace /path/to/your/translations/ with the appropriate folder structure of your plugin, take a look at the design-library for a practice example.
Leave the _env variables untouched.

References

Read on how to use the crowdin web interface to translate plugins.