adding information about ngettext
[squirrelmail.git] / 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