Internationalizing Templates

Internationalizing templates as dealt with in this article is made possible from SPIP 1.7.

What’s the Use of Multilingual Templates?

As soon as documents get on line some of SPIP’s “automatic” information is adapted to conform to the chosen language. Dates, in particular, are displayed in the language chosen for the site, or for an article, or for a section, and the forms are displayed in the corresponding language — as in the interface needed for posting messages on a forum. All these translations are already present in SPIP 1.7.

This, however, isn’t enough as webmasters write some information into their templates, mainly describing the site’s navigation principles. For example, they need to display texts such as “Site Map”, “Comment on this article”, “Articles by the same author”, and the like. On a site with only one language, such elements are easy to add — you only need to write the required words inside the HTML code of your templates. On a multilingual site, however, there’s a hitch — at the bottom of an article in French you need to display “Répondre à cet article” but if an article is in English you need to display a different message (“Comment on this article”).

SPIP offers two ways of managing language-specific textual elements:

— (1) One way is to store template textual elements in language files — one file for each of the languages used on the site — that are kept apart from the templates. So one template (for instance, article.html) fetches those textual elements defined by the webmaster’s language-specific codes. This way the article.html template will automatically display “Répondre à cet article” or “Comment on this document”, according to the article language. Webmasters are strongly advised to follow this method which offers most flexibility and makes updates easier — since you work with only one template which automatically manages several languages. Moreover, some tools will eventually be added to SPIP to make team work on the translation of your site interface easier — several administrators each of them speaking a different language will be able to translate the interface of the same site from the private area without having to make any changes in the template files.

— (2) The other way is accessible more quickly, and is technically very simple as it is based on creating a separate template files for each language. Just create an article.html file to manage articles in French (if the default language is French), and another article.en.html file to manage articles in English (note that, in fact, article.html manages all the languages but English). Such a method is well-adapted for building a site quickly as long as there are only a few languages, and the structure is kept fairly simple. However, this method isn’t advised if many languages are used and/or if separate templates are used for different sections.

— "Multilingual blocs", introduced by [SPIP 1.7.2], works in the templates as well as in the content. You just have to include the following in your template:

and the sentence will be displayed in the required language. Altough this system is very flexible, it reaches its limits as soon as the number of languages increases and various translators contribute to the site (indeed, they would have to modify the templates which can be avoided by the language files method).

1. Using language files

The basic principle of language files is to write a code into only one template corresponding to a language-specific textual element ( a “string”). The code doesn’t change from one language to another but the text gets translated into the specific language.

Here’s an example. You can decide the telechargement code will correspond to:
— the “télécharger ce fichier” string in French
— the "download this file" string in English
— the "descargar este archivo" string in Spanish
— etc. In the article template file, i.e. article.html — one file managing all the languages — you only need to write the following code (please mind the syntax):

When the article is displayed the code will be replaced by its translation into the language of the article.

For example, you can write the following code into the article.html template, and inside the loop displaying the documents attached to the article:

If the article’s in French you’ll get this:

<a href="/IMG/jpg/mydocument.jpg">télécharger ce fichier</a>

If the article’s in English you’ll get this:

<a href="/IMG/jpg/mydocument.jpg">download this file</a>

and so on. To recap, one template having one code displays a text which is translated into all the languages used on the site.

-  How to use already translated texts

To make the webmaster’s job easier, a number of pre-translated strings are provided with SPIP (the translations were made by SPIP translators). Using these strings corresponding to much-required textual elements on websites, the webmaster can quickly make a layout for various languages even if she can’t speak them.

You can get the list of ready-made strings from the private area — go to the “Site Administration”, then select “Language Management”, then click on “Language Files”. All you have to do now is look for the codes you need, and copy and paste them into your templates.

The language files of the private area.

Here’s an example: A webmaster wants to create the layout for a site in French, Spanish and Arabic but she can speak neither Spanish nor Arabic. Writing the codes supplied with SPIP into her templates she doesn’t need to look for translation in Spanish or Arabic since the translation work has already been done beforehand by SPIP translators. So, setting the layout in French with the codes included with SPIP she can be sure her pages will be immediately displayed in Spanish and in Arabic.

If articles in Polish are added later on they’ll be immediately displayed with the textual elements translated in Polish without the webmaster’s need to make any changes.

Another advantage of this method is that creating multilingual templates for “distribution” is made easier. Templates that are made in this way can be used straightaway in any language into which SPIP is, or will be, translated.

From a technical point of view the standard textual elements provided with SPIP are stored in the “public” language files:
— /ecrire/lang/public_fr.php3 has strings in French
— /ecrire/lang/public_en.php3 has them in English
— etc.

-  How to create your own codes

Moreover, you can create your own codes corresponding to strings you’d like to add yourself: It is only a matter of creating your own language files following the pattern used in the public... files. To create your own files, install the following files either in your template directory or in the /ecrire/lang directory:
— local_fr.php3 to define strings in French,
— local_en.php3 to define them in English,
— etc.

Note: In versions before [SPIP 1.8], these personal language files could only be placed in the /ecrire/lang directory.

For example, the following strings in French can be created:
— telechargement to display “Télécharger la dernière version”, [1]
— quoideneuf to display “Modifications récentes” [2].

