JSON-encoded Configuration Syntax

JSON-encoded configuration file describes all the information needed for qTranslate-X to function. Information on how JSON-encoded files are distributed and loaded is provided in Integration Guide. The format and syntax of JSON-encoded files is described below.

JSON-encoded configuration is an associative array with two main keys: “admin-config” and “front-config”. Each “-config” is an array of independent tokens, each of which describes pages, fields, forms and other relevant configuration information. All tokens have distinctive names (handles), and sets of tokens of the same kind are assembled in associative arrays with handles as keys. This way it becomes easy to override a token with a new value when a few configuration files are loaded sequentially one after another.

The browser’s tool “Inspect” is available on right-click in most of browsers (Ctrl+Shift+I in Chrome, for example) can help to find out the id, class, name and other attributes of a  fields that need to become multilingual. Once the the attributes of fields are known, an appropriate jQuery selector can be composed and used in “jquery” string, as explained on this page. The simplest way is to identify a filed by its “id” if available, then “jquery” string is not even needed in the configuration.

Below is the description of allowable syntax in a configuration. It is a good idea to have an example of some configuration in front of the eyes in which you may look up the keywords being mentioned. For example, you may open the main configuration file of qTranslate-X for that purpose. Unfortunately PHP’s JSON parser is not very friendly with syntax errors reporting. If you cannot see an error, try to simplify the expression until it gets parsed without errors, and then add back the stuff by little pieces – then it is easier to spot the syntax error. On bright side, the JSON syntax is not terribly complex, and normally an error is either an extra comma at the end of a list, or unclosed bracket, or forgotten quotation mark, or something simple like that.

The syntax of “admin-config” branch.

The value of each item in array “admin-config” is a hash table with the following possible keys:

• ‘pages’ – defines the pages, to which this configuration item is applicable. It consists of a hash of items in the form “page => query”, where ‘page’ is a regular expression, which is matched against WordPress global variable $pagenow with the operation preg_match('!'.$page.'!', $_SERVER['QUERY_STRING']), and string ‘query’ is a regular expression, which is matched against URL query string with the operation preg_match('!'.$query.'!', $_SERVER['QUERY_STRING']). The array can have as many pairs “page => query” as desirable. A token is considered applicable to the current admin page if one of the pairs matches $pagenow and $_SERVER['QUERY_STRING'], otherwise the whole item is skipped for the current page.
• ‘anchors’ – consists of tokens to define where the sets of Language Switching Buttons (LSB) are placed on the page. The key of each token is an “id” of an HTML element, around which a set of LSB is placed. The value of token is an associative array with key ‘where’ pointed to a string with values
  • ‘before’ – LSB is placed as previous sibling of the HTML element
  • ‘after’ – LSB is placed as next sibling of the HTML element
  • ‘first’ – LSB is placed as first child of the HTML element
  • ‘last’ – LSB is placed as last child of the HTML element

  If ‘anchors’ is omitted, then the first form in the first element of class ‘wrap’ is taken as an HTML element before which LSB set is placed. If form is not found this way, then the first form, which has a child element of class ‘wrap’ is taken.

