Allows the use of a POT/PO/MO (gettext) set of language definitions with Twig, using an identical syntax to the current official Twig translation extension.
It supports full extraction of Twig templates into language catalogues from the gettext/gettext library, which you can use to write out POT files if desired.
Additionally support for extraction of text values from PHP is possible when directly using the translate
function
from\Acpr\I18n\Translator
in your code. For instance, you may be creating translated flash messages and storing them
in your session to be used by subsequent twig templates.
-
Translation tags (
{% trans %} ... {% endtrans %}
) and filters (| trans
) -
Variable interpolation
{% trans with { '%var%': var } %}%var%{% endtrans %}
-
Pluralisation
{% trans count 3 %}%count% item|%count% items{% endtrans %}
-
Message specific domains
{% trans from 'errors' %} ... {% endtrans %}
-
Message contexts
{% trans %} ... {% context %}Some context{% endtrans %}
-
Notes/comments for the translation
{% trans %} ... {% notes %}A translation note{% endtrans %}
-
or some horrid combination of all of them
{% trans count 5 with { '%name%': 'Adam' } from 'errors' %} %name% has %count% apple|%name% has %count% apples {% notes %}A translation note {% context %}Some context to the translation {% endtrans %}
The extraction of which would result in a
errors.pot
file that contains:#. A translation note msgctxt "Some context to the translation" msgid "%name% has %count% apple" msgid_plural "%name% has %count% apples" msgstr[0] ""
And the (default, i.e. no language supplied) output of which would look like
Adam has 5 apples
The PHP extraction works by parsing the text of your PHP files through nikic/php-parser . This requires your PHP to be valid in order to work.
You could have a PHP file
/** @var $translator \Acpr\I18n\Translator **/
$pluralApples = $translator->translate(
'%name% has %count% apple',
[
'%name' => 'Adam'
],
'errors',
'Some context to the translation',
'%name% has %count% apples',
5
);
// Assuming no translations had been loaded
// $pluralApples == 'Adam has 5 apples'
The extraction of which would result in a errors.pot
file that contains:
msgctxt "Some context to the translation"
msgid "%name% has %count% apple"
msgid_plural "%name% has %count% apples"
msgstr[0] ""
-
The extraction specifically looks for usages of a
translate
function with the correct signature. This may result in false positives dependent on your code base. -
It is not currently possible to add notes/comments to a translation entry.
-
For the correct values to be parsed, the string arguments to the
translate
function must be inlined strings (quoted or heredoc). It is not possible to use variables.// This will *not* work $var = 'I have an apple'; $value = $translator->translate($var); // This will $value = $translator->translate('I have an apple');
See extract.php and index.php for example usage.
v3 introduces a new method of extracting keys that removes whitespace of more than 2 characters from the primary language keys (see the release notes for more information)
There is a script available in the scripts folder that will help to migrate any existing PO files you have to the newer keys and minimise the pain of poedit deciding everything is new rather than different. It will likely need editing to your requirements but is usage is simple.
$ cp scripts/v3_po_update.php folder/containing/po.files
$ cd folder/containing/po.files
# edit script as appropriate for your translation domains
$ php v3_po_update.php