README

Yii Translator Message Extractor

The package allows automatically extracting translation IDs from PHP source files and writing them to one of the translator message sources.

Requirements

• PHP 8.0 or higher.

Installation

The package could be installed with Composer:

composer require yiisoft/translator-extractor

Configuration

You need configure MessageReader and MessageWriter in config file of the package, config/console/translator-extractor.php:

For example, when using PHP MessageSource the config will be the following using relative path:

use \Yiisoft\Translator\Message\Php\MessageSource;

return [
    Extractor::class => [
        '__construct()' => [
            [
                DynamicReference::to([
                    'class' => ExtractorCategorySource::class,
                    '__construct()' => [
                        'app',
                        'messageReader' => DynamicReference::to(static fn () => new MessageSource($params['yiisoft/translator-extractor']['messagePath'])),
                        'messageWriter' => DynamicReference::to(static fn () => new MessageSource($params['yiisoft/translator-extractor']['messagePath'])),
                    ],
                ]),
            ],
        ],
        '->translate' // optional, default value for Translation call to look for.
    ],
];

And in params.php file you can configure parameters of a message source:

return [
    'yiisoft/yii-console' => [
        'commands' => [
            'translator/extract' => ExtractCommand::class,
        ],
    ],
    'yiisoft/translator-extractor' => [
        // Using relative path:
        'messagePath' => dirname(__DIR__, 5) . '/messages',
    ],
];

Or if with using PHP MessageSource the config will be the following using Aliases:

use \Yiisoft\Translator\Message\Php\MessageSource;

return [
    Extractor::class => [
        '__construct()' => [
            [
                DynamicReference::to([
                    'class' => ExtractorCategorySource::class,
                    '__construct()' => [
                        'app',
                        'messageReader' => DynamicReference::to(static fn (Aliases $aliases) => new MessageSource($aliases->get('@message'))),
                        'messageWriter' => DynamicReference::to(static fn (Aliases $aliases) => new MessageSource($aliases->get('@message'))),
                    ],
                ]),
            ],
        ],
    ],
];

Attention: Both MessageReader and MessageWriter should be configured for using the same MessageSource. The extractor needs it to work with existing messages.

General usage

./yii translator/extract

This command will recursively find all messages in the code starting with the current directory and will save it into a message source for default language en. You can specify the path explicitly:

./yii translator/extract /path/to/your/project

Notice: By default extractor has vendor directory in the application directory excluded. To include it you can specify empty value for except:

./yii translator/extract /path/to/your/project --except=''

Full list of options:

Usage:
  translator/extract [options] [--] [<path>]

Arguments:
  path                       Path for extracting message IDs.

Options:
  -L, --languages=LANGUAGES  Comma separated list of languages to write message sources for. By default it is `en`. [default: "en"]
  -C, --category=CATEGORY    Default message category to use when category is not set. [default: "app"]
  -E, --except[=EXCEPT]      Exclude path from extracting. (multiple values allowed)
  -O, --only[=ONLY]          Use the only specified path for extracting. (multiple values allowed)

Specify languages

You can specify multiple languages to write IDs into:

./yii translator/extract --languages=en,ru

Or in short format:

./yii translator/extract -Lru

Specify default category

Also, you can specify default message category to use when category is not set.

./yii translator/extract --category=your_category_name

Using except option

To exclude all directories named dir1 use --except:

./yii translator/extract --except=**/dir1/**

To exclude both vendor and tests directories the following options could be used:

./yii translator/extract --except=./vendor/** --except=./tests/**

Using only option

To parse only test.php files in any directory use --only option:

./yii translator/extract --only=**/test.php

To parse only /var/www/html/test.php file use:

./yii translator/extract --only=/var/www/html/test.php

For more info about except and only parameters check documentation of yiisoft/files package.

Working with gettext

The package currently does not support extracting messages into gettext format. To extract messages for gettext, you may use the following shell script (in Linux-based OS):

find src/ -name *.php | xargs xgettext --from-code=utf-8 --language=PHP --no-location --omit-header --sort-output --keyword=translate --output="locales/category.pot"

for d in locales/*/ ; do
    for i in locales/*.pot; do
        if [ ! -f "$d$(basename "$i" .pot).po" ]; then
            touch "$d$(basename "$i" .pot).po"
        fi

        msgmerge --update --silent --backup=off "$d$(basename "$i" .pot).po" $i
    done
done

Documentation

• Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

License

The Yii Translator Message Extractor is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Follow updates