DeepL Translate Github Action

🏆 v1.0.0 of this github action was awarded the Grand Prize of Maintainer must-haves category in the GitHub + DEV 2023 Hackathon

Intro

This action uses the DeepL Translate API to translate files in your repository to any target languages supported by DeepL. Since DeepL API does not officially support markdown tag handling yet, this github action helps to mitigate some issues that DeepL may have when it comes to .md documents.

✨ In v1.0.0, common text files such as .md | .html | .xml | .txt are supported.

✨ From v2.0.0 onwards, flat locale JSON files are also supported.

✨ From v2.1.0 onwards, nested locale JSON files are also supported.

Inputs

Name	Description	Required
`deepl_api_key`	API Key for DeepL API	yes
`target_languages`	Target languages to translate to. Refer to DeepL docs for language codes. You can also input `all` for all target languages that DeepL supports.	yes
`input_file_path`	Path of the file you want to translate. Accepts `.html, .xml, .md, .txt, .json`	yes
`output_file_name_pattern`	Output file name pattern. e.g: `public/locales/{language}/common.json` where language is replaced by the target language code	yes
`no_translate_start_tag`	Start tag to ignore when translating in the case of HTML-like files such as `.html, .xml, .md, .txt`	no
`no_translate_end_tag`	End tag to ignore when translating in the case of HTML-like files such as `.html, .xml, .md, .txt`.	no

Example usage

For standard text files such as `.md`, `.html`, `.xml`, `.txt`

name: Translate documents from docs/simple folder
on:
  workflow_dispatch:
  pull_request:
    types: [opened, synchronize]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: DeepL Translate Github Action
        uses: lyqht/deepl-translate-github-action@v2.0.0
        with:
          target_languages: zh,ja
          input_file_path: docs/simple/original.md
          output_file_name_pattern: docs/simple/{language}.md
          deepl_api_key: ${{ secrets.DEEPL_API_KEY }}

With this workflow, you will get docs/simple/zh.md and docs/simple/ja.md

For locale json

name: Translate locales json
on:
  workflow_dispatch:
  pull_request:
    types: [opened, synchronize]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: DeepL Translate Github Action
        uses: lyqht/deepl-translate-github-action@v2.1.0
        with:
          target_languages: fr,ja
          input_file_path: locales/en.json
          output_file_name_pattern: locales/{language}.json
          deepl_api_key: ${{ secrets.DEEPL_API_KEY }}

With this workflow, you will get locales/fr.json, locales/ja.json.

Demo

For a simple demo of translating HTML-like text files, refer to the deepl-demo repository.
For a more advanced demo of translating both the README.md and locale/x.json, refer to nuxt3-app-vue-i18n repository, with a deployed app.

When the github action runs, it will produce commits like the following based on your input paths.

For nested locale JSON

name: Translate locale commons json
on:
  workflow_dispatch:
  pull_request:
    types: [opened, synchronize]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: DeepL Translate Github Action
        uses: lyqht/deepl-translate-github-action@v2.1.0
        with:
          target_languages: fr,ja
          input_file_path: public/locales/en/common.json
          output_file_name_pattern: public/locales/{language}/common.json
          deepl_api_key: ${{ secrets.DEEPL_API_KEY }}

With this workflow, you will get public/locales/fr/common.json, public/locales/ja/common.json.

For a demo, refer to refine-i18n-react repository, with a deployed app.

FAQ

How to get DeepL API Token

First, you need to sign up for the free DeepL API plan. Then you can go to https://www.deepl.com/account/summary and retrieve your token there.

If you don't have an existing GitHub Action workflow for your repository

Create a folder .github/workflows if you don't have it already
Inside that folder, create a YAML file say translate.yml
In the translate.yml file, you can copy the example below and modify it to your usage.

Why am I getting an error of "Permission to git denied to github-actions[bot]"

You have to set the workflow permissions under Repository Settings > Actions > Workflow permissions to be "Read and write permissions".

The script is cool but I don't want to use a GitHub action. Can I run it locally?

Well, you're in luck! Refer to local.ts and modify your env variables accordingly.

lyqht/deepl-translate-github-action