Then if you write the following codes into your templates: <:telechargement:> and <:quoideneuf:> they’ll be displayed as translated texts, exactly as they are defined in the local_...php3 files.

Please note that codes are arbitrary — you’re the one making them up. Of course you’re advised to choose codes you can easily remember (better not choose numbers). As is often the case with computer codes it’s best to use letters from the Latin alphabet only, and avoid all kinds of accents and the like.

Language files contain the various translations of the codes you use; these are PHP files with a table each, associating the strings to the language-specific codes. They’ll contain this, for instance:

-  French version :

-  Catalan version:

Here’s the structure:

— beginning of file:

— end of file:

— the part of the file you can change is made up of several definition lines following this pattern:

N.B. Each definition line ends with a comma, except for the last line.

N.B.2. The textual string to be translated must be converted into HTML codes — accented characters, namely, must be converted into their HTML equivalent, such as &eacute;.

Apostrophes inside the strings must be “escaped”, i.e. with a backslash before them. For instance, the “What’s new?” string must be written in this way: What\'s new?.

Note: It is planned to eventually include a tool to manage and create your own language files without having to change the PHP files manually. Such a tool will also make the use of “special” characters easier (accented characters, characters from non-Western alphabets, apostrophe escaping etc.) as well as the association of several people to the interface translation process.

For the present being, the tool managing the translation of textual strings isn’t supplied directly with SPIP, and its broad use at the moment makes it a little too complicated for that task — we use this tool to translate all the SPIP interface, and not only the local...php3 type of files. The program, called spip_trad, which we use to translate our SPIP software, the spip.net site etc. is itself available under the GNU/GPL Licence but isn’t included with the standard version of SPIP. You can download it and use it on your site or for other software projects. If you improve it, or if you have ideas how to change it, feel free to discuss the issues on the translators’ mailing-list, spip-trad, as the programme doesn’t have any real existence outside the SPIP project.

2. Separate language-specific templates

This second method, which is more accessible to novice-webmasters, is to create a separate template for each language. This is rather similar to creating separate templates for certain sections in order to get specific graphic displays.

Imagine you want to build a site in English (the default language), in Vietnamese, and in Spanish. You’ll need to create three different template files:

— article.html for English (in fact, for all the languages having no stated language files, see Note below),
— article.vi.html for Vietnamese,
— article.es.html for Spanish.

(Note: if an article is published in German while there’s no article.de.html then the default article.html template will be used).

Important: for the “language” templates to be taken into account as they are defined by adding a .lang at the end of its name, the “by default” version must exist on the site. In this example, if the article.html doesn’t exist the Vietnamese or Spanish files won’t be taken into account — though we’d have preferred naming that file directly as article.en.html.

You can combine this with section naming. Files will be taken into account in the following order:

— article=8.es.html (template for the articles in Spanish belonging to section 8 but not to the sub-sections),
— article=8.html (template for the articles of section 8, but not its sub-sections),
-  article-2.es.html (template for the articles in Spanish belonging to section 2 and its sub-sections),
— article-2.html (template for the articles of section 2 and its sub-sections)
— article.es.html (template for the articles in Spanish),
— article.html (template for articles),
— article-dist.html (template for articles supplied with SPIP).

Note: Apart from a few exceptions the language codes to be used here require two standardized letters (ISO norm), such as “es”. A copy of the list can be found on the site of the Library of Congress (USA).

To ensure maximum compatibility, two-letter ISO codes must be used (“iso 639-1”) when they exist at all, while for the more specialized naming of a language inside its linguistic family a three-letter ISO code (“iso 639-2 T”) is required. For instance, German is referred to as “de”. However, ISO takes only 182 languages into account, out of the 5.000 to 7.000 languages actually spoken over the world. For the languages not yet listed you can refer to the list provided by ethnologue.com. To get more information, feel free to join the spip-trad mailing-list.

How to make life easier for yourself. One of the very simple structuring methods provided with SPIP to organize a multilingual site is to associate languages directly to sections instead of associating them to this or that article. So in the case where articles from one language are gathered in one section (or in one sector) you can simply create special templates (for certain sections) without using language names.

This way, if all the articles in Spanish are gathered in section 8 (and its sub-sections) you can simply name the file adapted to Spanish rubrique-8.html rather than rubrique.es.html.

You can guess the problems that can crop up using this method:

— the article-2.html file must exist if the article-2.es.html is to be selected ;
— you can’t conversely decide that article.es.html must be used instead of article-2.html if article-2.es.html doesn’t exist: section selection always has the priority over language selection.
— if a correction must be made in a template the same correction must be made in the other versions,
— you need to be able to write textual elements yourselves into template files even if you don’t necessarily understand the language — fancy having to create templates in Bengali while you can speak a little Gaelic and hardly any Navajo?

This method can be helpful only to work quickly on simple sites with few section-specific templates or none at all, and/or with few languages. As soon as your multilingual project becomes a bit more ambitious you’d be best-advised to resort to the language file method.

Footnotes

[1telechargement: download; Télécharger la dernière version: Download the latest version

[2quoideneuf: what’s new?; Modifications récentes: Latest Changes

Author bealach, Paolo Published : Updated : 26/10/12

Translations : عربي, català, Deutsch, English, Español, français, italiano, Nederlands, Türkçe, українська