Migration Guide

Unless mentioned otherwise, each step is mandatory or strongly recommended.

To users migrating from qTranslate or other qTranslate forks: Unfortunately, you will almost surely need to make some adjustments to your setup, unless your site is very simple. qTranslate-X has many new features which made older qTranslate not 100% compatible. We are really sorry for the inconvenience, please expect about two hours of extra time to spend on migration before you figure it all out. Please, follow the instruction below very carefully and precisely. The good news is that we never had an unsuccessful case, all who wanted to migrate, eventually done it, but sometimes it is more painful than in other cases. It would be awesome if you can take time to write a migrating script after a success, although we understand that such a script will find a way to fail no matter how complex it is, because of huge diversity of the cases we have seen so far. Everyone’s setup is different and unique. On other hand, while you are going through all the pain, you also learn new features of qTranslate-X as a side effect, which will help you in the future. It is not all wasted then. Thank you very much for your cooperation and understanding.

1. Review “Known Issues” and if you use some plugins mentioned there, consider delaying the migration, unless you wish to try your luck and to have fun exploring new features of qTranslate-X.
2. If you use plugin Qtranslate Slug, be prepared to revert the migration as it does not work well enough in some cases. The good news is that many users reported that the latest Qtranslate Slug works well for them.
3. If you make use of mqTranslate’s translator permissions framework, do not migrate yet, and report your need for it, since we do not know how many clients actually use this feature, and we may never import it, if nobody expresses interest.
4. Make a complete backup of your website (files + database).  Here are instructions from WordPress’ documentation on how to do it in a simple way. It is a good idea to make a separate test-copy of your website (files + database) and use it to test the migration. There is a number of WordPress plugins, which may help you to create a test-copy of your site, see, for example, plugin Duplicator. Such a test-copy is always handy to have to troubleshoot any issues you may encounter in the future as well.
5. Deactivate mqTranslate, qTranslate Plus, qTranslate, zTranslate or any other multilingual plugin, which you previously used.
6. Install plugin qTranslate-X.
7. Activate qTranslate-X. If you have not deactivated other previously used multilingual plugin, you may get “Warning: Activation of plugin qTranslate-X deactivated plugin … since they cannot run simultaneously …”. Just confirm and go ahead.
8. If you have previously run zTranslate or qTranslate, skip to step #14.
9. If you previously run WPML, use plugin W2Q: WPML to qTranslate and skip to the end of this document.
10. Go to Settings > Languages page.
11. Open “Import / Export” section.
12. Select item “Import settings from …” for the plugin you were using until now (like mqTranslate, or qTranslate Plus, for example). Make sure to choose “Import …” and not “Export …”. Those two items are close to each other on the screen and a mistake will cause you to restore the backup and to start over.
13. Click “Save Changes“.
14. At this point, both, front-end and admin side, should be working without errors, but may lack some functionality, which will be recovered after conversion of database and adjusting CSS. Please, test it all through, and troubleshoot all the errors, before going further. For example, if you get a blank screen at the front-end, then read #16 and troubleshooting instructions to resolve any issue before continuing to the next step. If you migrated from qTranslate, you will almost surely need to adjust CSS as it is mentioned in #17, and turn on option “Compatibility Functions“. In case you have migrated from mqTranslate, “Compatibility Functions” is automatically enabled by default, as the most common case. You may turn it off manually, if your setup does not require it. If your theme or other plugins use direct calls to one of former qTranslate functions, you may encounter a problem like the one, which was resolved on this support thread, if “Compatibility Functions” is off.
15. Converting the database. As of version 3.1, qTranslate-X includes a new method to separate languages in the localized values. Every newly saved localized value will use it by default. Preexistent previously localized values will continue to be correctly handled even if they do not use this new method. They will be converted one by one if they are modified in the future. Read more.
    qTranslate-X includes a conversion tool that allows you to convert your whole database to the new separator format. This is not mandatory, unless you observe broken layout at front pages, otherwise we strongly recommend to run such a conversion only if you are an experienced user. Furthermore, we do not recommend running this tool on very large databases as PHP execution time limit might prevent the process to complete. If you still need to run it and it could not finish within PHP time limit, ask for help.
16. If you get “Fatal error” like ‘Plugin could not be activated because it triggered a fatal error.’ Look in the message, it probably complains about one of the functions name of which starts from prefix ‘qtrans_’, which means that your theme or other plugins, make direct calls to internal functions of former plugin qTranslate, and those functions are no longer available. If so, then you need to turn on option “Compatibility Functions”, mentioned in #14. What if you cannot do it, because plugin is not active and cannot be activated? This should be fairly rare case, which happens only for poorly developed themes or plugins, but you can do the following. * Deactivate all plugins. * Switch the theme to ‘Twenty Fifteen’ or any other standard and simple theme. * Activate qTranslate-X * Turn on option “Compatibility Functions” * Now you can bring back your theme and other plugins.
17. If CSS of your theme or some plugins was previously customized for one of the earlier qTranslate forks, you may need to rename prefixes ‘qtrans_’ to ‘qtranxs_’ in the CSS files, or make other meaningful adjustments.
18. If you have previously had multilingual Woocommerce attribute values, you will need to re-save them, just press button “Update” in attribute value editor page for each attribute value. Use integrating plugin WooCommerce & qTranslate-X to take advantage of all the new features. Make sure to deactivate all other Woo+Q integrating plugins, since they were written without taking into account new qTranslate-X functionality.
19. Plugin “qTranslate META” seems to continue functioning after turning on “Compatibility Functions”, however you may consider using newer SEO packages like “WordPress SEO” with integrating plugin “WordPress SEO & qTranslate-X“, or  “All in One SEO Pack” with integrating plugin “All in One SEO Pack & qTranslate-X“.

If you still encounter a problem after migration, please review some most commonly occurred, and successfully resolved problems, listed below.

• mqTranslate‘s users may need to read about browser redirection rules as some of the rules are different from what they got accustomed under mqTranslate. Most of it also applicable to other qTranslate forks as well as to the original qTranslate.
• Issue with Translated Alt Tag Breaking Page Layout

Options “Convert Database”

As of version 3.1, qTranslate-X includes a new method to separate languages in the localized values, referred as “square-bracket-only encoding”, as opposite to dual-style encoding legacy qTranslate format. Every newly saved localized value will use it by default. Preexistent, previously localized values will continue to be correctly handled even if they do not use this new method. They will be converted one by one if they are modified in the future.

Set of options “Convert Database” allows to convert the majority of the database values between the new square-bracket-only format and legacy dual-style encoding format.

Below is the list of database fields affected (in format ‘table.field’):

• posts.post_title
• posts.post_content
• posts.post_excerpt
• options.option_value
• postmeta.meta_value (as of version 3.2)

Custom values of 3rd party plugins stored in non-standard places are not converted by this procedures, but manual adjustments will work fine.

Running this tool on very large databases may not work as PHP execution time limit might prevent the process to complete. It may help to run the same procedure multiple times, since the part which is already done will be passed quicker.