[Main UI] How to organize i18n source files?

[Hilbrand]

To be able to internationalize the new ui all text should be put into the i18n directory (obviously). I want to create some of this. My question is. What is the best way to organize this? A js file per module? or 1 file? and what naming conventions for the keys should be used?

Regarding empty-states.json. In the empty-state-placeholder.vue it says TODO: i18n. Is that still relevant?

[ghys]

Good question, getting the i18n infrastructure right the first time is actually a pretty complex matter, which is probably why I've been avoiding it and postponing it for so long ;)

The contents of the i18n folder and their format with empty-states.json and so on were temporary until we get that i18n infrastructure done, so they will likely change.

First we need to choose the framework, for Vue projects there's basically vue-i18n, vuex-i18n and vue-i18next.

• vue-i18n is by far the most popular and adopted, it has a good feature set, good documentation and the best tooling (I especially like vue-i18n-extract)
• vuex-i18n is interesting as well since it uses Vuex, but a little more niche;
• vue-i18next is based on the larger i18next which is framework-agnostic and has the best features wrt. pluralization rules etc. and can work with gettext .po/.pot files which worked really well for HABPanel.

I'd tend to go with the safest and probably better supported choice - vue-i18n.

Now to organize the translation files, there are a lot of options.

First we need to make sure that whatever we decide plays nice with Crowdin, as I suppose we'll keep on using it to crowdsource the translations (no real need to change and the other projects already use it).

Second, since we can expect to have translations in 20+ languages and don't really need to dynamically switch (the locale is loaded from /rest/ before anything is displayed), I think it's obvious that we don't load them at once and do lazy loading at least to filter out the messages in the other languages. One exception could be the setup wizard where it could be nice to switch after you set the language on the first screen. Not sure if it's really necessary after saving the regional settings, a page refresh does the trick and isn't too much of a hassle. We can actually just do that - refresh the page - if the language/region has been changed.

Third, there's already quite a bit of lazy loading of the module themselves, to avoid loading code from some areas before the user actually goes into it - especially if there's a big dependency. If there's a significant amount of translations for an area, we might choose to split these messages into files specific to this area, I think it has to be examined on a case-by-case basis, but a lot of messages could probably go to a pool of "shared messages" without it becoming too big. Lazy-loading also implies HTTP requests which induces a lag, if it's too frequent and perceptible that's not good, so we shouldn't abuse it.

Finally, support for config descriptions (to localize the widget configs, metadata namesapces like Alexa/Google Assistant and so on) and the cron editor probably have to be implemented separately.

For keys, I usually ruled out Fallback interpolation since having the actual English messages as keys is kinda ugly, but on the other hand, there are benefits to it - not having to move these English messages to assets, and finding good descriptive key names. With Crowdin and vue-i18n-extract we can probably make it work. I'll make some experiments but I'd also like to have other opinions about this.

[Hilbrand]

First we need to choose the framework

I'd tend to go with the safest and probably better supported choice - vue-i18n.

I would agree. it seems much more active than the other. So does indeed look like the safest option. But it seems vue-i18n is being moved to vue-i18n-next, but that is not yet stable and to make things complicated, this is something different than vue-i18next...

First we need to make sure that whatever we decide plays nice with Crowdin

Agreed. Based on what I found about this it seems to be compatible. I did see that there was an issue where if no translation available Crowdin returns an empty string, and vue-i18n will than render the empty string instead of fallback. However this can be changed in Crowdin in settings and there might be a fix already in vue-i18n. Mentioning just in case.

For keys,...having the actual English messages...

This looks interesting. But for longer sentences or complete text blocks this seems less attractive. As a simple change in a text block would mean a change in key. So in general I would lean to not use the text as actual key.

[ghys]

This looks interesting. But for longer sentences or complete text blocks this seems less attractive. As a simple change in a text block would mean a change in key. So in general I would lean to not use the text as actual key.

You're right, but I believe we could do both - for strings like 'Check the channels you wish to create as new Point items. You can alter the suggested names and labels as well as the semantic class and related property., obviously a technical key is better, but for simple labels like 'Equipments', 'Locations', 'Close' or even 'Developer Tools' or 'Help & About' which won't probably change much I'm also fine with the English label itself as the key. If we use common sense, I wouldn't mind mixing the two.

