How to

How to set and use a multilingual child theme.

Importing multilingual datas of a website previously controlled by Polylang plugin

Preamble

VERY IMPORTANT: change of plugins must be preceded by IMPERATIVELY a backup of the database.

Performing backups has been very helpful in the phases of development of this new feature to Xili-language 2.21+ and allowed at any time to return to an earlier phase.

Although Xili-language taxonomy and that of Polylang have the same name, there are differences explained in this article.

This post concerns webmasters with a good level of knowledge of WordPress … and those who know the “CMS” reasons behind to move from Polylang to Xili-language (2.21+).

Preparation

Installation WITHOUT ACTIVATION  to the 3 xili-language plugins, Xili-tidy-tags and Xili-dictionary. Either via FTP or through the list of plugins.

Open multiple tabs in your browser: two on the list of extensions, one on the visitor site side and one on the dashboard.

Desactivate Polylang

Caution, in the list of extensions, you must  only desactivate Polylang without deleting it because otherwise, for lack of option provided for this purpose by the author, all specific data Polylang will be deleted.

desactivate Polylang
desactivate Polylang
Activate xili-language
Activate xili-language

Once, Xili-language activated, a semi-automatic multi-step process is set up and opens the welcome page:

Welcome screen after activation
Welcome screen after activation

Once in the page settings, it is seen that the elements left behind by Polylang are detected and processed for multilingual management now by xili-language:

before regeneration
before regeneration

Regeneration multilingual elements

The regeneration of links between posts made, the message says to go to the Settings for Experts tab.

regeneration done
regeneration done

Because the next step is taxonomies, go to the previously prepared browser tab where there is the list of extensions and enable Xili-tidy-tags:

Activate xili-tidy-tags
Activate xili-tidy-tags

Going back to the settings page Expert Xili-language and the window (meta-box) “special actions and parameters”:

Start taxonomy groups recovering
Start taxonomy groups recovering

Operations related to taxonomies relate Tags (post_tag) primarily:

Tags list and languages
Tags list and languages

now screen xili-tidy-tags assign

xili-tidy-tags assigning done
xili-tidy-tags assigning done

They prepare the items for categories that are managed in translation mode (without cloning) by xili-language and Xili-dictionary. (see Article …)

To clean the WP base before removing the Polylang extension, you have to go to the next step (this can be done later):

To launch DB cleaning process
To launch DB cleaning process
Ready to delete plugin files
Ready to delete plugin files

 

CAUTION :

It goes without saying that now Polylang should not be reactivated. To go back: use the backups.

The Polylang files are deletable via the page showing list of extensions or better via FTP. Xili-language, however, has made so renaming the file
 uninstall.php to uninstall_XL_desactived.php
so it does not destroy particular taxonomy “language” in the process “deleting” managed by  WP.

 

Multilingual WP plugins and (custom) taxonomy

Since 2009, Xili-language followed two years later by Polylang are two plugins that use a taxonomy named “language”. This is possible since WP 2.3 – see file taxonomy.php
The main advantage of this approach taxonomy is that it does not destroy records (post) originals. (Indeed, other extensions modify the fields ‘post_content’ and add tables …)

Like those basic categories (category) and keywords / tags (post_tag), each element (term) of the taxonomy is described by its name, its shortcut (slug) and description. The other fields are the technical elements (term_id, taxonomy_id …)

Example of category “Recent News”
– Name : Recent News
– Slug : recent-news
– Description : the most recent news to be published

Inside xili-language and the taxinomy “language”, a language is defined as:
– Name : fr_FR (iso)
– Slug : fr_fr
– Description : French
and
with Polylang, the choice is different :
– Name : French
– Slug : fr (raccourci)
– Description : several serialized data in a table (array) whose name iso (locale => en_US) used by WP to name translation files.

The key point (pivot) is in both cases, iso code that describes the language and country of its use: fr_CA is used in Canada if we are to be precise.

Using serialized data in the description field is a Polylang originality that is not found in WP. Such fields do not allow SQL query. (need php functions)

As shown locale.php JetPack file (used by Xili-language), language management is very complex and use multiple encodings. You can find other invariant elements like the name cited in the language (French) and the writing direction (ltr). In fact, there is very little quantity of rtl languages.

With a few hundred lines, Xili-language (2.21+) can recover multilingual elements of a previous WP installation driven by Polylang. (see instructions post)
Xili-dictionary is also compatible with Polylang active (through filters and an abstraction of the taxonomy model). For example to translate language files for a theme or plugin with creation of pot, po, mo files.

WordPress multilingual monosite: dreamed specifications

There are eighteen months, early 2014, a comparative study thrust multilingual solutions was begun. In the context of a mono-site WordPress installation, is it possible to define a list of specifications that allows to make an appropriate choice?

