People, who write feature rich AJAX applications, that access the server mainly for database content, will come to the point,
where they need internationalized and localized content. especially when one writes interfaces in different languages.
what one needs is a basic access to POSIX-style date and currency formats, country-, script- and currency-names. fortunately
there are already many organisations and sources out there that can be used to derive a comprehensive JS-class with only
one purpose: internationalizing and localizing ones programs.
jsL10N, or shorthand $L, tries to provide all the necessary information one needs to make interfaces in at least 264 languages
possible and easy to develop. the system is intended to be small and fast. the informations provided are derived from the
Unicode CLDR Project,
The Open Group Base Specifications Issue 6 - IEEE Std 1003.1,
Debian ISO-codes,
X11 locale.alias,
Tags for Identifying Languages (draft-ietf-ltru-registry-14)
and many more.
at the moment following informations are provided in detail: ISO 639, ISO 3166, ISO 3166-2 (partly), UN M.49, ISO 4217, ISO 15924 and POSIX.
jsL10N can be downloaded here. if some of the links are dead, please contact the author or visit handgestrickt netzwerk.
For the people who cannot wait to see $L in action here is some really short example:
<script language="JavaScript" type="text/javascript" src="jsL10N.js"></script>
<script language="JavaScript" type="text/javascript">
$L.init();
alert($L.iso639('en'));
alert($L.iso3166('us'));
alert($L.strftime('%x %X'));
$L.each('posix',function(key) {
alert(key+': '+$L.posix(key));
});
</script>
The first line initializes $L with the default values 'en-us' as the "from"-language and the browsers language as the
"to"-language.
Line 2 outputs the string representation of the ISO 639 code 'en' in the "to"-language.
Line 3 outputs the string representation of the ISO 3166 code 'us' in the "to"-language.
Line 4 outputs the current date and time with the given POSIX format in the "to"-language.
Line 5-7 output the keys and values of all POSIX-entries in the "to"-language.
The following list will explain all functions in the JavaScript-file in detail and give examples on how to use them. the syntax
is the same as in the PHP-documentation. means the return type is always given and optional arguments are in square brackets.
the most basic and important functions are mentioned on top. the helper function that users rarely use are at the bottom.
The auhtor of this examples assumes, that one is using a common AJAX-framework, so $() is used as a shorthand for
document.getElementById().
for better understanding a list of what the specifications mean is provided here:
modern AJAX-frameworks often make use of shorthands. for people who like the quick and simple usage, jsL10N also provides such a shorthand, called $L. Note: jsL10N and $L are the same. one can always exchange them. example:
var foo = $L.iso639('en');
var bar = jsL10N.iso639('en');the results of both variables are absolutely identical.
config is the one and only property that jsL10N provides. here you can set all user configurations.
$L.config = {
from: 'de-de',
to: 'fr-fr'
};
$L.config = {
from: '<?php echo $_GET['from']; ?>',
to: '<?php echo $_GET['to']; ?>'
};the example sets german as the "from"-language and french as the "to"-language. the second example shows a way to do it in PHP.
void $L.init()
initializes jsL10N. if no configurations were made by the user, it provides default values.
$L.init();
$L.config = {
from: 'de-de',
to: 'fr-fr'
};
$L.init();the first example inits jsL10N using default values. the second example sets german as the "from"-language and french as the "to"-language, then initializes jsL10N.
string $L.iso639(iso639_code[,to_language])
returns the string representation of the given ISO 639 code value in the "to"-language. if "to"-language
is not given, it takes the configuration "to"-language. returns a string on success, otherwise boolean false.
alert($L.iso639('en','fr-fr'));returns the english language name value in french.
string $L.iso3166(iso3166_code[,to_language])
returns the string representation of the given ISO 3166 code value in the "to"-language. if "to"-language
is not given, it takes the configuration "to"-language. returns a string on success, otherwise boolean false.
alert($L.iso3166('us','de-de'));returns the USA region name value in german.
string $L.unm49(unm49_number[,to_language])
returns the string representation of the given UN M.49 number code value in the "to"-language. if "to"-language
is not given, it takes the configuration "to"-language. returns a string on success, otherwise boolean false.
alert($L.unm49(3,'zh-cn'));returns the North American region number code value in chinese (mandarin).
string $L.iso3166_2(iso3166_2_code,[iso3166_2_code,[,to_language]])
returns the string representation of the given ISO 3166-2 code value in the "to"-language. this method can be called
in two modes. the first is, that you pass by two pieces of the ISO 3166-2 code. the second on is, that you pass a combined
ISO 3166-2 code (combined by a minus or an underscore) and leave the second argument empty (boolean false). if "to"-language
is not given, it takes the configuration "to"-language. returns a string on success, otherwise boolean false.
alert($L.iso3166_2('de','nw','fr-fr'));
alert($L.iso3166_2('de-nw',false,'fr-fr'));
alert($L.iso3166_2('de_nw',false,'fr-fr'));all 3 examples return the german 'Nordrhein-Westfalen' sub-region code value in french.
string $L.iso15924(iso15924_code[,to_language])
returns the string representation of the given ISO 15924 code value in the "to"-language. if "to"-language
is not given, it takes the configuration "to"-language. returns a string on success, otherwise boolean false.
alert($L.iso15924('arab','ru-ru'));returns the arabian script code value in russian.
string $L.iso4217(iso4217_code[,to_language])
returns the string representation of the given ISO 4217 code value in the "to"-language. if "to"-language
is not given, it takes the configuration "to"-language. returns a string on success, otherwise boolean false.
alert($L.iso4217('eur','zh-cn'));returns the euro currency code value in chinese (mandarin).
mixed $L.posix(posix_key[,to_language])
returns the string or array representation of the given POSIX key value in the "to"-language. if "to"-language
is not given, it takes the configuration "to"-language. returns a string or array on success, otherwise boolean false.
alert($L.posix('d_t_fmt','zh-cn'));
alert($L.posix('abmon','de-de'));the first example returns the date time format in chinese (mandarin). the second example returns an array of the abbreviated month names in german.
string $L.getLang(language_string[[from_language[,to_language]])
returns the string representation of the given language translated from the "from"-language to the
"to"-language. if "from"- and "to"-language are not given, it takes the configuration values.
returns a string on success, otherwise boolean false.
alert($L.getLang('Mittelhochdeutsch','de-de','zh-cn'));returns the chinese (mandarin) translation of the german language name for the german language.
string $L.getRegion(region_string_or_number[[from_language[,to_language]])
returns the string representation of the given region translated from the "from"-language to the
"to"-language. if "from"- and "to"-language are not given, it takes the configuration values.
returns a string on success, otherwise boolean false. note: it works with ISO 3166 and UN M.49.
alert($L.getRegion('Deutschland','de-de','fr-fr'));
alert($L.getRegion('Afrika','de-de','it-it'));the first example returns the french translation of the german language name for the german country (ISO 3166). the second example returns the italian translation of the german language name for the african continent (UN M.49).
string $L.getScript(script_string[[from_language[,to_language]])
returns the string representation of the given script translated from the "from"-language to the
"to"-language. if "from"- and "to"-language are not given, it takes the configuration values.
returns a string on success, otherwise boolean false.
alert($L.getScript('arabe','fr-fr','zh-cn'));returns the chinese (mandarin) translation of the french language name for the arabian script.
string $L.getCurr(currency_string[[from_language[,to_language]])
returns the string representation of the given currency translated from the "from"-language to the
"to"-language. if "from"- and "to"-language are not given, it takes the configuration values.
returns a string on success, otherwise boolean false.
alert($L.getCurr('Yen Giapponese','it-it','de-de'));returns the german translation of the itialian language name for the japanese yen.
string $L.getPosix(posix_string[[from_language[,to_language]])
returns the string representation of the given POSIX value translated from the "from"-language to the
"to"-language. if "from"- and "to"-language are not given, it takes the configuration values.
returns a string on success, otherwise boolean false.
alert($L.getPosix('domenica','it-it','fr-fr'));returns the french translation of the itialian language name for the day sunday.
string $L.getSubRegion(subregion_string[[from_language[,to_language]])
returns the string representation of the given subregion translated from the "from"-language to the
"to"-language. if "from"- and "to"-language are not given, it takes the configuration values.
returns a string on success, otherwise boolean false.
alert($L.getSubRegion('Hiroshima','de-de','ru-ru'));returns the russian translation of the german language name for the japanese subregion Hiroshima.
string Date.format(format_string)
this method() extends the Date-object by the ability to format a date conforming to strftime() and the
Open Group Specification for strftime().
takes the POSIX month and day names and default formats from the "to"-language in the configuration.
the following placeholder are allowed in the format string:
%a is replaced by the locale's abbreviated weekday name. %A is replaced by the locale's full weekday name. %b is replaced by the locale's abbreviated month name. %B is replaced by the locale's full month name. %c is replaced by the locale's appropriate date and time representation. %C is replaced by the century number (the year divided by 100 and truncated to an integer) as a decimal number [00-99]. %d is replaced by the day of the month as a decimal number [01,31]. %D same as %m/%d/%y. %e is replaced by the day of the month as a decimal number [1,31]; a single digit is preceded by a space. %h same as %b. %H is replaced by the hour (24-hour clock) as a decimal number [00,23]. %I is replaced by the hour (12-hour clock) as a decimal number [01,12]. %j is replaced by the day of the year as a decimal number [001,366]. %m is replaced by the month as a decimal number [01,12]. %M is replaced by the minute as a decimal number [00,59]. %n is replaced by a newline character. %p is replaced by the locale's equivalent of either a.m. or p.m. %r is replaced by the time in a.m. and p.m. notation; in the POSIX locale this is equivalent to %I:%M:%S %p. %R is replaced by the time in 24 hour notation (%H:%M). %S is replaced by the second as a decimal number [00,61]. %t is replaced by a tab character. %T is replaced by the time (%H:%M:%S). %u is replaced by the weekday as a decimal number [1,7], with 1 representing Monday. %U is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. %V is replaced by the week number of the year (Monday as the first day of the week) as a decimal number [01,53]. If the week containing 1 January has four or more days in the new year, then it is considered week 1. Otherwise, it is the last week of the previous year, and the next week is week 1. %w is replaced by the weekday as a decimal number [0,6], with 0 representing Sunday. %W is replaced by the week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0. %x is replaced by the locale's appropriate date representation. %X is replaced by the locale's appropriate time representation. %y is replaced by the year without century as a decimal number [00,99]. %Y is replaced by the year with century as a decimal number. %Z is replaced by the timezone name or abbreviation, or by no bytes if no timezone information exists. %% is replaced by %.
examples:
$L.config = {
from: 'de-de',
to: 'fr-fr'
};
var d = new Date();
alert(d.format('%x'));returns the date written the french way.
string $L.strftime(format_string[,timestamp_seconds])
formats a given timestamp by the format string. see the Date.format()-method for explanations of the
format string. if no timestamp is given, the current timestamp is taken.
alert($L.strftime('%x'));returns the date written the "to"-language way in the configuration.
void $L.each(type_string,callback_function)
executes the callback function for every value in the data arrays of the given type. type can be 'iso639', 'iso3166', 'unm49',
'iso3166_2', 'iso15924', 'iso4217' and 'posix'. the first argument passed to the callback function is the key of the data
arrays current element. if the type is 'iso3166_2' a second argument is passed, which is the subkey of the region.
$L.each('posix',function(key) {
alert(key+': '+$L.posix(key));
});
$L.each('iso3166_2',function(key1,key2) {
alert(key1+'-'+key2+': '+$L.iso3166_2(key1,key2,'zh-cn'));
});the first example returns all POSIX keys and values for the "to"-language in the configuration. the second example returns all ISO 3166-2 sub-regions in chinese (mandarin).
string $L.searchIndex(type_string,code_or_number[,to_language])
this is a helper method for the methods iso639(), iso3166(),
unm49(), iso3166_2(), iso15924(),
iso4217() and posix(). it searches the index for the given type until it finds
the given code or number and returns the "to"-language representation. type can be 'iso639', 'iso3166', 'unm49',
'iso3166_2', 'iso15924', 'iso4217' and 'posix'. if "to"-language is not given, it takes the configuration
"to"-language. returns a string on success, otherwise boolean false.
alert($L.searchIndex('iso639','en','ru-ru'));returns the russian translation of the english language name.
string $L.searchInData(type_string,from_string[,from_language[,to_language]])
this is a helper method for the methods getLang(), getRegion(),
getScript(), getCurr(), getPosix() and
getSubRegion(). it searches the "from"-language data for the given type until it finds
the given code or number and returns the "to"-language representation. type can be 'iso639', 'iso3166', 'unm49',
'iso3166_2', 'iso15924', 'iso4217' and 'posix'. if "from"- and "to"-language are not given,
it takes the configuration values. returns a string on success, otherwise boolean false.
alert($L.searchInData('iso639','Mittelhochdeutsch','de-de','it-it'));returns the italian translation of the german language name.
array $L.split3166_2(iso3166_2_code)
this is a helper method for the methods iso3166_2() and getSubRegion(). it
takes a combined ISO 3166-2 code and splits it by minus or underscore. returns an array on success, otherwise boolean false.
var pieces = $L.split3166_2('de-nw');
alert(pieces[0]);
alert(pieces[1]);returns the combined ISO 3166-2 code for germanies 'Nordrhein Westfalen', split into 2 pieces.
string $L.browserLang()
this is a helper method for the init()-method. it tries to find out which language settings have been
made in the browser. if a combined locale-alias (ISO 639, minus-sign, ISO 3166) is not found, it tries to guess the language
with the guessLang()-method. returns a string on success, otherwise boolean false.
string $L.guessLang()
this is a helper method for the browserLang()-method. it tries to find out combined locale-alias
(ISO 639, minus-sign, ISO 3166) by a given ISO 639 code. returns a string on success, otherwise boolean false.
boolean $L.isTypeOf(type[,value[,value[,value...]]])
this method checks the type for every given value. returns true on success, otherwise boolean false.
string $L._pad(number,length)
this is a helper method for the Date.format()-method. it pads a given string to a length,
filling with zeros.
jsL10N was written by Stefan Jelner/handgestrickt netzwerk <info@handgestrickt.biz> in 2007. if you have any questions or comments, feel free to send me a message.
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Contact information: Stefan Jelner