O3: Localization strategy for text from coded concepts

This example came up today in a prep call for the Ampath 3.x pilot. They don’t need translations but we expect others will (e.g. Mekom & PIH distros).

In the Lab Results viewer, we can now see text-based results. These are shown based on concepts. The question is: How would you auto-change the language of the text when the user changes their locale?

From PR for O3-1028, thanks to @dkibet

I am assuming our approach will involve these 2 steps, but I want to confirm with others here:

Step 1: Add alternative translations in your Concept Dictionary. e.g. if we wanted to see “POSITIVE” in Spanish, we’d make sure there was a translation available like so:

Step 2: When user changes their locale, the software automatically also applies any text from that locale (so picking “es” would auto-change the “Positive” results to be shown as “Positivo”). (The locales should be standardized based on ISO 639-1.)

I think there is still work to do to enable Step 2. Does this general design/flow match what folks were thinking?

CC @dkayiwa @mksd @bistenes @jdick

1 Like

(and thanks to @ball for making me aware of this helpful documentation so I could experiment a bit in our 3.x demo environment: Localization and Languages - Documentation - OpenMRS Wiki)

I’ve been thinking about this for a while, and we should definitely improve this indeed. By “this” I mean having the ability to flick the locale through the menu and see the effect right away on the screen. Right now the only way for another locale to properly get applied is to reload the page, right, is that what you mean @grace?

I think all translations for the configured available locales should all be brought in through web responses. That way all L10n-ble terms would have all their translations made available to the frontend and our frontend would be able to pick the right one based on the selected locale through the locale menu.

For instance if the available locales are en and fr, right now we are GETting stuff like that from the backend (pseudo code here):

  "entity": "encounterType",
  "name": "Vitals"

We should rather GET something like:

  "entity": "encounterType",
  "name": "Vitals",
  "display": {
    "en": "Vitals",
    "fr": "Signes vitaux"

This would allow our frontend to have all possible display strings at hand at all times for all pieces of data that can be L10n, which should be all metadata, including concepts of course.

At least for concepts, initially the FHIR2 module sent all available translations of the concept… This turned out to be extremely unpopular with, well, anyone who had to look at the FHIR data as there are a lot of translations for many concepts, so things have shifted to use Concept#getName() which is sensitive to the current user’s locale.

That said, I think @mksd’s idea is probably the right way to go… It’s really the only way to get “instant” updates on the client side. The options (broadly speaking) are:

  1. The backend does the translation itself, meaning that the frontend will need to reload anything that might’ve changed when the locale changes.
  2. The backend does no real translation itself and just hands off all possible translations to the frontend.
  3. As above, but the backend returns only the values for a configurable set of locales, e.g., only those in the locale.allowed.list global property.
1 Like

I’m wondering how common or important this use case is? Do users typically choose to change language frequently when using the application? I would think this is the kind of thing that most users set once and never change, and that this describes more of a developer/implementer need as something they want to do to ensure the site is localized or to view the site as other users may see it. Not that this is an invalid need, just trying to pressure test the requirement.

1 Like

I don’t think it’s necessarily a frequent one, but it is a bit of a first impression one, e.g., if I change the language from English → French (even if it’s only the first time I login to the app), I’d expect that the UI would update. Having to manually reload the page (not a big deal, but something non-technical users often don’t think about doing) seems to provide a worse user-experience. I suppose that the UX can be more easily addressed, e.g., by changing things so that changing locale actually does a page refresh.

1 Like

Agreed, or if we decide that setting the locale is a session action, then it should only be allowed when the session is first put together: so “at login”. In our case this could happen at the location picker screen, since for entreprise setups the login screen itself goes away (since authentication happens elsewhere).

That may sound awkward but is IMO less clunky and misleading from a UX perspective than leaving the impression that the language can be flicked at all times.

To clarify, this was what I had in mind.

From a platform team perspective I think we should already implement things that way, i.e. all pieces of metadata should carry their set of allowed/configured display strings at all times. Simply because it is fairly easy to do. The scope creep is more on the frontend side…

@mseaton flicking the locale from within the app is not yet a hard requirement, but in my experience and looking at certain projects coming down the line I see it coming in multiple places. And anyway I favour the idea that we anticipate the architecture with this goal in mind.


Yes it does. :slightly_smiling_face:

This is one of those areas where i would say, let us keep it simple. When some one changes the locale, just do a full page reload. Preloading all allowed locales, does not only require more developer effort, but also consumes more browser memory, more network bandwidth, for a rarely used feature. Even those that use it, they do it once. Am assuming that the user’s preferred locale is saved and always loaded as the default when they log in. Am also assuming that we still have resource constrained environments, in mind. :slightly_smiling_face:


100% agreed with all Daniel’s points above.

Sorry for being late to this discussion. We had previously put a lot of thought into the notion of concept name translation at MVP. We never really got it fully implemented and it also involved being able to translate the “captions” on forms as well. We tried to include these in the dictionary but it was too tightly coupled to the data later. But going to the concept name translation, the thought was to create a “preferred in locale” flag (which was created) to auto translate if the locale was changed. There was also the idea that there should be a preferred train of translation languages which would be used. For example, if you translated from Spanish to English, it would initially look for the preferred in locale in the specific language (en_uk, etc.) and if there were no preferred translations or any in en_uk it would default up to en, etc.

Since CIEL does not enforce translations in all locales, we assumed that the final translation would also default to English.

Lastly, there was some discussion that when translations were auto-generated, the original name in the original language should also be shown.

Agreed with Daniel, Grace, and Mike on this one. Adding a bunch of network overhead in order to support language switching without reloads is, in my opinion and in the absence of clear evidence to the contrary, not worth it.

Changing locale should of course trigger a refresh automatically; the user should not have to refresh it themselves. This should be ticketed.

And yes, @grace , that’s how I would expect the translations for lab results to work.