Multilingual Interface Implementation

THL Toolbox > Developers' Zone > Application Interface Issues > Multilingual Interface Implementation

Multilingual Interface Implementation

Contributor(s): Than Grove (PHP & XML)

Introduction

THL is committed to designing its core applications with multilingual interfaces so that international users can rely upon an English interface, Tibetans can rely upon a Tibetan language interface, and so forth.

The general approach for internationalization of THL is to use dictionary files to look up words or phrases in a particular language. In ROR and PHP-based pages, these files are stored in YAML ("YAML Ain't Markup Language"), a simple human-readable data storage syntax. (See external link: http://www.yaml.org/ and in particular external link: http://yaml.org/refcard.html for a description of YAML.) In the XML-based Cocoon applications, such as a scholarly essay or catalog, store their dictionary files in XML.

PHP Applications and Pages

The majority of the web pages for THL and a few of the apps are in PHP. These use YAML to store their translation equivalents.

How Internationalization is Set up In PHP

There are three types of YAML files used in the process of translating THL pages. Most are stored in the "/global" folder at the root of the site in a sub-folder called "/locale". Portal-specific equivalents can also be stored in a "/locale" folder at the portal level, as in "/encyclopedias/literary/locale".

The three types of YAML files used in PHP apps are:

  1. thl-locales.yml : This is describes the locales available in PHP translation. Any new language must be added to this file. It begins with a list of "langs"

that contains the iso two-letter abbreviation for that language, followed by a few language specific variables set for each available language. This file is located at external link: http://{DOMAIN}/global/locale/thl-locales.yml .

  1. General Language Dictionary: Each language has it's own general dictionary stored in the "/global/locales" folder in a sub-folder named with its two-letter

abbreviation and the name of the file is "thl-view-{abbr}.yml". Thus, there is for example: external link: http://{DOMAIN}/global/locale/bo/thl-view-bo.yml that contains the translations for Tibetan.

  1. Portal-Specific Language Dictionary: Terms or phrases specific to a certain portal within THL can be stored in the portal itself in a "/locale" folder without

being put in a separate folder by language abbreviation, as in external link: http://{DOMAIN}/encyclopedias/literary/locale/thl-view-zh.yml . There can be a specific dictionary at any sub-level within THL and the will all be concatenated with the global one for pages within that portal.

In both of the latter locations, there needs to be one YAML file for each available language. If a YML file is missing, the system will default to english. However, if a term is not found within an existing YAML file, then a blank will appear in its place on the page. All YAML files at the same level must have exactly the same terms translated.

The syntax of the YAML dictionaries is to have all translations subsumed under the category of "vocab". Each term has either a direct equivalent or has a series of sub-options for different "uses" of the word. An example is:

home: 'home' introduction:

this: 'introduction' to: 'introduction to {{what}}'

…

placeNames: drepung: this: 'Drepung' of: 'Drepung's' lhasa: this: 'Lhasa' of: 'Lhasa's' sera: this: 'Sera' of: "Sera's"

In the PHP calls these are called by strings such as "home", "introduction.this", or "placeNames.lhasa.of", which return the corresponding (in this case English) phrase. The "{{what}}" marks the place where a string passed to the translation function is substituted so that the function call might look something like:

echo ts("introduction.to", t("encyclopedia.many"));

which would result in:

<span lang="eng">Introduction to Encyclopedias</span>

There are two specific PHP files used to create the internationalization functionality. They are both found in the /global/php folder. These are:

  1. {link:spyc.php|external link: http://{DOMAIN}/global/php/spyc.php} : This is an open-source PHP YAML parser found at external link: http://code.google.com/p/spyc/ used to read the

YAML dictionaries.

  1. {link:thl-i18n.php|external link: http://{DOMAIN}/global/php/thl-i18n.php} : This contains the code for implementing the dictionaries. It loads the spyc.php file and

then reads in the appropriate YAML dictionaries and concatenates them as necessary. It has functions to write the HTML code for the language selection drop-down list as well as functions to look up and display the appropriate translation.

The thl-i18n.php file is included in the header.php global document. If for some reason you must have a separate header.php file for a particular part of the site, then this file must include the line

require_once "$droot/global/php/thl-i18n.php";

There are four important functions within this file for implementing the language lookups:

  1. write_lang_opts() : this writes the HTML code for the language option drop down list.
  2. t($lsname,$strobj = NULL, $strobj2 = NULL) : This is the basic translation routine. The first parameter, lsname, is required. $strobj is the string that replaces

the "{{what}}" in the translation. The last parameter, $strobj2, is for the few situations when there is a second "{{what2}}" string to replace.

  1. ts($lsname,$strobj = NULL, $strobj2 = NULL) : This is the same as the translation function except it surrounds the result string in a span element

whose class is set according to the appropriate style for THL CSS to apply the correct font and style characteristics. The style class is set in the information for that language found in the "/global/locale/thl-locales.yml" file.

  1. createI18nImageTag() : This creates separate image tags for each language and is used when there is text within the image.

The language in which to display the page is set by the drop-down options list and is recorded in a persistent cookie, called "thl-lang".

How to Implement Internationalization in PHP

In order to allow gradual implementation of internationalization, the code is globally included in all pages, but is by default turned off. To turn on the globalization, one has to include the PHP statment,

$multilingual = true;

Somewhere at the top of the PHP page that has been translated. This will display the language options drop down list for that page. (Ultimately, when a critical mass of pages have been translated, we can make this on by default.)

Strings

To call a simple string translation, use the ts() function. The first parameter should be the string that identifies the desired text, if that text has a "{{what}}" in it, then a second parameter is added with the text for that substitution. If there is a second "{{what2}}", use the third parameter of the function. Both these replacement texts should also be translated but with the t() function so that only the outer function for the whole phrase is surrounded by the span tags. As both these functions return strings, the output needs to be printed or "echo"-ed to the HTML result, use the "echo" command for this. Thus, an example might be:

<? echo ts("introduction.to",t("literary.of",t("encyclopedia.one"))); ?>

Wikis

Since teaser boxes contain large chunks of text that we may or may not want to translate, a separate mechanism is used to determine the text to display. This does not rely on the YAML dictionaries, but is determined by the presence or absence of an appropriate wiki-link. In general, a wiki link for a teaser box looks something like:

<a href="/access/wiki/site/0b308aa3-d044-469b-009a-d34c7841413d/tibetan%20literary%20encyclopedia%20introduction.html" class="wiki c400 o1"></a>

If the text for that wiki is translated into say Chinese, then another wiki is created with the same name as the first but with "-zh" appended to it and a second wiki link tag is entered after the first. This second link has the class "zh-wiki" instead of "wiki". For Tibetan, the class would be "bo-wiki" and so forth. The result would be:

<a href="/access/wiki/site/0b308aa3-d044-469b-009a-d34c7841413d/tibetan%20literary%20encyclopedia%20introduction.html" class="wiki c400 o1"></a>
	<a href="/access/wiki/site/0b308aa3-d044-469b-009a-d34c7841413d/tibetan%20literary%20encyclopedia%20home%20-%20right1-zh.html" class="zh-wiki c400 o1"></a>

The code will choose the appropriate wiki depending on what language has been chosen.

Images

Another important function in the php is the createI18nImageTag() function. This is used for images that have text within them. To use this function one must make an image for each language with the appropriate text within it. These must all be in the same image folder or sub folder and must all have the same name except that the non-english versions must have their language code preceded by a dash appended to the name before the extension. Thus, if English, Chinese, and Tibetan are activated, there must be three images, for example:

  1. /encyclopedia/literary/images/some-image.jpg
  2. /encyclopedia/literary/images/some-image-zh.jpg
  3. /encyclopedia/literary/images/some-image-bo.jpg

The function for creating the image has the definition of:

createI18nImageTag($iurl, $alttxt, $width, $height)

The first parameter, $iurl, is a string with the URL for the English version of the image. The last three parameters can either be strings, if the values are identical for all languages or an array of values keyed on the language code, as in:

<div id="masthead-title">
		<a href="/encyclopedias/literary/index.php" title="tibetan literary encyclopedia homepage link">
			<? createI18nImageTag("/encyclopedias/literary/images/masthead-title-literary.png", 
				"THL Literary Encyclopedia Link", 
				array("en" => "390", "bo" => "310", "zh" => "310"),
				array("en" => "28", "bo" => "50", "zh" => "50")); 
			?>
		</a>
	</div>

RoR Applications

TBA

XML Applications

TBA

Other Applications

TBA

Provided for unrestricted use by the {link:Tibetan and Himalayan Library|external link: http://www.thlib.org}