-
Notifications
You must be signed in to change notification settings - Fork 103
Startup Guide
No Startup Wizard is available yet, so it is very important to read this document through to avoid many possible problems and misunderstandings.
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-XT 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-XT 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, front-end will show the content in the language chosen by a viewer. There are a few methods how the front-end language can be chosen. Front-end language is independent of admin side language.
Compared to other translation plugins and commercial products such as WPLang, the main feature of this plugin, beside being open-source and entirely free, is to store all the translation content in a single post (pages). Unlike other plugins that create new posts and link them together, here the posts remain unique by contain an embedding of the different languages. Though has a much higher cost in complexity (for reading and updates), it also gives many advantages, especially on small websites. You have to evaluate your needs carefully before choosing one solution.
The plugin does not currently offer any kind of translation services. 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.
Yet there is no procedure for a full uninstall. If you test qTranslate-XT 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 altered without qTranslate-XT. 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. If you really need a full cleanup you will have to come up with your own solution (e.g. regex on the internal language tags).
See the main readme for a list of initial steps to install a plugin. We assume that you already installed the plugin and activated it. For general questions about the project, see also the main FAQ.
If your site previously used some other multilingual plugin, then please read the Migration-Guide.
Gutenberg is supported but there are some limitations. To enable the switching buttons, it is recommended to install the Classic Editor, see our FAQ#gutenberg.
After activation of qTranslate-XT, 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.
-
Configure desirable languages. Go to page “Settings/Languages” (
/wp-admin/options-general.php?page=qtranslate-xt), 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: It is 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. Also, avoid changing the default language once it is chosen, the expected behavior is now well defined. - 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.
- 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-xt&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-xt. 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. - If all the text of configuration page “Setting/Languages” (
/options-general.php?page=qtranslate-xt) is shown in English, then it means that plugin qTranslate-XT 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. - 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-xt&markdefault=true. This operation is irreversible, your website will no longer function correctly without plugin qTranslate-XT. 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-XT later. - If you upgrade from a previously run other multilingual plugin, you may find useful to read Migration Guide.
- 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. - Now you have to decide how visitors of your site will switch languages at the front-end.
- 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-XT 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-XT.
- If you spotted language tags ‘[:]’ in some texts at front-end, open FAQ and search for keywords “Custom Filters” or read Integration Guide.
- If you need some custom field to become multilingual, read Integration Guide.
-
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-xt) at least once, to have an idea what options are available. It may help you to better understand the behaviour of qTranslate-XT. FAQ list provide some advices, which you may find useful too. - 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 Browser redirection may help.
This is a free open-source project so the support is only ensured through its community.
If you still have trouble to find out how to enable the desirable features, open a topic at github.
If you think you found a bug, please check report it. Please always specify the version being used.
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.