Translate Your Website with PHP and gettext

In this article, we will show how to add internationalization to your website using PHP and gettext (PHP plugin).

Requirements

To translate your website using PHP and gettext, the following conditions must be met:

1. Your website should be installed on a web server which has PHP support.
2. You must have the gettext package installed and configured.
3. Install the Poedit tool on your computer. This tool is necessary for text translation.

For OS X, the installation of gettext is very simple if you have macports installed. In the command line, type

sudo port install gettext

and wait for the installation (you must have PHP installed first).

The PHP Code

In your website, you must create the inc folder which contains the locale.php file. This file must have the following content:

<?php if (session_id() == '') {
    session_start();
}

define('SESSION_LOCALE_KEY', 'ix_locale');
define('DEFAULT_LOCALE', 'en_US');
define('LOCALE_REQUEST_PARAM', 'lang');
define('WEBSITE_DOMAIN', 'messages');

if (array_key_exists(LOCALE_REQUEST_PARAM, $_REQUEST)) {
    $current_locale = $_REQUEST[LOCALE_REQUEST_PARAM];
    $_SESSION[SESSION_LOCALE_KEY] = $current_locale;
} elseif (array_key_exists(SESSION_LOCALE_KEY, $_SESSION)) {
    $current_locale = $_SESSION[SESSION_LOCALE_KEY];
} else {
    $current_locale = DEFAULT_LOCALE;
}

putenv("LC_ALL=$current_locale");
setlocale(LC_ALL, $current_locale);
bindtextdomain(WEBSITE_DOMAIN, dirname(__FILE__) . '/lang');
bind_textdomain_codeset(WEBSITE_DOMAIN, 'UTF-8');
textdomain(WEBSITE_DOMAIN);

Below we will explain the code in this file:

1. The first line checks if the session exists and, if it doesn’t, then it is created. We need the session because we must keep the selected locale inside it. Here you can read more about the PHP session.
2. The lines starting with the define keyword define a list of constants that are used in the script:
   • SESSION_LOCALE_KEY – defines the name of the session key under which the selected language can be found.
   • DEFAULT_LOCALE – defines the default locale.
   • LOCALE_REQUEST_PARAM – defines the name of the request parameter used to switch the language.
   • WEBSITE_DOMAIN – defines the domain name used by bindtextdomain and textdomain. The domain name must be the same as the name of the .mo files.
3. The next lines set the current locale on the $current_locale variable as follows:
   • If the lang parameter exists in the request map, then the value of this parameter is considered the new locale.
   • If the lang parameter is not present in the request, then we try to find the locale in the session (maybe the user changed the language in the past and we want to preserve his change).
   • If the lang parameter is not found in the request or in the session, then we consider the default one as current locale.
4. The last lines effectively set the PHP locale, bind the translation files which correspond to the selected locale to our domain and set our domain as the default domain.

The inc/locale.php file must be included at the beginning of each PHP file which require translation using the following code: <?php require_once ('inc/locale.php') ?>

The translatable text can be inserted in your PHP pages using one of the following two methods:

1. <?php echo gettext('A translatable text'); ?>
2. <?php echo _('A translatable text'); ?>

Create the Translation Files

In the inc folder, you must create a folder structure like lang/[locale]/LC_MESSAGES where [locale] must be replaced with your locales code.

For example, in our demo, we chose to implement the translation for English (US), French and Italian languages.

After that, open the Poedit tool, go to the File menu and click on the New Catalog menu item. A dialog like the following should be opened:

You must fill the fields in this dialog with the following values:

1. Project name and version – your website name
2. Team – your team name
3. Team’s email address – your team email address
4. Language – the language locale (for example: en_US, fr_FR, de_DE, it_IT, es_ES, nl_NL, etc.) or the language name. We preferred to use the language locale.
5. Charset – UTF-8
6. Source code charset – UTF-8

The next step is to select the Source paths tab. Here, click the New item button and insert this value: ../../../..

The last step is the saving part. Click the OK button and save the new catalog with the name of messages.po in the lang/[locale]/LC_MESSAGES folder where the [locale] value must be the locale of the catalog. The name of the catalog (messages.po) is strongly related to the name of the domain (the value of the WEBSITE_DOMAIN constant). This means that if, for example, you change the value of the WEBSITE_DOMAIN constant from messages to messages1, then the name of the .po files must be changed from messages.po into messages1.po.

After saving, click the Update button to refresh the catalog. PoEdit will now automatically scan all your website files inside the path you specified earlier (../../../..) and extract all strings that are passed to gettext() or _().

The update must be performed each time for each catalog after a change is performed in the website.

Even if you press Enter or introduce a new line, you must update all the .po files again because these files keep the line number of the messages.

Translate the Content

To translate the content, you must open all the .po files and translate each line in the catalog.

If everything works fine, after you change your website language, you will see your website translated.

There are other methods available for localization in PHP, but this method is very common and easy to use. As a mention, this method is used by WordPress to translate the static context (the text that is enclosed in plugins, templates, widgets, etc.).