GitHub Actions

Quick Start
Trigger workflow
Troubleshooting
Resources

Quick Start

Learn how to upload and download translations from your code on GitHub. This guide will show you how to configure GitHub Actions pipeline, import translations from repository file, and download a translated version to your project files.

GitHub Actions Marketplace

simplelocalize/github-action-cli action is a thin wrapper for SimpleLocalize CLI and allows you to use all CLI commands in your GitHub Actions pipeline. It is a recommended way to integrate SimpleLocalize with your GitHub Actions pipeline as it gives you full control over the process and the used CLI version.

Example: Upload, auto-translate and download

The following example shows how to use the action to upload translations to SimpleLocalize, auto-translate them, and download translated files.

name: 'My project'
on:
  push:
    branches: [ main ]

env:
  cli-version: '2.5.1'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Upload translations
        uses: simplelocalize/github-action-cli@v2
        with:
          api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          command: 'upload'
          cli-version: ${{ env.cli-version }}
          args: '--uploadPath ./translations/{lang}.json --uploadFormat single-language-json'

      - name: Auto-translate project
        uses: simplelocalize/github-action-cli@v2
        with:
          api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          command: 'auto-translate'
          cli-version: ${{ env.cli-version }}

      - name: Download translations
        uses: simplelocalize/github-action-cli@v2
        with:
          api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          command: 'download'
          cli-version: ${{ env.cli-version }}
          args: '--downloadPath ./translations/{lang}.json --downloadFormat single-language-json'

By default, the Upload translations step won't update existing translations. If you want to update existing translations you add --replace argument to the args field.

Example: Publish and pull translation from Translation Hosting

If you are using Translation Hosting to host your translations, you can use simplelocalize/github-action-cli to publish and pull translations from the hosting.

name: 'My project'
on:
  push:
    branches: [ main ]

env:
  cli-version: '2.5.1'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Publish translations
        uses: simplelocalize/github-action-cli@v2
        with:
          api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          command: 'publish'
          cli-version: ${{ env.cli-version }}
          args: '--environment _latest'

      - name: Pull translations
        uses: simplelocalize/github-action-cli@v2
        with:
          api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          command: 'pull'
          cli-version: ${{ env.cli-version }}
          args: "--pullPath ./translation-hosting-resources/ --environment _latest"

If you would like to filter files that are downloaded from Translation Hosting, you can use --filterRegex argument in the args field to specify a regular expression that will be used to filter files, eg: --filterRegex '_index.json' will download only _index.json file.

You can also change the environment that will be used to download translations by changing the --environment argument value.

GitHub Actions configuration

API Key

The api-key field is required, and it specifies the API key that will be used to authenticate the CLI. See where to find API key.

Command

The command field is required, and it specifies the CLI command that will be executed. GitHub Action supports all CLI commands. You can find the list of all available commands on the SimpleLocalize CLI GitHub page.

CLI Versioning

The cli-version field is required, and it specifies the version of the CLI that will be used in the action. You can find all available versions on the GitHub releases page.

Arguments

The args field is optional, and it specifies the arguments that will be passed to the CLI command. Every command has a different set of arguments. You can find the list of all available arguments on the SimpleLocalize CLI GitHub page.

Trigger workflow

You can also use SimpleLocalize to trigger a GitHub Actions workflows. In combination with the SimpleLocalize GitHub Action, you can create a fully automated translation pipeline in the way your team works. It's useful when you want to trigger a GitHub Action pipeline, e.g., somebody published translations to Translation Hosting, and you want to upload it somewhere else, or somebody exported translations from SimpleLocalize, and you want to process the file.

To start triggering GitHub Actions pipeline from SimpleLocalize, you need to create a new GitHub Personal Access Token (classic) with repo scope. After that, create a new webhook in the Webhooks section of your SimpleLocalize project.

webhook integration

Choose 'GitHub Actions' as a webhook type, enter your repository owner name, repository name, and token generated in the previous step.

Authorization: token {your_token}

Once you have created a webhook, you can use the following example to trigger a GitHub Action pipeline:

name: SimpleLocalize GitHub Action
on:
  # Allows external webhook trigger: https://api.github.com/repos/{owner}/{repo}/dispatches
  repository_dispatch:
    types:
      - simplelocalize_publication
      - simplelocalize_environment_publication

env:
  cli-version: '2.5.1'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      # Pull '_latest' translations
      # if 'simplelocalize_publication' event is triggered
      - name: Pull '_latest' translations
        uses: simplelocalize/github-action-cli@v2
        if: github.event.action == 'simplelocalize_publication'
        with:
          api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          command: 'pull'
          cli-version: ${{ env.cli-version }}
          args: "--pullPath ./i18n-latest/ --environment _latest"

      # Pull translations for the environment that was published
      # if 'simplelocalize_environment_publication' event is triggered
      - name: Pull '_production' or custom environment translations
        uses: simplelocalize/github-action-cli@v2
        if: github.event.action == 'simplelocalize_environment_publication'
        with:
          api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          command: 'pull'
          cli-version: ${{ env.cli-version }}
          args: "--pullPath ./i18n-${{ github.event.client_payload.environment }}/ --environment ${{ github.event.client_payload.environment }}"

The on.repository_dispatch.types field you can pass a list of events that will trigger the pipeline. The event name is always a combination of simplelocalize_ and lower case trigger value.

Troubleshooting

In case of any problems, please contact us at [email protected] or create an issue on GitHub.

Documentation