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.

Before 1.5.2 functions were stored in functions/i18n.php. Script is moved because it executes some code in order to detect functions supported by existing PHP installation and implements fallback functions when required functions are not available. Scripts in functions/ directory should not setup anything when they are loaded.

include_once (SM_PATH.'functions/ngettext.php') (line 1120)
include_once (SM_PATH.'functions/gettext.php') (line 1126)
include_once (SM_PATH.'class/l10n.class.php') (line 1119)
include_once (SM_PATH.'locale/'.$lang_dir.'/setup.php') (line 1089)

Automatic translation loading from setup.php files.

Solution for bug. 1240889. setup.php file can contain $languages array entries and XTRA_CODE functions.

array $languages (line 1068)

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 329)

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 200)

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 iconv or recode functions are enabled and translation uses utf-8 - function returns utf-8 encoded string. 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 285)

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
cleanup_nbsp (line 637)

Replaces non-braking spaces inserted by some browsers with regular space

This function can be used to replace non-braking space symbols that are inserted in forms by some browsers instead of normal space symbol.

  • return: Cleaned text
string cleanup_nbsp (string $string, string $charset)
  • string $string: Text that needs to be cleaned
  • string $charset: Charset used in text
fixcharset (line 346)

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 684)

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
set_my_charset (line 606)

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 399)

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 $content_type = ''])
  • 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.
  • string $content_type: The content type being served currently (OPTIONAL; if not specified, defaults to whatever the template set that is in use has defined).
sqi18n_convert_entities (line 770)

Converts html character entities to numeric entities

SquirrelMail encoding functions work only with numeric entities. This function fixes issues with decoding functions that might convert some symbols to character entities. Issue is specific to PHP recode extension decoding. Function is used internally in charset_convert() function.

  • return: string with character entities converted to decimals.
  • since: 1.5.2
string sqi18n_convert_entities (string $str)
  • string $str: string that might contain html character entities
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 50)

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 152)

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
sq_textdomain (line 132)

Gettext textdomain wrapper.

Makes sure that gettext_domain global is modified.

  • return: gettext domain name
  • since: 1.5.1
string sq_textdomain ( $domain, string $name)
  • string $name: gettext domain name
  • $domain

Documentation generated on Wed, 16 Apr 2014 04:18:23 +0200 by phpDocumentor 1.4.3