Migrating Content Translated with "Entity Translation" in Drupal

⚠️ November 2020 update: We've written an updated version of this tutorial with new code samples. Read it here.

Since the release of Drupal 8 with a standardized way of managing translations, many sites running Drupal 7 are making a switch to Drupal 8. In Drupal 7 there are two ways to translate content:

1. Using the content_translation module. The D7 core way of translating content, where every translation is a separate node.
2. Using the entity_translation module. Maintains one node with a unique nid, while translations take place at the field level.

In this article we will discuss how to migrate content translations created with the entity_translation module from Drupal 7 to Drupal 8. You can find our tutorial about migrating translations that use Content Translation here.

This article would not have been possible without the help of my colleague Dave. Merci Dave!

The problem

We have a Drupal 7 database containing article nodes, which might have translations in English, Spanish and French. Some of these nodes are language-neutral, i.e. non-translatable. Our target is to migrate the D7 nodes into a D8 website, preserving the translations.

Before we start

• Since this is an advanced migration topic, it is assumed you already know the basics of migration. If you are new to migrations in Drupal 8, I recommend that you read about migrating basic data to Drupal 8 first.
• This article assumes that you have read our previous article on how to migrate content translations from Drupal 7 to Drupal 8 or have the relevant knowledge.
• To execute the migrations in this example, you can download the drupal migration i18n example repository from GitHub. The module should work without any trouble for a standard Drupal 8 install. See quick-start for more information.
• To see the example migrations in action, you need:
  • A Drupal 8 site.
  • The relevant D7 database, since we are migrating data from a Drupal 6 site.
  • Drush will be required to execute migration commands.

The module

To write the migrations, we create a module - in our case, it has been named migrate_example_i18n. Just like migrating content translations from D7 to D8, we create 2 YML files to define:

• The example_creature_base migration will migrate all base data or non-translations.
  • The source/translations parameter is omitted or set to false.
  • The destination/translations parameter is omitted or set to false.
• The example_creature_i18n migration will migrate all translations.
  • The process/nid is configured to use the migration plugin to lookup the node in the base language.
  • The source/translations parameter is set to true.
  • The destination/translations parameter is to true.
  • The migration_dependencies parameter declares example_creature_base as a dependency.

We group the two migrations using the example_creature migration group to keep things clean and organized. Then we can execute both migrations with drush migrate-import --group=example_creature --update.

How to migrate Entity Translations?

Entity translations! Drupal 7 content translations are supported since Drupal 8.3. At the point of writing this, there is no standard method for migrating entity translations to Drupal 8. In this example, we will migrate D7 nodes translated with the entity_translation module, however, the procedure should be similar for other entity types as well. Before we start, here are some notes about what's so different about entity translations:

• All translations have the same entity_id. So, for a translated node, the entity_translation module will result in only one entry in the node table.
• Translation information, certain metadata and revision information for entities is stored in the entity_translation table.

So if an English node with ID 19 has translations in Spanish and French, the entity_translations table has the following records:

The above data structure is significantly different from the content translation structure. In fact, Drupal 8 handles translations much like the entity translation module! Hence, to handle entity-translations, we must take the entity_translation table into consideration, which the core d7_node source plugin does not do at the time of writing this article. Hence, we override the d7_node source with a custom source plugin named d7_node_entity_translation.

class D7NodeEntityTranslation

Reference: D7NodeEntityTranslation.php

This is where we jump into code! We override certain methods of d7_node source to add support for the entity_translation table.

class D7NodeEntityTranslation extends D7Node {
  // Determines if the node-type being translated supports entity_translation.
  protected function isEntityTranslatable() {}
  // Depending on the "source/translations" parameter, this method alters
  // the migration query to return only translations or non-translations.
  protected function handleTranslations(SelectInterface $query) {}
  // This method has been overridden to ensure that every node's fields are
  // are loaded in the correct language.
  public function prepareRow(Row $row) {}
  // This method is called by the prepareRow() method to load field values
  // for source nodes. We override this method to add support for $language.
  protected function getFieldValues($entity_type, $field, $entity_id, $revision_id = NULL, $language = NULL) {}
  // Since all source nodes have the same "nid", we need to use a
  // combination of "nid:language" to distinguish each source translation.
  public function getIds() {}
}

Here's a quick look at the changes we need to make:

• function getIds() tells the migrate API to use one or more source properties which should be used to uniquely identify source records. When working with entity translations, all translations have the same entity_id, but they have a different language. We override this method to tell Drupal to consider both the entity_id and the language properties to uniquely identify source records. So, the source records are uniquely identified something like 19:en, 19:es, 19:fr instead of using just 19.
• function handleTranslations() is the method which adds support for the translations parameter we use in the source plugin. The translations parameter tells Drupal whether to migrate entities in their base language or to migrate translations. We override this method to:
  • See if the node type being migrated supports entity translations.
  • If the node type supports entity translations, then we INNER JOIN entity_translation and read translation data and some entity metadata, like date of creation, date of updation, etc from that table.
• function prepareRow() as the name suggests, prepares a row of source data before it is passed to the process plugins. At this stage, field data is also attached to the source data. However, it does not load field data in the language specified in the source row. To overcome this problem, we override the getFieldValues() method and make sure it loads the field data in the same language as specified in the source row.

That's it! You should now be able to run the migration with drush migrate-import --group=example_creature --update. The output should look something like this:

$ drush mi --group=example_creature --update
Processed 9 items (9 created, 0 updated, 0 failed, 0 ignored) - done with 'example_creature_base'
Processed 9 items (9 created, 0 updated, 0 failed, 0 ignored) - done with 'example_creature_i18n'

Note: Keep an eye out for Drupal core updates. If the drupal_migrate module adds support for entity translations, migrating entity translations might become much easier.

Next Steps

• View the code for the migrate_example_i18n project on GitHub.
• Read about migrating content translations from Drupal 7 to Drupal 8.
• Read about migrating translated content from Drupal 6 to Drupal 8.
• Read about migrating translations from CSV, JSON or XML to Drupal 8.
• New to Drupal 8 migrations? Start with Drupal 8 migration basics.