Dev Notes for Translating Bahmni using Transifex

The Basics

Translation to any non-English language needs to happen via the Bahmni project on the Transifex website.
The dev team owns all the locale_en.json files, and Transifex owns all the other locale_<lang>.json files.
1. You should continue to add new messages in the locale_en.json files in the source code
2. You should continue to also modify existing English messages in the locale_en.json files in the source code, just as you always have.
If you add a new app with a new set of locale_<lang>.json files, you need to configure transifex for this. See below.

Non-English Translation Files

Do NOT put any non-English translations directly into the source code (because we will be downloading translations done on the website, and this is done blindly, without any merge process). Hence all strings in other language files will be overwritten with what we get from Transifex.

More Details

The Bahmni Transifex project is under the OpenMRS project. This allows Bahmni and OpenMRS teams to share translators, and to share translation suggestions across multiple OpenMRS distributions, since most vocabulary and terms are similar.
Underneath the Bahmni Transifex Project, are multiple Resources (one for each locale_en.json file).

Changing an existing English message will invalidate any translations for that message, and they will need to be translated again. This is intentional. Even if you didn't change the message key, any existing translations were done against a different text, so for safety they are presumed to be invalid, and need to be re-translated.

What we still need to do

Define and document a process for if/when translations are reviewed and pulled into the codebase.
Configure our build pipeline to automatically pull in (reviewed) translations.

How to add a new app

If you add a new app, with a new set of locale_<lang>.json files, you need to add this as a new resource in Transifex, and add it to the .tx/config file in our codebase.

First, to add the resource on Transifex (you need maintainer privileges for this):

Go to https://www.transifex.com/openmrs/bahmni/content/, Add Resource, and upload the initial locale_en.json as a Key-Value JSON file.
From within the newly created resource, go to Settings and add a category (e.g. "core" if it's part of the core Bahmni application)
Back at https://www.transifex.com/openmrs/bahmni/content/ click Auto Update Resources and put the "raw" github link to the locale_en.json file.

Second, to update the our .tx/config file, you can use the transifex client app to do this (from the root of openmrs-module-bahmniapps):

tx set --auto-local -r bahmni.clinical-app 'ui/app/i18n/clinical/locale_<lang>.json' --source-lang en --type KEYVALUEJSON --execute

You don't need to use the transifex client app: it is straightforward to copy-paste-edit from an existing resource description in .tx/config.

Then push these changes up to github.

Transifex CLI Script

The transifex.sh script is a tool designed to allows users to push source files for translation to Transifex or pull translated files from Transifex to their local repository.

Prerequisites

Before using the Transifex CLI script, ensure that the following prerequisites are met:

Transifex CLI: The script requires the Transifex CLI tool to be installed. If you don't have it installed, the script will automatically download and install it for you.
Ensure that you have a Transifex configuration file (".tx/config") in your repository. This file should contain the necessary configuration settings for your Transifex project.

Usage

To use the Transifex CLI script, follow these steps:

Step 1: Download the Script

Download the script to your local repository. You can do this by downloading the script code from our bahmni-infra-utils repository, and saving it to a file with a ".sh" extension, such as "transifex.sh".

Step 2: Set Permissions

Make the script executable by running the following command in your terminal:

chmod +x transifex.sh

Step 3: Run the Script

To push the translation source file to Transifex, run the script with the "push" argument:

./transifex.sh push

To pull translations from Transifex, run the script with the "pull" argument:

Note: Replace "./transifex.sh" with the actual path to your script file if it's located in a different directory.