LG Multi Language v1.1.0 Translate ExpressionEngine weblog entries and content into multiple languages

Overview

LG Multi Language is an ExpressionEngine extension and plugin combination addon that allows you to easily translate your weblog entries and other short phrases into multiple languages. The users current language is determined by either sub-domain or url segment providing real flexibility while not affecting expected ExpressionEngine template rendering.

1. Demo Top

Below is a simple demo of language translation which translates the word hello into Italian, German and French based on the URL segments.

Hello = Hello!. Hello was translated into: english (en)

Change the language to:

English (default) | Italian | German | French

The template code for this demo was as simple as:

<p>
    Hello = <strong>{exp:lg_ml:translate key="hello"}</strong>.
    Hello was translated into: <em> {lg_lang_title} ({lg_lang}) </em>
</p>

Weblog entry content can also be translated using global variables. See: Translate weblog entries.

2. Requirements Top

LG Multi Language has been tested on ExpressionEngine 1.6.4+.

3. Installation & configuration Top

3.1. Installation Top

The LG Multi Language addon download contains a system folder ( extension, plugin & language folders) and an example language file which is used for phrase translations. To install the addon follow the instructions below:

1. Download the latest version of the extension
2. Extract the .zip file to your desktop
3. Copy the system/extensions/ext.lg_multi_lang.php directory to your /system/extensions/ directory
4. Copy the system/plugins/pi.lg_ml.php directory to your /system/plugins/ directory
5. Copy the system/language/english/lang.lg_multi_language.php file to your /system/language/english/ directory

3.2. Activation Top

This extension has no special activation requirements. To activate:

1. Log in to your sites administration
2. Open the Extensions Manager
3. Enable Extensions if not already enabled
4. Enable the LG Multi Language extension
5. Update the extension settings.

3.3. Configuration Top

3.3.1. Language abbreviations Top

LG Multi Language recognises the following languages (language: language abbreviation):

• Afar: aa
• Abkhazian: ab
• Afrikaans: af
• Albanian: sq
• Amharic: am
• Arabic: ar
• Armenian: hy
• Assamese: as
• Aymara: ay
• Azerbaijani: az
• Bashkir: ba
• Byelorussian: be
• Bulgarian: bg
• Bihari: bh
• Bislama: bi
• Bhutani: dz
• Burmese: my
• Breton: br
• Cambodian: km
• Catalan: ca
• Corsican: co
• Croatian: hr
• Czech: cs
• Danish: da
• Dutch: nl
• English: en
• Esperanto: eo
• Estonian: et
• Basque: eu
• Farsi: fa
• Finnish: fi
• Fiji: fj
• Faroese: fo
• French: fr
• Frisian: fy
• Gaelic: gd
• Galician: gl
• German: de
• Greek: el
• Greenlandic: kl
• Guarani: gn
• Gujarati: gu
• Hausa: ha
• Hebrew: he
• Hindi: hi
• Hungarian: hu
• Irish: ga
• Interlingua: ia
• Interlingue: ie
• Inupiak: ik
• Indonesian: id
• Icelandic: is
• Italian: it
• Inuktitut: iu
• Japanese: ja
• Javanese: jv
• Kazakh: kk
• Kannada: kn
• Korean: ko
• Kashmiri: ks
• Kurundi: rn
• Kinyarwanda: rw
• Kurdish: ku
• Kirghiz: ky
• Latin: la
• Lingala: ln
• Laothian: lo
• Lithuanian: lt
• Latvian;Lettish: lv
• Malagasy: mg
• Maori: mi
• Macedonian: mk
• Malayalam: ml
• Mongolian: mn
• Moldavian: mo
• Marathi: mr
• Malay: ms
• Maltese: mt
• Nauru: na
• Nepali: ne
• Norwegian: no
• Occitan: oc
• Afan (Oromo): om
• Oriya: or
• Punjabi: pa
• Polish: pl
• Pashto/Pushto: ps
• Portuguese: pt
• Quechua: qu
• Rhaeto-Romance: rm
• Romanian: ro
• Russian: ru
• Kinyarwanda: rw
• Sanskrit: sa
• Sindhi: sd
• Sangho: sg
• Serbo-Croatian: sh
• Singhalese: si
• Slovak: sk
• Slovenian: sl
• Samoan: sm
• Shona: sn
• Serbian: sr
• Siswati: ss
• Sesotho: st
• Somali: so
• Spanish: es
• Sundanese: su
• Swedish: sv
• Swahili: sw
• Tamil: ta
• Telugu: te
• Tajik: tg
• Thai: th
• Tibetan: bo
• Tigrinya: ti
• Turkmen: tk
• Tagalog: tl
• Setswana: tn
• Tonga: to
• Turkish: tr
• Tsonga: ts
• Tatar: tt
• Twi: tw
• Uigur: ug
• Ukrainian: uk
• Urdu: ur
• Uzbek: uz
• Vietnamese: vi
• Volapuk: vo
• Welsh: cy
• Wolof: wo
• Xhosa: xh
• Yiddish: yi
• Yoruba: yo
• Zhuang: za
• Chinese: zh
• Zulu: zu

3.3.2. Extension Settings Top

LG Multi Language has two extension settings.

1. Languages
2. Default Language

Languages [required]

it|jp

A pipe delimited list of language abbreviations that will be used for URL comparisons. Eg: it|jp would limit URL comparison to Italian & Japanese.

Default language [required]

en

The default language abbreviation if no language can be determined by the URL.

4. User Guide Top

LG Multi Language uses simple URL parsing to determine the template language.

System administrators define the available languages in the extension settings and these are the languages that are used for URL parsing. If no language is parsed from the URL then the default language will be assigned to the global {lg_lang} and {lg_lang_title} global variables.

