Documentation: i18n/i18n.php

Class i18n - Handle internationalization

This library helps to internationalize (i18n) and localize (l10n) strings used throughout the software.

YACS leverages the gettext framework, which is the de facto standard for the internationalization of open source software.

According to this framework, three kinds of files are used to achieve both internationalization and localization:

* Machine Object - .mo files contain a binary representation of translated and localized strings. These are the files that are loaded by YACS. You can either download .mo files containing official translations from the YACS community, or translate some .pot files and compile them as .mo with a tool such as poEdit. Localized files are split per language and per module. For example, all French strings for scripts in the directory articles are loaded from the file i18n/locale/fr/articles.mo. Strings for root scripts are expected in the file i18n/locale/fr/root.mo.

* Portable Object - .po files contain pairs of original and translated strings. These are files handled and produced by software translators, or by any person with specific localization needs. To create a new portable object, take a .pot template file and copy it as a .po file. Then open the .po file with a dedicated tool such as poEdit to achieve the localization.

* Portable Object Template - .pot files are collections of strings extracted from the YACS software. These files are all located in the i18n/templates directory. They are generated as part of the release process of a new version of YACS. Translators can use standard tools from the gettext toolbox to merge their previous .po files with new .pot versions.

Note that YACS does not actually use the gettext PHP extension, because it is not supported by a number of ISPs. Instead, a small parser of .mo files has been developed, to allow smooth implementation across all servers.

In addition, YACS turns content of .mo files to standard PHP statements, in a .mo.php file. This kind of file is searched first, since it is faster to include a PHP script than to parse a .mo file.

How to create a new localization?

With each release of YACS a set of templates files (.pot) are generated in directory i18n/templates. To create a new localization you have to:

create a sub-directory in i18n/locale (see below)
use the msginit command to create in the new directory a set of .po files out of .pot template files
use poEdit, or any text editor, to populate .po files
copy the manifest.php file from the 'en' locale, and adapt it for your new locale

To name a new locale, you should follow best practices describes in RFC3066 and use any of following options:

language code as defined by ISO 639; e.g., 'en' for English, 'ar' for Arabic, or 'zu' for Zulu
language code, followed with an hyphen '-', then a country code as per ISO 3166-1; e.g., 'en_UK', 'zh_CN'

The manifest file allows webmasters to manage localizations from YACS main configuration panel.

How to share and use localizations?

Translators are encouraged to share the outcome of their work at the official YACS web site. The preferred format for new submissions is an archive containing all .mo files, plus manifest.php, for one locale.

At the moment YACS original archive includes full localization for English and French. To add new localizations webmasters have to download additional sets of .mo files and to push them to servers.

The preferred locale for a community can be selected from within YACS main configuration panel.

Locales for surfers are automatically selected based on hints provided by web browsers, and on availability of related files.

This script is a reference file of this system.

Voir aussi:

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com

bind() - Load localized strings for one module

function bind($module)

$module - string module name

c() - Get a localized string based on preferred language for the community

function &c($text)

$text - string the template string to be translated
returns string the localized string

This function is an equivalent to gettext(), except it deals with community localization.

initialize() - Initialize the localization engine

function initialize()

This function analyzes data provided by the browser to automate surfer localization.

load() - Load one .mo file

function load($language, $module)

$language - string target language
$module - string target module
returns TRUE on success, FALSE otherwise

This function attempts to include the .mo.php file, then, if it is not available, it parses the .mo file.

Expected data locations for language 'foo' and module 'bar' are:

i18n/locale/foo/bar.mo.php (for the PHP equivalent to the .mo file) and
i18n/locale/foo/bar.mo (for the original .mo file)

The function also attempts to create a .mo.php file if one does not exists, to speed up subsequent calls.

Loaded strings are all placed into the global array $l10n['foo']['bar'] for later use.

The function does not actually use the gettext PHP extension because of potential weak implementations. Instead, it parses directly binary content of the .mo file.

Voir aussi:

The Format of GNU MO Files

list_locales() - List all available locales

function list_locales()

returns array of ($locale => $label)

nc() - Localize in singular/plural as per community settings

function &nc($singular, $plural, $count)

$singular - string singular form
$plural - string plural form
$count - int number of items to consider
returns string the localized string

This function is equivalent to ngettext(), except that it localizes in the preferred language for the community.

ns() - Localize in singular/plural for a surfer

function &ns($singular, $plural, $count)

$singular - string singular form
$plural - string plural form
$count - int number of items to consider
returns string the localized string

This function is equivalent to ngettext(), except that it localizes in the preferred language for the surfer.

s() - Get a localized string for a surfer

function &s($text)

$text - string the template string to be translated
returns string the localized string, if any

This function is an equivalent to gettext(), except it deals with surfer localization.

server() - Get a localized string for a background process

function &server($name)

$name - string the label identifying string
returns string the localized string, if any

This function also transcode HTML entities to Unicode entities, if any.

user() - Get a localized string for a surfer

function &user($name, $forced='')

$name - string the label identifying string
$forced='' - string desired language, if any
returns string the localized string, if any

This function also transcode HTML entities to Unicode entities, if any.

get_local()

function get_local($label, $language=NULL)

$label -
$language=NULL -

get_preferred()

function get_preferred($label)

$label -