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