4.1. Which language? Top

The assigned language is determined by parsing the page and matching one of the language abbreviations defined in the extension settings. LG Multi Language checks the first sub-domain and first URL segment for a match.

4.1.1. Sub-Domain Top

The first sub-domain will be compared to the defined languages before any URL segments are parsed.

Example: Parsing http://jp.my-site.com/en/ against en|it|jp will set {lg_lang} to jp and {lg_lang_title} to Japanese. The first segment (/en/) will not be considered because a sub-domain match has been made.

4.1.2. URL segments Top

The first URL segment will be compared to the defined languages after the sub-domain has been checked.

If a match is made the segment will be removed from the segment global variables and ignored by future ExpressionEngine processing. This is necessary so ExpressionEngine handles template rendering correctly.

Example: Parsing http://my-site.com/it/blog/post/12 against en|it|jp will assign it to {lg_lang} and italian to {lg_lang_title}. {segment_1} will be set to "blog", {segment_2} will be set to "post" and {segment_3} will be set to "12".

4.2. Creating a language file Top

Language files are used by the {exp:lg_ml:translate} plugin to translate pieces of text such as category names, menu titles or page headings.

The language file must be placed in /system/language/lg_multi_language folder in your ExpressionEngine installation and use the following naming convention: lang.your-language-abbreviation.php.

Example: your site has both English and French phrases then the two language files will be /system/language/lg_multi_language/lang.en.php and/system/language/lg_multi_language/lang.fr.php

Sample language files have been provided in the download package (/samples/system/language/lg_multi_language/).

$conf['lg_multi_language_lang_path'] = '/path_to_lang_files/';

4.2.1. Language file content Top

The language file follows the same format as the standard ExpressionEngine language files. The file must consist of one associative array called $L. An example is provided below:

<?php $L = array(
    "key_1" => "translated phrase",
    "key_2" => "translated phrase 2"
) ?>

Note: the normal rules for escaping PHP strings and HTML entities apply for the array values in the array ‘$L’.

5. Tag Reference Top

5.1. Global Variables Top

LG Multi Language sets two global variables: {lg_lang} & {lg_lang_title} that are rendered before any other tags.

These global variables can be used to create dynamic template tags like {body_{lg_lang}} and {title_{lg_lang}} (See: Translate weblog entries).

{lg_lang}

The current language code eg: 'en', 'fr' etc

{lg_lang_title}

The current language in a human readable format eg: 'English', 'French' etc

5.2. {exp:lg_ml:translate} Top

{exp:lg_ml:translate key [, default]}

Requires the "key" parameter. If the language file contains a value for the "key", it is translated. If no translation is available, the optional "default" parameter will be rendered. If that is not available, the original value of the "key" parameter will be rendered.

5.2.1. Parameters Top

1. key
2. default

key [required]

key="The phrase you would like translated"

The key for the phrase you would like translated. The key must have a value in the language file to be successfully translated. This parameter is required.

default [optional]

default="A default phrase, just in case."

A default phrase that will be used if there is no valid translation for the requested language. This parameter is optional.

5.2.2. Examples Top

Translate a simple phrase in the current language

{exp:lg_ml:translate key="welcome_message" }

Translate a simple phrase in the current language with a default option if no p is found

{exp:lg_ml:translate
    key="welcome_message" 
    default="Welcome to my website" 
}

6. How to / tutorials Top

6.1. Translate short phrases Top

Translating short phrases is achieved using the {exp:lg_ml:translate} tag.

The tag requires the key parameter which is used to look up the translated string in the current language's language file. the default value can also be passed which is used if the p cannot be found.

6.1.1. Example Top

{exp:lg_ml:translate key="welcome_message" default="Hello"}

6.2. Translate weblog entries Top

Another approach to managing translations is to attach language-specific custom fields to your weblogs. The basic concept is that users will be able to open a single weblog entry to edit all translations for that entry, and the correct translation will be dynamically extracted by the template at render time.

This approach does not require entries in the language files, as the translated content is stored in the weblog entries themselves.

6.2.1. Create custom fields for each language Top

The preferred method of entering multiple language data is to use a multiple custom fields in a single entry.

1. Create a new weblog called "Blog"
2. Create a new custom field group with the following two custom fields and assign it to a weblog:
   1. English content:
      • Title: English Body
      • Short name: body_en
      • Instructions: English content for the entry.
   2. French content:
      • Title: French Body
      • Short name: body_fr
      • Instructions: French content for the entry.
3. Assign the custom field group to the "Blog" weblog
4. Publish a new entry adding both English and French content

6.2.2. Displaying language specific content Top

In your templates (inside a {exp:weblog:entries} tag, you can display language specific custom fields by using global variables inside template tags like so:

{exp:weblog:entries}
    {if lg_lang == "en"}{title}{if:else}{title_{lg_lang}}
    {summary_{lg_lang}}
    {body_{lg_lang}}
{exp:weblog:entries}

When the template is compiled for display, {lg_lang} will be replaced with the current language ID before any other template parsing. For example: If the user was accessing the page via:

http://HOST_URL/en/some-page/

{body_{lg_lang}} would become {body_en} in your template, resulting in the content of the weblog field of the same name being output.

7. Change Log Top

7.1. 1.1.0 Top

• Changed the location for all language files to match ExpressionEngine defaults
• Changed the "p" parameter to "key"
• Added "default" parameter (optional) incase the key is not found
• Tweaked URL parsing - only first sub-domain and url segment are considered when matching languages
• Updated documentation with more examples

7.2. 1.0.0 Top

• Initial Release

8. License Top

LG Multi Language is a commercial product and therefore its usage is subject to the commercial license agreement.