Web:Extend provides two functions that can be used to translate an application.
These functions are wrapped around the gettext extension
and provide a similar functionality. The framework also includes an alternative implementation
of gettext written in PHP, in case the extension is not available.
The translations functions of the framework handle both singular and plural form with the same function, as opposed to gettext.
The functions are _T and _WT.
The first function, _T, is used to translate the application's messages.
This is the only function you should need when writing an application using the Web:Extend framework.
The other function is used internally by the framework.
It uses a different domain (and thus different localization files) than the application.
The translation functions accept either one or three parameters. When passing only one parameter, the operation performed is equivalent to calling the gettext function. When 3 parameters are passed, the operation is equivalent to calling the ngettext function.
Assuming you have created a french locale file for your application, you can use the following code to switch to french and translate a few strings:
<?php // Switch to the french language setlocale(LC_ALL, 'fr_FR'); // Translate a few strings echo _T('Hello!'); // echoes: Bonjour ! echo _T('Thanks for using Web:Extend.'); // echoes: Merci d'utiliser Web:Extend.
Using the second form of the function requires a bit more work.
Let's assume we have a variable named $iNumberOfPonies.
We want to output pony if there's 0 or 1 pony, and ponies if there's 2 or more.
This is done like this:
<?php // Switch to the french language setlocale(LC_ALL, 'fr_FR'); // Plural translation // Echoes the first or second parameter's translation depending on $iNumberOfPonies echo _T('Singular version: %d pony.', 'Plural version: %d ponies.', $iNumberOfPonies); // You can also use sprintf to format the string echo sprintf(_T('Singular version: %d pony.', 'Plural version: %d ponies.', $iNumberOfPonies), $iNumberOfPonies);
The gettext manual has more examples for handling plural forms and multiple parameters.
Web:Extend also provides a complementary internationalization and localization solution. With it, you can correctly format numbers and dates for every cultures, among other things.
There are 3 options applicable to the translation functions. To change an option, simply define its constant. You must define them before loading the framework if you wish to change the default values.
APP_LOCALE_DOMAIN: Domain used by the application.
Defaults to app. The domain represents the name of the file used by the localization functions.
For example, if you change the domain to example, the translation file will be called example.mo.
APP_LOCALE_PATH: Path to the locale folder. Defaults to app/locale.
WEE_TRANSLATE: If defined, it forces the use of the alternative gettext implementation,
even if the PHP extension is available.
Web:Extend uses gettext files to store the translation strings.
The file format and the associated utilities are described in the gettext documentation.
The locale files are stored in the app/locale folder by default.
The name of the language files is app.mo by default.
Using the default values, the locale files are stored as follow:
app/locale/en_GB/LC_MESSAGES/app.mo app/locale/en_US/LC_MESSAGES/app.mo app/locale/fr_FR/LC_MESSAGES/app.mo
To generalize, locale files are stored in path_to_locale/lang/category/file.mo.
The language used by the application is defined using the setlocale function. Details may vary depending on your operating system, refer to the PHP documentation for more information.