Skip to content
Front end to gettext that lets you translate your PHP and Twig files in a snap.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Zend Framework 2 Gettext File Editor

Want a PHP/Twig file parser that's local to your project, with a web GUI to deal with gettext intricacies? This project is it!

How it works

This project combines a parser, an PHP PO file editor, and gettext CLI commands to do what programs like PoEdit do at the surface. You use translation markers in your code like:

// php code
_( "this string will automatically get picked up by gettext");
$sm->get('translator')->translate( "So will this one" );
$el->setLabel( "This one too");
// twig code
{% trans %}This is a singular translation{% endtrans %}
{% trans "This is also a singular translation" %}

{% set apples = 3 %}
{% trans %}
There is one apple in the cart.
{% plural apples %}
There are {{ apples }} in the cart.
{% endtrans %}

Then, when you use the web GUI you'll see a set of fields where you can edit all of your translatable-text.


To install the packages:

composer require saeven/zf2-poeditor

Then add these modules to your ZF2 application config:


Access /translate to confirm that it's set up. If you don't have a Twig/Trans bridge in there already, you can also load


To gain {% trans %} for Twig

You have to make sure that you have gettext installed as well. Check your system with these commands:

which msgfmt
which gettext
which xgettext
which msguniq

If they all exist, you are in business. Otherwise, Google how to get gettext binaries installed on your system.


Once you have downloaded the Composer package, copy the autoload config to your project:

cp ./vendor/saeven/zf2-poeditor/config/autoload/circlical.translator.local.php ./config/autoload

In that file, you'll see these config keys:

Key Name Description
xgettext Full path to your xgettext executable.
msgcat Full path to your msgcat executable.
msgfmt Full path to your msgfmt executable.
backup_dir The folder where .po files are backed up with each pass. must be writable
cache_dir The cache folder where the temporary .pot files are stored during compilation. must be writable
stub_functions See 'Stubs' below
stub_filters See 'Stubs' below


If you are coming from the camp that combines PoEdit with a Twig extractor, you'll remember those instances where you'd get a giant error message but no reason why. 90% of the time, it's because a developer had added a custom filter or helper that wasn't registered with the extractor. The outcome is breakage: the extractor dies, PoEdit can't ferry the error, and you're stuck cutting and pasting messages to identify the culprit.

Enter stubs.

When you are using this package, the Twig errors will be reported in plain sight if you meet this circumstance.

![Error Sample] (

In that image, you can see that the GrilledCheese helper is not registered (what a shame, so tasty). Somewhere in the Twig files, there's a {{ GrilledCheese }} that's causing the problem. To fix this:

  • Open up the translator config
  • Add 'GrilledCheese' to the function stubs
  • Save the config
  • Click refresh inside the translator

Filters work similarly, the error message will guide you properly.

Some Instructions!

Locale Discovery

Locale discovery depends on the proper set up of gettext message folders within your modules. These would like like:

module/Application/language/en_US/LC_MESSAGES module/Application/language/fr_CA/LC_MESSAGES

You'll have to set these up or there'll be no locales in the dropdown within the translator.

Scan Mode

The system scans your module folders only, for PHP and Twig files.

Compile Trigger

The pot files are compiled when you select a locale.

Configuration Required!

If you don't configure the languages that you work on, then you won't get the right PO headers in place. If this happens, then compilation from po to mo is not possible. Be sure to configure your file with the language team, charset, and plural form for your language.

Sanity Check

You can check your ./data/cache/translator folder for these files while you're working. Their presence lets you know things should be working:

  • *.php.pot
  • *.pot
  • translator.ini


This is a first release, but it works very well. It's my hope to PSR-7 this with Expressive so that all frameworks can benefit from its use. Throwing out to the world can only make it better! Have an idea or an issue you can solve? PR it up, let's make this tool a solid alternative to PoEdit together!

Thanks in advance!

You can’t perform that action at this time.