Overview

This component provides Localization of strings. It is written for use in Turbine but it can be used in any container compatible with Avalon's ECM container.

There two implementations

  • SimpleLocalizationService and
  • LocalizationService
The SimpleLocalizationService provides basic localization functions for generic applications whereas the LocalizationService adds support for web applications and depends on a servlet container environment.

SimpleLocalizationService

Role Configuration

    <role
        name="org.apache.fulcrum.localization.SimpleLocalizationService"
        shorthand="localization"
        default-class="org.apache.fulcrum.localization.SimpleLocalizationServiceImpl"/>

Component Configuration

Item Datatype Cardinality Description
localization@locale-default-language String [0|1] The default language to use if none is specified. If this attribute is absent, the JVM default language will be used.
localization@locale-default-country String [0|1] The default country to use if none is specified. If this attribute is absent, the JVM default country will be used.
bundles Complex [1] The list of configured bundles.
bundles/bundle String [1..n] The name of the bundle

Component Configuration Example

    <localization locale-default-language="en" locale-default-country="US">
      <bundles>
        <bundle>org.apache.fulcrum.localization.BarBundle</bundle>
        <bundle>org.apache.fulcrum.localization.FooBundle</bundle>
      </bundles>
    </localization>

LocalizationService

Role Configuration

    <role
        name="org.apache.fulcrum.localization.LocalizationService"
        shorthand="localization"
        default-class="org.apache.fulcrum.localization.DefaultLocalizationService"/>

Component Configuration

Item Datatype Cardinality Description
localization@locale-default-language String [0|1] The default language to use if none is specified. If this attribute is absent, the JVM default language will be used.
localization@locale-default-country String [0|1] The default country to use if none is specified. If this attribute is absent, the JVM default country will be used.
bundles Complex [1] The list of configured bundles.
bundles/bundle String [1..n] The name of the bundle (first one is default bundle)

Component Configuration Example

    <localization locale-default-language="en" locale-default-country="US">
      <bundles>
        <bundle>org.apache.fulcrum.localization.BarBundle</bundle>
        <bundle>org.apache.fulcrum.localization.FooBundle</bundle>
      </bundles>
    </localization>

Resource Bundles

Resource bundles are basically property files. You might have one for the "en" locale thus: 

    LABEL_ORGANIZATION = organisation
    CURRENT_RECORD = Record {0} of {1}

and another for the "en_US" locale thus: 

    LABEL_ORGANIZATION = organization

Please see the java.util.ListResourceBundle and java.util.ResourceBundle classes for more information.

Usage

    TurbineServices.getInstance().getService(LocalizationService.ROLE)
    .getString("DISPLAYPROJECTS_TITLE");

Wow. That is a lot of typing. In Turbine, that could be easily shortened to this: 

    Localization.getString("DISPLAYPROJECTS_TITLE");

The hard example above was given as an example of using Services. The easy example is the one that you really should be using. Another cool feature of the Localization class is that you can pass in a RunData object like this: 

    Localization.getString(data, "DISPLAYPROJECTS_TITLE");

This has the added effect of using the Accept-Language HTTP header to determine which language to display based on what setting the user has defined in the browser. Can you say Dynamic Localization? ;-)

The Localization class also supports the formatting of localized strings containing parameters, such as in 

    Localization.format(Localization.getDefaultBundle(), 
        Localization.getLocale(data.getRequest()),
        "CURRENT_RECORD",
        recno, all);

This actually doesn't look too nice, however the call using the Turbine LocalizationTool from a Velocity template just deflates to 

    $l10n.format("CURRENT_RECORD", $recno, $all);
    ## Other examples
    ## No arguments
    $l10n.LABEL_ORGANIZATION
    ## One argument
    $l10n.format("STRING_KEY_ONE_ARG" "arg1")
    ## Three or more arguments
    $l10n.format("STRING_KEY_3_OR_MORE_ARGS" ["arg1", "arg2", "arg3"])