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 (recommended)
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.