Language in CumulusUtils

From Cumulus Wiki
Revision as of 08:11, 12 April 2021 by HansR (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Introduction

It is fairly common in the Cumulus community to have dynamic language switch possibility on the website. That is not the approach for CumulusUtils. CumulusUtils takes the approach to set the language at compile time i.e. all strings are placed in a language file and the user can translate himself. The idea is that local websites are basically used by locals who need local language. The programming effort to change language dynamically is considered too big.

Translations are shared in a sticky thread on the forum. You can ask the original poster of a language file to add your modifications or you can post your own language file.

Setting the Language

The language for CumulusUtils is set in the cumulusutils.ini file with the parameter - surprise, surprise - Language. The default language is British English and after the first run - when the inifile is created - the user can change the language.

The choice has been made to use the Windows Language Code Identifier (LCID) Reference (you will find the codes in this pdf document) with only the five position codes as valid. So for British English the code en-GB is used. The first two digits determine the language, the last two digits determine the country and therefore the locale.

NOTE: be aware, that using a locale different from the one used for CumulusMX you may run into problems. Especially the abbreviated month names cause trouble because they are used for creating the file names for the monthly log files. If you doe not seem to be able to solve the issue, please contact @HansR on the forum. See: Trouble in Paradise.

Any entry of a language code other than five digits or invalid language or country will trigger an error and fall back to the default en-GB.

Both the CumulusUtils Gauges and the CumulusUtils Graphs (made with HighCharts) have their own language subsystem. If anywhere the languages don't match it is seen as an error with a fall back to the default of en-GB. The gauges language file (language.js) is part of the gauges subsystem but can be modified in concertation with Mark Crossley who then will put it back into the gauges repository and I will take it up in the CumulusUtils distribution. An example of this is the the now presence of two Norwegian languages. A new language must also be acknowledged by HansR for CumulusUtils to make the new language code accepted.

The current languages defined and accepted are:

   EN, FR, DE, NL, SE, DK, FI, NN, NB, IT, ES, CT, GR, PT, CS, PL

Output

The language setting triggers the creation of a file with the name CUstringsXX.ini where XX stands for the language code as above - you will always find the file CUstringsEN.ini as the default language file. This file resides in the CumulusMX directory (all inifiles of CumulusUtils are in the CumulusMX directory). This file is referred to as the language file and upon creation it contains strings which will be shown in a website page in the original English version e.g.

   Temperature=Temperature

The word before the '=' is the tag, the word after is the actual text used and the text to be translated. Not all strings will be present in the file on the first run because of configuration choices. So translation may be done in phases.

The format of the file when created is in UTF-8 so any weird character your language has will be accepted. Just make sure that, after editing the translation, the file is saved as UTF-8. No specific HTML codes are required.

Locale

One other feature of the language setting is that it defines the Locale used within CumulusUtils i.e. which Culture settings will be used. This is specifically important for the number separators as comma's and points. The output of numbers will follow the specified locale within CumulusUtils.

Trouble in Paradise

One design feature of CumulusMX is that the Locale is used in the file naming of the monthly logfiles of CumulusMX. This leads sometimes to problems: if the Locale used for CumulusUtils is different from the Locale used by CumulusMX, the monthly logs cannot be read in some cases. In this case the user can make use of the inifile parameter

   MonthsOfMiracleAndWonder=jan,feb,mrt,apr,mei,jun,jul,aug,sep,okt,nov,dec

which is defaulted with the abbreviated month names for the locale used by CumulusUtils. Changing these abbreviated month names to the ones used by CumulusMX will solve that issue.

If you change the Locale of CumulusUtils, you may have to remove this parameter to reset it and change the defaults again.