Sep 2009 11

jQuery.i18n.properties

Project page has moved!

The project page for the jQuery.i18n.properties plugin is now located at:
http://code.google.com/p/jquery-i18n-properties

Due to lack of resources, the plugin has received little or no attention lately… If you would like to volunteer by helping on the plugin development, please contact me to become a project committer!

The page below is now locked for editing and commenting, and will be kept here only for historic purposes. Please use the new project page for creating issues, providing feedback, etc…


About


jQuery.i18n.properties is a lightweight jQuery plugin for providing internationalization to javascript from ‘.properties’ files, just like in Java Resource Bundles. It loads and parses resource bundles (.properties) based on provided language and country codes (ISO-639 and ISO-3166) or language reported by browser.


Resource bundles are ‘.properties‘ files containing locale specific key-value pairs. The use of ‘.properties‘ files for translation is specially useful when sharing i18n files between Java and JavaScript projects. This plugin loads the default file (eg, Messages.properties) first and then locale specific files (Messages_pt.properties, then Messages_pt_PT.properties), so that a default value is always available when there is no translation provided. Translation keys will be available to developer as javascript variables/functions (functions, if translated value contains substitutions (eg, {0}) or as a map.


This plugin was inspired on the Localisation assistance for jQuery from Keith Wood, and is made available under a dual license (GPL and MIT).



Features


  • Use Java standard ‘.properties‘ files for translations
  • Use standard ISO-639 for language code and ISO-3166 for country code
  • Sequential loading of resource bundles from base language to user-specified/browser-specified so there is always a default value for an untranslated string (eg: msg.properties, msg_pt.properties, msg_pt_PT.properties)
  • Use browser reported language if no language was specified
  • Placeholder substitution in resource bundle strings (eg, msg_hello = Hello {0}!!)
  • Suport for namespaces in keys (eg, com.company.msgs.hello = Hello!)
  • Support for multi-line property values
  • Resource bundle keys available as Javascript vars/functions or as a map



Example


Take as an example the following Messages.properties, Messages_pt.properties and Messages_pt_PT.properties:

Messages.properties
1
2
3
4
# This line is ignored by the plugin
msg_hello = Hello
msg_world = World
msg_complex = Good morning {0}!
Messages_pt.properties
1
2
# We only provide a translation for the 'msg_hello' key
msg_hello = Bom dia
Messages_pt_PT.properties
1
2
# We only provide a translation for the 'msg_hello' key
msg_hello = Olá

Now, suppose these files are located on the ‘bundle/‘ folder. One can invoke the plugin like below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// This will initialize the plugin
// and show two dialog boxes: one with the text "Olá World"
// and other with the text "Good morning John!"
jQuery.i18n.properties({
    name:'Messages',
    path:'bundle/',
    mode:'both',
    language:'pt_PT',
    callback: function() {
        // We specified mode: 'both' so translated values will be
        // available as JS vars/functions and as a map

        // Accessing a simple value through the map
        jQuery.i18n.prop('msg_hello');
        // Accessing a value with placeholders through the map
        jQuery.i18n.prop('msg_complex', ['John']);

        // Accessing a simple value through a JS variable
        alert(msg_hello +' '+ msg_world);
        // Accessing a value with placeholders through a JS function
        alert(msg_complex('John'));
    }
});

This will initialize the plugin (loading bundle files and parsing them) and show a dialog box with the text “Olá World” and other with “Good morning John!”. The english word “World” is shown because we didn’t provide a translation for the msg_world key. Also notice that keys are available as a map and also as javascript variables (for simple strings) and javascript functions (for strings with placeholders for substitution).



Usage

Options

Option Description Notes
name Partial name (or names) of files representing resource bundles (eg, ‘Messages’ or ['Msg1','Msg2']) Required
String or String[]
language ISO-639 Language code and, optionally, ISO-3166 country code (eg, ‘en’, ‘en_US’, ‘pt_PT’). If not specified, language reported by the browser will be used instead. Optional
String
path Path to directory that contains ‘.properties‘ files to load. Optional
String
mode Option to have resource bundle keys available as Javascript vars/functions OR as a map. The ‘map’ option is mandatory if your bundle keys contain Javascript Reserved Words. Possible options: ‘vars’ (default), ‘map’ or ‘both’ Optional
String
callback Callback function to be called uppon script execution completion. Optional
function()

Including and invoking the plugin

  1. Load the script:
    1
    2
    <script type="text/javascript" language="JavaScript"
      src="js/jquery.i18n.properties-min.js"></script>
  2. Initialize the plugin (minimal usage, will use language reported by browser), and access a translated value (assuming a key named ‘org.somekey‘ exists):
    1
    2
    3
    4
    jQuery.i18n.properties({
      name: 'Messages',
      callback: function(){ alert( org.somekey ); }
    });



Demo

See a small demonstration



Download


1.0.8  [2010-07-09]



Change Log


1.0.8  [2010-07-09]
  • Fixed IE bug caused by the MS buggy implementation of String.split() method
1.0.7  [2010-06-09]
  • Added support for multi-line properties
  • Prevent browser caching of old property files
1.0.6  [2010-03-28]
  • Fixed checkKeyNamespace issue (FF only)
  • Fixed issue that truncated values when containing ‘=’ symbol
  • Added demo page
1.0.4  [2009-12-29]
  • When using the map approach to retrieve bundle values, unicode chars may not be properly unescaped
1.0.3  [2009-10-06]
  • When using the map approach to retrieve bundle values, if there’s no value for a specified key, key is returned (previously, null was returned)
  • Fixed lot of errors accordingly to JSLint
1.0.2  [2009-09-18]
  • Option to have resource bundle keys available as Javascript vars/functions AND/OR as a map. The later is mandatory if your bundle keys contain Javascript reserved words
1.0.1  [2009-09-14]



Known issues


  • Cross-site requests not allowed (see Same Origin policy).
  • Local file requests (file://) may fail in some browsers (Chrome Issue 40787)
  • Having HTML elements with IDs equal to key values in .properties files will fail on some browsers (IE, Chrome) when values are not accessed through jQuery.i18n.prop() method.
    Example:

    1
    2
    3
    4
      <!-- on HTML file: -->
      <div id="test123">ola</div>
      # on .properties file:
      test123 = qwerty

    Executing “alert(test123);” will output the div object with id “ola” and not the “qwerty” string!

  1. Matthew Lohbihler

    Note that the behaviour of this plug-in is not quite like resource bundles in Java. (I’m assuming that this is the goal.) In particular, single quotes are used to escape { and }. Also, double quotes end up with a preceding “\” character. For example, if your properties are:

    test.t1=asdf ”{0}”
    test.t2=asdf ‘{0}’
    test.t5=This is “a quote”

    … Java will produce:

    asdf ‘p1′
    asdf {0}
    This is “a quote”

    … while this plugin will produce:

    asdf ”p1”
    asdf ‘p1′
    This is \”a quote\”

    This plugin is so very useful when used with a Java server, so it would be wonderful if these discrepancies could be resolved.