| 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 and defines translations |
| 96 | that are enabled in SquirrelMail. |
| 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 functions/i18n.php. First part of function name is word listed in |
| 131 | $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 | |