Drupal 8 Migrate Multilingual Content using Migrate API

As a follow-up to my previous blog post about the usage of Migrate API in Drupal 8, I would like to give an example, how to import multilingual content and translations in Drupal 8.

Prepare and enable translation for your content type

Before you can start, you need to install the “Language” and “Content Translation” Module. Then head over to “admin/config/regional/content-language” and enable Entity Translation for the node type or the taxonomy you want to be able to translate.

As a starting point for setting up the migrate module, I recommend you my blog post mentioned above. To import data from a CSV file, you also need to install the migrate_source_csv module.

Prerequisites for migrating multilingual entities

Before you start, please check the requirements. You need at least Drupal 8.2 to import multilingual content. We need the destination option “translations”, which was added in a patch in Drupal 8.2. See the corresponding drupal.org issue here.

Example: Import multilingual taxonomy terms

Let's do a simple example with taxonomy terms. First, create a vocabulary called “Event Types” (machine name: event_type).

Here is a simplified dataset:

You may save this a csv file.

Id;Name;Name_en
1;Kurs;Course
2;Turnier;Tournament

The recipe to import multilingual content

As you can see in the example data,  it contains the base language (“German”) and also the translations (“English”) in the same file.

But here comes a word of warning:

Don't try to import the term and its translation in one migration run. I am aware, that there are some workarounds with post import events, but these are hacks and you will run into troubles later.

The correct way of importing multilingual content, is to

1. create a migration for the base language and import the terms / nodes. This will create the entities and its fields.
2. Then, with an additional dependent migration for each translated language, you can then add the translations for the fields you want.

In short: You need a base migration and a migration for every language. Let's try this out.

Taxonomy term base language config file

In my example, the base language is “German”. Therefore, we first create a migration configuration file for the base language:

This is a basic example in migrating a taxonomy term in my base language ‘de'.

Put the file into <yourmodule>/config/install/migrate.migration.event_type.yml and import the configuration using the drush commands explained in my previous blog post about Migration API.

id: event_type
label: Event Types
source:
  plugin: csv
  # Full path to the file. Is overriden in my plugin
  path: public://csv/data.csv
  # The number of rows at the beginning which are not data.
  header_row_count: 1
  # These are the field names from the source file representing the key
  # uniquely identifying each node - they will be stored in the migration
  # map table as columns sourceid1, sourceid2, and sourceid3.
  keys:
    - Id
ids:
  id:
    type: string
destination:
  plugin: entity:taxonomy_term
process:
  vid:
   plugin: default_value
   default_value: event_type
  name:
    source: Name
    language: 'de'
  langcode:
    plugin: default_value
    default_value: 'de'

#Absolutely necessary if you don't want an error
migration_dependencies: {}

Taxonomy term translation migration configuration file:

This is the example file for the English translation of the name field of the term.

Put the file into <yourmodule>/config/install/migrate.migration.event_type_en.yml and import the configuration using the drush commands explained in my previous blog post about Migration API.

id: event_type_en
label: Event Types english
source:
  plugin: csv
  # Full path to the file. Is overriden in my plugin
  path: public://csv/data.csv
  # The number of rows at the beginning which are not data.
  header_row_count: 1
  keys:
    - Id
ids:
  id:
    type: string
destination:
  plugin: entity:taxonomy_term
  translations: true
process:
  vid:
    plugin: default_value
    default_value: event_type
  tid:
    plugin: migration
    source: id
    migration: event_type
  name:
    source: Name_en
    language: 'en'
  langcode:
     plugin: default_value
     default_value: 'en'

#Absolutely necessary if you don't want an error
migration_dependencies:
  required:
    - event_type

Explanation and sum up of the learnings

The key in the migrate configuration to import multilingual content are the following lines:

destination:
  plugin: entity:taxonomy_term
  translations: true

These configuration lines instruct the migrate module, that a translation should be created.

tid:
  plugin: migration
  source: id
  migration: event_type

This is the real secret. Using the process plugin migration,  we maintain the relationship between the node and its translation.The wiring via the tid field make sure, that Migrate API will not create a new term with a new term id. Instead, the existing term will be loaded and the translation of the migrated field will be added. And thats exactly what we need!

Now go ahead and try to create a working example based on my explanation. Happy Drupal migrations!