GitHub Actions

Last modified: April 13, 2023Author: Jakub Pomykała

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.

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.

Action step

By default, the action will try to find simplelocalize.yml file in the root of your repository and use it as a configuration file.

# simplelocalize.yml
apiKey: API_KEY
uploadPath: ./src/translations.json
uploadFormat: multi-language-json
- name: Execute 'simplelocalize upload' command
  uses: simplelocalize/github-action-cli@v1
  with:
    command: 'upload' # or 'download', 'auto-translate', 'publish', 'pull'
    cli-version: '2.2.0'
    # args: '--replace --delete --dryRun --uploadPath ./translations/{lang}.json'
    # you can pass additional arguments to the command using `args` input

Example workflow

The following example shows how to use the action to upload translations to SimpleLocalize, auto-translate them, download translated files and publish them to the latest environment, and finally pull _index.json file with all translations from the latest environment to the hosting directory.

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Upload translations
        uses: simplelocalize/github-action-cli@v1
        with:
          api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          command: 'upload'
          cli-version: '2.2.0'
          args: '--uploadPath ./translations/{lang}.json --uploadFormat single-language-json'
      - name: Auto-translate project
        uses: simplelocalize/github-action-cli@v1
        with:
          api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          command: 'auto-translate'
          cli-version: '2.2.0'
      - name: Download translations
        uses: simplelocalize/github-action-cli@v1
        with:
          api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          command: 'download'
          cli-version: '2.2.0'
          args: '--downloadPath ./translations/{lang}.json --downloadFormat single-language-json'
      - name: Publish translations
        uses: simplelocalize/github-action-cli@v1
        with:
          api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          command: 'publish'
          cli-version: '2.2.0'
          args: '--environment latest'
      - name: Pull translations
        uses: simplelocalize/github-action-cli@v1
        with:
          api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          command: 'pull'
          cli-version: '2.2.0'
          args: "--pullPath ./translation-hosting-resources/ --environment latest --filterRegex '_index.json'"

simplelocalize/download

Action downloads translation file(s) from translation editor to local files.

https://github.com/simplelocalize/download

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Download translations
        uses: simplelocalize/[email protected]
        with:
          apiKey: <YOUR_API_KEY>
          downloadPath: ./{lang}/translations.json
          downloadFormat: single-language-json
          downloadOptions: "ESCAPE_NEW_LINES" # optional
          languageKey: en # optional, it accepts only one language key
          customerId: ikea # optional, it accepts only one customer id

simplelocalize/upload

Action uploads translation file(s) from local files to translation editor.

https://github.com/simplelocalize/upload

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Upload translations
        uses: simplelocalize/[email protected]
        with:
          apiKey: <YOUR_API_KEY>
          uploadPath: ./{lang}/translations.json
          uploadFormat: single-language-json
          uploadOptions: "PUBLISH_AFTER_IMPORT,TRIM_LEADING_TRIALING_SPACES" # optional
          languageKey: en # optional, it accepts only one language key

simplelocalize/pull

Action downloads Translation Hosting resources from environment set in --environment and saves them in a directory set in --pullPath param.

https://github.com/simplelocalize/pull

name: 'My project'
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Pull translations
        uses: simplelocalize/[email protected]
        with:
          apiKey: <YOUR_API_KEY>
          pullPath: ./my-hosting/
          environment: latest # or 'production'

Sample output

Run simplelocalize pull --apiKey <YOUR_API_KEY> --pullPath ./hosting --environment latest
Established active environments: [cli]
Loading configuration file from: simplelocalize.yml
Configuration file not found
Found 14 hosting resources for 'latest' environment
Downloading ./hosting/_index.json
Downloading ./hosting/_languages.json
Downloading ./hosting/de_DE.json
Downloading ./hosting/de_DE/activity.json
Downloading ./hosting/de_DE/login.json
Downloading ./hosting/en.json
Downloading ./hosting/en/activity.json
Downloading ./hosting/en/login.json
Downloading ./hosting/fr_FR.json
Downloading ./hosting/fr_FR/activity.json
Downloading ./hosting/fr_FR/login.json
Downloading ./hosting/pl_PL.json
Downloading ./hosting/pl_PL/activity.json
Downloading ./hosting/pl_PL/login.json
Downloaded 14 hosting resources to ./hosting

Note that all saved files has .json extension.

Resources