Table of contents
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@v3
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@v3
with:
api-key: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
command: 'auto-translate'
cli-version: ${{ env.cli-version }}
- name: Download translations
uses: simplelocalize/github-action-cli@v3
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 --overwrite 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@v3
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@v3
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.
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@v3
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@v3
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.