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