school/html-java-script/myAWSsite/html/phpMyAdmin/vendor/phpmyadmin/twig-i18n-extension/README.rst

Twig i18n Extension
===================

The ``i18n`` extension adds `gettext`_ support to Twig. It defines one tag,
``trans``.

Installation
------------

This library can be installed via Composer running the following from the
command line:

.. code-block:: bash

    composer require phpmyadmin/twig-i18n-extension

Configuration
-------------

You need to register this extension before using the ``trans`` block

.. code-block:: php

    use PhpMyAdmin\Twig\Extensions\I18nExtension;

    $twig->addExtension(new I18nExtension());

Note that you must configure the ``gettext`` extension before rendering any
internationalized template. Here is a simple configuration example from the
PHP `documentation`_

.. code-block:: php

    // Set language to French
    putenv('LC_ALL=fr_FR');
    setlocale(LC_ALL, 'fr_FR');

    // Specify the location of the translation tables
    bindtextdomain('myAppPhp', 'includes/locale');
    bind_textdomain_codeset('myAppPhp', 'UTF-8');

    // Choose domain
    textdomain('myAppPhp');

.. caution::

    The ``i18n`` extension only works if the PHP `gettext`_ extension is
    enabled.

Usage
-----

Use the ``trans`` block to mark parts in the template as translatable:

.. code-block:: twig

    {% trans "Hello World!" %}

    {% trans string_var %}

    {% trans %}
        Hello World!
    {% endtrans %}

In a translatable string, you can embed variables:

.. code-block:: twig

    {% trans %}
        Hello {{ name }}!
    {% endtrans %}

During the gettext lookup these placeholders are converted. ``{{ name }}`` becomes ``%name%`` so the gettext ``msgid`` for this string would be ``Hello %name%!``.

.. note::

    ``{% trans "Hello {{ name }}!" %}`` is not a valid statement.

If you need to apply filters to the variables, you first need to assign the
result to a variable:

.. code-block:: twig

    {% set name = name|capitalize %}

    {% trans %}
        Hello {{ name }}!
    {% endtrans %}

To pluralize a translatable string, use the ``plural`` block:

.. code-block:: twig

    {% trans %}
        Hey {{ name }}, I have one apple.
    {% plural apple_count %}
        Hey {{ name }}, I have {{ count }} apples.
    {% endtrans %}

The ``plural`` tag should provide the ``count`` used to select the right
string. Within the translatable string, the special ``count`` variable always
contain the count value (here the value of ``apple_count``).

To add notes for translators, use the ``notes`` block:

.. code-block:: twig

    {% trans %}
        Hey {{ name }}, I have one apple.
    {% plural apple_count %}
        Hey {{ name }}, I have {{ count }} apples.
    {% notes %}
        This is shown in the user menu. This string should be shorter than 30 chars
    {% endtrans %}

You can use ``notes`` with or without ``plural``. Once you get your templates compiled you should
configure the ``gettext`` parser to get something like this: ``xgettext --add-comments=notes``

Within an expression or in a tag, you can use the ``trans`` filter to translate
simple strings or variables:

.. code-block:: twig

    {{ var|default(default_value|trans) }}

Complex Translations within an Expression or Tag
------------------------------------------------

Translations can be done with both the ``trans`` tag and the ``trans`` filter.
The filter is less powerful as it only works for simple variables or strings.
For more complex scenario, like pluralization, you can use a two-step
strategy:

.. code-block:: twig

    {# assign the translation to a temporary variable #}
    {% set default_value %}
        {% trans %}
          Hey {{ name }}, I have one apple.
        {% plural apple_count %}
          Hey {{ name }}, I have {{ count }} apples.
        {% endtrans %}
    {% endset %}

    {# use the temporary variable within an expression #}
    {{ var|default(default_value|trans) }}

Extracting Template Strings
---------------------------

If you use the Twig I18n extension, you will probably need to extract the
template strings at some point.

Using Poedit 2
~~~~~~~~~~~~~~

Poedit 2 has native support for extracting from Twig files and no extra
setup is necessary (Pro version).

Using ``xgettext`` or Poedit 1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Unfortunately, the ``xgettext`` utility does not understand Twig templates
natively and neither do tools based on it such as free versions of Poedit.
But there is a simple workaround: as Twig converts templates to
PHP files, you can use ``xgettext`` on the template cache instead.

Create a script that forces the generation of the cache for all your
templates. Here is a simple example to get you started

.. code-block:: php

    use Twig\Environment;
    use Twig\Loader\FilesystemLoader;
    use PhpMyAdmin\Twig\Extensions\I18nExtension;

    $tplDir = __DIR__ . '/templates';
    $tmpDir = '/tmp/cache/';
    $loader = new FilesystemLoader($tplDir);

    // force auto-reload to always have the latest version of the template
    $twig = new Environment($loader, [
        'auto_reload' => true,
        'cache' => $tmpDir,
    ]);
    $twig->addExtension(new I18nExtension());
    // configure Twig the way you want

    // iterate over all your templates
    foreach (new RecursiveIteratorIterator(new RecursiveDirectoryIterator($tplDir), RecursiveIteratorIterator::LEAVES_ONLY) as $file)
    {
        // force compilation
        if ($file->isFile()) {
            $twig->loadTemplate(str_replace($tplDir . '/', '', $file));
        }
    }

Use the standard ``xgettext`` utility as you would have done with plain PHP
code:

.. code-block:: text

    xgettext --default-domain=messages -p ./locale --from-code=UTF-8 -n --omit-header -L PHP /tmp/cache/*.php

Another workaround is to use `Twig Gettext Extractor`_ and extract the template
strings right from `Poedit`_.

.. _`gettext`:                https://www.php.net/gettext
.. _`documentation`:          https://www.php.net/manual/en/function.gettext.php
.. _`Twig Gettext Extractor`: https://github.com/umpirsky/Twig-Gettext-Extractor#readme
.. _`Poedit`:                 https://poedit.net/

History
-------

This project was forked in 2019 by the phpMyAdmin team, since it was abandoned by the
`Twig project`_ but was still in use for phpMyAdmin.

.. _`Twig project`: https://github.com/twigphp/Twig-extensions

If you find this work useful, or have a pull request to contribute, please find us on
`Github`_.

.. _`Github`: https://github.com/phpmyadmin/twig-i18n-extension/