Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/saeven/zf2-poeditor

Front end to gettext that lets you translate your PHP and Twig files in a snap.
https://github.com/saeven/zf2-poeditor

Last synced: 25 days ago
JSON representation

Front end to gettext that lets you translate your PHP and Twig files in a snap.

Awesome Lists containing this project

README 

        
# 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

// 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

// 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.



## Installation



To install the packages:



    composer require saeven/zf2-poeditor



Then add these modules to your ZF2 application config:



    CirclicalTranslationEditor



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



    CirclicalTwigTrans



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.



## Configuration



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* |



### Stubs



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]

(http://i.imgur.com/GW2LmIr.png)



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



## Contributing



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!