
pywws.Localisation
******************

Localisation.py - provide translations of strings into local language

   usage: python RunModule.py Localisation [options]
   options are:
    -h       or  --help       display this help
    -t code  or  --test code  test use of a language code


Introduction
============

Some of the pywws modules, such as WindRose.py, can automatically use
your local language for such things as wind directions. The
Localisation.py module, mostly copied from examples in the Python
documentation, enables this.

Localisation of pywws is done in two parts - translating strings such
as 'rising very rapidly', and changing the 'locale' which controls
things like month names and number representation (e.g. '23,2' instead
of '23.2'). On some computers it may not be possible to set the
locale, but translated strings can still be used.


Using a different language
==========================

The language used by pywws is set in the "[config]" section of the
"weather.ini" file. This can be a two-letter language code, such as
"en" (English), or can specify a national variant, such as "fr_CA"
(Canadian French). It could also include a character set, for example
"de_DE.UTF-8".

The choice of language is very system dependant, so Localisation.py
can be run as a standalone program to test language codes. A good
starting point might be your system's "LANG" environment variable, for
example:

   jim@brains:~/Documents/weather/devel$ echo $LANG
   en_GB.UTF-8
   jim@brains:~/Documents/weather/devel$ python pywws/Localisation.py -t en_GB.UTF-8
   Locale changed from (None, None) to ('en_GB', 'UTF8')
   Translation set OK
   Locale
     decimal point: 23.2
     date & time: Friday, 14 October (14/10/11 13:02:00)
   Translations
     'NNW' => 'NNW'
     'rising very rapidly' => 'rising very rapidly'
     'Rain at times, very unsettled' => 'Rain at times, very unsettled'
   jim@brains:~/Documents/weather/devel$

In most cases no more than a two-letter code is required:

   jim@brains:~/Documents/weather/devel$ python pywws/Localisation.py -t fr
   Locale changed from (None, None) to ('fr_FR', 'UTF8')
   Translation set OK
   Locale
     decimal point: 23,2
     date & time: vendredi, 14 octobre (14/10/2011 13:04:44)
   Translations
     'NNW' => 'NNO'
     'rising very rapidly' => 'en hausse très rapide'
     'Rain at times, very unsettled' => 'Quelques précipitations, très perturbé'
   jim@brains:~/Documents/weather/devel$

If you try an unsupported language, pywws falls back to English:

   jim@brains:~/Documents/weather/devel$ python pywws/Localisation.py -t ja
   Failed to set locale: ja
   No translation file found for: ja
   Locale
     decimal point: 23.2
     date & time: Friday, 14 October (10/14/11 13:08:49)
   Translations
     'NNW' => 'NNW'
     'rising very rapidly' => 'rising very rapidly'
     'Rain at times, very unsettled' => 'Rain at times, very unsettled'
   jim@brains:~/Documents/weather/devel$

Once you've found a suitable language code that works, you can
configure pywws to use it by editing your "weather.ini" file:

   [config]
   language = fr


Creating a new translation
==========================

If there is no translation file for your preferred language then you
need to create one. See *How to use pywws in another language* for
detailed instructions.

-[ Functions ]-

+------------+--------------------------------------------------------------------------------------------+
| "SetLocale | Set the 'locale' used by a program.                                                        |
+------------+--------------------------------------------------------------------------------------------+
| "SetTransl | Set the translation used by (some) pywws modules.                                          |
+------------+--------------------------------------------------------------------------------------------+
| "SetApplic | Set the locale and translation for a pywws program.                                        |
+------------+--------------------------------------------------------------------------------------------+

pywws.Localisation.SetLocale(lang)

   Set the 'locale' used by a program.

   This affects the entire application, changing the way dates,
   currencies and numbers are represented. It should not be called
   from a library routine that may be used in another program.

   The "lang" parameter can be any string that is recognised by
   "locale.setlocale()", for example "en", "en_GB" or "en_GB.UTF-8".

   Parameters:
      **lang** (*string*) -- language code.

   Returns:
      success status.

   Return type:
      bool

pywws.Localisation.SetTranslation(lang)

   Set the translation used by (some) pywws modules.

   This sets the translation object "Localisation.translation" to use
   a particular language.

   The "lang" parameter can be any string of the form "en", "en_GB" or
   "en_GB.UTF-8". Anything after a "." character is ignored. In the
   case of a string such as "en_GB", the routine will search for an
   "en_GB" language file before searching for an "en" one.

   Parameters:
      **lang** (*string*) -- language code.

   Returns:
      success status.

   Return type:
      bool

pywws.Localisation.SetApplicationLanguage(params)

   Set the locale and translation for a pywws program.

   This function reads the language from the configuration file, then
   calls "SetLocale()" and "SetTranslation()".

   Parameters:
      **params** (*object*) -- a "pywws.DataStore.params" object.

pywws.Localisation.main(argv=None)
