Troubleshooting

Guidelines

• if you are looking for an answer to “How to …” question, it may help to first read the FAQ.
• please make sure you use the latest qTranslate-XT and WordPress.
• first check the open issues and look if someone didn't report a similar problem.
• if it's a new issue, report the problem the best as you can so that the developers can reproduce it and other users may also help you. Please follow the instructions for integration and debugging before reporting.
• suggestions for improvements and new features may only be considered if they are clearly described and if they concern a broad use of the plugin. Proposals for code changes are welcome through usual Pull Requests (PR) with github. Please follow the best practices by Google before submitting a patch (CL=ChangeList).
• there is no general support for specific development, technical assistance or coding problems. This is a free plugin and the work of integration is yours. Please keep in mind github is not a general forum. Only well-documented technical issues or appropriate feature requests will be accepted.

Integration with other plugins

A frequent cause of problems comes from newer versions of third-party plugins that create some regressions and integration issues. WordPress is very heterogeneous environment with an infinite possibility of combinations of plugins that could affect the normal behavior or qTranslate-XT. It is impossible to test all combinations of plugins, especially because of the nature of qTranslate-XT working at a low level in WordPress.

The first thing you should do is to disable all possible plugins and enable them one at a time to identify some potential integration conflicts. Once you have identified the combination of plugins creating the problem, try to push a bit the investigation as much as you can.

For purely technical problem it is crucial that the developers are able to reproduce it otherwise there is very little chance the problem can be fixed. The more accurate information, the faster the fix. Enabling the debugging features in PHP and WordPress helps a lot.

Debugging

The first step is to figure out what error is occurring. One possibility is to look for error messages in the main PHP log files such as error_log but this depends a lot on your PHP configuration and how these errors are reported. Since this plugin is for WordPress it is generally more convenient to debug using the specific features with WordPress.

Debugging in WordPress

See the related WordPress doc about debugging. The following steps may help:

• Enable WP_DEBUG in /wp-config.php, which may help to see more useful messages: change line define('WP_DEBUG', false); to have true.
• By default WP_DEBUG_DISPLAY is set to true but it will be ignored when WP_DEBUG is false so you should never have to change WP_DEBUG_DISPLAY, but if you ever set it to false just comment the line and it should come back to true.
• Enable WordPress debug logging by setting WP_DEBUG_LOG to true (see debug.log) or other choices, this could be useful for CLI or CRON jobs.
• Install a favorite debugging plugin, for example, “Debug Bar“, which sometimes help to see the error messages quicker, or more advanced tools such as Sentry which offers powerful tracking features even with the free acount.
• Try to reproduce the problem under a simpler configuration with as many plugins off as possible and with one of the standard themes, like “Twenty Sixteen”, “StoreFront”, etc. This may help you to figure out which plugin is in conflict.
• Serious developers would ideally use a development tool with Xdebug and breakpoints enabled.

For problems due to client-side scripts (Javascript) - mostly for the admin section:

• Lookup if there are any error messages in the console inspector. Most browsers show the console on pressing shortcut Ctrl+Shift+I (Chrome, Safari) or CTRL+Shift+K (Firefox).
• Enable SCRIPT_DEBUG constant in /wp-config.php to load the JS scripts in debug mode with more details.

Debugging with PHP

If you can't idenfity the problem, a generic PHP feature to check is the level of assertions in your PHP interpreter. From the command line you can run php -i | grep assert or check php --ini to list your configuration files. Here are the settings valid with PHP 7.

Directive	Default value	Possible values
zend.assertions	1	1: generate and execute code (development mode) 0: generate code but jump around it at runtime -1: do not generate code (production mode)
assert.exception	0	1: throw when the assertion fails, either by throwing the object provided as the exception or by throwing a new AssertionError object if exception wasn't provided 0: use or generate a Throwable as described above, but only generate a warning based on that object rather than throwing it (compatible with PHP 5 behaviour)

A recommended settings for debugging is:

zend.assertions = 1
assert.exceptions = 0

The asserts are turned into a warning (E_WARNING) which is good enough. The fact that it is shown or not depends on your WP DEBUG configuration but this is specific to WordPress as described above. Turning into exception might be useful if you have more specific exception handlers.

Development vs Production mode

Every website has different needs but this section gives you the most common setups to switch between development and production. In production you look rather for the most optimal performance. But even then, it can be very useful to have some of the debugging features enabled, but of course this might degrade the performance. Here are some suggestions, leaving the default as much as possible:

