doc/i18n.txt

   1 SquirrelMail internationalization
   2
   3 This document should explain how SquirrelMail internationalization works and
   4 provide information about some aspects of implementation.
   5
   6 1. Supported languages
   7 2. $languages array
   8 3. XTRA_CODE functions
   9 4. Display of different charsets
  10 5. IMAP folder names
  11 6. Plural forms
  12
  13 -------------------------------
  14 1. Supported languages
  15 -------------------------------
  16 Valid language codes are:
  17 * ar    - Arabic, windows-1256 charset
  18 * bg_BG - Bulgarian, windows-1251 charset
  19 * bn_IN - Bengali, utf-8 charset
  20 * ca_ES - Catalan, iso-8859-1 charset
  21 * cs_CZ - Czech, iso-8859-2 charset
  22 * cy_GB - Welsh, iso-8859-1 charset
  23 * da_DK - Danish, iso-8859-1 charset
  24 * de_DE - German, iso-8859-1 charset
  25 * el_GR - Greek, iso-8859-7 charset
  26 * en_GB - British, iso-8859-15 charset
  27 * en_US - English, charset depends on $default_charset
  28 * es_ES - Spanish, iso-8859-1 charset
  29 * et_EE - Estonian, iso-8859-15 charset
  30 * eu_ES - Basque, iso-8859-1 charset
  31 * fa_IR - Farsi, utf-8 charset
  32 * fi_FI - Finnish, iso-8859-1 charset
  33 * fo_FO - Faroese, iso-8859-1 charset
  34 * fr_FR - French, iso-8859-1 charset
  35 * he_IL - Hebrew, windows-1255 charset
  36 * hr_HR - Croatian, iso-8859-2 charset
  37 * hu_HU - Hungarian, iso-8859-2 charset
  38 * id_ID - Indonesian, iso-8859-1 charset
  39 * is_IS - Icelandic, iso-8859-1 charset
  40 * it_IT - Italian, iso-8859-1 charset
  41 * ja_JP - Japanese, euc-jp charset (emails are created in iso-2022-jp)
  42 * ko_KR - Korean, euc-kr charset
  43 * lt_LT - Lithuanian, utf-8 charset
  44 * ms_MY - Malay, iso-8859-1 charset
  45 * nb_NO - Norwegian (Bokmal), iso-8859-1 charset
  46 * nl_NL - Dutch, iso-8859-1 charset
  47 * nn_NO - Norwegian (Nynorsk), iso-8859-1 charset
  48 * pl_PL - Polish, iso-8859-2 charset
  49 * pt_BR - Portuguese (Brazil), iso-8859-1 charset
  50 * pt_PT - Portuguese (Portugal), iso-8859-1 charset
  51 * ro_RO - Romanian, iso-8859-2 charset
  52 * ru_UA - Ukrainian Russian, koi8-r charset
  53 * ru_RU - Russian, utf-8 charset
  54 * sk_SK - Slovak, iso-8859-2 charset
  55 * sl_SI - Slovenian, iso-8859-2 charset
  56 * sr_YU - Serbian, iso-8859-2 charset
  57 * sv_SE - Swedish, iso-8859-1 charset
  58 * ug    - Uighur, utf-8 charset (some systems don't support Uighur system locale)
  59 * th_TH - Thai, tis-620 charset
  60 * tl_PH - Tagalog, iso-8859-1 charset (main translation is missing, only some plugins are translated)
  61 * tr_TR - Turkish, iso-8859-9 charset
  62 * uk_UA - Ukrainian, koi8-u charset
  63 * zh_CN - Chinese Simplified, gb2312 charset
  64 * zh_TW - Chinese Traditional, big5 charset
  65
  66 Charset totals:
  67 * iso-8859-1   = 21
  68 * iso-8859-2   = 8
  69 * utf-8        = 5
  70 * iso-8859-15  = 2
  71 * iso-8859-7   = 1
  72 * iso-8859-9   = 1
  73 * koi8-r       = 1
  74 * koi8-u       = 1
  75 * windows-1251 = 1
  76 * windows-1255 = 1
  77 * windows-1256 = 1
  78 * tis-620      = 1
  79 * gb2312       = 1
  80 * big5         = 1
  81 * euc-jp       = 1
  82 * euc-kr       = 1
  83
  84 -------------------
  85 2. $languages array
  86 -------------------
  87 $languages array is stored in functions/i18n.php and defines translations
  88 that are enabled in SquirrelMail.
  89
  90 Format of array:
  91     $languages['language_code']['key'] = 'value'
  92
  93 Possible array key names:
  94 * NAME      - Translation name in English. Any 8bit symbols must be html encoded.
  95 * CHARSET   - Charset used by translation
  96 * ALIAS     - 'language_code' should contain short language name
  97               (iso-639). 'value' should contain name of other 'language_code'
  98               that defines translation with NAME and CHARSET keys.
  99               Entry links short language form with long form (language+country).
 100               See: http://www.loc.gov/standards/iso639-2/langhome.html and
 101               http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html
 102 * ALTNAME   - Native translation name. Any 8bit symbols must be html encoded.
 103               Name is visible when $show_alternative_names is enabled.
 104 * LOCALE    - Full locale name (in xx_XX.charset format or other format required
 105               by php gettext functions). From 1.4.4/1.5.1 'value' can contain
 106               array. If php version is older than 4.3.0, system uses only first
 107               locale name listed in array. First locale name must be compatible
 108               with FreeBSD system locale names.
 109 * DIR       - Text direction. Used to define Right-to-Left languages. Possible
 110               values 'rtl' or 'ltr'. If undefined - defaults to 'ltr'.
 111 * XTRA_CODE - translation uses special functions. (see chapter 3. XTRA_CODE functions)
 112
 113 Each 'language_code' definition requires NAME+CHARSET or ALIAS keys. Other keys are
 114 optional.
 115
 116 ----------------------
 117 3. XTRA_CODE functions
 118 ----------------------
 119 XTRA_CODE functions provide way to change interface behavior, when translation
 120 requires special handling of some SquirrelMail functions. Functions are enabled
 121 by setting XTRA_CODE option in $languages array and including appropriate
 122 functions in functions/i18n.php. First part of function name is word listed in
 123 $languages['language_code']['XTRA_CODE'] value. Second part is one of special
 124 keywords. Possible keywords:
 125 * _decode
 126 Used in src/compose.php, src/i18n.php, src/view_text.php, functions/mime.php
 127 Requires mbstring support
 128
 129 * _encode
 130 Used in src/compose.php, src/read_body.php
 131
 132 * _encodeheader
 133 Used in functions/mime.php
 134 Returning function
 135
 136 * _decodeheader
 137 Used in functions/mime.php
 138 Returning function
 139
 140 * _downloadfilename
 141 Used in functions/mime.php
 142
 143 * _utf7_imap_encode
 144 Used in functions/imap_utf7_local.php
 145 Returning function
 146
 147 * _utf7_imap_decode
 148 Used in functions/imap_utf7_local.php
 149 Returning function
 150
 151 * _strimwidth
 152 Used in functions/mailbox_display.php
 153 Returning function
 154
 155 * _wordwrap
 156 Used in functions/strings.php (sqWordWrap)
 157
 158 --------------------------------
 159 4. Display of different charsets
 160 --------------------------------
 161 When SquirrelMail generates html pages, it uses charset set by translation
 162 selected by end user. Interface can display emails encoded in different
 163 charsets. In order to display characters that might be unsupported by user's
 164 charset, SquirrelMail uses decoding functions that convert non us-ascii symbols
 165 into html entities. All decoding functions are stored in functions/decode/
 166 directory.
 167
 168 By default SquirrelMail includes decoding functions that support iso-8859-x,
 169 windows-125x, utf-8, us-ascii, koi8-r, koi8-u, tis-620, ns-4551_1, iso-ir-111,
 170 cp855 and cp866 charsets. Other decoding functions are distributed in separate
 171 packages. Separate packaging of decoding functions is supported from
 172 SquirrelMail 1.4.4 and 1.5.0.
 173
 174 Some decoding functions might require php recode support. If your php
 175 installation does not support recode, you might be using slower and cpu/memory
 176 intensive functions.
 177
 178 --------------------
 179 5. IMAP folder names
 180 --------------------
 181 IMAP folder names use UTF7-IMAP charset. Folder names that are stored in
 182 conf.pl must be encoded in UTF7-IMAP charset. SquirrelMail uses internal
 183 functions that convert folder names from/to utf7-imap charset. By default those
 184 functions work with iso-8859-1 charset. Other charsets are supported only
 185 when php mbstring extension supports them.
 186
 187 TODO: write independent implementation of charset to utf7-imap conversion.
 188
 189 ---------------
 190 6. Plural forms
 191 ---------------
 192 From v.1.5.1 SquirrelMail includes support of plural forms. It allows to use
 193 correct translation forms with numbers. For example. "We have %s squirrel on
 194 the roof." and "We have %s squirrels on the roof." can be written in one
 195 function call without checking actual number for squirrels. Gettext functions
 196 also deal with non English languages that might use different word forms for
 197 two, five, ten or more units.
 198
 199 Support is provided by ngettext functions that exist in php gettext extension
 200 from php 4.2.0 and by ngettext function replacements from php-gettext classes
 201 (http://savannah.nongnu.org/projects/php-gettext). In order to use it correctly
 202 when php gettext extension does not have ngettext support, SquirrelMail uses
 203 bindtextdomain and textdomain wrappers that load missing functions.
 204
 205 If plugins want to use ngettext functions without increasing php requirements
 206 to 4.2.0 with gettext support, they should require SquirrelMail 1.5.1, use
 207 sq_bindtextdomain function instead of bindtextdomain and use sq_textdomain
 208 function instead of text domain function. If SquirrelMail wrapper functions
 209 are used, there is no need to issue sq_bindtextdomain when plugins reverts to
 210 SquirrelMail domain.
 211
 212 More information about ngettext and plural forms can be found at:
 213 http://www.gnu.org/software/gettext/manual/html_chapter/gettext_10.html#SEC150