That way i18n doesn't get in the way for obvious strings when adding new stuff, we can simply use $t('Edit') and others instead of simply 'Edit' - if they're unique - and not bother looking up translation keys unless it's strictly necessary.

[kaikreuzer]

I suppose we'll keep on using it to crowdsource the translations (no real need to change and the other projects already use it).

Yes, I'd say so, too. Actually, we should think about the other UIs in this repo as well, when enabling this repo for Crowdin.
We e.g. currently have https://crowdin.com/project/openhab-habpanel, which we should somehow migrate over (@ghys it seems we have quite abandoned them since almost two years...? See openhab/org.openhab.ui.habpanel#351)

[ghys]

I'd like to revive this because it would probably be nice to have at least some localization for the non-admin parts in major languages for the 3.0 release.

According to the analytics on the website, the audience's top 10 configured languages in their browsers are, in order:

rank	language
1.	en-us
2.	de-de
3.	de
4.	en-gb
5.	it-it
6.	en
7.	ru-ru
8.	nl-nl
9.	fr-fr
10.	es-es

And here are the top countries of origin, since visitors might have a preference for English while users would prefer their mother tongue (or their country's dominant language):

rank	country
1.	Germany
2.	United States
3.	United Kingdom
4.	Italy
5.	Netherlands
6.	Austria
7.	Russia
8.	France
9.	Belgium
10.	Switzerland
11.	Poland
12.	Spain
13.	Canada
14.	Australia
15.	Sweden

The 16th country (India) is below 2% of the total audience.

I think given who's active here we can easily do German, Dutch and French, at least, even without Crowdin next week. It will cover Austria, Belgium, (most of) Switzerland and Canada. Italian, Russian, Spanish, Polish, Swedish (and any other!) would be a plus and be welcome if someone reacts quickly enough.

The scope would only be what's displayed to users, while the admin sections would remain in English for the time being. Replacing every text by translate directives is a painful and thankless task.
By user-facing I mean tab labels on the home page, the profile page, the about page, maybe a translation for the equipment & property cards - for those we could borrow from https://github.com/openhab/openhab-core/tree/master/bundles/org.openhab.core.semantics/src/main/resources - and some common words like "Back" or "Cancel" etc.
Also the login/authorize page in core.
The setup wizard (even if it's not strictly for users) would be the cherry on top, to give a good first impression.

Wdyt?

[TBail]

I am with you that we should able to do the "main" languages in a very short time.

To bring the community closer to the developers i would stick with crowdin. For many people the git hurdle is to high to contribute.

I am not sure if a mixture between english and another language is a good thing. I see that in some bindings and find it anoying to have one channel in englisch and another in german. So even if it is painfull we should do that. And yes i will help on that.

[ghys]

I am not sure if a mixture between english and another language is a good thing. . I see that in some bindings and find it anoying to have one channel in englisch and another in german.

I agree with you, that's why for now I don't even think it's that necessary to translate the admin area at all. A large part of the labels and messages are dynamic, coming from the API (even in the main settings menu, the right column are the service names) and most aren't translated.
Admins should therefore be fine with English, since they have to understand these messages anyways. Then when we have a significant part of the thing types, channel types and so on with translations, we can start thinking about localizing the admin pages completely.

[comradekingu]

Just having a gander at projects still using Crowdin, and trying to find out how that came to be.
Suggested moving at FOSDEM a good many years ago, but maybe it isn't a big priority because it can keep being a bit so-so?

First we need to make sure that whatever we decide plays nice with Crowdin, as I suppose we'll keep on using it to crowdsource the translations (no real need to change and the other projects already use it).

Once done, I think moving ship is the biggest problem to solve.
https://docs.weblate.org/en/latest/formats.html
→https://docs.weblate.org/en/latest/formats/i18next.html

To bring the community closer to the developers i would stick with crowdin. For many people the git hurdle is to high to contribute.

Weblate has direct linking to source for every string, and even direct editing of source strings if needed.
The underlying issue to solve is first and foremost that there is no community between translators on Crowdin.

[florian-h05]

I will close this issue now as we have i18n support in MainUI and the question how to structure the translation files is obviously solved now. One can have a look at the i18n folder on how to do it.