Language in CumulusUtils

From Cumulus Wiki
Revision as of 09:03, 29 June 2023 by HansR (talk | contribs) (→‎Locale)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

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 do not seem to be able to solve the issue, please contact @HansR on the forum. See: Trouble in Paradise.

Any entry of an illegal locale code 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.

In CUtils the gauges languages are determined through the locale. If the language from the locale does not exist it falls silently back to en-GB

The current languages defined and accepted are:

   EN, FR, DE, NL, SE, DA, 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

From version 6.19.0 the Locale has become the central parameter and is defined through the Language parameter e.g. Language=nl-NL (unfortunate but historically determined).

If the locale is invalid, it is defaulted to en-GB.

The Locale determines the language and country settings for CUtils. All module and website output of dates and numbers are governed by the Locale. The user has no other configuration possibility to choose forrmat of dates and numbers. It is what it is.

Trouble in Paradise (for version < 7.0.0)

One design feature of CumulusMX is that the Locale is used in the file naming of the monthly logfiles of CumulusMX. This sometimes leads 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 or of the machine on which you run CumulusMX (causing a change of filenames for the monthly logs), you may have to remove this parameter to reset it and change the defaults again or you may have to change the month abbreviations to what is expected.