Localization / translation best practices - Follow Up

[todor-dk]

Moin.

I've read issue #270 , which has many hints on how to localize the software. I would like to improve the English translations, at least for the items that my system supports. I've made a list of items that I need to translate. But I do have some questions.

1. Some items are already translated, but the current translation differs from what I can find in the manuals and also from what the display on my boiler's controller actually shows. Example: 730: Current: "Summer/winter changeover temp", Shown by controller: "Heating limit" (somewhat closer to the German text). 750: Current: "Room temp gain factor", shown by controller: "Room influence". What is the procedure here? Do different systems / controllers reuse the command numbers for different purposes or call the commands something substantially different? And if so, how do we handle this?

2. I understood that memory is very limited on some devices, therefore we try to avoid having duplicate strings. Likewise, we keep the strings relatively short. a. Is there is list of commonly accepted abbreviations to use? For example: DHW, HC1, Temp etc. b. Can't we get the compiler to do string interning (instead of having to de-duplicate by hand)? c. Do we have build tools to give us some indication on how much memory the strings are using and how close we are to the memory limit on different devices?

3. I see that there is an open PR #418 with new translations. If I am to work on better translations, should I take the master branch and work from there or the PR?

4. Just to confirm - it's not possible to have several language simultaneously in a compiled version and have an option to choose the language via the Settings UI - all due to memory limitations. Finally, the LANG C is used for the AJAX front-end, so it can read/parse the information it needs.

5. Finally, has anybody been able to find an English manual for Brötje BBS 15 C or an LMU74/75 based system?

Thanks.

[dukess]

Hi! 2b - unfortunately, no. GCC have "-fmerge-constants" option but it works not for all cases. 2c - just compiling with selected language and all ebabled modules. 4. Yes, you right.

[fredlcore]

Yes, there are no unified translations across heaters and brands. For new parameters, we take the description from one of the manuals or from the heater itself and we only add a different translation if the meaning changes significantly. For the examples that you have given that would not be the case, because despite the quite different wording, the meaning can still be understood in both ways - and most importantly, the function of 730 and 750 is the same across the board.

In addition to the caveats that @dukess has mentioned, I'm reluctant to just let everyone start to translate the texts, at least for the English translation that I'm able to verify. First of all, it is not enough to just use "Google Translate" for example and come up with a translation that may or may not be accurate. We're talking about technical terms here where meaning might easily get lost. And secondly, you cannot even just use your manual and start taking the parameter descriptions from there blindly. For many parameter numbers, the function is the same across all brands that we have come across so far. But quite a few differ from each other. So you would always have to check back with the German version and see if that description is matching the English translation in your manual. Just to give you one example: Parameter 8321 could either be "Aktuelle Regeldifferenz" or "Primärtauschertemperatur". If you don't know the German meaning, you won't know if your description in your English manual can be used or if you have to add a new text to the code. We would need someone who speaks both English and German and has the time to do the translations thoroughly. Otherwise it's just fitting for one person's machine and the rest will be "Kraut und Rüben" ;)...

[todor-dk]

Thanks. But this was already answered by #270. Of course I won't Google translate the texts. I do understand and read German decently, just that I am not good at writing.

My idea was to take the English texts directly from the display on my controller / boiler and if possible compare them to a reference English manual and double-check them against the German texts. This is where I discovered that there are some inconsistencies. But your answer is clear - keep the existing translation, even if deviating.

Do you still want help with the missing texts? Or should I just create a private branch.

If so, I would still like to know when the binary will reach the limit of the smaller devices. Dukess wrote to compile with all features "on". But what is the target size for smallest devices that BSB-LAN supports?

[fredlcore]

Well, of course any help that fits the above requirements is welcomed, so if you understand and read German decently, you'll be able to spot the differences if there are any.

And just to be clear, my point is not to keep the existing translation even if its deviating - it depends if there is a deviation from wording or in meaning. In case of the former, the translation stays, in case of the latter, we would have to add a new line in cmdtbl and create a new description string etc.

I'm not sure why the memory size would matter in that respect. Since for every non-existing translation, the German term is used, memory consumption will vary only very little even if all terms are translated into English or any other language. The reason why we don't want duplicates is that these would have to be translated multiple times as well, and in all languages. Also, duplicates increase the likeliness of typos if you have to enter the same term multiple times in locations possibly far away from each other etc.

[todor-dk]

OK. I understand the de-duplication strategy. There are few cases where the English text is marginally longer then the German. But I guess we are talking about max. 500 bytes in total.

If the deviation is insignificant, I will keep it. If it is larger or I am unsure, I will ask.

When you write "we would have to add a new line in cmdtbl". Are you talking about texts where there are different meanings, like 866 and 866_2? If I understood the cmdtbl logic correctly, some entries are device specific and therefore the alternative texts. #define STR886_TEXT "Norm Außentemperatur" #define STR886_2_TEXT "Pumpendrehzahl Maximum OEM"

[fredlcore]

Yes, so far we only had different meanings across device families or device variants. Not within the same device family/variant. Often times, not only the meaning differs, but also the Command ID and/or the data type etc. So if there is a difference in meaning, there has to be a new line in cmdtbl one way or the other...

[1coderookie]

Hi

I've read issue #270 , which has many hints on how to localize the software. I would like to improve the English translations, at least for the items that my system supports. I've made a list of items that I need to translate. But I do have some questions.

You said, you've made a list of the items you have to translate. Maybe post it, so that we can have a look at it and/or @GSzabados also can compare it with his work. I'm kinda curious anyway which parameters aren't translated yet that you want to come up with, especially cuz you have a LMU7x, which isn't the latest controller out there.

