README-NLS

   1 Notes on National Language Support (NLS)
   2 ****************************************
   3
   4 This package is internationalized with libintl-perl, a free
   5 internationalization library for Perl, you will need to install a copy of
   6 libintl-perl in order to use the package.  You can get libintl-perl from the
   7 Comprehensive Perl Archive Network CPAN at http://www.cpan.org/.
   8
   9 The following notes are meant to be a quick start guide for somewhat
  10 experienced users and system administrators and many important details had to
  11 be omitted for brevity.  If you have any difficulties with the
  12 internationalization features of this package, no matter if you are a
  13 programmer, a translator, or an end user, feel free to ask at the mailing list
  14 for libintl-perl.  To do so, send an e-mail to the address
  15 <libintl-perl AT imperia DOT net> (please replace "AT" with a "@", and "DOT"
  16 with a dot ".").
  17
  18 You can subscribe to this list at
  19
  20      http://ml.imperia.org/mailman/listinfo/libintl-perl
  21
  22 A searchable archive of earlier postings is located at
  23
  24      http://ml.imperia.org/libintl-perl/
  25
  26 You may already find an answer to your question there.
  27
  28 Feel free to include this document in your own Perl packages internationalized
  29 with libintl-perl, no severe copyright restrictions apply.  You should send
  30 corrections or improvements to the author Guido Flohr <guido AT imperia DOT
  31 net>, so that others can benefit from your changes.
  32
  33 The End User's View
  34 ===================
  35
  36 The installation routine for this package will automatically take care that
  37 your system has a sufficient version of libintl-perl installed.  This is
  38 basically sufficient for proper operation, but - especially if
  39 internationalized software is new to you - you should read on carefully in
  40 order to fully benefit from the internationalization (I18N) features of this
  41 package.
  42
  43 Perl Setup
  44 ----------
  45
  46 The I18N library libintl-perl will run with a wide range of Perl versions (at
  47 least from Perl version 5.005_03 to Perl 5.8.0) but you will experience slight
  48 difference in features and performance depending on the version of Perl you
  49 use.
  50
  51 With Perl versions prior to 5.7.3 you can use the package for all European
  52 scripts (including those with Greek or Cyrillic scripts), and also for many
  53 scripts used outside Europe, like Arabic, Hebrew, Georgian, Vietnamese or
  54 Thai, more general all scripts using 8 bit charsets.  Other scripts are only
  55 available if the translations in this package are provided in Unicode and they
  56 can only be output in Unicode.
  57
  58 Beginning with Perl 5.7.3 the module Encode became part of the Perl core, and
  59 it offers you a much wider range of possible scripts.  If you plan to use some
  60 of the lesser used scripts for Chinese, Japanese, and Korean, you should also
  61 install the module Encode::HanExtra.
  62
  63 Setting Your Language
  64 ---------------------
  65
  66 Most modern systems are already prepared and configured for
  67 internationalization, and the user interface of the software you have
  68 installed will already be configured for your preferred language.  Packages
  69 internationalized with libintl-perl will honor these configuration settings
  70 and will also operate in your preferred language if the necessary translations
  71 are available.
  72
  73 The environment variable "LANGUAGE" has the highest precedence for
  74 translations.  The most common format for this environment variable is a
  75 (lowercase) two-letter language code and an (uppercase) two-letter country
  76 code separated by an underscore "_", for example:
  77
  78      LANGUAGE=fr_BE
  79      export LANGUAGE
  80
  81 This will set your language preferences to French ("fr") for Belgium ("BE").
  82 Other examples are French for France ("fr_FR"), German for Austria ("de_AT"),
  83 and so on.  You can also omit the country part ("FR", "DE", "IT", "RU", ...)
  84 in which case a default setting for the country will be assumed.
  85
  86 If there are no translations available for your selected languages, the
  87 original message (normally in English) will be displayed.
  88
  89 You can also define a chain of languages to be tried separated by a colon:
  90
  91      LANGUAGE=fr_BE:fr_FR:fr:it
  92
  93 Read this as: "I want translations in French for Belgium.  If they are not
  94 available try French for France, then any French translation, and finally
  95 Italian".  Please note that this chain notation is only allowed for the
  96 environment variable "LANGUAGE", it is not valid for any of the following
  97 variables.
  98
  99 If "LANGUAGE" is not set, the library checks the variable "LANG".  It has the
 100 same syntax as "LANGUAGE" but does not allow the preferences chain with the
 101 colon syntax.  After "LANG" the variable "LC_MESSAGES" (think "locale category
 102 messages") is tried, and finally "LC_ALL".
 103
 104 Note for Microsoft Windows users: The locale preferences you have configured
 105 for your system cannot yet be evaluated by libintl-perl.  This may change for
 106 future versions of libintl-perl but for the moment you have to make do with
 107 the instructions given above.  In order to set environment variables, you have
 108 to right-click on the icon "My Computer" on your desktop, select "Properties"
 109 in the context menu, and then click the tab labelled "Environment variables".
 110
 111 Setting the Output Charset
 112 --------------------------
 113
 114 Even if you have managed to properly select your preferred language, you may
 115 still have difficulties reading the program languages, because libintl-perl
 116 was unable to determine the correct charset to use for messages.  For example,
 117 it may assume Unicode ("UTF-8") but you really need ISO-Latin-1 (also known as
 118 "Latin-1" or "ISO-8859-1").  If this is the case, please set the environment
 119 variable "OUTPUT_CHARSET" to the appropriate value, for example:
 120
 121      OUTPUT_CHARSET=iso-8859-1
 122      export OUTPUT_CHARSET
 123
 124 Charset names are case-insensitive, i. e. "LATIN-1" is the equivalent to
 125 "Latin-1" or even "lAtIn-1".
 126
 127 Note: The output charset "utf8" is NOT recognized.  Please use the correct
 128 abbreviation "utf-8" (with a hyphen) instead.
 129
 130 The Translator's View
 131 =====================
 132
 133 If you want to contribute a new translation to this package, please contact
 134 the author first.  Somebody may have already started this translation, and
 135 furthermore the package author will be able to give you detailled instructions
 136 and help.
 137
 138 Translating a Perl package is not much work and it does not require any
 139 technical skills.  If you are able to use the software itself, you will also
 140 be able to contribute a translation for your language.  But why should you do
 141 that? You are able to read and understand this text and you will also be able
 142 to understand the English messages that the software spits out by default.
 143
 144 Computers are an integral part of today's society.  Computers are used to
 145 explore new sources of information, forbidding computers would be a modern
 146 form of censorship.  Computers may also improve social life, the internet
 147 helps people to find contacts in their area and all over the world, even if
 148 they would otherwise be deprived from that because of a handicap, lack of money
 149 for traveling, or other reasons.  In many societies, the ability to use and
 150 handle a computer also has a strong impact on your perspectives in life, you
 151 may not be able to find an adequate job because of your lack of computer
 152 experience, or you may even lose your job because of that.
 153
 154 Everybody should benefit from computers, regardless of cultural
 155 background. Computers are expansive goods, and their price is already a high
 156 barrier to cross.  If computers speak in a foreign language, the learning
 157 curve gets steeper and the barrier gets even higher.  You can help the people
 158 that share your native language by contributing a translation.  The author of
 159 this package has already prepared everything, the rest is up to you!
 160
 161 The Programmer's View
 162 =====================
 163
 164 You have downloaded this package because you want to use it in your own
 165 project(s).  The fact that the package is internationalized with libintl-perl
 166 does not affect its usability in any way.  But you should keep in mind that
 167 textual messages produced by the package may change according to the locale
 168 settings at run-time.  This can lead to errors.  For example, if you parse
 169 error messages produced by the package, you will most probably fail to detect
 170 what you are looking for, if these error messages are suddenly presented in
 171 another language or another output charset.
 172
 173 It is probably needless to say that this is bad practice and an indicator for
 174 a poorly written interface.  Either you have missed the correct method for
 175 determining the substance of the message in a locale-independent manner, or
 176 the author of the package has mis-designed the package interface.  In any
 177 case, this is a technical problem that should be solved by technicians.  You
 178 should not put that burden on the shoulders of your users but rather solve the
 179 problem in cooperation with the author of the module that causes it.
 180
 181 If this is absolutely impossible, as a temporary workaround you can completely
 182 switch off the native language support of the package by setting the
 183 environment variable "LANGUAGE" to the special value "C":
 184
 185      BEGIN {
 186          $ENV{LANGUAGE} = $ENV{LANG} = "C";
 187      }
 188
 189 The value "C" instructs libintl-perl to leave all messages untouched, and you
 190 can use the package as if it was not internationalized at all.
 191
 192 If the project you are working on is not yet internationalized, you should
 193 consider to prepare it for internationalization now.  Doing so is only little
 194 work for yourself, but results in a large benefit for the users of your
 195 software.  The package "libintl-perl" ships with exhaustive documentation for
 196 programmers and a sample package that you can use as a skeleton for your own
 197 project(s).  Internationalizing Perl software with libintl-perl is easy, the
 198 package that this file is a part of, prooves that.
 199
 200 Guido Flohr