How to automate localization in the Bonita UI Designer

The Bonitasoft presales team often uses several applications in our showroom, built with fragments and using localization. Like you, in development teams, they want to improve the efficiency of their development and optimize the maintenance of their applications.

After a first step using a single localization file in one of the showroom applications, they decided to integrate Crowdin into their build pipeline to get rid of the copy-paste pattern and ensure that the same key will be displayed in the same way in all the showroom Living Applications' pages and forms.

The goal now is to automate the localization process through an integration with Crowdin and GitHub.

Since Bonita UI Designer & Crowdin don’t use the same approach about localization assets, we will need to add pre & post steps to integrate automated GitHub actions based on translator work.

Note: We use Crowdin in this example because it’s the translation manager we use to translate Bonita, but you could use another TMS, such as https://weblate.org/en/.

Localization in Bonita UI Designer and in a translation manager. How does that work?

In Bonita UI Designer, each page contains an asset file called localization.json which contains all translations. This file contains keys (in English) and the equivalent in each language.

Therefore, if you use the same localization.json for all your pages or if you use fragments, your only option is to modify all the localization.json on all your pages if you need to modify a translation or a key.

On its side Crowdin (or another translation manager) imports a source file with translation keys and will generate a localization file per language.

Automate your translations in a few steps

We are now going to see together the different steps to automate the localization. The example we use is based on an application called "Invoice management" and using fragments.

Translate your localization.json

• A Crowdin project called showroom is created with 2 languages: French and Spanish.

In this project, we are going to set up an integration with GitHub to automate translations.

• From Crowdin, connect the GitHub repository of your project and configure it to set the localization file as a source.

Your translated files will be automatically added in your project thanks to automated pull requests, as stated on the screenshots below.

GitHub PRs

Files added to your project and visible in Bonita Studio

As Crowdin is going to create one localization file per language, we need to concatenate them to fit the Bonita UI Designer rules (a single localization file per page)

Automate the creation of the Bonita UI Designer localization file through GitHub actions

GitHub actions are used to

• Prepare a file in the right format for Crowdin by scanning all files and creating a single file (crowdin.yml) with all keys readable by Crowdin. This is done using a java program for GitHub actions called crowdin-util which exports and imports sources and adds keys.
• Import the crowdin file and duplicate it in all pages and fragment files of the repository

Here you will find both workflows and crowdin configuration file:

• exportCrowdinKeys.yml

name: Export Crowdin keys

on:

 push:

   branches-ignore: - 'l10n**'

   workflow_dispatch:

jobs:

  exportCrowdinKeys:

     runs-on: ubuntu-latest

     steps:

        - uses: actions/checkout@v2

        - name: Set up Java uses: actions/setup-java@v2 with: java-version: '11' distribution: 'adopt'

        - name: Get localization keys jar run: | pwd ls -ltr cd localization mvn -s settings.xml -DGITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} clean dependency:copy -Dartifact=com.bonitasoft.localization:crowdin-utils:0.0.4 - name: Run import run: | java -jar localization/target/dependency/crowdin-utils-0.0.4.jar /home/runner/work/app-InvoiceManagement/app-InvoiceManagement exportKeys

        - name: Git status run: | cd /home/runner/work/app-InvoiceManagement/app-InvoiceManagement git status

        - uses: EndBug/add-and-commit@v7 # You can change this to use a specific version name: Commit new keys with: add: 'localization/localization*.json --force' message: 'add new localization keys'

• importCrowdinKeys.yml

name: Import Crowdin keys

on:

 push:

   branches: - 'l10n**'

 workflow_dispatch:

jobs:

  importCrowdinTranslation:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v2

      - name: Set up Java uses: actions/setup-java@v2 with: java-version: '11' distribution: 'adopt'

      - name: Get localization keys jar run: | pwd ls -ltr cd localization mvn -s settings.xml -DGITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} clean dependency:copy -Dartifact=com.bonitasoft.localization:crowdin-utils:0.0.4

      - name: Run import run: | java -jar localization/target/dependency/crowdin-utils-0.0.4.jar /home/runner/work/app-InvoiceManagement/app-InvoiceManagement importKeys

      - name: Git status run: | cd /home/runner/work/app-InvoiceManagement/app-InvoiceManagement git status

      - uses: EndBug/add-and-commit@v7 # You can change this to use a specific version name: Commit new translations with: add: '**/localization.json' message: 'add new localization translation'

• crowdin.yml

"files": [

     { "source": "/localization/localization.json", #source files filter

     "translation": "/localization/localization_%locale%_crowdin.json"  #where translations are stored

     }

What about new pages?

If you have a new page with new titles or keys, you will have to initialize them in your localization.json source file, as described below.