README.md

Translate Readme  

A GitHub Action to automate the translation of your README.md files via Crowdin ✨

What does this action do?

• Upload your README.md file to Crowdin
• Download the translations from Crowdin to the specified place
• Manage the languages switcher in your README.md file

Usage

Set up a workflow in .github/workflows/translate-readme.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.

# .github/workflows/translate-readme.yml
name: Translate Readme

on:
  # When you push to the `main` branch
  push:
    branches: [ main ]
  # And optionally, once every 12 hours
  schedule:
    - cron: '0 */12 * * *' # https://crontab.guru/#0_*/12_*_*_*
  # To manually run this workflow
  workflow_dispatch:

jobs:
  translate-readme:
    runs-on: ubuntu-latest

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

    - name: Translate Readme
      uses: crowdin/[email protected]
      env:
        CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
        CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
        # Optional. Only for Crowdin Enterprise
        CROWDIN_ORGANIZATION: ${{ secrets.CROWDIN_ORGANIZATION }}

Creating a PR

To create a PR with the updated table, we recommend usage of the Create Pull Request Action:

# .github/workflows/translate-readme.yml
name: Translate Readme

on:
  # When you push to the `main` branch
  push:
    branches: [ main ]
  # And optionally, once every 12 hours
  schedule:
    - cron: '0 */12 * * *' # https://crontab.guru/#0_*/12_*_*_*
  # To manually run this workflow
  workflow_dispatch:

jobs:
  translate-readme:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

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

    - name: Translate Readme
      uses: crowdin/[email protected]
      env:
        CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
        CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

    - name: Create Pull Request
      uses: peter-evans/create-pull-request@v5
      with:
        title: New Readme Translations by Crowdin
        body: By [translate-readme](https://github.com/crowdin/translate-readme) GitHub action
        commit-message: New Readme Translations
        committer: Crowdin Bot <[email protected]>
        branch: docs/readme-translations

Languages Switcher

The Translate Readme Action will automatically add a language switcher to your README.md file.

To enable it, add the following placeholders to your README.md file:

<!-- TRANSLATE-README-LANGUAGES-START -->
<!-- TRANSLATE-README-LANGUAGES-END -->

Also, don't forget to add the following option to your workflow step:

​- name: Translate Readme
  uses: crowdin/[email protected]
  with:
+    language_switcher: true
  env:
    CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
    CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

Options

Option	Default value	Description
file	README.md	The Readme file name
destination	./	A directory where the localized readmes will be placed
languages	All Crowdin project languages	A list of Crowdin language codes to translate the Readme
language_switcher	false	Defines whether to add a language switcher to the Readme
upload_sources	true	Defines whether to upload the source file to Crowdin
download_translations	true	Defines whether to download translations from Crowdin

Environment variables

Variable	Description
CROWDIN_PROJECT_ID	Your Crowdin Project ID (numeric)
CROWDIN_PERSONAL_TOKEN	Your Crowdin Personal Access Token
CROWDIN_ORGANIZATION	Your Crowdin Enterprise organization name (only for Crowdin Enterprise)

Automatic Pre-Translation

You can Pre-Translate your README.md file before creating a PR. Use the following configuration for that:

# .github/workflows/translate-readme.yml
name: Translate Readme

on:
  push:
    branches: [ main ]

jobs:
  translate-readme:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

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

      - name: Upload README.md to Crowdin
        uses: crowdin/[email protected]
        with:
          upload_sources: true
          download_translations: false
        env:
          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

      - name: Pre-Translate README.md via Translation Memory
        uses: crowdin/github-action@v1
        with:
          command: 'pre-translate'
          command_args: '-l uk --method tm'
        env:
          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

      - name: Download Readme translations from Crowdin
        uses: crowdin/[email protected]
        with:
          upload_sources: false
          download_translations: true
        env:
          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

      # Create a PR with the latest translations

For more about the Pre-Translate command arguments, please refer to the official Crowdin CLI documentation.

Demo

Visit the translate-readme-demo to see how the action works in a real project.

Contributing

If you want to contribute please read the Contributing guidelines.

Author

• Andrii Bodnar

License

The Translate Readme 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.