Integration Guide

This guide assumes that the reader is already familiar with the way of how qTranslate-XT works and with general purpose of this plugin, otherwise it is recommended to first read pages like Startup Guide, FAQ, general plugin description, and to have at least one site already successfully running under qTranslate-XT.

Plugin qTranslate-XT is designed to be configurable to support arbitrary themes and plugins. Any suggestion is very welcome.

If you wish to add some translatable fields for custom plugins or themes, follow the steps below to create a JSON-encoded configuration file. Once you got it working, do not forget to send your file to the plugin authors, to include it into their distribution. You may also ask the plugin authors to review these notes and to create an applicable configuration file. In many simple cases, all a developer would need to do is to set class “i18n-multilingual” on the fields that need to be multilingual.

What does the integration mean?

1. Any localization plugin needs to know which text fields are designed to be multilingual. In case of qTranslate-XT, it means to store multilingual text values for such fields and to provide an admin interface to edit multilingual values in a user-friendly way. Hence, the first task of integration is to provide the information about which fields are desired to be multilingual.
2. The second task is to “translate” multilingual fields at frontend, which means that a text in currently active viewer language is extracted from each multilingual value to be displayed at frontend.

To integrate a plugin or theme with qTranslate-XT means to provide relevant information for these two tasks.

Below is the description of how integration can be done. There are a few integrating plugins which already implement some of the methods described. It may be useful to look at their code, and to use them as a starting point for your own plugin if necessary.

Configuration is loaded from a collection of JSON-encoded files.

Configuration page "/wp-admin/options-general.php?page=qtranslate-xt#integration" provides options “Configuration Files” and “Custom Configuration”, which load the main configuration for qTranslate-XT from file i18n-config.json distributed with the plugin, and/or from 3rd-party files in JSON-encoded format. Other plugins and themes may include file i18n-config.json in the root folder of their distribution for qTranslate-XT to pick it up and to load on a plugin activation or on a theme switch.

On activation of qTranslate-XT, the whole set of configuration files is updated in the following order:

1. Main configuration file
2. Themes
3. Must-use plugins (must-use plugins)
4. Plugins

For each group, the following places are searched for i18n-config.json files in the given order of priority, first looking for an external file, then for built-in configuration provided by qTranslate-XT. Only the first file found is kept for each group (plugin or theme), in response to different events.

• On a plugin activation & for all plugins on activation of qTranslate-XT

1. /wp-content/plugins/[plugin-dirname]/i18n-config.json
2. /wp-content/plugins/qtranslate-xt/i18n-config/plugins/[plugin-dirname]/i18n-config.json

• On a switch of the theme & on activation of qTranslate-XT

1. /wp-content/themes/[theme-stylesheet]/i18n-config.json
2. /wp-content/plugins/qtranslate-xt/i18n-config/themes/[theme-stylesheet]/i18n-config.json
3. The search continues with the parent theme(s), aggregating the theme configuration recursively as long as applicable, but only the first file found is kept for each child or parent theme.

• Must-use plugins are always active, therefore they are only searched on the activation of qTranslate-XT

1. /wp-content/mu-plugins/[mu-plugin-basename]/i18n-config.json
2. /wp-content/plugins/qtranslate-xt/i18n-config/plugins/[mu-plugin-basename]/i18n-config.json

These paths are listed for a standard WordPress installation. The actual paths may vary depending on your setup. Note the mu-plugins only consist of files, not directories unlike the plugins, but the basename of the file is used similarly.

Option “Configuration Files” gets auto-adjusted if some relevant i18n-config.json files are found. A configuration files of deactivated plugins or theme get auto-removed from option “Configuration Files”. In most cases, this is what you would want to do, otherwise you may adjust option “Configuration Files” manually.

The configuration may be customized further through additional configuration files listed in option “Configuration Files”. Additional files are better to store outside of plugin/theme folder in order for them to survive the updates.

The order of files listed in option “Configuration Files” matters, since each next configuration file may override the values of some configuration tokens already provided within one of the previous files. Configuration provided in option “Custom Configuration” gets processed in the same way as the one loaded from files. It is a convenient shorthand for small enough pieces of configuration to try before they get finalized in some configuration file. “Custom Configuration” gets processed last, giving you an opportunity to override any other already loaded configuration token.

Important: After one of the configuration files is modified, the configuration needs to be re-saved by pressing button “Save Changes” on page /wp-admin/options-general.php?page=qtranslate-xt#integration, in order for the file modifications to take effect.

