Changes in Usage

Here are a few points to keep in mind while making the transition from cPanel's legacy language system to the Cpanel::Locale system.

Always use "lang" to refer to the legacy system
Deprecated tools
Calling the locale object
Legacy-style tags will be deprecated
Locale methods
Character sets
Calling the current locale name
Character orientation
The "You are not using a utf-8 language file" Error Message

Always use "lang" to refer to the legacy system

Use "locale" to refer to the new Cpanel::Locale system.

Deprecated tools

These are no longer in use; do not use them:

$Cpanel::Lang::LANG{$lang}{$key}
Cpanel::Lang
Cpanel::TieLang
Whostmgr::Lang
Anything with the term "lang" in it
Calls to /usr/local/cpanel/bin/cachelangfiles need to be changed to /usr/local/cpanel/bin/build_locale_databases
The 'charset' key (more information below)

Calling the locale object

The locale object is available to Cpanel::Template templates as the variable locale. The legacy system sometimes had a lang variable available which worked like this:

[% lang.arbitrary_legacy_style_tag_here %]

This would now be:

[% locale.maketext('arbitrary_legacy_style_tag_here') %]

Note: Essentially this is perl -pi -e 's{lang\.(\w+)}{locale.maketext(\"$1\")}g;' path/to/file

Legacy-style tags will be deprecated

Once we start using the new style, we won't use the legacy-style tags. The key will be the phrase:

[% locale.maketext('Hello World') %]

Locale methods

One nice thing about having locale available is that you have all the methods available for free:

<meta http-equiv="Content-Type" content="text/html;charset=[% locale.encoding() %]" />

Note: You could pass all the phrases as maketext() to the template, but that will take control away from the template. (For example, if you add, edit, or delete what it is saying, you'd have to update the caller to pass different arguments. This would defeat the purpose of a template.)

There should be little overhead to template processing, as it is only passing an object (essentially, a hashref), the object is a singleton, and the constructor is only called if it has not been called yet inside the Cpanel::Template package.

Character sets

Fetching the character set has changed. The legacy system had a key called 'charset'. That key should be avoided now, and in fact won't work. It was used to fetch the character encoding like so:

<cpanel langprint="charset"> or some version like $LANG{$lang}{'charset'}

The locale object has a method called encoding() that returns the current locale's character set (usually utf-8). An API2 call exists for it, which is formatted like so:

<?cp Locale::get_encoding(%,encoding) ?>

Calling the current locale name

You can get the current locale's name in its native tongue via:

<?cp Locale::get_locale_name(%,name) ?>

Character orientation

You can set the base character orientation via the dir attribute in the <html> tag. (This is recommended over using the <body> tag).

Using Template Toolkit markup, this would look like:

<html dir="[% locale.get_html_dir_attr() %]">

Using cPanel API2 tags, this would look like:

<html dir="<?cp Locale::get_html_dir_attr(%,dir) ?>">

Important: Either of these methods may return no data if given bad arguments.

If you need to change the base character orientation for a given string (such as locale menus or other mixed language pages), you can use the following code:

<bdo dir="[% locale.get_html_dir_attr(tag) %]">text in 'tag's language</bdo>

<option value="[% tag %]" dir="[% locale.get_html_dir_attr(tag) %]">

The "You are not using a utf-8 language file" Error Message

You should remove the following message from your custom themes:

You are not using a utf-8 language file. You should not save utf-8 data or you will get corrupted results.

This message was based on the name of the legacy language. (e.g. 'german' would trigger the message while 'german-utf8' would not) Since we have standardized naming and because your character set will almost certainly be utf-8, you should remove this message from your custom themes.

Topic revision: r7 - 28 Dec 2009 - 20:28:49 - Main.JustinSchaefer

CpanelLocale.LocaleUsage moved from Sandbox.LocaleUsage on 01 Oct 2009 - 19:39 by Main.JustinSchaefer - put it back