API de traduction des entités

Dans Drupal 8, la langue des champs n’est plus exposée dans l’API publique, à la place les champs sont attachés à des objets avec prise en charge de la langue, dont ils « héritent » leur langue.

Les principaux avantages sont :

• Nous n’avons plus à nous soucier de la portabilité des champs, car cela est géré par l’objet entité lui-même.

// Déterminez le $active_langcode d’une manière ou d’une autre.
$translation = $entity->getTranslation($active_langcode);
$value = $translation->field_foo->value;

• Nous n’avons plus besoin de passer la langue active, en fait nous pouvons simplement passer un objet traduction qui implémente EntityInterface et qui est en réalité un clone de l’objet source, simplement avec une langue interne différente. Cela signifie que dans de nombreux cas, le code obtenu n’a pas besoin de connaître la langue (bien sûr, sauf si cela est explicitement lié à la langue).

// Instanciez l’objet traduction approprié une seule fois et transmettez-le partout où il est nécessaire.
// Ceci est généralement géré par les sous-systèmes du cœur et dans de nombreux cas courants
// une récupération explicite de l’objet traduction n’est pas nécessaire.
$langcode = Drupal::languageManager()->getLanguage(Language::TYPE_CONTENT);
$translation = $entity->getTranslation($langcode);
entity_do_stuff($translation);

function entity_do_stuff(EntityInterface $entity) {
  $value = $entity->field_foo->value;
  // faire quelque chose
}

• Nous avons maintenant une API réutilisable pour la résolution de la langue de l’entité, qui peut être utilisée pour déterminer la traduction d’entité la plus appropriée à un contexte donné :

// Code simplifié pour générer un tableau rendu pour une entité.
function viewEntity(EntityInterface $entity, $view_mode = 'full', $langcode = NULL) {
  // La méthode EntityManagerInterface::getTranslationFromContext()
  // applique la logique de négociation de langue sur l’objet entité entier
  // et retourne l’objet traduction approprié pour le contexte donné.
  // Le paramètre $langcode est optionnel et indique la langue du
  // contexte actuel. S’il n’est pas spécifié, la langue du contenu courant
  // est utilisée, ce qui est le comportement souhaité lors du rendu.
  // Notez que les valeurs des champs ne sont pas modifiées dans le processus,
  // donc les valeurs vides ne seront simplement pas affichées.
  $langcode = NULL;
  $translation = $this->entityManager->getTranslationFromContext($entity, $langcode);
  $build = entity_do_stuff($translation, 'full');
  return $build;
}

Nous pouvons également fournir un paramètre optionnel $context, qui peut être utilisé pour décrire le contexte dans lequel l’objet traduction sera utilisé :

// Code simplifié de génération de remplacements de tokens.
function node_tokens($type, $tokens, array $data = array(), array $options = array()) {
  $replacements = array();

  // Si aucune langue n’est spécifiée pour ce contexte, on utilise par défaut
  // la langue par défaut de l’entité.
  if (!isset($options['langcode'])) {
    $langcode = Language::LANGCODE_DEFAULT;
  }

  // Nous passons un paramètre $context décrivant l’opération en cours.
  // L’opération par défaut est 'entity_view'.
  $context = array('operation' => 'node_tokens');
  $translation = \Drupal::service('entity.repository')->getTranslationFromContext($data['node'], $langcode, $context);
  $items = $translation->get('body');

  // faire quelque chose

  return $replacements;
}

La logique utilisée pour déterminer l’objet traduction retourné peut être modifiée par des modules. Voir LanguageManager::getFallbackCandidates() pour plus de détails.

Les données réelles des champs sont partagées entre tous les objets traduction, et modifier la valeur d’un champ non traduisible modifie automatiquement sa valeur pour tous les objets traduction.

$entity->langcode->value = 'en';
$translation = $entity->getTranslation('it');

$en_value = $entity->field_foo->value; // $en_value vaut 'bar'
$it_value = $translation->field_foo->value; // $it_value vaut 'bella'

$entity->field_untranslatable->value = 'baz';
$translation->field_untranslatable->value = 'zio';
$value = $entity->field_untranslatable->value; // $value vaut 'zio'

À tout moment, on peut créer une instance d’un objet traduction à partir de l’objet source ou d’un autre objet traduction grâce à la méthode EntityInterface::getTranslation(). Si la langue active est explicitement nécessaire, elle peut être obtenue via EntityInterface::language(). L’entité source peut être obtenue via EntityInterface::getUntranslated().

$entity->langcode->value = 'en';

$translation = $entity->getTranslation('it');
$langcode = $translation->language()->id; // $langcode vaut 'it'

$untranslated_entity = $translation->getUntranslated();
$langcode = $untranslated_entity->language()->id; // $langcode vaut 'en'

$identical = $entity === $untranslated_entity; // $identical vaut TRUE

$entity_langcode = $translation->getUntranslated()->language()->id; // $entity_langcode vaut 'en'

EntityInterface possède désormais plusieurs méthodes facilitant le travail avec les traductions d’entités. Si un morceau de code doit agir sur chaque traduction disponible, il peut utiliser EntityInterface::getTranslationLanguages() :

foreach ($entity->getTranslationLanguages() as $langcode => $language) {
  $translation = $entity->getTranslation($langcode);
  entity_do_stuff($translation);
}

Il existe aussi des moyens d’ajouter une traduction, de la supprimer ou de vérifier sa présence :

if (!$entity->hasTranslation('fr')) {
  $translation = $entity->addTranslation('fr', array('field_foo' => 'bag'));
}

// Ce qui équivaut au code suivant, bien qu’une exception soit levée si un code langue invalide est spécifié.
$translation = $entity->getTranslation('fr');
$translation->field_foo->value = 'bag';

// Accéder à un champ sur un objet traduction supprimé provoque une exception.
$translation = $entity->getTranslation('it');
$entity->removeTranslation('it');
$value = $translation->field_foo->value; // lance une InvalidArgumentException

Lorsque des traductions d’entité sont ajoutées ou supprimées du stockage, les hooks suivants sont déclenchés :

• hook_entity_translation_insert()
• hook_entity_translation_delete()

La langue d’un champ peut toujours être obtenue en appelant la méthode appropriée sur l’objet champ lui-même :

$langcode = $translation->field_foo->getLangcode();