Translation Queue

This document describes the usage / implementation of the Translation Queue in Pimcore projects.

Configuration

Cronjob

*/5 * * * * php bin/console messenger:consume twocream_deepl_object_translation --time-limit 300

Object Translation

Describes how an object must be passed to the Translation Queue so that it can be translated. All localized fields within an object can be translated, as long as they are direct fields, are located in blocks, and are part of an ObjectBrick. In order for the different fields to be translatable, they must be passed to the queue in a specific way.

TranslateObjectMessage

<?php

public function __construct(
  // The ID of the object to be translated
  int $objectId,

  // The language (Pimcore) from which to translate
  string $pimcoreSourceLanguage,

  // The languages (Pimcore) into which to translate,
  // If no languages are specified, ALL languages configured in Pimcore are translated
  ?array $pimcoreTargetLanguages = null,

  // The fields directly defined within localized field containers.
  // If no field is specified, no field will be translated.
  ?array $localizedFields = null,

  // The block fields within the object that should be translated.
  // Nested with the fields inside the blocks to be translated.
  // If no block or field is specified, nothing will be translated.
  ?array $blockFields = null,

  // The Object-Brick fields within an object that should be translated.
  // First, include the bricks that need to be translated.
  // Then, include the fields within a brick that should be translated.
  // If no brick field, brick, or field in the brick is specified, no translation occurs.
  ?array $bricks = null,

  // List of Field Collections fields and their selected Field Collection types with the fields to be translated.
  // The array structure can be inferred from the example below.
  ?array $fieldCollections = null,

  // List of object relation fields within the object to be translated.
  // Which fields within the object relation should be translated is determined based on the DeepL object configuration.
  // The array structure can be inferred from the example below.
  ?array $objectRelations = null,

  // The glossary IDs to be used for translating the object
  // Nested from source language to target languages and glossary IDs
  ?array $glossaries = null,

  // Skip translation if content already exists in the field of the respective target language
  bool $skipExistingTranslations = false,

  // If active, texts from the source language are considered during translation and are inherited.
  // These are then written locally in the target language.
  bool $allowInheritedValues = false
)

Example

<?php

$localizedFields = [
  'FeldInnerhalbEinesLokalisiertenFeldContainersImObjekt',
  'input',
];

$blockFields = [
  'BlockFeldImObjekt' => [
    'FeldInnerhalbEinesLokalisiertenFeldContainer',
  ],
  'block' => [
    'blockInput',
  ],
];

$bricks = [
  'BrickFeldImObjekt' => [
    'NameDesBricksInnerhalbDesBrickFeldes' => [
      'FeldInnerhalbDesBricksInnerhalbEinesLokalisiertenFeldContainer',
    ],
    'test2' => [
      'input'
    ],
  ],
];

$fieldCollections = [
  'FieldCollectionFeldImObjekt' => [
    'NameDerAusgewähltenFieldCollection' => [
      'FeldInnerhalbDerFieldCollectionA',
      'FeldInnerhalbDerFieldCollectionB',
    ],
  ],
];

$objectRelations = [
  'RelationsFeldA',
  'RelationsFeldB',
  'RelationsFeldC',
];

$deepLGlossaryIds = [
  'de' => [
    'pl_PL' => 'f31ee103-a555-4085-8864-86894d506d27',
  ],
];

new TranslateObjectMessage(
  61,
  'de',
  ['en', 'pl_PL'],
  $localizedFields,
  $blockFields,
  $bricks,
  $fieldCollections,
  $relations,
  $deepLGlossaryIds
);

Using the Message Queue

We need the Symfony Message Bus within controllers, event listeners, etc., to send a message. Through the TranslationConfigurationLoader, we obtain the DeepL object configuration for the respective object class.

<?php

use Pimcore\Controller\FrontendController;
use Pimcore\Model\DataObject;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Twocream\CoreBundle\Helper\EditLockHelper;
use Twocream\DeepLBundle\Exception\DeepLConfigurationNotFoundException;
use Twocream\DeepLBundle\Helper\TranslationConfigurationLoader;
use Twocream\DeepLBundle\MessageQueue\TranslateObjectMessage;

class DefaultController extends FrontendController
{
    public function defaultAction(
        Request $request,
        // The MessageBus is a service and should be injected (via constructor)
        MessageBusInterface $messageBus
    ): Response {
        $object = DataObject::getById($request->get('objectId'));

        // We can request the YAML configuration of the DeepL object configuration via the TranslationConfigurationLoader
        $configuration = TranslationConfigurationLoader::getDataObjectConfiguration($object::class);

        if ($configuration === null) {
            throw new DeepLConfigurationNotFoundException(
                sprintf('No configuration found for %s', $object::class)
            );
        }

        $sourceLanguage = $request->get('sourceLanguage');
        $targetLanguage = $request->get('targetLanguage');
        $glossaryId = $request->get('glossaryId') ?? null;
        $skipExistingTranslation = $request->get('skipExistingTranslation') ?? false;
        $allowInheritedValues = $request->get('allowInheritedValues') ?? false;

        $fields = $configuration['fields'] ?? null;
        $blocks = $configuration['blocks'] ?? null;
        $bricks = $configuration['bricks'] ?? null;
        $fieldCollections = $configuration['fieldCollections'] ?? null;
        $objectRelations = $configuration['relations'] ?? null;

        $deeplGlossaryId[$sourceLanguage][$targetLanguage] = $glossaryId;

        // OPTIONAL (STRONGLY RECOMMENDED)
        // The Translation Queue always performs a "Release."
        // This prevents the object from being open in the backend during processing
        // / shows a "being processed" message.
        // For more information, see the documentation of the core bundle.
        EditLockHelper::lock(
            $object->getId(),
            'object',
            'translation'
        );

      // The MessageBus has a method. Using dispatch()
      // the message is added to the queue and processed
      $messageBus->dispatch(new TranslateObjectMessage(
        $object->getId(),
        $sourceLanguage,
        [$targetLanguage],
        $fields,
        $blocks,
        $bricks,
        $fieldCollections,
        $relations,
        $deepLGlossaryId,
        $skipExistingTranslation,
        $allowInheritedValues
      ));

      // ...
    }
}