Migrate WordPress from qTranslate-X to WPML

I have been blogging in multiple languages for couple of years: in my mother tongue german and – because of international visitors – also in english. In the beginning I decided to go for the qTranslate plugin. Unfortunately, development stalled at some time and I had to find an alternative. Luckily there were some forks – qTranslate-X was a good successor.

Sadly, development has stalled again. There have been no updates since 2016 and with newer WordPress versions coming into picture, annoying bugs increase. Since WordPress 4.9, the plugin is not able to translate categories and other taxonomies, such as tags, anymore (that was one reason why I have not posted any new posts in the last time). Because receiving updates in the near future looked unrealistic to me, I had to find another alternative.

After some researches I found out that WordPress Multilingual Plugin (WPML) seems to be the best option for multilingual blogs. This plugin is not available for free, but seems to have reached de-facto standard status because of the qualitative support. Especially the positive support rating convinced me – qTranslate or qTranslate-X were available for free, but especially after major updates problems occurred quite often. On the other hand, there are not many comparable or cheaper alternatives. Some comparisons (including qTranslate-X) can be found on the manufacturer website.

Differences to qTranslate-X

Basically, qTranslate-X inserts meta tags in all WordPress elements (posts, pages, menus,…) to control language behaviour – e.g.:

[:de]Hallo Welt[:en]Hello World

WPML changes this – it doubles those elements. This means, a bilingual post consists of two different IDs that are linked to each other via the database. Depending on the client language or URL  the appropriate localised version is displayed.

Because there are multiple post IDs per language, this also leads into comments per post version. This is a huge difference – but could also increase clarity. As an example, french visitors will not see any german comments that do not represent added value to them.

Migration

Before starting the migration it is essential that you have a valid backup of your WordPress installation including the database. Having a non-tested backup could force really bad behaviours.. 😉

The migration has been documented by the vendor and requires multiple steps:

  1. Installing the qTranslate X Cleanup and WPML Import plugin
  2. Disabling qTranslate-X and enabling the installed plugin
  3. Importing translations
  4. Creating rewrite rules
  5. Removing qTranslate-X

The migration worked like a charm for me in accordance with the documentation.

Reworking

After the migration I stumbled upon some posts, that had empty titles hatten – instead of the former title there were only some fragments such as “(de)” or “(de) (en)“. Because I had a working backup, it was easy to restore the titles.

In addition to that, categories and tags had to be translated manually. There is an editor for translating taxonomies per language below the menu WPML > Taxonomy Translation:

Translating categories

Translating categories

I decided to add a postfix containing the ISO 639-1 language code (e.g. de, en,…) to the particular taxonomies. This helped me with additional reworking tasks we will see later. It was pretty annoying that all translated blog posts were lacking categories snd tags. Manually fixing relationships for more than 500 posts was no options so I decided to have a deeper look at the WordPress database as I also found no way within the WPML plugin to fix the missing information.

WPML Category and Tag Migration Assistant

After some researches and tests I wrote a small PHP utility which fixes missing categories and tags – you can get it on GitHub.

Requirements and functionality

The tool requires that you translated your taxonomies like described above. To repeat it: it is important that you follow this naming schema:

taxonomyName-languageCode

languageCode refers to a 2-letter ISO 639-1 language code (e.g. de, en,…).

I’d also like to repeat that it is essential to have a functional backup. I tested the migration utility only with my installation (WordPress 4.9) and cannot guarantee that it also works for other versions. 😉

This utility basically does the following:

  1. It iterates through all posts of the given source language and discovers associated categories and tags and translations
  2. In addition, it tries to find translations of linked taxonomies – this requires that you already translated all taxonomies and followed the naming schema above
  3. Afterwards it maps detected translations to translated taxonomies and increases counters

Installation and start

To install the utility, simply clone the repository and upload the wpml_assistant folder to your web server. After opening the script using a web browse, a form is displayed. Enter the obligatory database information and some details regarding the used languages:

  • Database server hostname
  • WordPress database name
  • Username
  • Password
  • Source language (ISO 639-1 code, e.g. en or de)
  • Target language (ISO 639-1 code)
  • Change simulation
wpml-migration-assistant

wpml-migration-assistant

Migration progress is displayed in a table enabling you to see which blog posts (including categories and tags) were discovered and assigned to their corresponding translations. I highly recommend starting an simulation in the first place – to avoid bad misbehaviours because of incorrect language parameters. For installations with dozens of posts it might be possible that the script runs into a timeout and needs to be executed twice.

Leave a Reply