Skip to content
file-text

GitHub Action

Translate Readme

v0.1.2 Latest version

Translate Readme

file-text

Translate Readme

Automate translation of your README.md files via Crowdin

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: Translate Readme

              
  uses: crowdin/[email protected]
Learn more about this action in crowdin/translate-readme

Choose a version

Translate Readme Tweet GitHub Repo stars

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

build-test e2e-test codecov GitHub

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

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.