Config	Default	Dev	Prod	Comment
WP_DEBUG	false	true		also for faster runtime, only for the WP/plugins
WP_DEBUG_DISPLAY	true			only matters when WP_DEBUG is true so you generally never override this (more intended to be disabled for CLI/CRON)
SCRIPT_DEBUG	false	(true)		only when debugging JS scripts in WP/plugins
zend.assertions	1		(-1)	skip for faster PHP execution BUT it can be a good idea to keep the assertions enabled even in production!
assert.exceptions	0			turn assertions into E_WARNING (irrelevant with zend.assertions != 1)

Debugging Javascript

The JS scripts for production are distributed in qtranslate-xt/dist. They are bunded with wepback via npm.
For JS developers willing to debug qTranslate-XT or to implement new features, it is possible to build locally the target scripts with different levels. To update the scripts from qtranslate-xt folder:

• npm install: install/update node.js dependencies (node_modules)
• npm run build: minified versions for production
• npm run dev: debug versions for development with original source maps
• npm run watch: debug versions for active development with auto-rebuild

System requirements: node.js (recommended version LTS) and npm.
For more information about webpack devool: https://webpack.js.org/configuration/devtool/

Frequent problems

• Blank page at frontend: in case of blank page, in most of cases seen, it was a fatal error from a call to undefined function name of which starts with qtrans_*, which is explained in FAQ topic. Most likely solution is to turn on option “Compatibility Functions” on page /wp-admin/options-general.php?page=qtranslate-xt#integration.

• Cannot login as admin. To gain access again, rename folder “/wp-content/plugins/qtranslate-xt” to something else – this will auto-disable the plugin and let you login again. Then look for errors in error_log. Possible reasons:

  • Messed up .htaccess file. In order to reset it, press “Save Changes” button on page Settings/General (/wp-admin/options-general.php), or fix it manually.
  • Syntax error in file /wp-config.php for example on the line define('WP_DEBUG', false); .

• If Setting/Languages page, /wp-admin/options-general.php?page=qtranslate-xt, shows no options regardless which tab is chosen, it is most likely due to a 3rd-party javascript error, which prevents java script from the normal execution. Fix the error or disable offending plugin to get the setting page back to normal view.

• If number of menu items becomes big enough, you will need to increase max_input_vars in php.ini, which is by default set to 1000. If you have WP_DEBUG on, you will see one of the messages

  Warning: Input variables exceeded 1000
    Warning: Invalid argument supplied for foreach() in /wp-content/plugins/qtranslate-xt/admin/qtx_admin.php on line 14
    

  in menu editor /wp-admin/nav-menus.php a few menu items before it will generate fatal error. Contact your hosting provider to find out how to increase max_input_vars. The value you need is roughly 100 + [number of enabled languages] times [number of menu items] times 11.

• 500 Internal Server Error – most likely check your .htaccess file and fix it. For example, we observed improper call of function [flush_rewrite_rules()](https://codex.wordpress.org/Function_Reference/flush_rewrite_rules) at front-end on each request with theme Viva Hotel (other themes of the same author possibly have this problem too). This function regenerates .htaccess file and should never be called at front end. When qTranslate-X is active, it makes function home_url() return a language specific home URL, which causes .htaccess file to be improperly generated in addition to the problem of its generation on each request. Once this file is generated incorrectly, the server start responding with 500 error, which is extremely hard to troubleshoot.To offset the problem, you may precede the call with an “if” statement like this:

  if( (defined('WP_ADMIN') && WP_ADMIN) && !defined('DOING_AJAX'))
     flush_rewrite_rules();

  which will make this call run only at admin side. However, this is still not a proper fix, and you should let the theme know to correct this problem permanently according to WordPress instructions.

• Notice: Undefined index: admin_config – most likely the update or installation of the plugin did not work correctly for some reason. It may, for example, happen if plugin’s code was overwritten on the file system without doing deactivate/activate actions from WordPress admin page. In most cases, re-saving of Settings/Languages options on page /wp-admin/options-general.php?page=qtranslate-xt fixes the issue. Doing “Deactivate” and then “Activate” actions for plugin qTranslate-XT on page /wp-admin/plugins.php may help too.

Report an issue

Finally, if you can't solve the problem you can report the issue. The result of these investigation steps will be a useful information to mention. When you submit the ticket please follow:

• first look at the current issues to see if the problem hasn't been reported yet
• keep the title short
• describe your problem accurately so it can be understood / reproduced
• give the versions from the Troubleshooting section in the options
• keep in mind you should always try with the last versions of this plugin!
• install manually from github or use GitHub Updater to get the latest releases (intermediate versions to be discussed in the issue)
• issues may be rejected if they can't be reproduced or if they don't follow the guidelines given above.