Slim Framework, true to its name, is an excellent PHP framework¬†when other options seem too bloated, complex, or dependency heavy. The flexibility it offers to¬†leverage functionality from any library you choose is one of its strengths. Unfortunately, documentation can be sparse on specific topics, with some examples using the older Slim 2, and others not discussed in conjunction with Slim. Here’s a guide to using Slim version 3 with Symfony’s excellent Twig templating engine for L18N.

Dependency Setup

Assuming your Slim project is already using Slim for your templating needs, you’ll want to ensure you have the Twig Extensions package installed as well:

composer require twig/extensions

The Twig Extensions package includes several extensions, two of which are key to Internationalization and Localization:

  • I18n – connecting twig with the power of gettext
  • Intl – providing localization helpers for dates, numbers, and monetary values

You’ll need to ensure you have the intl PHP extension installed.

Loading Twig Extensions into Slim

To load the Twig Extensions into twig, you’ll need to find your Twig_Environment. You should already have the \Slim\Views\TwigExtension extension loaded in your Slim container. Assuming your instance is in the variable $view, add these lines:

$view->addExtension(new Twig_Extensions_Extension_I18n());
$view->addExtension(new Twig_Extensions_Extension_Intl());

If you only need the functionality of one or the other, then obviously only load what you need. Check out the Twig Extensions documentation for more details.

Setting Up Locales

Because the Twig Extensions I18N functionality is a wrapper around gettext, you’ll need to follow its normal configuration procedure, and then you’ll have access to helpers you can leverage within your Slim templates.

Generate Locales

Depending on your Linux distribution, you’ll need to appropriately generate the locales your project will support. For Ubuntu and other Debian-derived distributions, you can use locale-gen (followed by a list of locales to generate) along with dpkg-reconfigure locales. Centos uses localedef.

Further resources:

Ubuntu/Debian
Centos/Fedora

Declare Locale and Load Text Domain

The Twig Extensions documentation gives an example for setting up your locale within PHP and loading a textdomain for gettext that your project will use for translations.

Your own method may vary. Here’s a helper-class based example from a Slim 2.x project.

In my case, I created custom Slim 3 middleware. I negotiated locale using aura/accept using client request headers to select the best locale supported by my Slim project versus the client preferences.

In short, determine which locale to use, then have the current Slim instance switch to that locale for that user.

Using Twig L10N and I18N Extensions within Templates

Once you have the extensions installed and loaded into twig, your PHP environment has the intl extension, you have determined the locale to use and switched your Slim instance to use the new locale, you’re all set to use the helpers slim provides.

Here the vanilla Twig Extensions documentation shines. See examples in the official documentation.

Creating and Maintaining Translations

Surely you’ll want several translations built out for your app, and an easy way to maintain them. Luckily, leveraging the full power and popularity of gettext, you can create translations using Poedit. Unfortunately, Twig needs some help for translatable strings to be detected. Luckily, the Twig Gettext Extractor project makes easy work of the task.

As a user of Twig with Slim, you’ll find very few references for getting this to work with Slim rather than Symfony.

Its documentation suggests creating a copy of their script and customizing it manually, using any extensions you may need. I had issues until I commented out loading of Symfony-Specific Twig extensions they load by default, and adding in all extensions I’m using for Twig with Slim. The tool works by rendering each of your templates and extracting the generated PHP code (which gettext tools can statically extract from just fine) from the template cache. Accordingly, ensure all extensions used by your Twig Environment are loaded if necessary.

Other topics not discussed:

  • Leveraging the Intl Twig Extension