Language Packs

Jadu Language Packs provide a set of classes and methods for managing hard-coded text in Galaxy sites in multiple languages.

Language Packs are managed via Continuum CMS. Each Language Pack is a collection of key / value pairs. Hard-coded site text on the site is replaced with a Language Pack key lookup in order to load text in the required language.

For example, on the News page, the hard-coded heading “Latest News” would be replaced with a Language Pack lookup for the key “news-heading” in the site’s assigned Language Pack.

Using Language Packs

In order to make Language Packs available to a script, add the following include statement:

require_once(“Language/Main.php”);

This file will include all of the necessary PHP class files.

Selecting a Language Pack

In the standard Galaxies templates this is done automatically within the include includes/language.php.

In order to get a list of all available Language Packs, first create an instance of the the DataMapper class. There is a static helper function available for this:

$dataMapper = Jadu_Language_DataMapper_Pack::getDefaultInstance($mainDB, $db);

$mainDB is an ADOdb connection to the Continuum CMS site, $db is an ADOdb connection to the site currently being accessed. These may be the same object.

The DataMapper can then be used to list all Language Packs in the database:

$allLanguagePacks = $dataMapper->getAll();

Methods are also available for retrieving Language Packs mapped to specific Galaxies Sites. See the API documentation for more details.

Entry Overriding

Entries can be added to the Continuum CMS database and the Galaxies site database. Entries found in the Galaxies site database will override entries with the same key in the Continuum CMS database.

Using Language Pack Entries

Entries should be accessed via the methods of the Jadu_Language_Pack class: getText() and getUnencodedText(). These methods will handle entry overriding and character conversion correctly. The two methods work in the same way and have identical signatures, however as the name suggests, getUnencodedText() does not encode HTML entities on the entry before returning it. getUnencodedText() should only be used if the text is not being output to an HTML document, if the HTML entity encoding will happen later on or if the value of the entry contains HTML markup.

The examples below all use getText() but getUnencodedText() could be used as a direct replacement if required.

Basic usage

Example: loading the News header:

<h2><?php print $lang->getText(“news-heading”); ?></h2>

The line above will retrieve the value mapped to the key “news-heading” from the currently selected Language Pack. Output for the English Language Pack may look like this:

<h2>Latest News</h2>

Dynamic entries

The second parameter of getText() allows an array of arguments to be passed in to be used by the entry. Example - using the current category name in the News header:

<h2><?php print $lang->getText(“news-category-heading”, array(“Business”)); ?></h2>

The text “Business” will be inserted into the value for the key “news-category-heading”. Output might look like this:

<h2>Business News</h2>

The position of the argument within the text is controlled by a placeholder. In the example above, the entry has the following value:

“%1$s News”

Please note: All arguments in the array should have HTML entities encoded before they are passed to getText() as they will not be encoded as part of the return value.

Inserting multiple values

When multiple arguments are used, the number in the placeholder maps to the argument’s index.

Example - passing multiple arguments to getText() for News metadata:

<meta name="Description" content="<?php print
    $lang->getText(
        'news-category-metadata-description',
        array(“My Web Site”, “Business”));?>" />

Output:

<meta name="Description" content="My Web Site - latest news regarding Business" />

Entry value:

%1$s - latest news regarding %2$s

The comments field in the entry should be used to document what values should be used for each argument.

Internally,getText() uses vsprintf(), documentation for which is available in the PHP manual http://php.net/manual/en/function.vsprintf.php.

Plurals

Each Language Pack entry is able to store two values, a singular and a plural version. If the plural value is populated, the third parameter of getText() determines whether singular or plural is used. If the value is 1, the singular value is returned, otherwise the plural version.

Example - number of News Articles:

<h2><?php print $pack->getText(
        “news-num-articles”,
        array(count($newsArticles)), count($newsArticles));?></h2>

Output - 1 News Article:

<h2>There is 1 News Article available</h2>

Output - 2 News Articles:

<h2>There are 2 News Article available</h2>

Singular value:

“There is %1$d News Article available”

Plural value:

“There are %1$d News Articles available”

The number of News Articles needs to be passed twice, once to be used in the output text and once to register the count to determine the singular / plural selection.

results matching ""

    No results matching ""