SquirrelMail internationalization functions

This file contains variuos functions that are needed to do internationalization of SquirrelMail.

Internally the output character set is used. Other characters are encoded using Unicode entities according to HTML 4.0.

include_once (SM_PATH.'functions/gettext.php') (line 1125)
require_once (SM_PATH.'functions/global.php') (line 23)

Everything uses global.php...

array $languages (line 800)

This array specifies the available translations.

Structure of array: $languages['language']['variable'] = 'value'

Possible 'variable' names: NAME - Translation name in English CHARSET - Encoding used by translation ALIAS - used when 'language' is only short name and 'value' should provide long language name ALTNAME - Native translation name. Any 8bit symbols must be html encoded. LOCALE - Full locale name (in xx_XX.charset format). It can use array with more than one locale name since 1.4.5 and 1.5.1 DIR - Text direction. Used to define Right-to-Left languages. Possible values 'rtl' or 'ltr'. If undefined - defaults to 'ltr' XTRA_CODE - translation uses special functions. See http://squirrelmail.org/docs/devel/devel-3.html

Each 'language' definition requires NAME+CHARSET or ALIAS variables.

  • name: $languages
charset_convert (line 264)

Combined decoding and encoding functions

If conversion is done to charset different that utf-8, unsupported symbols will be replaced with question marks.

  • return: converted string
  • since: 1.4.4 and 1.5.1
string charset_convert (string $in_charset, string $string, string $out_charset, [boolean $htmlencode = true])
  • string $in_charset: initial charset
  • string $string: string that has to be converted
  • string $out_charset: final charset
  • boolean $htmlencode: keep sm_encode_html_special_chars encoding
charset_decode (line 178)

Converts string from given charset to charset, that can be displayed by user translation.

Function by default returns html encoded strings, if translation uses different encoding. If Japanese translation is used - function returns string converted to euc-jp If $charset is not supported - function returns unconverted string.

sanitizing of html tags is also done by this function.

  • return: decoded string
string charset_decode (string $charset, string $string, [boolean $force_decode = false], [boolean $save_html = false])
  • string $charset
  • string $string: Text to be decoded
  • boolean $force_decode: converts string to html without $charset!=$default_charset check. Argument is available since 1.4.5 and 1.5.1.
  • boolean $save_html: disables sm_encode_html_special_chars() in order to preserve html formating. Use with care. Available since 1.4.6 and 1.5.1
charset_encode (line 220)

Converts html string to given charset

  • since: 1.4.4 and 1.5.1
string charset_encode (string $string, string $charset, [boolean $htmlencode = true])
  • string $string
  • string $charset
  • boolean $htmlencode: keep sm_encode_html_special_chars encoding
fixcharset (line 280)

Makes charset name suitable for decoding cycles

ks_c_5601_1987, x-euc-* and x-windows-* charsets are supported since 1.4.6 and 1.5.1.

  • return: Adjusted name of charset
  • since: 1.4.4 and 1.5.0
string fixcharset (string $charset)
  • string $charset: Name of charset
is_conversion_safe (line 540)

Function informs if it is safe to convert given charset to the one that is used by user.

It is safe to use conversion only if user uses utf-8 encoding and when converted charset is similar to the one that is used by user.

  • return: is it possible to convert to user's charset
bool is_conversion_safe (string $input_charset)
  • string $input_charset: Charset of text that needs to be converted
japanese_charset_xtra (line 618)

Japanese charset extra function

void japanese_charset_xtra ()
korean_charset_xtra (line 749)
void korean_charset_xtra ()
set_my_charset (line 511)

Sets default_charset variable according to the one that is used by user's translations.

Function changes global $default_charset variable in order to be sure, that it contains charset used by user's translation. Sanity of $squirrelmail_language and $default_charset combination provided in the SquirrelMail configuration is also tested.

There can be a $default_charset setting in the config.php file, but the user may have a different language selected for a user interface. This function checks the language selected by the user and tags the outgoing messages with the appropriate charset corresponding to the language selection. This is "more right" (tm), than just stamping the message blindly with the system-wide $default_charset.

void set_my_charset ()
set_up_language (line 330)

Set up the language to be output if $do_search is true, then scan the browser information for a possible language that we know

Function sets system locale environment (LC_ALL, LANG, LANGUAGE), gettext translation bindings and html header information.

Function returns error codes, if there is some fatal error.

  1. = no error,
  2. = mbstring support is not present,
  3. = mbstring support is not present, user's translation reverted to en_US.

  • return: function execution error codes.
int set_up_language (string $sm_language, [bool $do_search = false], [bool $default = false])
  • string $sm_language: Translation used by user's interface
  • bool $do_search: Use browser's preferred language detection functions. Defaults to false.
  • bool $default: Set $sm_language to $squirrelmail_default_language if language detection fails or language is not set. Defaults to false.
sq_bindtextdomain (line 94)

Gettext bindtextdomain wrapper.

Wrapper solves differences between php versions in order to provide ngettext support. Should be used if translation uses ngettext functions.

This also provides a bind_textdomain_codeset call to make sure the domain's encoding will not be overridden.

  • return: path to translation directory
  • since: 1.4.10 and 1.5.1
string sq_bindtextdomain (string $domain, [string $dir = ''])
  • string $domain: gettext domain name
  • string $dir: directory that contains all translations (OPTIONAL; if not specified, defaults to SquirrelMail locale directory)
sq_change_text_domain (line 49)

Wrapper for textdomain(), bindtextdomain() and bind_textdomain_codeset() primarily intended for plugins when changing into their own text domain and back again.

Note that if plugins using this function have their translation files located in the SquirrelMail locale directory, the second argument is optional.

  • return: The name of the text domain that was set *BEFORE* it is changed herein - NOTE that this differs from PHP's textdomain()
  • since: 1.4.10 and 1.5.2
string sq_change_text_domain (string $domain_name, [string $directory = ''])
  • string $domain_name: The name of the text domain (usually the plugin name, or "squirrelmail") being switched to.
  • string $directory: The directory that contains all translations for the domain (OPTIONAL; default is SquirrelMail locale directory).
sq_setlocale (line 131)

php setlocale function wrapper

From php 4.3.0 it is possible to use arrays in order to set locale. php gettext extension works only when locale is set. This wrapper function allows to use more than one locale name.

string sq_setlocale (int $category, mixed $locale)
  • int $category: locale category name. Use php named constants (LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC, LC_TIME)
  • mixed $locale: option contains array with possible locales or string with one locale

Documentation generated on Mon, 14 Oct 2019 04:24:39 +0200 by phpDocumentor 1.4.3