Getting Mika to show times and dates in the right timezone, language, etc..

This page explains how to set the system timezone, language, and country. This affects the presentation of date and time information but also other issues such as the default currency.

Setting the timezone and locale

To tell Mika to use a specific timezone or Locale, use the following system properties:

  • user.timezone
  • user.language
  • user.country

You can set these either on the command line, e.g. -Duser.timezone=Europe/Paris, or in the file lib/mika/system.properties or lib/mika/mika.properties as a line like 

user.language=pt

Note that lib/mika/mika.properties is read in after lib/mika/system.properties, so if a property is defined in both files then the value in lib/mika/mika.properties will override the one in lib/mika/system.properties. Both files are copied from core-vm/resource/system/mika.timezones to the output at build time.

It is strongly recommended to follow standard Linux practice and run the hardware real-time clock on GMT/UTC, and to use user.timezone to get times displayed correctly. This will also ensure that the switch to summer time (daylight saving time) and back occurs automatically, which sure beats having to adjust the system clock twice a year.

Note 1: Mika does not try to guess these settings from the Linux environment because the tricks used to do this on desktop Linux mostly do not work on embedded Linux systems.

Note 2: since rev. 931 it is also possible to set the default timezone in the mika.timezones file, see below.

Note 3: currently updating one of these system properties using System.setProperty() will not result in dynamically changing the presentation of dates, times etc.. We do realise that this could be very useful, and it will be included in a forthcoming revision of Mika.

Making Mika aware of more (or less) timezones and locales

Mika gets all its timezone from the file lib/mika/mika.timezones; during build time this file is copied from core-vm/resource/system/mika.timezones to the output. By editing this file you can customise your version of Mika by adding timezones needed in specific markets, or strip out unused data to create a smaller distribution. Note: if formatting and display of times and dates is important to your application you should check carefully that the data for your target timezone(s) is correct. We try to keep it that way, but these things are at the whim of politicians and we may miss some changes.

mika.timezones contains three types of lines:

  • comment lines (empty or starting with '#')
  • definitions. The simplest type of definition looks like this:

A=1 which means that timezone "A" is one hour ahead of GMT/UCT, does not use daylight saving time, and has no "display names". (This is the military timezone A or "Alpha"). A more complex definition is WET=0(3,-1,7,1.0,10,-1,7,2.0)1.0 "WET" "Western European Time" "WEST" "Western European Summer Time" which defines the timezone for the UK, Ireland and Portugal: reading from left to right the timezone with internal name "WET" has offset 0 from GMT, summer time begins in March (month 3) on the last (-1th) Sunday (day 7, sorry) at 1 a.m. and ends in October on the last Sunday at 2 a.m. "clock time", and summer time is 1 hour ahead of winter time. In winter the short display name is "WET" and the long one is "Western European Time", in summer these are "WEST" and "Western European Summer Time".

  • aliases. A line such as

Europe/Vilnius=2 means that this timezone is always 2 hours ahead of GMT/UCT, while Europe/Dublin=WET means that this timezone is a synonym for the "WET" zone defined above. A special case of this syntax is Default=Europe/Dublin which means that "Europe/Dublin" will be used as the default Locale when no user.timezone system property is defined.

Note that if you set user.timezone to an alias such as Europe/Vilnius or Europe/Dublin the default display format for times will use "GMT+02:00" resp. "CET" or "CEST" rather than the user.timezone value itself. This is intentional.

Language and country settings for the names of days and months

These are defined in the file lib/mika/mika.datesymbols, which like the mika.timezones file is copied from the core-vm/resource/system directory at build time. This file is read in as a "properties" file, in which the "key" consists of:

  • the "base" key in lower case, see below;
  • optionally followed by a dot and the two-letter ISO abbreviation for a language in lower-case, such as "fr";
  • optionally followed by a dot and the two-letter ISO abbreviation for a country in upper case, such as "CA".

The "value" is then the name of the day or month in this language + country = locale.

The "base" key is one of the following:

  • day of the week (full form): one of monday, tuesday, wednesday, thursday, friday, saturday, sunday
  • day of the week (short form): one of mon, tue, wed, thu, fri, sat, sun
  • month of the year (full form): one of january, february, march, april, maylong (!), june, july, august, september, october, november, december
  • month of the year (full form): one of jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec
  • era: either bc or ad
  • time of day: am or pm (not used all countries).

If Mika wanted to know the full name for October in Brazilian Portugese it would look first for october.pt.BR, then for october.pt and finally for october - if it didn't find any of these (or didn't find a mika.datesymbols file) then it would default to the hard-coded value "October". With the default mika.datesymbols file the second attempt would succeed (october.pt) and "outobro" would be printed.

As with the timezones, you can customise these files and you should check that the data for your target markets is correct.

Note 1: look out for the case! 'Base" and "language" are lower-case and "country" is upper-case, end of story!

Note 2: in theory you could have entries such as sunday.DE=Sonntag, i.e. specifying a country but not a language; however this has not been tested and is not recommended. (It would probably not mix well with other keys such as sunday.de.CH).

Note 3: although java.util.Locale recognises "variants" as well as languages and countries, this setting is ignored by Mika for date/time formatting purposes.

TODO: Currently the display names of timezones are not localised, so for example CET is not reprented as MEZ when user.language=de. This should be handled in the same way as days and months (which implies that the display names should move from the mika.timezones file to mika.datesymbols).

Currencies

Currency support in Mika is currently somewhat rudimentary. It makes use of the lib/mika/resource/currency directory, which like the files above is copied from core-vm/resource/system/resource/currency. This contains the following files:

  • countryMap.properties, which maps two-letter upper-case country names to three-letter upper-case currency abbreviations, e.g. BE = EUR
  • XXX.properties files which contain key=value pairs for
    • symbol e.g. symbol = \u20A0 for the Euro, and
    • fraction.digits, generally = 2.

TODO: This is stylistically inconsistent with the treatment of timezones and locales, so it is likely to change in the future (or the timezones and locales will change, but this seems less likely).