README

Manually pasted text on document for translation, by means of buffering is translated by one approach (helpful for DB sources).
Include vendors:

Installation

$ composer require ali-translator/buffered-translation

Quick start

Since this package extended from ali-translator/translator, at first you need create $translator and wrapper, with vector of his translation - $plaiTranslator

use ALI\BufferTranslation\BufferTranslation;
use ALI\Translator\PlainTranslator\PlainTranslator;
use ALI\Translator\Languages\LanguageRepositoryInterface;

/** @var PlainTranslator $plainTranslator */
/** @var LanguageRepositoryInterface $languageRepository */

$bufferTranslation = new BufferTranslation($plainTranslator, $languageRepository);

Move created $bufferTranslation to document creating process :

/** @var \ALI\BufferTranslation\BufferTranslation $bufferTranslation */
?>
<h1>
    <?= $bufferTranslation->add('Hello World!') ?>
</h1>
<p>
    <?= $bufferTranslation->add('Hello {name}', ['name' => 'Tom']) ?>    
</p>

Use "logical variable" for plural templates:

?>
<p>
    <?= $bufferTranslation->add(
            '{name} has {plural(appleNumbers,"=0[no one apple] =1[one apple] other[many apples]")}', 
            [
                'appleNumbers' => 0,
                'name' => 'Tom',
            ]
    ) ?>
    <?= $bufferTranslation->add($stringFromDb, [], [BufferContentOptions::OPTION_WITH_HTML_ENCODING => true]) ?>  
</p>

Custom post-translation modification:

<script>
    alert('<?= $bufferTranslation->add($errorText, [], [
                  BufferContentOptions::MODIFIER_CALLBACK => function (string $translation): string {
                       return Html::escapeJavaScriptStringValue($translation);
                  },
         ]) ?>');
</script>

And then translate this buffer document:

use ALI\BufferTranslation\BufferTranslation;

/** @var BufferTranslation $bufferTranslation */
/** @var string $html */

echo $bufferTranslation->translateBuffer($html);

Multiple level parameters, and they options

$html = '<div class="test">' . $bufferTranslation->add('Hello {child}. Hi {object}', [
        'child' => [
            'content' => 'Tom and {secondName}',
            'parameters' => [
                'secondName' => [
                    'content' => 'Andrea',
                    'options' => [
                        BufferContentOptions::WITH_CONTENT_TRANSLATION => true,
                    ]
                ],
            ],
        ],
        'object' => 'sun',
    ]) . '</div>';
$translatedHtml = $bufferTranslation->translateBuffer($html);

Translation is recursive.

Logical variables

Template support is implemented on the basis of the "ali-translator/text-template" package, which also supports "logical variables". These are variables that use "functions" to modify content. More details can be found at the link to the package.
Example:
Поїздка {uk_choosePrepositionBySonority('Поїздка', 'в/у', 'Львів')} Львів

Options

Every buffered phrase has translation options parameters, with next features:

BufferContentOptions::WITH_CONTENT_TRANSLATION It's bool parameter, which indicates whether to translate included parameter.
By default, this value is set to "false".
BufferContentOptions::WITH_FALLBACK Bool parameter, which determines whether the original text will be returned if no translation is found.
By default, this value is set to "true".
BufferContentOptions::WITH_HTML_ENCODING - use html encode for output text
BufferContentOptions::MODIFIER_CALLBACK - custom post-translation modifier

Translation of a fragment of buffered text

If you only need to translate a single piece of buffered text, you should use the "translateBufferFragment" method:

$translatedHtml = $bufferTranslation->translateBuffer($pieceOfHtml);

this method only translate the found keys in the given context, not all buffered text.

Translation of buffered array

! Translation of buffered arrays is less efficient than normal translation of compiled text, and should not be considered as a primary option.

/**
* @param array|null $columnsForTranslation - null means "all string columns"
* @param bool $isItBufferFragment - Choose whether you want to translate the entire buffer or only the existing keys in the text
 */
$translatedBufferedArray = $bufferTranslation->translateArrayWithBuffers($bufferedArray, $columnsForTrnasl, $columnsForTranslation);

Hints

If you have already a buffered key and want to use it in another template, you can use this script:

$bufferTranslation->add('Some {text}',[
    'text' => $bufferTranslation->getTextTemplateItemByBufferKey($alreadyBufferedTextKey) 
]);

If you use several BufferedTranslation services at once (for example, the language of texts in the code and dynamic texts from the database is different) - and you need to use the translation of one of the texts in the second template, it is recommended to do so:

$buffer = $firstBufferTranslation->add('Some {text}',[
    'text' => $secondBufferTranslation->createAndAddTextTemplateItem('текст') 
]);

Later, before "resolve", you need to call the "preTranslateAllInsideTextTemplates" method, which will translate all registered templates:

$firstBufferTranslation->preTranslateAllInsideTextTemplates();
$secondBufferTranslation->preTranslateAllInsideTextTemplates();

$buffer = $firstBufferTranslation->translateBuffer($buffer);
$result = $secondBufferTranslation->translateBuffer($buffer);

More details can be found in the test code: ./tests/unit/FewBufferTranslationServiceAtOnceTest.php

Suggest packets

ali-translator/translator-js-integrate - Integrate this packet to frontend js
ali-translator/auto-html-translation - Parses html document, and translate included texts
ali-translator/url-template - Helps on url language resolving

Tests

In packet exist docker-compose file, with environment for testing.

docker-compose run php composer install
docker-compose run php vendor/bin/phpunit

ali-translator / buffered-translation

Maintainers

Details