doc/i18n.txt

   1
   2     *************************************
   3     * SquirrelMail internationalization *
   4     *************************************
   5
   6 $Date$
   7 $Revision$
   8
   9 This document should explain how SquirrelMail internationalization works and
  10 provide information about some aspects of implementation.
  11
  12 1. Supported languages
  13 2. $languages array
  14 3. XTRA_CODE functions
  15 4. Display of different charsets
  16 5. IMAP folder names
  17 6. Plural forms
  18 7. Language setup
  19 8. Time zones
  20
  21 -------------------------------
  22 1. Supported languages
  23 -------------------------------
  24 Valid language codes are:
  25 * ar    - Arabic, windows-1256 charset
  26 * bg_BG - Bulgarian, windows-1251 charset
  27 * bn_IN - Bengali, utf-8 charset
  28 * ca_ES - Catalan, iso-8859-1 charset
  29 * cs_CZ - Czech, iso-8859-2 charset
  30 * cy_GB - Welsh, iso-8859-1 charset
  31 * da_DK - Danish, iso-8859-1 charset
  32 * de_DE - German, iso-8859-1 charset
  33 * el_GR - Greek, iso-8859-7 charset
  34 * en_GB - British, iso-8859-15 charset
  35 * en_US - English, charset depends on $default_charset
  36 * es_ES - Spanish, iso-8859-1 charset
  37 * et_EE - Estonian, iso-8859-15 charset
  38 * eu_ES - Basque, iso-8859-1 charset
  39 * fa_IR - Farsi, utf-8 charset
  40 * fi_FI - Finnish, iso-8859-1 charset
  41 * fo_FO - Faroese, iso-8859-1 charset
  42 * fr_FR - French, iso-8859-1 charset
  43 * he_IL - Hebrew, windows-1255 charset
  44 * hr_HR - Croatian, iso-8859-2 charset
  45 * hu_HU - Hungarian, iso-8859-2 charset
  46 * id_ID - Indonesian, iso-8859-1 charset
  47 * is_IS - Icelandic, iso-8859-1 charset
  48 * it_IT - Italian, iso-8859-1 charset
  49 * ja_JP - Japanese, euc-jp charset (emails are created in iso-2022-jp)
  50 * ko_KR - Korean, euc-kr charset
  51 * lt_LT - Lithuanian, utf-8 charset
  52 * ms_MY - Malay, iso-8859-1 charset
  53 * nb_NO - Norwegian (Bokmal), iso-8859-1 charset
  54 * nl_NL - Dutch, iso-8859-1 charset
  55 * nn_NO - Norwegian (Nynorsk), iso-8859-1 charset
  56 * pl_PL - Polish, iso-8859-2 charset
  57 * pt_BR - Portuguese (Brazil), iso-8859-1 charset
  58 * pt_PT - Portuguese (Portugal), iso-8859-1 charset
  59 * ro_RO - Romanian, iso-8859-2 charset
  60 * ru_UA - Ukrainian Russian, koi8-r charset
  61 * ru_RU - Russian, utf-8 charset
  62 * sk_SK - Slovak, iso-8859-2 charset
  63 * sl_SI - Slovenian, iso-8859-2 charset
  64 * sr_YU - Serbian, iso-8859-2 charset
  65 * sv_SE - Swedish, iso-8859-1 charset
  66 * ug    - Uighur, utf-8 charset (some systems don't support Uighur system locale)
  67 * th_TH - Thai, tis-620 charset
  68 * tl_PH - Tagalog, iso-8859-1 charset (main translation is missing, only some plugins are translated)
  69 * tr_TR - Turkish, iso-8859-9 charset
  70 * uk_UA - Ukrainian, koi8-u charset
  71 * zh_CN - Chinese Simplified, gb2312 charset
  72 * zh_TW - Chinese Traditional, big5 charset
  73
  74 Charset totals:
  75 * iso-8859-1   = 21
  76 * iso-8859-2   = 8
  77 * utf-8        = 5
  78 * iso-8859-15  = 2
  79 * iso-8859-7   = 1
  80 * iso-8859-9   = 1
  81 * koi8-r       = 1
  82 * koi8-u       = 1
  83 * windows-1251 = 1
  84 * windows-1255 = 1
  85 * windows-1256 = 1
  86 * tis-620      = 1
  87 * gb2312       = 1
  88 * big5         = 1
  89 * euc-jp       = 1
  90 * euc-kr       = 1
  91
  92 -------------------
  93 2. $languages array
  94 -------------------
  95 $languages array is stored in functions/i18n.php (v. 1.5.0 or older) or
  96 locale/*/setup.php files and defines enabled SquirrelMail translations.
  97
  98 Format of array:
  99     $languages['language_code']['key'] = 'value'
 100
 101 Possible array key names:
 102 * NAME      - Translation name in English. Any 8bit symbols must be html encoded.
 103 * CHARSET   - Charset used by translation
 104 * ALIAS     - 'language_code' should contain short language name
 105               (iso-639). 'value' should contain name of other 'language_code'
 106               that defines translation with NAME and CHARSET keys.
 107               Entry links short language form with long form (language+country).
 108               See: http://www.loc.gov/standards/iso639-2/langhome.html and
 109               http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html
 110 * ALTNAME   - Native translation name. Any 8bit symbols must be html encoded.
 111               Name is visible when $show_alternative_names is enabled.
 112 * LOCALE    - Full locale name (in xx_XX.charset format or other format required
 113               by php gettext functions). From 1.4.4/1.5.1 'value' can contain
 114               array. If php version is older than 4.3.0, system uses only first
 115               locale name listed in array. First locale name must be compatible
 116               with FreeBSD system locale names.
 117 * DIR       - Text direction. Used to define Right-to-Left languages. Possible
 118               values 'rtl' or 'ltr'. If undefined - defaults to 'ltr'.
 119 * XTRA_CODE - translation uses special functions. (see chapter 3. XTRA_CODE functions)
 120
 121 Each 'language_code' definition requires NAME+CHARSET or ALIAS keys. Other keys are
 122 optional.
 123
 124 ----------------------
 125 3. XTRA_CODE functions
 126 ----------------------
 127 XTRA_CODE functions provide way to change interface behavior, when translation
 128 requires special handling of some SquirrelMail functions. Functions are enabled
 129 by setting XTRA_CODE option in $languages array and including appropriate
 130 functions in locale/language_code/setup.php. First part of function name is word
 131 listed in $languages['language_code']['XTRA_CODE'] value. Second part is one of special
 132 keywords. Possible keywords:
 133 * _decode
 134 Used in src/compose.php, src/i18n.php, src/view_text.php, functions/mime.php
 135 Requires mbstring support
 136
 137 * _encode
 138 Used in src/compose.php, src/read_body.php
 139
 140 * _encodeheader
 141 Used in functions/mime.php
 142 Returning function
 143
 144 * _decodeheader
 145 Used in functions/mime.php
 146 Returning function
 147
 148 * _downloadfilename
 149 Used in functions/mime.php
 150
 151 * _utf7_imap_encode
 152 Used in functions/imap_utf7_local.php
 153 Returning function
 154
 155 * _utf7_imap_decode
 156 Used in functions/imap_utf7_local.php
 157 Returning function
 158
 159 * _strimwidth
 160 Used in functions/mailbox_display.php
 161 Returning function
 162
 163 * _wordwrap
 164 Used in functions/strings.php (sqWordWrap)
 165
 166 --------------------------------
 167 4. Display of different charsets
 168 --------------------------------
 169 When SquirrelMail generates html pages, it uses charset defined in translation
 170 selected by end user. Interface can display emails encoded in different
 171 charsets. In order to display characters that might be unsupported by user's
 172 charset, SquirrelMail uses decoding functions that convert non us-ascii symbols
 173 into html entities. All decoding functions are stored in functions/decode/
 174 directory.
 175
 176 By default SquirrelMail includes decoding functions that support iso-8859-x,
 177 windows-125x, utf-8, us-ascii, koi8-r, koi8-u, tis-620, ns-4551_1, iso-ir-111,
 178 cp855 and cp866 charsets. Other decoding functions are distributed in separate
 179 packages. Separate packaging of decoding functions is supported from
 180 SquirrelMail 1.4.4 and 1.5.0. us-ascii decoding replaces all 8bit symbols with
 181 question marks. utf-8 decoding function does not enable decoding of five and six
 182 byte utf-8 symbols by default (code is commented) and replaces all incorrectly
 183 formated 8bit symbols with question marks.
 184
 185 Some decoding functions might require php recode extension or php 4.3+ mbstring
 186 extension. If your php installation does not support them, you might be using
 187 slower and cpu/memory intensive functions.
 188
 189 --------------------
 190 5. IMAP folder names
 191 --------------------
 192 IMAP folder names use UTF7-IMAP charset. Folder names that are stored in
 193 conf.pl must be encoded in UTF7-IMAP charset. SquirrelMail uses internal
 194 functions that convert folder names from/to utf7-imap charset. By default those
 195 functions work with iso-8859-1 charset. Other charsets are supported only
 196 when php mbstring extension supports them.
 197
 198 TODO: write independent implementation of charset to utf7-imap conversion.
 199
 200 ---------------
 201 6. Plural forms
 202 ---------------
 203 From v.1.5.1 SquirrelMail includes support of plural forms. It allows to use
 204 correct translation forms with numbers. For example. "We have %s squirrel on
 205 the roof." and "We have %s squirrels on the roof." can be written in one
 206 function call without checking actual number for squirrels. Gettext functions
 207 also deal with non English languages that might use different word forms for
 208 two, five, ten or more units.
 209
 210 Support is provided by ngettext functions that exist in php gettext extension
 211 from php 4.2.0 and by ngettext function replacements from php-gettext classes
 212 (http://savannah.nongnu.org/projects/php-gettext). In order to use it correctly
 213 when php gettext extension does not have ngettext support, SquirrelMail uses
 214 bindtextdomain and textdomain wrappers that load missing functions.
 215
 216 If plugins want to use ngettext functions without increasing php requirements
 217 to 4.2.0 with gettext support, they should require SquirrelMail 1.5.1, use
 218 sq_bindtextdomain function instead of bindtextdomain and use sq_textdomain
 219 function instead of textdomain function. If SquirrelMail wrapper functions
 220 are used, there is no need to issue sq_bindtextdomain when plugins reverts to
 221 SquirrelMail domain.
 222
 223 More information about ngettext and plural forms can be found at:
 224 http://www.gnu.org/software/gettext/manual/html_chapter/gettext_10.html#SEC150
 225
 226 -----------------
 227 7. Language setup
 228 -----------------
 229 SquirrelMail uses set_up_language() function to setup language environment.
 230 Environment is setup automatically when include/validate.php is loaded.
 231
 232 SquirrelMail gets interface language from three places:
 233  a) user preference. It is set in Options -> Display Preferences -> Language.
 234     preference uses language key. If user's preferences are not available (user
 235     is not logged in), system tries to extract language value from
 236     'squirrelmail_language' cookie.
 237  b) default squirrelmail language that is set in configuration
 238     ($squirrelmail_default_language variable).
 239  c) preferred language setting provided by browser. It is used only when default
 240     squirrelmail language is set to empty string
 241
 242 If language information is not available, SquirrelMail falls back to US English
 243 translation.
 244
 245 -------------
 246 8. Time zones
 247 -------------
 248 If php install allows modifying environment variable TZ, SquirrelMail allows
 249 end users to select different time zone in their preferences. It can be set in
 250 Options -> Personal Information -> Your current timezone. Time zone is
 251 setup automatically when include/validate.php is loaded.
 252
 253 If TZ variable can't be modified (php is running is safe mode and variable
 254 is not listed in php safe_mode_allowed_env_vars), user's time zone options are
 255 not visible and interface uses default webserver's time zone.
 256
 257 SquirrelMail 1.5.0 and older store list of available time zones in
 258 locale/timezones.cfg. Since 1.5.1 standard times zones are moved to
 259 include/timezones/standard.php and time zone handling differs from older
 260 SquirrelMail versions. Time zone configuration is controlled in SquirrelMail
 261 configuration utility (conf.pl), 4. General Options -> 15. Time zone
 262 configuration menu option. Administrator can select standard, strict, custom
 263 and custom strict time zone handling.
 264
 265 Standard handling does not differ from previous SquirrelMail versions and
 266 SquirrelMail uses GNU C geographical location based time zone names. Strict
 267 handling uses time zone codes with offset from GMT. Strict time zones should
 268 work on systems that don't support GNU C time zone naming. Custom and custom
 269 strict handling uses config/timezones.php file instead of
 270 include/timezones/standard.php.
 271
 272 config/timezones.php file should store $aTimeZones array with different set of
 273 time zones. See default time zone set in include/timezones/standard.php.For
 274 example:
 275
 276 <?php
 277 // World outside US border is a mirage
 278
 279 $aTimeZones=array();
 280 $aTimeZones['America/New_York']['NAME']='US Eastern standard time';
 281 $aTimeZones['America/New_York']['TZ']='EST5EDT';
 282
 283 $aTimeZones['America/Chicago']['NAME']='US Central standard time';
 284 $aTimeZones['America/Chicago']['TZ']='CST6CDT';
 285
 286 // Oliver County, ND
 287 $aTimeZones['America/North_Dakota/Center']['NAME']='US, Oliver County [ND]';
 288 $aTimeZones['America/North_Dakota/Center']['TZ']='CST6CDT'; // CST since 1992
 289
 290 $aTimeZones['America/Denver']['NAME']='US Mountain standard time';
 291 $aTimeZones['America/Denver']['TZ']='MST7MDT';
 292
 293 $aTimeZones['America/Los_Angeles']['NAME']='US Pacific standard time';
 294 $aTimeZones['America/Los_Angeles']['TZ']='PST8PDT';
 295
 296 // Aliaska
 297 $aTimeZones['America/Juneau']['NAME']='Aliaska, Juneau';
 298 $aTimeZones['America/Juneau']['TZ']='NAST9NADT';
 299 $aTimeZones['America/Yakutat']['NAME']='Aliaska, Yakutat';
 300 $aTimeZones['America/Yakutat']['TZ']='NAST9NADT';
 301 $aTimeZones['America/Anchorage']['NAME']='Aliaska, Anchorage';
 302 $aTimeZones['America/Anchorage']['TZ']='NAST9NADT';
 303 $aTimeZones['America/Nome']['NAME']='Aliaska, Nome';
 304 $aTimeZones['America/Nome']['TZ']='NAST9NADT';
 305 $aTimeZones['America/Adak']['NAME']='US, Aleutian Islands';
 306 $aTimeZones['America/Adak']['TZ']='AST10ADT';
 307
 308 $aTimeZones['Pacific/Honolulu']['NAME']='US, Hawaii';
 309 $aTimeZones['Pacific/Honolulu']['TZ']='UCT10';
 310 $aTimeZones['America/Phoenix']['NAME']='US, Arizona';
 311 $aTimeZones['America/Phoenix']['TZ']='MST7'; // gmt-7
 312 $aTimeZones['America/Shiprock']['LINK']='America/Denver';
 313
 314 $aTimeZones['America/Boise']['NAME']='US, South Idaho';
 315 $aTimeZones['America/Boise']['TZ']='MST7MDT';
 316 $aTimeZones['America/Indianapolis']['NAME']='US, Indiana';
 317 $aTimeZones['America/Indianapolis']['TZ']='EST5';
 318 $aTimeZones['America/Indiana/Indianapolis']['LINK']='America/Indianapolis';
 319 // Crawford County, Indiana
 320 $aTimeZones['America/Indiana/Marengo']['NAME']='US, Crawford County [IN]';
 321 $aTimeZones['America/Indiana/Marengo']['TZ']='EST5';
 322 // Starke County, Indiana
 323 $aTimeZones['America/Indiana/Knox']['NAME']='US, Starke County [IN]';
 324 $aTimeZones['America/Indiana/Knox']['TZ']='EST5';
 325 // Switzerland County, Indiana
 326 $aTimeZones['America/Indiana/Vevay']['NAME']='US, Switzerland County [IN]';
 327 $aTimeZones['America/Indiana/Vevay']['TZ']='EST5';
 328 $aTimeZones['America/Louisville']['NAME']='US, Louisville [KY]';
 329 $aTimeZones['America/Louisville']['TZ']='EST5EDT';
 330 $aTimeZones['America/Kentucky/Louisville']['LINK']='America/Louisville';
 331 // Wayne, Clinton, and Russell Counties, Kentucky
 332 $aTimeZones['America/Kentucky/Monticello']['NAME']='US, Wayne, Clinton, and Russell Counties [KY]';
 333 $aTimeZones['America/Kentucky/Monticello']['TZ']='EST5EDT';
 334 // Michigan
 335 $aTimeZones['America/Detroit']['NAME']='US, Michigan';
 336 $aTimeZones['America/Detroit']['TZ']='EST5EDT';
 337 // The Michigan border with Wisconsin switched from EST to CST/CDT in 1973.
 338 $aTimeZones['America/Menominee']['NAME']='US, Menominee [MI]';
 339 $aTimeZones['America/Menominee']['TZ']='CST6CDT';
 340 ?>
 341
 342 GNU C time zone naming should be supported by many Unix OSes. It is recommended
 343 way of setting time zone, because it handles historical changes and daylight
 344 savings specific to selected geographical location. Strict time zones might
 345 provide inaccurate or outdated time zone settings.
 346
 347 If modifications in TZ environment are visible in your webserver's logs (time
 348 offset is changed), make sure that you can reproduce such behavior in latest php
 349 version and report bug to php developers. Issue can be fixed by blocking use of
 350 time zone (php safe mode and TZ is not listed in safe_mode_allowed_env_vars
 351 setting or forced_prefs plugin) or by attaching special php script with
 352 putenv('TZ=some time zone') call in php auto_append_file setting (suggestion is
 353 not tested and you might have to fix all SquirrelMail exit calls).
 354
 355 Please note, that use of auto_append_file provides only temporally workaround
 356 and does not fix your php setup. Script that runs as unprivileged user, should
 357 be unable to affect webserver's logging system.
 358