2. I understood that memory is very limited on some devices, therefore we try to avoid having duplicate strings. Likewise, we keep the strings relatively short. a. Is there is list of commonly accepted abbreviations to use? For example: DHW, HC1, Temp etc.

No, there isn't. In issue #283 we had a short discussion about this and came to the conclusion, that it would be best to write down the full names without abbreviations.

3. I see that there is an open PR Improved English translation for 8000-8011 parameters #418 with new translations. If I am to work on better translations, should I take the master branch and work from there or the PR?

What do you mean with "better translations"? As @fredlcore already mentioned, these are technical terms, so there shouldn't be a 'better' alternative. If you don't find the expression of a parameter either in your operational unit or in an official manual, then better don't touch it. Afaik @GSzabados mostly is using english manuals to look up the wording. And as @fredlcore already said, one should not use Google translations or whatsoever.

5. Finally, has anybody been able to find an English manual for Brötje BBS 15 C or an LMU74/75 based system?

Unfortunately not, the manuals from Brötje are mostly in German language. Also for the LMU7x in general I only have a technical datasheet from Siemens in English language, but no user manual where the programs are listed/described.

Btw: Please send us (fredlcore and/or me) an email with the exact name of your heating system and the full output of /Q if you didn't already.

[GSzabados]

Hi @todor-dk,

All the translations in the #418 are from English manuals matched with the German manuals what I could find on Brotje's website and I have got from @1coderookie. Unfortunately different versions of the manuals have different wording for a few things, even on the same language manuals (both German and English manuals had different wordings for the same thing, but both understandable and meaning the same). So all the translations there contains the "official" technical terms.

I started a bit of a wrong foot with my translation as I started with a manual and listed all the parameters what I needed, and then I found the document about how to do the translations, and I was a bit off, but managed to sort it out.

That's how I did it, and maybe not the easiest, but a workable approach is to place the German translation into an Excel spreadsheet, separate the parameter number. Place aside the current English translation to match the parameter numbers and then you see what is missing currently, then look up the parameter number in the manuals both English and German, and add the English translation to where it is missing. At the end you can end up with a complete list of translations. Excel is easy to be able to format and concatenate things to the format how the translation file should be, so after that it is just a copy and paste to a text file. If you work your way from top to bottom in the manuals, then you can fulfill everything in order, as the numbers are in increasing order, except when it is a sub-thing, like the heater or burner states, then it is all over the place in the range of parameters. (If you look at the manuals you will understand what I mean.)

Best Regards,

Gábor

[todor-dk]

Hi @GSzabados,

I did something similar to you. I re-arrange few entries LANG_EN.h to follow the order in LANG_DE.h. Then I wrote a script to process both files and insert dummy lines in LANG_EN.h for the missing entries. This resulted in two files that are nearly identical when it comes to line numbers (the English has 2-3 entries not found in the German file). This means that I could open both files side-by-side in Notepad++ and scroll from top to bottom and match the corresponding lines. The dummy entries added by the script make it easy just to fill the missing English text. But this was the easy part.

Finding the correct English translation is the headache. Like you, I've leached the internet for every English (and German and Danish) manual I could find. I came to the conclusion that the same command numbers have changed the nomenclature in the English manuals over time. The older systems (from the laste 2000's) use slightly different nomenclature than the newer systems (from the late 2010's). A stupid example was is the Occupancy or Presence button. This is called different in different English manuals. The same applies to more complex / technical terms. I decided to call the button Presence/occupancy button.

The second issue is that apparently some manufacturers mapped the more exotic commands to a slightly different meaning. I believe that this is due to the fact that Siemens produces a general purpose controller that can be used in many heating related applications. Nobody says that the pump connect to let's say output 2 on the controller has to pump the HC2. For some applications it may circulate the water in a swimming pool.

After trying the approach of going systematically trough a manual (I chose RVSx3, AVS75, AVS37 etc. User and OEM Manual from Siemens, as it seamed the most comprehensive one), I discovered that this did not work. Many items deviated substantially from the existing German translations. I decided to be very conservative and translate only things that are very close to the existing German text. I would also consult the German and Danish manuals that I had and if there was a deviation in the meaning, I would skip the command. This helped, but turned out to be a less productive approach that I expected.

Finally, as most people are egoistic and do what they need for themselves, I decided to concentrate on the strings that I need for my boiler. I made a list of all items that BSB-LAN had on my boiler. I wrote a script to generate an Excel with the command items that my system supports and a column with the English translations and the master German translation. Then I went trough every item on the display on the boiler (set to English) and compared it to what the Excel had. If a translation was missing, I took it from the display of the control unit. After all, if the life system uses it, it must be correct. Of course, I did double-check with the German reference strings that the meaning is the same. If there was a deviation, I left it untranslated.

It's my birthday today, so I will spend time drinking and eating. Tomorrow, we have a major release for the app I am developing at work, so there will be very little time for BSB-LAN'ing. But I hope that the upcoming weekend or between Christmas and New Year will give me few days to finish the translations. I will look at how to merge #418 with my work and submit it to the BSB-LAN devs.

Best Regards/MFG, -Todor

[1coderookie]

So HAPPY BIRTHDAY to you Todor! :birthday: :partying_face:

For the naming of that presence/occupancy button, please go for "presence", as we refer to it like this and as I also use the term "presence button" in the BSB-LAN manual: https://1coderookie.github.io/BSB-LPB-LAN_EN/chap06.html#64-simulating-the-presence-function EDIT: And cuz it's called "Präsenztaste" in German..

[fredlcore]

Yes, happy b'day from me too, and thanks for your efforts! I think the "egoistic" way is the best because you are correct about the life system which must be correct for your heater. Only then we'll know for sure what matches and what doesn't...