Creating A Multi-lingual Site

Making your site supported multiple languages can reach a larger global audience. The internationalization and localization features in PHPLucidFrame makes it much easier. In a single-language application, your code will look like this:

<h1>Blog</h1>

For a multi-lingual application, you need to internationalize your code by using _t() function in your code:

<h1><?php echo _t('Blog') ?></h1>

However, even though your application is single-language, you are always recommended to use _t() function so that you can easily switch from single-language to multi-language application at any time. You can pass multiple arguments to _t() like sprintf() for the dynamic value replacement.

PHPLucidFrame operates the translation process based on the configuration variables $lc_translationEnabled, $lc_languages and $lc_defaultLang. So, you don’t need to worry about overhead using _t().

Configuration of Internationalization

If you are code is ready for internationalization, you should then configure /inc/config.php for your language settings. There are three global configuration variables for this purpose - $lc_translationEnabled, $lc_languages and $lc_defaultLang.

# $lc_translationEnabled - Enable/Disable language translation
$lc_translationEnabled = true;
# $lc_languages: Site languages (leave this blank for single-language site)
$lc_languages = array(
    /* 'lang_code' => 'lang_name' */
    'en' => 'English',
    'my' => 'Myanmar',
);
# $lc_defaultLang: Default site language (leave blank for single-language site)
# One of the key of $lc_languages
$lc_defaultLang = 'en';

You can also use optional sub-language-code, in capital letters, that specifies the national variety (e.g., en-GB or en-US or zh-CN) for $lc_languages. The sub-codes are typically linked with a hyphen.

Creating PO files

The next step is to create your po files, which contain all translatable strings in your application. PHPLucidFrame will look for your po files in the following location.

/i18n/<language-code>.po

To create or edit your po files it’s recommended that you do not use your favorite editor. There are free tools such as PoEdit which make editing and updating your po files an easy task; especially for updating an existing po file.

Basically, you don’t need to have po file for the default language. As per the code sample in the release, there are two languages - English and Myanmar. As English is default language, there is no en.po file in the directory. You can copy and rename the file default.en.po to [your-language-code].po. For example, if you want to create Japanese translation file, you would rename it to ja.po and add your translation strings in the file.

There are two types of translations:

  • language-string-based translation
  • custom key-based translation

Typically, you could use language-string-based translation in case a string is same meaning across the pages. For example, you have the “Cancel” buttons in several pages and if they have same meaning, you could have the following one statement in your language po file:

msgid "Cancel"
msgstr "Your language meaning for Cancel"

You just need to use the only msgid string for all of your “Cancel” buttons.

<button type="button" name="btnCancel"><?php echo _t('Cancel'); ?></button>

However, you may want to set different meaning for different “Cancel” buttons depending on pages or actions. Then, you should use custom key-based translation.

msgid "cancel-at-this-page"
msgstr "Your language meaning for Cancel"

msgid "cancel-at-another-page"
msgstr "Your language different meaning for Cancel"

In this case, you must use the appropriate key for your “Cancel” buttons in your coding and you must also have a po file for your default language.

<button type="button" name="btnCancel">
    <?php echo _t('cancel-at-this-page'); ?>
</button>

<!-- at another page -->
<button type="button" name="btnCancel">
    <?php echo _t('cancel-at-another-page'); ?>
</button>

Note

  • If you updated your po file, you have to clear browser cookie or session to take effect.

Translation of Long Paragraphs

The po files are useful for short messages, if you find you want to translate long paragraphs, or even whole pages - PHPLucidFrame has a way to handle it. Let’s say you have a page “About Us” for the whole page translation, you can create a template file in the directory /i18n/ctn/<language-code>/.

/i18n/ctn/<language-code>/about-us.<language-code>

Then, you just need to use _tc() function where you want to appear the paragraphs. It will render the current default language file content.

echo _tc('about-us');

This function is available to use for dynamic value replacement, for example, you could have the placeholders :contact-url and :home-url in the file content, you can pass the values to the function to replace them.

echo _tc('about-us', array(':contact-url' => _url('contact'), ':home-url' => HOME));

Switching the Site Language

Letting your site visitors switch their preferred language is a must for multi-language sites; by clicking the flag or by selecting the option from a language drop-down. There is a Javascript API available - LC.Page.languageSwitcher() by passing the language code being switched, for example,

$(function() {
    $('#language-combo').change(function () {
        LC.Page.languageSwitcher($(this).val());
    });
});

You could also generate hyperlinks to click on the language flags. For this case, you can use the framework function _self(NULL, $theLanguageCodeToBeSwitched) to get the current URL replaced by the language code. You could check the sample code in at /app/inc/tpl/header.php.

Note

  • For dynamic content generation from database, you are suggested to check the sample codes in the release at /app/admin.
  • PHPLucidFrame stores all translation strings read from po file in session. If you updated the po file, you need to clear your session to take it affect.