Easy Multi-Language Twig Apps with Gettext

This tutorial demonstrates how to add multi-language support to a PHP application using Twig and Gettext. It's significantly faster than userland solutions like Symfony's translation component. We'll modify a pre-existing English-only application (nofw) to illustrate this.

Key Advantages:

• Efficiency: Gettext's native implementation offers superior performance compared to userland alternatives.
• Simplicity: The process of adding internationalization to an existing application is surprisingly straightforward.
• Comprehensive Guide: This tutorial covers environment setup, string extraction (using xgettext), .po and .mo file generation, Twig integration via the i18n extension, and helpful utility scripts.

Setup and Fundamentals:

We'll use Homestead Improved (assuming Gettext is already installed; instructions for manual installation are provided later). Because nofw uses Twig, the i18n extension is required:

<code class="language-bash">git clone https://github.com/swader/nofw
cd nofw
git checkout tags/2.93 -b 2.93
composer require twig/extensions</code>

(Note: This clones an older nofw version without built-in internationalization for tutorial purposes.)

Follow the nofw README to configure the database. The application should now be running.

Gettext uses gettext("string") or its alias _("string") to mark translatable strings. If a translation isn't found, the original string (the placeholder) is returned.

Let's test this with a simple PHP file (outside of Twig) to verify Gettext functionality. Create i18n.php:

<code class="language-php"><?php
$language = "en_US.UTF-8";
putenv("LANGUAGE=" . $language);
setlocale(LC_ALL, $language);

$domain = "messages";
bindtextdomain($domain, "Locale");
bind_textdomain_codeset($domain, 'UTF-8');

textdomain($domain);

echo _("HELLO_WORLD");</code>

Create the directory structure:

The code sets the language, locale, and domain for Gettext. Running this will echo "HELLO_WORLD" because the language file is missing.

String Extraction:

Use xgettext to extract strings from your files:

<code class="language-bash">xgettext --from-code=UTF-8 -o Locale/messages.pot public/i18n.php</code>

This creates messages.pot (Portable Object Template). Generate an English .po file:

<code class="language-bash">msginit --locale=en_US --output-file=Locale/en_US/LC_MESSAGES/messages.po --input=Locale/messages.pot</code>

Edit messages.po, translating "HELLO_WORLD" (e.g., to "Howdy"). Compile to .mo:

<code class="language-bash">msgfmt -c -o Locale/en_US/LC_MESSAGES/messages.mo Locale/en_US/LC_MESSAGES/messages.po</code>

Adding a New Language (e.g., Croatian):

1. Install the locale: sudo locale-gen hr_HR hr_HR.UTF-8; sudo update-locale; sudo dpkg-reconfigure locales
2. Generate the .po file: mkdir -p Locale/hr_HR/LC_MESSAGES; msginit --locale=hr_HR --output-file=Locale/hr_HR/LC_MESSAGES/messages.po --input=Locale/messages.pot
3. Translate "HELLO_WORLD" to "Zdravo" in messages.po.
4. Compile to .mo: msgfmt -c -o Locale/hr_HR/LC_MESSAGES/messages.mo Locale/hr_HR/LC_MESSAGES/messages.po
5. Change i18n.php's locale to hr_HR.UTF-8 and test. A server restart might be needed.

Twig Integration:

Add this to app/config/config_web.php:

<code class="language-bash">git clone https://github.com/swader/nofw
cd nofw
git checkout tags/2.93 -b 2.93
composer require twig/extensions</code>

In your Twig templates, use the trans block:

<code class="language-php"><?php
$language = "en_US.UTF-8";
putenv("LANGUAGE=" . $language);
setlocale(LC_ALL, $language);

$domain = "messages";
bindtextdomain($domain, "Locale");
bind_textdomain_codeset($domain, 'UTF-8');

textdomain($domain);

echo _("HELLO_WORLD");</code>

xgettext doesn't handle Twig directly, so we'll use a caching mechanism. Create app/bin/twigcache.php:

<code class="language-bash">xgettext --from-code=UTF-8 -o Locale/messages.pot public/i18n.php</code>

Then extract strings from the cached files:

<code class="language-bash">msginit --locale=en_US --output-file=Locale/en_US/LC_MESSAGES/messages.po --input=Locale/messages.pot</code>

Update .po files using msgmerge and recompile .mo files.

Bonus: Utility Scripts (app/bin/i18n):

The tutorial provides bash scripts (addlang.sh, update-pot.sh, update-mo.sh, config.sh) to automate the process of adding languages, updating .pot and .mo files. These scripts are detailed in the original text.

Deployment:

Ensure Gettext is installed and locales are generated on your server. On Ubuntu:

<code class="language-bash">msgfmt -c -o Locale/en_US/LC_MESSAGES/messages.mo Locale/en_US/LC_MESSAGES/messages.po</code>

The .pot, .po, and .mo files should be part of your version control. Adapt the installation command and scripts for non-Ubuntu systems. The FAQs section provides further details and troubleshooting information.

The above is the detailed content of Easy Multi-Language Twig Apps with Gettext. For more information, please follow other related articles on the PHP Chinese website!