In the majority of cases, a configuration file is the only thing that one needs in order to integrate a 3rd-party plugin or theme. A user may prepare such a file by oneself. Looking through the examples of existent configuration files may help a lot.

Modules and plugins

If more advanced PHP coding is needed to implement sophisticated additional filters and features, then a simple configuration file is not enough. For example, in order to integrate plugin WooCommerce one needs to save the language in which an order was made in order to use the same language in communication e-mails with a customer later. qTranslate-XT now supports popular plugins such as WooCommerce or ACF through built-in modules.

If you want to add support for new plugins, you can look at the existing modules and propose a Pull Request to integrate your changes. Another solution is to create a separate plugin for a whole customized behavior. You can also achieve similar integration with themes.

How to designate the fields to be multilingual?

There is a number of ways to declare multilingual fields:

1. JSON-encoded files listed in option “Configuration Files” or JSON code provided in option “Custom Configuration” is the most flexible and general way.

2. Attribute “class” of a field can be set to one of the following reserved names:

   • i18n-multilingual — for multilingual input fields like <input> or <textarea> encoded with square-bracket [:] style.
   • i18n-multilingual-curly — for multilingual input fields encoded with curly-bracket {:} style. Sometimes square bracket encoding interferes with and gets affected by WordPress shortcodes, which also use square brackets [] for their syntax. Then curly bracket encoding style may serve the need. It is equivalent to attribute "encode":"{" in JSON-encoded configuration.
   • i18n-multilingual-display — a display element with no input, like <div>, <span>, <option>, etc. If it has a multilingual value, then it will respond to Language Switching Buttons. It is equivalent to attribute "encode":"display" in JSON-encoded configuration.
   • i18n-multilingual-term — input field is processed as a term name, which is handled differently from normal input field by the underneath framework. It is equivalent to attribute "encode":"term" in JSON-encoded configuration.
   • i18n-multilingual-slug — input field is processed as a slug name. An additional PHP coding is required to handle this kind of multilingual encoding. It is equivalent to attribute "encode":"slug" in JSON-encoded configuration.

   Providing these class names makes the same effect as listing the fields in JSON-encoded files.

3. The values of “id” and “class” attributes provided in options grouped under “Custom Fields” will be searched in HTML elements to make them multilingual on all admin pages accessed through /wp-admin/post.php page. These provide a lot of opportunities, but they do not cover all possible cases. What if we need to assign a field to be translatable on other than /wp-admin/post.php page? What if a field with the same “id” is translatable on one page and is regular field on another page? However, this method, implemented earlier, still works and is sometimes helpful for simple enough sites.

4. A developer may choose to provide configuration programmatically through filters ‘i18n_admin_config’ and ‘i18n_front_config’, which allow to adjust ‘admin-config’ and ‘front-config’ branches of the configuration respectively. Look up their documentation in the source code.

5. As a last resort, one may enter raw multilingual value in any text field manually. The frontend may show it translated if an applicable filter happened to be on the way.

How to translate multilingual fields at frontend?

Once multilingual field is declared and a multilingual value is stored in the field using one of the methods described above, the frontend may still show the raw multilingual value as is without translation. There are a few ways to make multilingual field to be displayed translated.

1. Use WordPress translation function __(). A multilingual text gets translated whenever it is passed through the standard WordPress translation function __().
2. Use WordPress filters. Many themes and plugins pass a value through  a call to “apply_filters('filter_name',$text);“. Once you find out which filter is in effect, you may list its name in configuration option “Custom Filters”, or in token ‘filters’ of ‘front-config’ branch of JSON-encoded configuration.
3. A developer may use one of the designated interface filters to pass a value through in order to get it translated. This method is applicable to both front- and admin-end.

A number of commonly used filters are always enabled by default. For example, filter ‘the_content’ is applied on the whole content of a page or post. If there is some multilingual text in the content, it will get translated then. There are many more filters enabled by default, which you may look up in the code or in i18n-config.json default configuration. Those filters make the majority of themes and plugins to work without an additional coding or configuration, but there are a lot of special cases as well.

Need additional javascript functionality?

It is easy enough to inject your own additional integrating java script with configuration tokens ‘js-conf’ and ‘js-exec’.
Read Guide for Custom Java Scripts for more information.

When JSON-encoded configuration is not enough.

If JSON-encode configuration cannot satisfy all your needs, then an additional integrating plugin or a child theme may be developed to facilitate whatever extra complex functionality is needed. Read PHP Developer Guide for more information.