The GitHub Action

The EasyTranslate Translation Action for GitHub and how to use it

et-translation-action

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 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

Pull content back to GitHub

Download translated files 

Translating the strings

Limitations

 

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 library for translation, pull them back when translated, and download the strings as .json files. Below here you get all three explained.

 

Find more details about integration and the action itself in the GitHub marketplace here. [LINK:GitHub marketplace: https://github.com/marketplace/actions/easytranslate-translation-action ]

 

Create your file structure on EasyTranslate

First you need to setup the library with your strings and structure by pushing the strings to your library on the EasyTranslate platform. Currently this is available for i18n format. Push also works for updating your libraries.

If you have not setup a string library yet, you can see how to do so here. It can be done through both the platform and API.

Our API documentation can be found here.

 

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 library you have selected.

 

Below the example 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: $
ref: $

- 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: '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'

 

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 identifyer 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 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 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 identifyer 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

 

undraw_Firmware_re_fgdy

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 library. The files will be downloaded with 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 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 identifyer 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.

startautomationTo start a translation manually, go into the library, select the strings you want translated and click the menu next to Add key in the upper right corner and select Start automation.

The strings will be translated as individual projects to the languages set for the 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 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: 

[LINK: https://docs.github.com/en/actions/using-workflows