Yii 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'])),
],
]),
],
],
],
];
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
andMessageWriter
should be configured for using the sameMessageSource
. 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
except
option
Using 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/**
only
option
Using 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
Testing
Unit testing
The package is tested with PHPUnit. To run tests:
./vendor/bin/phpunit
Mutation testing
The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:
./vendor/bin/roave-infection-static-analysis-plugin
Static analysis
The code is statically analyzed with Psalm. To run static analysis:
./vendor/bin/psalm
License
The Yii translator extractor is free software. It is released under the terms of the BSD License. Please
see LICENSE
for more information.
Maintained by Yii Software.