Startup Guide

A Startup Wizard will be added to the plugin soon enough, but while it is not yet there, it is very important to read this document through to avoid many possible problems and misunderstandings.

If your site previously used some other multilingual plugin, then please read the migration instructions.

This plugin offers a way to maintain dynamic multilingual content on a WordPress site. While static localization is already excellently implemented and offered by WordPress framework through po/mo file framework, it is still impossible to maintain dynamic multilingual content without an additional specialized plugin, to a kind of which qTranslate-X belongs to. For example, what if you need to make title, content and excerpt of a page to be multilingual? In theory, it could be handled by po/mo files, but in an insanely inconvenient way.

To deal with dynamic content, qTranslate-X provides language switching buttons on applicable admin editing pages, which, once pressed, make all the text of multilingual fields to be filled with the language chosen. The instant language change happens locally in your browser without sending an additional request to the server. Once the content has been entered in multiple languages on admin side, frontend will show the content in the language chosen by a viewer. There are a few methods how the frontend language can be chosen. Frontend language is independent of admin side language.

The plugin does not currently offer any kind of translation services. The team has conducted an online survey to find out how people translate their content. You are welcome to make your entry too. It appears so far, that translation service is not an immediate need. Administrators normally have their ways to translate the content, but they need a convenient way to enter translated content into an appropriate place, which this plugin is designed to help with. Translation services might still be provided in the future releases as a paid feature.

If you test qTranslate-X for the first time and you are not sure if you will use it later, then do your testing on a test-copy of your site, since after a translated content is added, the site becomes unusable without qTranslate-X. All Raw ML values show up at front end, if the plugin is turned off. Is is safe to turn off/on the plugin though, as well as to change the theme, for testing purposes.

A list of initial steps to install a plugin is available at WordPress site and it will not be repeated here. We assumed that you already installed the plugin and activated it.

After activation of qTranslate-X, it is advisable to add “English” as one of the enabled languages and switch to it, when working with this instructions, otherwise it might be hard to match titles and names of items mentioned here with what you see on your admin screen.

To switch an admin language (#) use the language menu in the top right corner of the admin screen. Admin Language is not switchable through Setting/General page, when plugin is active.

Here are a few steps that you may follow, but keep in mind that every site is different, please, do not hesitate to use your own way.

  1. Configure desirable languages. Go to page “Settings/Languages” (/wp-admin/options-general.php?page=qtranslate-x), open section “Languages” and enable languages you wish to use on your site. Designate one of them to be the default, using option “Default Language / Order” in section “General Settings”.
    Important: Never change the default language once it is chosen. Once the content is populated, the default language values are stored differently and changing of the default language may make site unusable. It is also very difficult to change two-letter codes of the languages, once the site is populated with translations. Please, think carefully about choosing two-letter codes and the default language to begin with. Do not plan on changing them in the future. It is not impossible to change it, but it would be a very difficult and time consuming manual operation on the database.
  2. If your language is not listed, add a new language. It is important to choose two-letter “Language Code” carefully, since it might be quite difficult to change it later. Other fields can easily be adjusted at any time. Please, note that two-letter language code is arbitrary and it is up to admin to choose it appropriately for your site. It is advisable however to try to match two-letter Language Code with one of the commonly used abbreviations, if applicable. It is also a good idea for two-letter language code to match the first two letters of locale. Oppositely, “Locale” of a language cannot be chosen arbitrary, and it has to match the locale already in use in your instance of WordPress for each language. Use instructions from the next item if you have trouble to find out the locale code for a language. Once you figured it all out, do not forget to send the information you entered for the new language to the team to put it into plugin as a predefined language.
  3. If on the switch admin side to your language, pages show all text in English, then the “Locale” is probably wrongly entered for that language. “Locale” can be changed on a language edit page, /wp-admin/options-general.php?page=qtranslate-x&edit=xx (‘xx‘ is the two-letter Language Code), which is opened on click of link “Edit” in the list of languages on configuration page /wp-admin/options-general.php?page=qtranslate-x. If a wild guess or the default provided for locale code does not work, you may try to figure out the locale string needed from the menu “Site Language” on page “Settings/General” (/wp-admin/options-general.php). Open the source of this page, search for words “Site Language” and then look for items “<option value="xx_XX" ...” to find the option item applicable for your language. The string shown in the attribute ‘value’ is the locale code for your language in your instance of WordPress. You may also lookup the predefined locale in WordPress documentation.
  4. If all the text of configuration page “Setting/Languages” (/options-general.php?page=qtranslate-x) is shown in English, then it means that plugin qTranslate-X has not yet been translated into your language. If it is partly in English, then the translation is not finished. It is then your chance now to contribute to the translation.
  5. For the first time installation, it may make sense to run operation “Mark Default”, which is described under option “Convert Database”. Click the link provided, which activates url /wp-admin/options-general.php?page=qtranslate-x&markdefault=true. This operation is irreversible, your website will no longer function correctly without plugin qTranslate-X. If you are testing this plugin, please, do it on a test-copy of your site first, which you can easily reset in case you decide not to use qTranslate-X later.
  6. If you upgrade from a previously run other multilingual plugin, you may find useful to read migration instructions.
  7. Next decision to make is to choose “URL Modification Mode”. Most users choose “Pre-Path Mode”, for which you have to enable one of the pretty permalinks in WordPress configuration page “Settings/Permalinks” (/wp-admin/options-permalink.php). Pretty permalinks are also required for other url modification modes, except “Query Mode”. The least popular is “Query Mode”, since it is not SEO friendly.
  8. Now you have to decide how visitors of your site will switch languages at the front-end. FAQ topic “What language switching methods are available at front end?” may help you with this task.
  9. You are now ready to enter some translated content in other than default language. Go to edit any post or page and enter some translated content. Until at least one alternative language is populated in the content, all languages show the same text, and column “Languages” in the list of posts or pages shows “Languages are not set”. Same column will show a list of populated languages otherwise. Once alternative languages are populated, check how it appears at frontend when frontend language is switched. Important Note: once translated content is added, there is no way to use the website without qTranslate-X anymore. That is why it is wise to do your testing on a test-copy of your site which you may easily reset in case you decide not to use qTranslate-X.
  10. If you spotted language tags ‘[:]’ in some texts at front-end, open FAQ and search for keywords “Custom Filters” or read Integration Guide.
  11. If you need some custom field to become multilingual, read Integration Guide.
  12. Further customization is optional and can be done as needed. It is advisable to read help text for all options on page “Settings/Languages” (/wp-admin/options-general.php?page=qtranslate-x) at least once, to have an idea what options are available. It may help you to better understand the behaviour of qTranslate-X. FAQ list provide some advices, which you may find useful too.
  13. When testing the front end, you may notice that a URL gets sometimes redirected. It redirects to a standard URL using certain rules. Normal users of the site find those redirections helpful and/or unnoticeable. Testers may sometimes expect a different result, especially when hitting a language-neutral URL. In short, it keep currently active language, and switches the language only when a language-encoded URL is in use. If you still find it confusing, reading the explanation of how browser redirection works may help.

If you still have trouble to find out how to enable the desirable features, open a topic at plugin Support Forum at WordPress site.

If you think you found a bug, please report it to the authors.

In both cases, when asking for a help on Support Forum or reporting a bug, please provide a concise clean steps to reproduce a problem, preferably starting with a freshly installed WordPress instance.

We hope you will enjoy the use of our plugin. Please, do not forget to setup a recurring donation, if you plan on a heavy use of this plugin. Letting other people know about your experience with a review is also useful.

Other resources


One thought on “Startup Guide

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s