The first constraint is that a site with a WordPress installed single-site engine. (on the approach multisite installation is not addressed here although it has its own benefits.)

While technical supporting and doing site analysis and extensions, on several occasions, including recently, we have drawn attention to the sometimes old or deemed extensions (free or commercial) that profoundly alter the data (consistency and robustness) and the basic architecture.
Of course these web sites work but what he has behind? How will the data support the type approaches Json Api etc … without mentioning of course compatibility with the most common extensions.

Let us remember also that a multilingual website is not necessarily a set of pages, each of which has its “clone” in the other languages of the site. The user experience will also depend on the target population (multilingual country like Canada, Belgium, …) or International site “global”.

The “multilingual” character must be included in the editorial strategy (content strategy) and capabilities of establishment, operation and maintenance.
At it, the commercial nature of an extension is not a guarantee of solidity. The ability to read sources can also shed light on the webmasters who, with supplied base, will add the necessary customizations and contribute to future versions.

Bulk: some key elements of the specifications

On this first list, are listed below all technical elements that will be the basis of a strong installation that will continue with the successive versions of WP.

  • taxonomy dedicated to the language of a post (article, page, custom post) with 0, one or more languages assigned to it,
  • opportunity to describe the language with the ISO code and via an alias,
  • use of get text functionality (.mo / .po) for structural text themes and forms,
  • in the core, a theme, an extension: separation of data on the visitor side and admin side / author (not yet total for the core WP – core)
  • use of the sites dedicated .mo files that do not change those delivered with the themes and extensions,
  • Compatibility with default, shorts and perma links,
  • query wp_query simple for sub-selecting items,
  • code understandable to potential adjustments
  • cross-post visible link (? serialization in the description of taxonomy or custom field?)
  • reversibility (find datas with basic functions wp) – easily usable taxonomy
  • language selector (switcher) versatile (widget, menu, template tag)
  • Keywords (tags) taxonomy – grouping (alias), custom taxonomies
  • export / import via XML
  • xmlrpc – json,
  • available personalization filters,
  • no new tables (or few),
  • dashboard with components available such METABOX (minimum js, the browser tab)
  • pictures option / setable flags (any format, any name) – definable theme of the creator and the user
  • inline documentation (help, pointing js)
  • cookies / domain: options to be studied,

Bulk: some unacceptable elements that incite address some extensions with huge precautions

  • Modifying fields (title, content, …) posts (article, page) – in total contradiction with the WordPress data model

  • Translation posts added to the new tables or as custom post types

  • No explicit description of the model – however often visible (guessable) in the file uninstall.php (if available)

to be continued…

[update] this translation is done to contribute to this article in WordPress Core…

xili-language v. 2.15.1: flag features improved for theme’s developer

xili-language v. 2.15.0 introduced function add_theme_support ( 'custom_xili_flag') to permit flag features inside Media Library.
By adding a parameter array ($args), xili-language v. 2.15.1 introduces a way to register default flags coming from a sub-folder of the theme’s folder. An easy way to provide adapted flags to the webmaster in conformity with the design and look of the theme. No need to upload these preset images.

Example of code to put inside a function call by an add_action ‘after_setup_theme‘ (priority set to 12)

%2$s is used in ‘path’ because the flags are inside the child theme in this example. Here, it is supposed that all the pictures are present.

To deliver examples of loop, twenty fourteen-xili theme is managed inside xili-language plugin itself using available language list and testing if picture exists. And latest version of twenty thirteen-xili, will include another way.

xili-language v. 2.15: the easy way to manage flags for language selection!

This week, xili-language version 2.15 will be shipped with important new features for webmasters and theme developers.

Even if flags in language selection lists have limits (*) xili-language v. 2.15, will support flags, up to now it was necessary to use CSS to replace the name of a language with a flag image.

(*) same languages are spoken in multiple countries!

Some examples have been delivered in the 5 bundled multilingual child themes already like twenty fourteen xili which is in use here  live. A newer version of each child theme will be shipped and incorporate the recent new features introduced by xili-language 2.15.

With tools provided by the WordPress Core and those xili-language plugin introduces:

  • there is now an easy way to assign an image added to the media library as a flag,
  • a way to assign this flag to a language,
  • a new interface at the Appearance menu to adjust some parameters,
  • and an automatic process to generate style lines for the webpage header.

Developers will find:

  • a new add_theme_support() named ‘custom_xili_flag’,
  • new filters to set their custom themes,
  • new shortcodea to use flag images uploaded in library by the webmasters.

Some screenshots: Below, taken from the media list, a picture that is assigned as a flag (the second is assigned as header image)

flag example
flag example

The screenshot below shows the main option (flag or language name), a list of available flags uploaded to the media library and some very technical lines reserved for skilled and motivated users. For the five bundled themes, these values are provided as template style:

