Creating a multilingual site

Foreword: How to manage a multilingual site

There’s no one method of organising a multilingual site which covers every situation. Think, for example, about the following sites:
-  one containing poetry organised by themes (sections);
-  one with technical documentation (a site such as spip.net);
-  one of an institution in a bilingual country;
-  the site of a Bulgarian association with a few pages added in English for visitors from other countries.

The poetry site would probably mark the language of each poem individually, article by article. SPIP’s documentation is sorted by language into “sectors” (top-level sections) and shows the translations that are available for each article. The bilingual institution would need everything to exist in both languages; for example two sectors, English and Welsh, with an identical tree structure of sections and articles. The Bulgarian site would have one sector in English containing the articles which it has been thought the most important to translate, while the rest of its sectors would all be in Bulgarian (by default).

Principle

To give the flexibility for all these different situations, SPIP allows the language to be set for each section, article and news item. Both on the public site and in the private area, the typographic correction which is applied depends on the language of the current item. On the public site the language of the elements which SPIP inserts (e.g. dates and forms) also derives from the language of the current item.

In order to create a multilingual site it is first necessary to activate multilingual support and choose the languages you want to use on your site in the private area, using the section "Site Configuration / Language Management / Multilingual".

Configuring multilingual support

The site configuration allows you to choose at what level language settings are applied. This is intended to make administering the site easier by only showing a choice of languages where needed and reducing the risk of mistakes being made. [1]. SPIP suggests three levels of language choice, in order of complexity:

-  By sector (top-level section): in this case each top-level section corresponds to a language, which can be set by the site’s administrators. This language is applied to all sub-sections and to all articles and news items published within that sector. This setting should satisfy the needs of most multilingual sites and it preserves a clear structure and simple interface.

-  By section: with this setting it becomes possible to change the language for each section of the site, not just the top-level ones.

-  By article: with this setting it becomes possible to change the language for each article. This setting is compatible with the previous ones. For example, you can choose a language by section, but still apply exceptions for certain articles. This setting allows for great flexibility, but if you use it, take care not to build a site which bewilders its visitors.

Multilingual Blocks

Some elements, like authors and keywords, could be written differently depending on the language of the article they are attached to and their is no point in creating "Translation of this keyword" or "Translation of this author" since it is the same author who creates both articles or the same keyword that is attached to them. Therefore these elements do not have a language from the SPIP point of view yet it is possible to show them in the language of the context they are called in with the help of the "multi blocks" (simply put, the possibility for the keyword "Iraq" to be displayed as "Irak" when the language of the context is French).

The "multi block" is a SPIP shortcut, and its structure is pretty straightforward:

<multi>string1 [xx] string 2 [yy] string 3 ...</multi>

Going back to the previous example, the title of this keyword would be entered thus:

<multi>[en]Iraq [fr]Irak</multi>

If a multi block is to be displayed in a language that was not accounted for, it will always take the value of the first part of the block (string 1, in the first example and Iraq in the second). This is to avoid having a blank space instead of the keyword [2]

PS: Multi blocks can be used also, with the same structure in the templates see Internationalizing Templates.

How to manage the loops and tags

Once the site configuration has been set in the private area, we need to look at the templates. For even if we have assigned, as explained above, a language to each part of the site, the templates must be able to use the information when they display the pages.

1. A piece of good news: the site templates are already, for the most part, naturally multilingual. It is not necessary to have different templates in order to display articles in different languages. A single template can automatically adapt its display to the current language.

All the elements displayed in and around an article in a given language will be shown in that language. This applies to the article’s publication date, forum response forms, petition signatures and so on. In more general terms, every SPIP tag which is within an ARTICLES loop will be displayed in the language of the article (likewise for sections and news items).

Example: if your home page contains a list showing the site’s ten most recent articles together with their publication date, then the date of Arabic articles will display in Arabic, those in Polish will be in Polish, etc.

N.B.: For this to work the language in question has to be one of the languages into which SPIP has been translated. So if the article is written in Wolof but your version of SPIP has not yet been translated into Wolof (you are welcome to help in translating SPIP), then the date will be shown instead in the site’s default language.

2. HTML language tags and writing direction

If your site contains text not only in languages written left to right (the majority of languages), but also in languages written right to left (e.g. Arabic, Hebrew, Farsi), the HTML in your templates needs some additions for it to be displayed successfully. [3].

SPIP has a particular tag, #LANG_DIR, to define the direction of writing. The tag can be used as the value of the dir attribute in most HTML tags giving: "ltr" for left-to-right languages and "rtl" for right-to-left languages. [4].

A loop to correctly display a multilingual list of articles would thus be:

<BOUCLE_list(ARTICLES){par date}{inverse}{0,10}>
  <li dir="#LANG_DIR">[(#DATE|affdate)]:
  <a href="#URL_ARTICLE">#TITRE</a></li>
</BOUCLE_list>

The language of the page should be given at the beginning of the template, e.g.:

<html lang="#LANG">
<body dir="#LANG_DIR">
...
</body>
</html>

And finally, if the design of your page depends on elements which are right or left-aligned, these will need to be flipped. You do this by replacing all [5] the left or right markers of elements in the template by these tags: #LANG_LEFT and #LANG_RIGHT.

3. Translation links

SPIP makes it possible to create links between translations of an article. This is activated in the private area using the section "Site Configuration / Language Management / Multilingual". When writing a new article it can be marked as a translation by entering the article number of the original reference article using the ARTICLE LANGUAGE AND TRANSLATIONS form above the body of the new article. (When you create a new translation by using the button "Write a new translation of this article", this number is inserted automatically.) When translation links exist, the criterion {traduction} allows you to extract all the language versions of an article using an ARTICLES loop.

For example, to show all the translations of the current article:

<BOUCLE_translations(ARTICLES){traduction}{exclus}>
[<a href="#URL_ARTICLE" dir="#LANG_DIR">(#LANG|traduire_nom_langue)</a>]
</BOUCLE_ translations>

Note the criterion {exclus} which stops the current article being displayed itself, and the filter {afficher_nom_langue} which provides the name of the language: "English", instead of its code, en; "français" instead of fr, etc.

-  A further criterion {origine_traduction} (for the purists) makes it possible to select just the "original version" of the current article.

International templates for heavily multilingual sites

What we’ve described above makes a template multilingual insofar as it draws its elements from SPIP: the text produced by the loops is displayed in the correct direction, with the right typographical rules; dates, forms, etc. are shown in the right language.

But the textual comments which are written directly into the HTML of the templates (headings like "Site plan", links like "Printable version", etc.) will only be displayed as they have been written. For some sites – bilingual ones or ones which have a main language and just a few articles in other languages – this may not be a big problem: these mentions can remain in just the site’s main language or, in the case of a bilingual site, a separate template can be used for each language.

However, if you want to create and maintain a truly multilingual site, neither of these solutions is realistic. It becomes necessary to create a list of language-specific texts which will be called into place within the HTML of the template. To do this, a small effort is necessary, and how to do it is described in another article.

Further details on writing direction

-  The typographical shortcuts <code> and <cadre> always produce a text written from left to right, even if used within an article whose language is written from right to left. This is because these two shortcuts are used to display code or computer data which is nearly always written from left to right (and usually using Western letters).

-  The HTML attributes left and right are often also present in CSS style sheets. This may mean that you need to include a part of the style sheet in your template (in order to be able to use the tags #LANG_LEFT and #LANG_RIGHT) rather than placing everything in a separate .css file.

-  This table shows the values produced by the SPIP tags concerned with the direction of writing: