.png?height=120&name=logo_blue%20(1).png){kind=logo}
The EasyTranslate Translation Action for GitHub and how to use it
What can it do?
When you need the strings for your app translated and your version control is done through GitHub, our Translation Action can help you keep everything synchronised. Simply build a String Library in your EasyTranslate account and save a copy of your strings to be translated. Then you can easily update them and pull them back to the branch you need them for.
Our GitHub action will help you synchronise your translation files from your source code into our String Library.
Index:
Create your file structure on EasyTranslate
Please be familiar with the general usage of GitHub actions when you start working with the EasyTranslate Translation Action. You can see their documentation here.
How to use it?
The action has 3 main uses: Push your files and structure to your EasyTranslate String Library for translation, pull them back when translated, and download the strings as .json files. Below you get all three explained.
Find more details about integration and the action itself in the GitHub marketplace here. https://github.com/marketplace/actions/easytranslate-translation-action
Create your file structure on EasyTranslate
First, you need to set up the String Library with your strings and structure by pushing the strings to your String Library on the EasyTranslate platform. Currently, this is available in i18n format. Push also works for updating your libraries.
If you have not set up a string String Library yet, you can see how to do so here. It can be done through both the platform and API.
When your pull request (PR) is open and labelled with push-easytranslate-strings it will trigger the workflow to call the EasyTranslate translation action. The action will push the strings found within the address pattern resources/files/**/**json. It uses the given access token to create or sync them with the string Strin Library you have selected.
Below, you can see a list of all the properties you need to update or pay attention to.
Example:
name: 'Push your strings to EasyTranslate'
on:
pull_request:
types: [ labeled ]
jobs:
download_strings:
if: $false
runs-on: ubuntu-latest
name: Send strings to EasyTranslate
steps:
- name: Checkout
uses: actions/checkout@v3
with:
token: $ <-- This is the github access token and needs to be stored in your repo (settings -> secrets and variables -> actions)
ref: $ <-- this needs to stay as is
- name: Execute our action
uses: "easytranslate-com/strings-library-github-action@v1"
id: push_easytranslate
with:
easytranslate_action: 'push'
source_language: 'en'
source_root_folder: 'files'
translation_file_paths: '**/strings.json'
target_languages: 'de,ja'
access_token: $ <-- This is the ET access token and needs to be stored in your repo (settings -> secrets and variables -> actions)
base_api_url: 'https://api.platform.easytranslate.com'
team_name: 'easytrranslatecom'
string_library_id: '63d0e5b923e85e42250de2ba'
- name: Show Response
run: |
echo $
echo $
Remember to update the following properties with the correct information.
token: Should be set in your own environment
source_language: You need to state the source language of your text
source_root_folder: Make sure it matches your setup and needs
translation_file_paths: Make sure it matches your setup and needs
target_languages: Input the languages the strings should be translated to
access_token: Should be set in your own environment
team_name: The team identifier you are connecting to.
string_library_id: 'easytranslate-string-library-id'
Create your file under .github/workflows/push-to-easytranslate.yml
Pull content back to GitHub
You can pull the content back from the String Library to GitHub at any time.
When your pull request (PR) is open and labelled with pull-easytranslate-strings it will trigger the workflow to call the EasyTranslate translation action. The action will pull all strings from the given String Library.
Please note this action only works if the strings are created using the push action.
Example:
name: 'Pull your strings from EasyTranslate'
on:
pull_request:
types: [ labeled ]
jobs:
pull_strings_from_easytranslate:
if: $false
runs-on: ubuntu-latest
name: Download strings from EasyTranslate
steps:
- name: Checkout
uses: actions/checkout@v3
with:
token: $
ref: $
- name: Checkout PR
env:
GITHUB_TOKEN: $
run: gh pr checkout $
- name: Execute our action
uses: "easytranslate-com/strings-library-github-action@v1"
id: pull_easytranslate
with:
easytranslate_action: 'pull'
source_language: 'en'
source_root_folder: 'resources'
translation_file_paths: 'files/**/**json'
target_languages: 'da,de'
access_token: $
base_api_url: 'https://api.platform.sandbox.easytranslate.com'
team_name: 'x-force-deadpool'
string_library_id: 'easytranslate-string-library-id'
- name: Update the pull request
if: $false
env:
GITHUB_TOKEN: $
run: |
git config user.name 'Your Name'
git config user.email 'Your GitHub email'
git add .
git commit -am 'Updating strings'
git push
Remember to update the following properties with the correct information.
token: Should be set in your own environment
source_language: You need to state the source language of your text
source_root_folder: Make sure it matches your setup and needs
translation_file_paths: Make sure it matches your setup and needs
target_languages: Input the languages the strings should be translated to
access_token: Should be set in your own environment
team_name: The team identifier you are connecting to.
string_library_id: The ID for your String Library
git config user.name. Add your Github username to authorise pull requests
git config user.email: Add your Github user email to authorise pull requests
Download translated files
If you prefer to have the translated content as files, you can download them as .json files as in the example below. The action will download all strings from the given String Library. The files will be downloaded in i18n format.
I18next is an internationalization-framework written in and for JavaScript. Read more about it here.
When your pull request (PR) is open and labelled with download-easytranslate-strings it will trigger the workflow to call the EasyTranslate translation action. The action will download all the strings from the selected String Library.
The files will be under the resources folder, and their file names will be based on the language code, so in the below example, 3 files will be created with the following names: en.json, de.json and da.json. Each file will contain the strings translated into the respective languages (da and de), and a file with the source (en).
The download_strings_format can be flat or nested.
If the value is flat the key names will be as string {"global.welcome": "Your Value"}. If the value is nested the key names will be as objects "{global": {"welcome": "Your Value"}}.
Example:
name: 'Download your strings from EasyTranslate'
on:
pull_request:
types: [ labeled ]
jobs:
pull_strings_from_easytranslate:
if: $false
runs-on: ubuntu-latest
name: Download strings from EasyTranslate
steps:
- name: Checkout
uses: actions/checkout@v3
with:
token: $
ref: $
- name: Checkout PR
env:
GITHUB_TOKEN: $
run: gh pr checkout $
- name: Execute our action
uses: "easytranslate-com/strings-library-github-action@v1.0.1"
id: pull_easytranslate
with:
easytranslate_action: 'download'
source_language: 'en'
source_root_folder: 'resources'
translation_file_paths: 'files/**/**json'
target_languages: 'da,de'
access_token: $
base_api_url: 'https://api.platform.sandbox.easytranslate.com'
team_name: 'x-force-deadpool'
string_library_id: 'easytranslate-string-library-id'
download_strings_format: 'flat'
- name: Update the pull request
if: $false
env:
GITHUB_TOKEN: $
run: |
git config user.name 'Your Name'
git config user.email 'Your GitHub email'
git add .
git commit -am 'Updating strings'
git push
Remember to update the following properties with the correct information.
token: Should be set in your own environment
source_language: You need to state the source language of your text
source_root_folder: Make sure it matches your setup and needs
translation_file_paths: Make sure it matches your setup and needs
target_languages: Input the languages the strings should be translated to
access_token: Should be set in your own environment
base_api_url: 'https://api.platform.sandbox.easytranslate.com'
team_name: The team identifier you are connecting to.
string_library_id: The ID for your String Library
git config user.name. Add your Github username to authorise download requests
git config user.email: Add your Github user email to authorise download requests
Translate
To translate the strings, you need to start the translation automation manually.
To start a translation manually, go into the String Library, select the strings you want to be translated, click the menu next to Add key in the upper right corner and select Start automation.
The strings will be translated as a grouped project to the languages set for the String Library.
See more about translation and projects here.
Limitations
Usage: Please note that your account with EasyTranslate has a limit on the amount of strings you can have in your String Libraries. You can see your limit in the platform under Settings and then Usage. Here you can also see how much you are currently using and options for upgrading.
Please be familiar with the general usage of GitHub actions when you start working with the EasyTranslate Translation Action. You can see their documentation here: