A few months later, our clients prefered a media library using Drupal Media in Core and an Entity Browser to search and find their media assets.

The question is: Is it possible to convert my old-fashioned image fields to new shiny media entities?
The answer is: Yes, there is a way out of your misery!

We created a module called: "Migrate File Entities to Media Entities".
https://www.drupal.org/project/migrate_file_to_media

The module allows you, to migrate Drupal 8.0 file entities to Drupal 8.5 media entities, using the migrate module.

The main features of the module?

• It provides a drush command that automatically detects all file / image fields and creates the corresponding media reference field.
• Before migrating the files to media entities, a binary hash of all images is calculated, and duplicate files are recognized. If the same file was uploaded multiple times on different nodes, only one media entity will be created.
• Migration of translated file / image fields is supported. Having different images per language will create a translated media entity with the corresponding image.
• Using migrate to file module allows drush processing, rollback and track changes.

How to migrate images to media entities

Prepare target media fields

• Prepare the media fields based on the existing file fields using the following drush command:

  drush migrate:file-media-fields <entity_type> <bundle> <source_field_type> <target_media_bundle>

  Example

  drush migrate:file-media-fields node article image image

  For all file fields the corresponding media entity reference field will be automatically created suffixed by {field_name}_media.

Prepare duplicate file / image detection

In order to detect duplicate files / images, run the following drush command to calculate a binary hash for all files. The data will be saved to the table "migrate_file_to_media_mapping". You need to run this drush command to be able to import media entities.

drush migrate:duplicate-file-detection

Create a custom migration per content type based on the migrate_file_to_media_example module

• Create a custom module
• Create your own migration templates based on the examples in migrate_file_to_media_example.

The module provided a custom migrate source plugin called "media_entity_generator".

id: article_images
label: Article Image to Media Migration
migration_group: media
source:
  plugin: media_entity_generator
  entity_type: node
  bundle: article
  langcode: 'en'

  # provide a list of all field names you want to migrate
  field_names:
  - field_image
  - field_image2

destination:
  plugin: entity:media

You need to create a migration per entity bundle and provide a list of all field names, you want to migrate. The source plugin will query the database and find all files / images linked with these fields.

Step-by-step instruction how to migrate your own files / images.

Step 1: Create media entities.

File migrate_file_to_media_example/config/install/migrate_plus.migration.article_images.yml

This is the starting point. This migration creates a unique media entity from all files / images referenced by fields in the configuration field_names of the source plugin.
In the example, we have two image fields called: "field_image" and "field_image2".

Important:
The drush command to calculate the binary hash needs to be run before you can use the media_entity_generator source plugin.

Using rokka.io on Step 1:

File migrate_file_to_media_example/config/install/migrate_plus.migration.article_images_rokka.yml

This is an example migration, how to move all images to the rokka.io image content delivery network. You need to install the
drupal rokka module.

Step 2: Create media entity translations.

File migrate_file_to_media_example/config/install/migrate_plus.migration.article_images_de.yml

This migration adds a translation to existing media entities if a translated file / image field is found.

Step 3: Link media entities with media reference field on target bundle.

File migrate_file_to_media_example/config/install/migrate_plus.migration.article_media.yml

This migration links the newly created media entities with entity reference field on the target bundle.

Step 4: Check the migration status.

drush migrate:status

Step 5: Run the migration.

drush migrate:import <migration_name>

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!