-
Notifications
You must be signed in to change notification settings - Fork 110
FAQ
- If you are new to qTranslate-XT, please, read Startup Guide.
- If you think you encountered a bug, please follow the Troubleshooting Guide and then report it providing step-by-step instructions how to reproduce the problem, preferably starting from a fresh standard WordPress installation.
- If you have integration issues, please read Integration Guide to find out how to integrate your theme or a 3rd-party plugin with qTranslate-XT.
Topics:
- Gutenberg
- Languages
- Translations
- Custom fields
- Language switching
- Browser redirection
- Developer
- Legacy
- Uninstall
- Extensions
The block editor (Gutenberg) is partially supported in Single Language edit mode only. It is recommended you install the Classic Editor to keep the usual features using the legacy TinyMCE editor. This plugin is very convenient as it allows you to select which editor to use as default or for every post.
DISCLAIMER: this feature is only a recent addition and there might be some problems we are not aware of. Though the operations should not put your database at risk, better to always backup regularly. The main risk concerns the post being edited. Be sure to test this separately first, before using it in full production.
The limitation to single language mode means you have to edit every language separately, one after the other. If you want to publish a post with all languages at the same time:
- edit the first language and save the content as draft
- switch to other language, save as draft
- finally publish the whole post with all languages.
Known issues:
- IGNORE the warnings of "Restore backup" #809
The full support with Language Switching Buttons (LSB) requires much more work because of the whole different software architecture of Gutenberg. Other solutions may come later.
Yes, all languages are supported and more and more get included. If yours is not included, you can easily add it through the Language Manager (/wp-admin/options-general.php?page=qtranslate-xt#languages). If you are a native speaker of that language, consider sending us the information to be included permanently in the plugin configuration.
Yes, it does. RTL should get enabled by WordPress based on locale of active language. If you turn the plugin off and switch the whole WordPress to RTL language, it should work correctly, and then it should continue working the same way when qTranslate-XT is active. If it does not work right without qTranslate-XT, then start your research from WordPress RTL documentation.
It means that there is no translation entered yet. Just start populating the translations and you will see the list of languages populated instead of “Languages are not set”. Until at least one alternative language is populated in the content, all languages show the same text.
Yes, it is possible, but it is not simple, since once configured, all the multilingual entries get that code in language tags ([:xx], {:xx}, <!--:xx-->) and qTranslate-XT may not be aware of some custom multilingual values to change all automatically.
However there is a current limitation that only allows the language code to be on 2 letters. It would be good to extend the support for locales and new href formats.
If you really need to change one of the two-letter codes, then you may dump your database in a .sql text file, then replace all language tags with what you need and import the changed database back to the server.
Do not forget to also set the new two-letter code in the configuration of language properties at page /wp-admin/options-general.php?page=qtranslate-xt&edit=xx.
Plugin Qtranslate Slug is semi-integrated, will work on some configurations, but it is not safe, generally you will end up with some problems. It needs a better integration with qTranslate-XT.
Generally, yes, it is needed. Oftentimes, it works fine without ending tag, it depends on how ML value is in use. For example, __('[:en]en-text[:xx]xx-text') will work the same with or without ending tag. Now, consider that this value was stored in a variable $ml, and then theme uses it inside some other text, for example, __('<language-neutral text>'.$ml.'<other language-neutral text>'). Then you can see that for ‘en’ language you will get “en-text” instead of intended “en-text”. Things like that happen routinely in complex themes.
In the future, we plan to improve performance of the plugin by removing all little translation filters and translating the whole resulting page with many embedded multilingual values at once. If ending tags are not there, this would not work at all.
That is why you should always use ending tag [:], just in case to prevent any possible problems.
Yes and no. Users can type comments in any language they want, but plugin is not aware of the language users used in comments and does not track the languages in use for comments.
Normally, it is considered a responsibility of user to read the comments in any language and to translate them as needed using other external tools like Google Translate, for example.
However, there are 3rd-party plugins, which allow to separate comments by language, although it may make little sense, since you would rather wish to show all comments and let user to decide which one they want to read.
As to comments, we leave it up to user.
Yes, some themes put additional text fields per page or per post. By default, those fields have no way to respond to Language Switching Buttons in editors. However, you may enter “id” or “class” name attribute of those fields into “Custom Fields” section of “Languages” configuration page in “Settings”, and they will then respond to the language switching buttons allowing you to enter different text for each language. To lookup “id” or “class”, right-click on the field in the post or the page editor, choose “Inspect Element”, and look for which attributes are defined for that field. If you cannot uniquely distinct the field neither by if nor by class, report on the forum threads.
The theme must pass those values through translation function __() before displaying on the front-end output. If this is not done, you will see the text of all languages displayed one after another. Most themes use __() translation by default, otherwise you may ask theme author to make this little modification for each field you need to be translatable. However, sometimes, they pass a value through apply_filters() function before displaying the value, and then you may put that filter name into configuration filed “Custom Filters” to get the value translated properly.
The following fields are pre-configured to be translatable by default:
- all input fields of class “
wp-editor-area“, which normally include all TinyMCE visual editors. - fields with the following id: “title”, “excerpt”, “attachment_caption”, “attachment_alt”.
This applies to post, pages and media editors (/wp-admin/post*).
Read Integration Guide for more information on how to integrate qTranslate-XT with a 3rd-party plugin or a theme.
Some themes have additional to the standard WP design fields, which need to be translated. In such a case, try entering all the translations in one field using raw multilingual format Raw ML like this:
[:en]English Text[:de]Deutsch[:]
or like this (obsolete way)
English TextDeutsch
You may also embed language-neutral text in-between the language-specific content, like this:
[:en]English Text[:][:de]Deutsch[:]
Note that closing tag right before the opening tag is redundant. For example, the following encoding is equivalent to the example above:
[:en]English Text[:][:de]Deutsch[:]
Two encoding modes are interchangeable, although most people prefer to use square-bracket style ‘[:]’, because it is shorter and easier to edit.
If a theme uses translate function __() before displaying those fields, then they will be shown correctly, otherwise suggest theme author to put __() calls in. Most themes do it this way.
Many plugins and themes pass a value through a call of filter function apply_filters('name_of_filter',$var) before printing the value on the screen. If this is a case, then one can put 'name_of_filter' into “Custom Filters” option of qTranslate-XT to make such field appear translated at the front-end.
Read Integration Guide for more information on how to integrate qTranslate-XT with a 3rd-party plugin or a theme.
See Customization of the Language Switcher Menu.
See Front language switcher FAQ.
See Integration Guide and JSON configuration.
qTranslate-XT redirects to a canonical URL before rendering a page, which is necessary for some plugins (BuddyPress, for example) to work correctly. Canonical URL is defined based on options “Site Address (URL)” and “WordPress Address (URL)” from page /wp-admin/options-general.php, option “URL Modification Mode” from /wp-admin/options-general.php?page=qtranslate-xt read more.
If .htaccess then redirects to a different URL, an infinite redirection loop may occur, which can be fixed after proper editing of .htaccess file. In most cases, the default .htaccess from hosting service provider works correctly.
- If you test it with manual typing of language-neutral URL which gets redirected back to previously active language, then see Browser-redirection.
- Check for anything funny in
[.htaccess](https://codex.wordpress.org/htaccess)file. - Did you turn on option “Disable language client cookie ‘qtrans_front_language’ (not recommended).” on page
/wp-admin/options-general.php?page=qtranslate-xt#advanced? Then turn off option “Detect Browser Language” on page/wp-admin/options-general.php?page=qtranslate-xt#general.
On the first visit of my site with home URL, I get other language than the browser’s displayed one, even after I cleared all the cookies.
Many browsers have additional option “Preferred Languages” or have a way to sort the languages by preference. The browser’s displayed language may not be set at the top of preferred languages. Check the settings.
Many people (mostly former qTranslate users) start report of a problem similarly to this: “I have option ‘Hide URL language information for default language’ on, but when I go to a language-neutral URL, it shows non-default language.” In short, it is because the active language is kept in cookies and whatever language user chose in the recent browsing is kept on language-neutral URLs for the sake of user convenience. Or it may happen on the first visit, when no cookie is yet set, and then it switches to the preferred language of user browser.
One has to use language-encoded URL in order to switch language. You may find useful to read the explanation of Browser Redirection Based on Language.
I am a developer, which functions should I use to translate the raw multilingual values to a specific language?
For the full developer guides, read pages Integration Guide and Developer Interface. The most frequently used key points are reiterated here for the sake of convenience.
If you need to translate a value to other language, use code like this:
$text = apply_filters('translate_text', $text, $lang=null, $flags=0);
$term = apply_filters('translate_term', $term, $lang=null, $taxonomy=null);
$url = apply_filters('translate_url', $url, $lang=null);
All three accept strings, as well as arrays and objects, as arguments and so will be returned converted to the language specified by two-letter code provided by argument $lang, which defaults to the active language, if omitted.
Standard WordPress function get_locale() returns a locale of active language.
Pay attention, that all calls to multilingual framework must be done after it is initialized in the action ‘plugins_loaded’ with priority ‘2’. Calls to function get_locale(), for example, within your plugin file outside of any function will not work properly in a general case, since language is not yet detected and multilingual framework is not yet initialized. Place your code into an appropriate action or filter, for example, action ‘plugins_loaded’ with normal priority will do.
We discourage people to make direct calls to the plugin’s functions. Normally, one can get away with safe calls to apply_filters. Let us know about other desirable filters.
I am a developer. Following the logic of the plugin, I expected to see term names in wp_terms table in Raw ML format, but instead, I see the default language values only. Where the translations of terms are stored?
- Table
wp_termshas “name” in the default language. If the default language uses non-latin alphabet, the values may be scrambled with%xxencoding in the database. - Option “qtranslate_term_name” stores the translations of terms with mapping like
"term_name_in_default_language" => array("xx" =>"xx_name", "yy" =>"yy_name", "zz" =>"zz_name", ... ). This associative array is accessible at run time via global variable$q_config['term_name'], which should never be used directly in a 3rd-party code.
This may change in the future, but for now, we keep maintaining the original design.
However, this should not be of user concern, since all functions like [get_term](https://developer.wordpress.org/reference/functions/get_term/)() or [get_terms](https://developer.wordpress.org/reference/functions/get_terms/)() bring properties “name” and “description” in Raw ML format at admin side, or already translated to active language at front-end. The Raw ML values are also get cached in property i18n_config of WP_Term objects at front-end, in case a developer still needs them for some reason.
At front-end, many multilingual options get translated so that call to function get_option() returns a translated to active language value. Sometimes a developer needs to get a raw untranslated multilingual value, usually to be able to get a translated value for other than active language. One may retrieve such raw value with a code like this:
$alloptions = wp_load_alloptions();//returns loaded/cached values. there is no overhead at runtime $raw_value = $alloptions['option_name'];
I am a developer, how can I alter global configuration of qTranslate-XT for the specific purpose of my plugin?
You can use add_action for hooks 'qtranslate_loadConfig' and 'qtranslate_admin_loadConfig' to alter the configuration stored in global variable $q_config. Read more in Integration Guide.
[obsolete, although should work, use Integration Guide instead] Yes, enter the relevant and distinctive part of your page URL into “Custom Pages” configuration option. When page is loaded, two Java scripts will be added, “admin/js/common.js” and “admin/js/edit-custom-page.js”, from which you may figure out how it works. The Language Switching Buttons will control fields listed in “Custom Fields” option. Those fields will now store the input for all enabled languages. It is up to the theme and other relevant plugins, if those field values will show up translated on the front-end. Some theme and plugins pass the values through __() translation function and then values are translated. They might use apply_filters method, and then name of that filter can be listed in “Custom Filters” configuration option, in order to get the field translated on the front-end.
If your case is still cannot be handled in this general way, you may develop your own Java script, similar to “admin/js/edit-custom-page.js”, and load it from your own file path using “qtranslate_custom_admin_js” hook. Looking through other “admin/js/edit-*.js” scripts may give you an idea how to do yours.
This is a work in progress and any suggestions are appreciated. We will probably end up using some kind of an xml configuration file customizable per each plugin/theme which needs to be integrated. Such an xml-file will list pages with queries affected (“Custom Pages” option for now) along with ids and classes of fields on each page to have multilingual data either for editing or for display.
Ideally, only such an xml configuration file will need to be created in order to integrate a plugin or theme without additional coding.
I used to make direct calls to one of qtrans_* functions in my theme/plugin, but now those functions are not available.
WordPress policy prohibits use of the same function names if they already defined in other plugins, since this possibly leads to user-unfriendly fatal errors. That is why all functions with prefix qtrans_ were renamed to have prefix qtranxf_. However, once the plugin is running and all other conflicting plugins are disabled, you can turn on option “Compatibility Functions” and a number of former qTranslate methods with prefix qtrans_ become available again. This ensures compatibility with other plugins and themes that used direct calls to qTranslate methods in their code.
Note: Function qtrans_modifyTermFormFor, which some older themes or plugins call directly, is no longer available and should not be needed with qTranslate-XT. This function used to deal with multiple input lines per language, which qTranslate-XT does not use anymore. That multi-line framework is now replaced with Language Switching Buttons (LSB). Please, ask the authors of those themes and plugins to update their code, if you encounter one of those cases. In most of the cases, they would simply need to remove that extra code, otherwise Integration Guide may help.
They are not maintained anymore and their authors won't respond.
Yes, there is a number of new features, mostly of a convenience significance, which includes, but not limited to:
- A different design of language switching via conveniently located buttons (same way as it is done on zTranslate. No multiple lines for title fields anymore. This design simplifies backend programming and is less likely to be broken on future WP changes.
- “Language Switcher” menu item on WP menu editing screen.
- Category and tag names in the lists on editing pages also respond to language switching and will display the taxonomy names in the currently editing language.
- Theme custom fields can be made translatable in addition to the default translatable fields.
The correct strict answer would be ‘No’, although some sites may never notice it. What is modified, is changed for a reason to provide better support for WP general design and policies, and to ensure better survivability on WP, themes and other plugins updates. While it may cause temporary grief and pain, it should work out better in a long run. Below is a list of the most important changes.
- behaviour of function
home_url()is changed to consistently and always return language-enabled URL. This allowed to provide better compatibility with other plugins and themes, some of which used to modify their code to offset inconsistent behaviour of formerhome_url(). Those tricky changes will have to be now undone. - language detection algorithm is modified to ensure canonical URL to be processed, otherwise we first redirect to a canonical URL.
- language detection within AJAX calls has been improved and custom compatibility modifications in other plugins and themes may now become unnecessary.
When plugin is deactivated, no changes to database is done. All translations are kept and safe. Sometimes it is good to deactivate plugin to see all the raw multilingual values on admin side as well as on front-end for troubleshooting purposes.
When plugin is deactivated, all multilingual values are shown raw at front-end. The database needs to be cleaned up if you no longer plan to use the plugin.
Currently, there is no such function within the plugin. You may try to use 3rd-party plugin qTranslate Cleanup, which we never had a chance to test. If you happen to implement a script to do such cleanup properly, let us know.
Starting from version 3.5, there is a choice “Split database file by languages” for option “Convert Database” on page /wp-admin/options-general.php?page=qtranslate-xt#import, which allows to split .sql database file of multilingual site into separate single-language database files.
Use plugin Google XML Sitemaps or use “XML Sitemaps” feature of plugin Yoast SEO. You may also use Google XML Sitemaps v3 for qTranslate, which is now seems to be abandoned and unsupported anymore. There might be other sitemap generators out there compatible with qTranslate-XT, if you find one, please report it to us.
If you wish to use different flag images, point option “Flag Image Path” to your own folder, containing custom images outside of “plugins” or “themes” folders, where it will not be overridden during an update. Most people would put it somewhere under “uploads” folder.
Current version does not support multilingual media images. It seems to be an inappropriate though, as it would be hard to maintain and would blow up the server disk usage. However, image title, caption and alt text are multilingual fields and their values can be shown on the top of images with CSS configuration, if desired.
When I try to use Grid Templates of Grid Builder of WPBakery Visual Composer, my front-end gets heavily messed up with language tags like [:xx] shown around my items in the grid. What am I doing wrong?
Grid Templates (/wp-admin/edit.php?post_type=vc_grid_item) need not to be a multilingual objects, since they get inserted into other multilingual fields. Embedded multilingual fields are not implemented in qTranslate-XT, and it is not generally needed.
Make sure to turn off checkbox “vc_grid_item” in option “Post Types” on page /wp-admin/options-general.php?page=qtranslate-xt#advanced in order to make Grid Templates not to be multilingual. Then create a separate templates for each language instead, and insert an appropriate template into pages content as needed.
You may need to re-enter some information in some pages after turning off the checkbox “vc_grid_item”. In worst case, re-create templates and pages cleanly. Alternatively you may do those edits manually in database, removing language tags meaningfully, if you have advanced enough knowledge on database handling.
You may be using WPBakery Visual Composer without realizing it, as it may be included in your theme. If you have problem with “Grid Builder”, “Grid Templates”, “Backend Editor”, etc. and you have item “vc_grid_item” listed in the option “Post Types”, then the above is most likely applicable to you.