xili-language flag settings
xili-language flag settings

PROS:

  • choice of flags are free, no need to define a name or a type…
  • the plugin chooses the good picture uploaded and assigned to a language from the media library.
  • using filters, theme developers can deliver default values and settings.

CONS:

  • even more lines of code!

A new plugin to manage attachment and media: xili re/un-attach media

A new plugin  to manage attachment and media files called xili-re-un-attach-media which adds the actions Unattach and Reattach at the Media Library Table list to manage attachments in the File column just after View action.
This plugin is only active in admin (dashboard) side.

Link to [Github by dev.xiligroup].

Here is a zip xili-re-un-attach-media containing the plugin for testing. Please read carefully the readme.txt …

xili-re-un-attach-media is now in WP plugin repository.

xili-language v 2.13: new rules, new features and improvements…

This week, xili-language plugin (and xili-dictionary) were improved and shipped…

  • tested and improved with WP 3.9.1
  • 2nd tab in settings UI reorganized to adjust front side (visitor side).
  • 5th tab to set dashboard side (authoring and various technical settings).
  • includes authoring propagate options previously available only in theme’s class (see new 5th tab in settings UI).
  • WARNING : users of child theme examples (bundled series like twentyten to twentyfourteen-xili) must update and use latest releases now available in github – backup before langs subfolder to keep previous translations –
  • widgets adapted for theme customize appearance screen (WP 3.9+).
  • improved choice in parent/child .mo files priority,
  • try to search local-xx_YY in wp-content/languages/themes (WP_LANG_DIR)
  • improved All content xml export for all authorized CPTs.
  • fixes – returns from developers and webmasters are welcome.
  • code cleanup.

More about .mo

xili-language multilingual plugin, since his creation five year ago, is based on two main things:

  1. the language of post (and custom post) is defined by the custom taxonomy “language”.
  2. the ‘live’ translation of terms is mainly based on .mo file of current theme (like translation in a localized website) of the current language. The plugin choose the right language according the current language assigned to the single displayed post, the home page or a list of posts.

Case of a standalone theme (w/o parent)

With a current theme with textdomain twentyfourteen (without child), for a french context, the file fr_FR.mo is loaded. (and if created by xili-dictionary or by hand with poEdit, the local-fr_FR.mo).
If the files are not found in a sub-folder of the theme, if, available in subfolder wp-content/languages/themes, the files twentyfourteen-fr_FR.mo and twentyfourteen-local-fr_FR.mo are loaded.
Be aware about that:
if a term or sentence (msgid) and his translation (msgstr) are in the fr_FR.mo and in the local-fr_FR.mo, the translation of local-fr_FR.mo has priority. It is a good thing if you are not satisfied by the translation delivered by the theme’s author!
local-xx_YY.mo currently contains translations of terms et sentences from the website itself (title, date format, categories,…).

Case of child and parent themes:

By default, only the .mo files availables in child theme are loaded.
To help translation strategy and versioning, it is now possible to use also files from parent theme languages folder. xili-language is able the define how will be done the merging between child and parent files.
As in above case, a local file is loaded from the current (here child) theme and has full priority.
For the other files (child and parent), you can define the priority, child or parent… By example, if you don’t want to modify the parent .mo files, so define child files as a priority.

The form is inside the screen under the 4th tab of xili-language settings.

merging .mo files option
merging .mo files option

xili-language: a new shortcode revealed !

The latest version of xili-language provides a new shortcode named xili18n.

The short code is usable at the content of a page or post.

The purpose of the short code xili18n is to bring translatable terms inside of a text body. The translation for each language ist stored in the languages .mo file.

What is the goal?

Content can be very rich and complex nowadays (for example a table or form) same counts for specific terms. The idea is creating a clone-able version of a table or form for each language by inserting the shortcode for example at the table header of each column. So you simply need to copy the content into the different languages without translating these again and again.

Here is how the short code is used:

The result in English is of course  Edit !

But go to the French or German post to see the result in a foreign language.  😉

Question 1: is is possible to define a context ? Yes with param ctxt !

Question 2: is is possible to choose the text domain ? Yes with param textdomain !

Question 3: Limitations in msgid or msgstr ? Yes only html tags like <strong>, <em> and <br> are possible. See the source code of the xili-language plugin for more details.

Tip of the day: import translators comment from php to poEdit

Context

By default poEdit (here version 1.6.4 for Mac OSX 1O.9) forget to import translators comment in po file.
like here

to obtain this result in .po file:

After some researches, it seems that a command must be added to the php parser “–add-comments=translators”. No need to modify via terminal the config… just go to preferences of poEdit and the line in php parser config tab:

poedit parsers preferences
poedit parsers preferences
poedit php parser
complete command with –add-comment=…

As in WP codex ‘translators’ is low case !

Enjoy !

M.