\midcom_services_i18n

This is a basic MidCOM Service which provides an interfaces to the various I18n facilities of MidCOM.

The I18n service serves as a central access point for all aspects around internationalization and localization. It provides auto-detection of language data using HTTP Content-Negotiation along with a cookie-based fallback.

This class is able to run independently from midcom_application due to the fact that it is used in the cache_hit code.

Use this class to set the language preferences (charset and locale) and to gain access to the l10n string databases. A few helpers which can be used to ease translation work (like charset conversion) are in here as well.

All language codes used here are ISO 639-1 two-letter codes.

Summary

Methods
Properties
Constants
__construct()
set_charset()
set_language()
set_fallback_language()
get_current_language()
get_content_language()
get_fallback_language()
get_current_charset()
get_l10n()
get_string()
show_string()
list_languages()
convert_to_utf8()
convert_from_utf8()
convert_to_current_charset()
html_entity_decode()
No public properties found
No constants found
No protected methods found
No protected properties found
N/A
_set_startup_langs()
_read_cookie()
_read_http_negotiation()
_get_q()
_load_l10n_db()
iconv()
$_fallback_language
$_obj_l10n
$_current_language
$_current_charset
N/A

Properties

$_fallback_language

$_fallback_language : string

Fallback language, in case the selected language is not available.

Type

string

$_obj_l10n

$_obj_l10n : array<mixed,\midcom_services_i18n_l10n>

Cache of all instantiated localization classes.

Type

array<mixed,\midcom_services_i18n_l10n>

$_current_language

$_current_language : string

Current language.

Type

string

$_current_charset

$_current_charset : string

Current character set

Type

string

Methods

__construct()

__construct() 

Initialize the available i18n framework by determining the desired language from these different sources: HTTP Content Negotiation, Client side language cookie.

Its two parameters set the default language in case that none is supplied via HTTP Content Negotiation or through Cookies.

The default language set on startup is currently hardcoded to 'en', you should override it after initialization, if you want something else using the setter methods below.

The fallback language is read from the MidCOM configuration directive i18n_fallback_language.

set_charset()

set_charset(string  $charset) 

Set output character set.

Parameters

string $charset

Charset name.

set_language()

set_language(string  $lang) 

Set output language.

This will set the character encoding to the language's default encoding and will also set the system locale to the one specified in the language database.

If you want another character encoding as the default one, you have to override it manually using midcom_services_i18n::set_charset() after calling this method.

Parameters

string $lang

Language ISO 639-1 code

set_fallback_language()

set_fallback_language(string  $lang) 

Set the fallback language.

Parameters

string $lang

Language name.

get_current_language()

get_current_language() : string

Returns the current language code

Returns

string

get_content_language()

get_content_language() : string

Returns language code corresponding to current content language

Returns

string

get_fallback_language()

get_fallback_language() : string

Returns the current fallback language code

Returns

string

get_current_charset()

get_current_charset() : string

Returns the current character set

Returns

string

get_l10n()

get_l10n(string  $component = 'midcom', string  $database = 'default') : \midcom_services_i18n_l10n

Returns a l10n class instance which can be used to access the localization data of the current component.

Using the special name "midcom" you will get the midcom core l10n library.

Parameters

string $component

The component for which to retrieve a string database.

string $database

The string table to retrieve from the component's locale directory.

Returns

\midcom_services_i18n_l10n

The cached L10n database

get_string()

get_string(string  $stringid, string  $component = null, string  $database = 'default') : string

Returns a translated string using the l10n database specified in the function arguments.

Parameters

string $stringid

The string to translate.

string $component

The component for which to retrieve a string database. If omitted, this defaults to the current component (out of the component context).

string $database

The string table to retrieve from the component's locale directory. If omitted, the 'default' database is used.

Returns

string —

The translated string

show_string()

show_string(string  $stringid, string  $component = null, string  $database = 'default') 

This is a shortcut for echo $this->get_string(.

..);.

To keep the naming stable with the actual l10n class, this is not called echo_string (Zend won't allow $l10n->echo().)

Parameters

string $stringid

The string to translate.

string $component

The component for which to retrieve a string database. If omitted, this defaults to the current component (out of the component context).

string $database

The string table to retrieve from the component's locale directory. If omitted, the 'default' database is used.

list_languages()

list_languages() : Array

Lists languages as identifier -> name pairs

Returns

Array

convert_to_utf8()

convert_to_utf8(string  $string) : string

Convert a string assumed to be in the currently active charset to UTF8.

Parameters

string $string

The string to convert

Returns

string —

The string converted to UTF-8

convert_from_utf8()

convert_from_utf8(string  $string) : string

Convert a string assumed to be in UTF-8 to the currently active charset.

Parameters

string $string

The string to convert

Returns

string —

The string converted to the current charset

convert_to_current_charset()

convert_to_current_charset(string  $string, string  $charset = null) : string

Converts the given string to the current site charset.

The charset should be specified explicitly, as autodetection is very very error prone (though sometimes you don't have a choice).

Parameters

string $string

The string to convert.

string $charset

The charset in which string currently is, omit this parameter to use mb_detect_encoding (error prone!)

Returns

string —

The converted string.

html_entity_decode()

html_entity_decode(string  $text) : string

Wrapped html_entity_decode call

Parameters

string $text

The text with HTML entities, which should be replaced by their native equivalents.

Returns

string —

The translated string.

_set_startup_langs()

_set_startup_langs() 

Scans the HTTP negotiation and the cookie data and tries to set a suitable default language. Cookies have priority here.

_read_cookie()

_read_cookie() 

Try to pull the user's preferred language and character set out of a cookie named "midcom_services_i18n".

_read_http_negotiation()

_read_http_negotiation() : array

Pull available language out of the HTTP Headers

q-parameters for prioritization are supported.

Returns

array —

Keys are the languages, the value is their q-index.

_get_q()

_get_q(array  $params) 

Parameters

array $params

_load_l10n_db()

_load_l10n_db(string  $component, string  $database) 

Load the specified l10n library.

If loading the library failed, midcom_error is thrown, otherwise the l10n db cache is populated accordingly.

Parameters

string $component

The component for which to retrieve a string database.

string $database

The string table to retrieve from the component's locale directory.

iconv()

iconv(string  $source_charset, string  $destination_charset, string  $string) : mixed

This is a calling wrapper to the iconv library.

See the PHP iconv() function for the exact parameter definitions.

Parameters

string $source_charset

The charset to convert from.

string $destination_charset

The charset to convert to.

string $string

The string to convert.

Returns

mixed —

The converted string or false on any error.