• ‘forms’ – an array of hash items, one per each HTML form, which have some input fields translatable. All translatable fields can be grouped by the form which they belong to. Display fields (non-input ML fields) may also be grouped the same way, but then “form” can be any HTML element, which contains a tree of other elements, some of which are multilingual. Each hash in ‘forms’ may have the following keys:
  • ‘form’ – a hash with one pair “key => value”, which defines a container. Key may be one of the following:
    • ‘id’ – then ‘value’ is the ‘id’ attribute of the container, it gets searched with document.getElementById(value).
    • ‘jquery’ – the container is searched with jQuery selector $(value).
    • if there is no neither ‘id’ nor ‘jquery’, then the key of the token ‘form’ is interpreted as ‘id’.

    Once the container element is defined, the subsequent searches for input or display fields are done within this container element.

  • ‘fields’ – an array of items describing the translatable fields within the form. One item may define a set of fields. Each item may have pairs of “key => value” with the following keys (listed in the priority order):
    • ‘id’ – then ‘value’ is the ‘id’ attribute of the field, it gets searched with document.getElementById(value).
    • ‘jquery’ – the fields are searched with jQuery selector $(value). This is the most common way to define a field.
    • if there is no neither ‘id’ nor ‘jquery’, then the key of this token is interpreted as ‘id’.

    The search may be done within the container element(s) specified. By default, the container is an element defined by ‘form’, but sometimes more granulated containers are needed to uniquely define the set of fields. The alternative containers may be specified with one of the following keys:

    • ‘container_id’ – defines one container, which gets searched with document.getElementById(value).
    • ‘container_class’ – defines a set of containers, which is returned by the search document.getElementsByClassName(value).
    • ‘container_jquery’ – defines a set of containers, which is returned by the jQuery selector $(value).

    Once the set of containers is defined the subsequent searches are done within each container.

    • ‘encode’ – defines the type of the fields found by the above criteria. It may have one of the following values:
      • ‘input’ – text input field, either of type ‘text’ or ‘textarea’. This the default and the most common case. If key ‘encode’ is not specified then the field is assumed to be a text input field, this is how it is in use in most of examples. You may also specify the type of multilingual encoding for an input field with one of the following values for ‘encode’ key:
        • ‘[‘ – square bracket encoding like [:en]text[:]. This is the default encoding.
        • ‘{‘ – swirly bracket encoding like {:en}text{:}.
        • ‘<‘ – comment encoding, like <--:en-->text<--:-->.

        Different types of encoding provide flexibility, as any of them sometimes is in a conflict with a 3rd-party code.

      • ‘byline’ – a textarea, in which each line gets encoded with language tags separately from other lines. For example, field ‘woocommerce_tax_classes’ on page ‘/wp-admin/admin.php?wc-settings&tab=tax’ of plugin Woocommers needs such encoding.
      • ‘display’ – the field is not an input field, but rather any other HTML element, some nodes of which are multilingual values. The applicable nodes of such a field get translated according to the edit language chosen via Language Switching Buttons (LSB). This type of field does not need to know form, since it is not an input field, and ‘form’ key may be omitted on a token which defines ‘display’ type of fields only.

    All pairs are optional. Provide the minimum number of keys that defines the desirable fields uniquely within the page.

  In fact, token ‘form’ does not have to define <form> element, it can be an arbitrary HTML element, within which all configured fields are searched. All <input> fields must belong to a form, but display fields may be outside of a form. Thus, token ‘form’ simply defines a parent HTML element to search fields under. If ‘form’ is omitted, then the whole document is searched for each particular field listed.

• “js-conf” – list of scripts to be executed before line “new qTranslateX” in qtranslate-x/admin/js/common.js. It gives a chance to alter configuration variable qTranslateConfig. Each item defines one script with the the same key names as the names of arguments of WordPress function wp_register_script:
  • “handle” – name of handle. If omitted, then the key of this token is considered to be the handle.
  • “src” – file path, which is relative to ‘wp-content’ directory. If it starts with ‘./’, then the path is relative to  ‘plugins/qtranslate-x’ directory. Absolute file paths also acceptable.
  • “ver” – version of the script. If omitted, the version of plugin qTranslate-X is in use.
  • ‘javascript’ – a text of the code itself. It works well for small enough code instead of creating a separate .js file.
• “js-exec” – List of scripts to be executed after “new qTranslateX” in ‘qtranslate-x/admin/js/common.js’. It gives a chance to execute additional actions on qTranslateConfig.qtx. The possible “key=>value” pairs are the same as for key ‘js-conf’.

The syntax of “front-config” branch.

Array “front-config” works in a similar way as for configuration “admin-config” described above, with the following allowable keys:

• “pages” – similar to the admin-config’s “pages”, except that the page and query are matched against $_SERVER['REQUEST_URI'] and $_SERVER['QUERY_STRING'] without language encoding.
• “filters” – name of filters to enable. There are a few kinds of filters:
  • “text” – multiligual text gets passed through a call to function qtranxf_useCurrentLanguageIfNotFoundUseDefaultLanguage.
  • “term” – a taxonomy term name gets passed through a call to function qtranxf_useTermLib.
  • “url” – gets passed through a call to function qtranxf_convertURL in order to encode the url string with a currently active language according to options “URL Modification Mode”, including option “Hide URL language information for default language”.

The code of already existing integrating plugins may provide good examples, which also demonstrate the code separating between front- and back-end.