org.apache.cocoon.sax.component
Class I18nTransformer

java.lang.Object
  org.apache.cocoon.pipeline.component.AbstractPipelineComponent
      org.apache.cocoon.sax.AbstractSAXPipelineComponent
          org.apache.cocoon.sax.AbstractSAXProducer
              org.apache.cocoon.sax.AbstractSAXTransformer
                  org.apache.cocoon.sax.component.I18nTransformer

All Implemented Interfaces:

CachingPipelineComponent, Consumer, PipelineComponent, Producer, SAXConsumer, SAXPipelineComponent, SAXProducer, ContentHandler, LexicalHandler

public class I18nTransformer
extends AbstractSAXTransformer
implements CachingPipelineComponent

Internationalization transformer is used to transform i18n markup into text based on a particular locale.

Overview

The i18n transformer works by finding a translation for the user's locale in the passed resource bundles ResourceBundle. Locale is passed as parameter to the transformer.

For the passed local it then attempts to find a resource bundle that satisfies the locale, and uses it for for processing text replacement directed by i18n markup.

Usage

Files to be translated contain the following markup:

 <?xml version="1.0"?>
 ... some text, translate <i18n:text>key</i18n:text>
 

At runtime, the i18n transformer will find a resource bundle for the user's locale, and will appropriately replace the text between the <i18n:text> markup, using the value between the tags as the lookup key.

Pipeline Usage

To use the transformer in a pipeline, simply specify it in a particular transform, and pass locale, bundle and (optional) untranslated parameters:

 <map:match pattern="file">
   <map:generate src="file.xml"/>
   <map:transform type="i18n">
     <map:parameter name="locale" value="..."/>
     <map:parameter name="bundle" value="..."/>
     <map:parameter name="untranslated" value="..."/>
   </map:transform>
   <map:serialize/>
 </map:match>
 

i18n markup

For date, time and number formatting use the following tags:

• <i18n:date/> gives localized date.
• <i18n:date-time/> gives localized date and time.
• <i18n:time/> gives localized time.
• <i18n:number/> gives localized number.
• <i18n:currency/> gives localized currency.
• <i18n:percent/> gives localized percent.

Elements date, date-time and time accept pattern and src-pattern attribute, with values of:

• short
• medium
• long
• full

See DateFormat for more info on these values.

Elements date, date-time, time and number, a different locale and source-locale can be specified:

 <i18n:date src-pattern="short" src-locale="en_US" locale="de_DE">
   12/24/11
 </i18n:date>
 

Will result in 24.12.2011.

A given real pattern and src-pattern (not keywords short, medium, long, full) overrides any value specified by locale and src-locale attributes.

Nested Class Summary

static class

I18nTransformer.CustomEncodingControl Support for custom encodings in bundle files.

Field Summary

static String	ATTR_ATTR This attribute is used with any element (even not i18n) to translate attribute values.
static String	ATTR_CURRENCY This attribute is used to specify a different locale for the currency.
static String	ATTR_EXPR This attribute is used with any element (even not i18n) to evaluate attribute values.
static String	ATTR_FRACTION_DIGITS fraction-digits attribute is used with i18:number to indicate the number of digits behind the fraction
static String	ATTR_LOCALE This attribute is used with date and number formatting elements to indicate the locale that should be used to format the element value.
static String	ATTR_PARAM_NAME This attribute affects a name to the param that could be used for substitution.
static String	ATTR_PATTERN This attribute is used with date and number formatting elements to indicate the pattern that should be used to format the element value.
static String	ATTR_SRC_LOCALE This attribute is used with date and number formatting elements to indicate the locale that should be used to parse the element value.
static String	ATTR_SRC_PATTERN This attribute is used with date and number formatting elements to indicate the pattern that should be used to parse the element value.
static String	ATTR_TYPE This attribute is used with number formatting elements to indicate the type of formatting (currency | int-currency | percent | ...)
static String	ATTR_VALUE This attribute is used with date and number formatting elements to indicate the value that should be parsed and formatted.
static String	DEFAULT_ENCODING The default encoding of the resource bundle files.
static String	DEFAULT_NAMESPACE The namespace for XML elements inside messages.
static String	ELEM_CHOOSE i18n:choose element is used to translate elements in-place.
static String	ELEM_CURRENCY Currency element name
static String	ELEM_CURRENCY_NO_UNIT Currency without unit element name
static String	ELEM_DATE i18n:date is used to provide a localized date string.
static String	ELEM_DATE_TIME i18n:date-time is used to provide a localized date and time string.
static String	ELEM_IF i18n:if is used to test a locale.
static String	ELEM_INT_CURRENCY Integer currency element name
static String	ELEM_INT_CURRENCY_NO_UNIT Integer currency without unit element name
static String	ELEM_NUMBER i18n:number is used to provide a localized number string.
static String	ELEM_OTHERWISE i18n:otherwise is used to match any locale when no matching locale has been found inside an i18n:choose block.
static String	ELEM_PARAM i18n:param is used with i18n:translate to provide substitution params.
static String	ELEM_PERCENT Percent element name
static String	ELEM_TEXT i18n:text element is used to translate any text, with or without markup.
static String	ELEM_TIME i18n:time is used to provide a localized time string.
static String	ELEM_TRANSLATE i18n:translate element is used to translate text with parameter substitution.
static String	ELEM_WHEN i18n:when is used to test a locale.
static String	KEY_ATTR This attribute is used with i18n:text element to indicate the key of the according message.
static String	NS_I18N
static String	PARAM_BUNDLE This configuration parameter specifies the resource bundle's name to be used.
static String	PARAM_ENCODING The encoding of the resource bundle files.
static String	PARAM_LOCALE This configuration parameter specifies the default locale to be used.
static String	PARAM_PARSE_NAMESPACE The namespace for XML elements inside messages.
static String	PARAM_PARSE_XML If XML inside i18n messages shall be parsed.
static String	PARAM_UNTRANSLATED This configuration parameter specifies the message that should be displayed in case of a not translated text (message not found).

Constructor Summary

I18nTransformer()
Empty constructor, for usage with sitemap.

I18nTransformer(Locale locale, String bundle)

I18nTransformer(Locale locale, String bundle, String untranslated)

I18nTransformer(Locale locale, String bundle, String untranslated, String encoding)

I18nTransformer(String bundle)

Method Summary

void	characters(char[] chars, int start, int len)
CacheKey	constructCacheKey()
void	endElement(String uri, String name, String raw)
Locale	parseLocale(String localeString) Parses given locale string to Locale object.
void	setConfiguration(Map<String,? extends Object> configuration) Pass component specific configuration parameters to the pipeline component in a generic way.
void	setParseNamespace(String parseNamespace)
void	setParseXml(boolean parseXml)
void	setup(Map<String,Object> parameters) The shared object map for this pipeline run.
void	startElement(String uri, String name, String raw, Attributes attr)

Methods inherited from class org.apache.cocoon.sax.AbstractSAXTransformer

comment, endCDATA, endDocument, endDTD, endEntity, endPrefixMapping, endSAXRecording, endTextRecording, findPrefixMapping, ignorableWhitespace, processingInstruction, removeRecorder, sendEndPrefixMapping, sendStartPrefixMapping, setDocumentLocator, setRecorder, skippedEntity, startCDATA, startDocument, startDTD, startEntity, startPrefixMapping, startSAXRecording, startTextRecording

Methods inherited from class org.apache.cocoon.sax.AbstractSAXProducer

getSAXConsumer, setConsumer, setSAXConsumer, toString

Methods inherited from class org.apache.cocoon.pipeline.component.AbstractPipelineComponent

finish

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.cocoon.pipeline.component.PipelineComponent

finish

Field Detail

NS_I18N

public static final String NS_I18N

See Also:

Constant Field Values

ELEM_TEXT

public static final String ELEM_TEXT

i18n:text element is used to translate any text, with or without markup. Example:

   <i18n:text>
     This is <strong>translated</strong> string.
   </i18n:text>
 

See Also:

Constant Field Values

ELEM_TRANSLATE

public static final String ELEM_TRANSLATE

i18n:translate element is used to translate text with parameter substitution. Example:

 <i18n:translate>
   <i18n:text>This is translated string with {0} param</i18n:text>
   <i18n:param>1</i18n:param>
 </i18n:translate>
 

The i18n:text fragment can include markup and parameters at any place. Also do parameters, which can include i18n:text, i18n:date, etc. elements (without keys only).

See Also:

ELEM_TEXT, ELEM_PARAM, Constant Field Values

ELEM_CHOOSE

public static final String ELEM_CHOOSE

i18n:choose element is used to translate elements in-place. The first i18n:when element matching the current locale is selected and the others are discarded.

To specify what to do if no locale matched, simply add a node with locale="*". Note that this element must be the last child of <i18n:choose>.

 <i18n:choose>
   <i18n:when locale="en">
     Good Morning
   </en>
   <i18n:when locale="fr">
     Bonjour
   </jp>
   <i18n:when locale="jp">
     Aligato?
   </jp>
   <i18n:otherwise>
     Sorry, i don't know how to say hello in your language
   </jp>
 <i18n:translate>
 

You can include any markup within i18n:when elements, with the exception of other i18n:* elements.

Since:

2.1

See Also:

ELEM_IF, ATTR_LOCALE, Constant Field Values

ELEM_WHEN

public static final String ELEM_WHEN

i18n:when is used to test a locale. It can be used within i18:choose elements or alone. Note: Using locale="*" here has no sense. Example:

 <greeting>
   <i18n:when locale="en">Hello</i18n:when>
   <i18n:when locale="fr">Bonjour</i18n:when>
 </greeting>
 

Since:

2.1

See Also:

ATTR_LOCALE, ELEM_CHOOSE, Constant Field Values

ELEM_IF

public static final String ELEM_IF

i18n:if is used to test a locale. Example:

 <greeting>
   <i18n:if locale="en">Hello</i18n:when>
   <i18n:if locale="fr">Bonjour</i18n:when>
 </greeting>
 

Since:

2.1

See Also:

ATTR_LOCALE, ELEM_CHOOSE, ELEM_WHEN, Constant Field Values

ELEM_OTHERWISE

public static final String ELEM_OTHERWISE

i18n:otherwise is used to match any locale when no matching locale has been found inside an i18n:choose block.

Since:

2.1

See Also:

ELEM_CHOOSE, ELEM_WHEN, Constant Field Values

ELEM_PARAM

public static final String ELEM_PARAM

i18n:param is used with i18n:translate to provide substitution params. The param can have i18n:text as its value to provide multilingual value. Parameters can have additional attributes to be used for formatting:

• type: can be date, date-time, time, number, currency, currency-no-unit or percent. Used to format params before substitution.
• value: the value of the param. If no value is specified then the text inside of the param element will be used.
• locale: used only with number, date, time, date-time types and used to override the current locale to format the given value.
• src-locale: used with number, date, time, date-time types and specify the locale that should be used to parse the given value.
• pattern: used with number, date, time, date-time types and specify the pattern that should be used to format the given value.
• src-pattern: used with number, date, time, date-time types and specify the pattern that should be used to parse the given value.

See Also:

ELEM_TRANSLATE, ELEM_DATE, ELEM_TIME, ELEM_DATE_TIME, ELEM_NUMBER, Constant Field Values

ATTR_PARAM_NAME

public static final String ATTR_PARAM_NAME

This attribute affects a name to the param that could be used for substitution.

Since:

2.1

See Also:

Constant Field Values

ELEM_DATE

public static final String ELEM_DATE

i18n:date is used to provide a localized date string. Allowed attributes are: pattern, src-pattern, locale, src-locale. Usage examples:

  <i18n:date src-pattern="short" src-locale="en_US" locale="de_DE">
    12/24/01
  </i18n:date>

  <i18n:date pattern="dd/MM/yyyy" />
 

If no value is specified then the current date will be used. E.g.:

   <i18n:date />
 

Displays the current date formatted with default pattern for the current locale.

See Also:

ELEM_PARAM, ELEM_DATE_TIME, ELEM_TIME, ELEM_NUMBER, Constant Field Values

ELEM_DATE_TIME

public static final String ELEM_DATE_TIME

i18n:date-time is used to provide a localized date and time string. Allowed attributes are: pattern, src-pattern, locale, src-locale. Usage examples:

  <i18n:date-time src-pattern="short" src-locale="en_US" locale="de_DE">
    12/24/01 1:00 AM
  </i18n:date>

  <i18n:date-time pattern="dd/MM/yyyy hh:mm" />
 

If no value is specified then the current date and time will be used. E.g.:

  <i18n:date-time />
 

Displays the current date formatted with default pattern for the current locale.

See Also:

ELEM_PARAM, ELEM_DATE, ELEM_TIME, ELEM_NUMBER, Constant Field Values

ELEM_TIME

public static final String ELEM_TIME

i18n:time is used to provide a localized time string. Allowed attributes are: pattern, src-pattern, locale, src-locale. Usage examples:

  <i18n:time src-pattern="short" src-locale="en_US" locale="de_DE">
    1:00 AM
  </i18n:time>

 <i18n:time pattern="hh:mm:ss" />
 

If no value is specified then the current time will be used. E.g.:

  <i18n:time />
 

Displays the current time formatted with default pattern for the current locale.

See Also:

ELEM_PARAM, ELEM_DATE_TIME, ELEM_DATE, ELEM_NUMBER, Constant Field Values

ELEM_NUMBER

public static final String ELEM_NUMBER

i18n:number is used to provide a localized number string. Allowed attributes are: pattern, src-pattern, locale, src-locale, type. Usage examples:

  <i18n:number src-pattern="short" src-locale="en_US" locale="de_DE">
    1000.0
  </i18n:number>

 <i18n:number type="currency" />
 

If no value is specifies then 0 will be used.

See Also:

ELEM_PARAM, ELEM_DATE_TIME, ELEM_TIME, ELEM_DATE, Constant Field Values

ELEM_CURRENCY

public static final String ELEM_CURRENCY

Currency element name

See Also:

Constant Field Values

ELEM_PERCENT

public static final String ELEM_PERCENT

Percent element name

See Also:

Constant Field Values

ELEM_INT_CURRENCY

public static final String ELEM_INT_CURRENCY

Integer currency element name

See Also:

Constant Field Values

ELEM_CURRENCY_NO_UNIT

public static final String ELEM_CURRENCY_NO_UNIT

Currency without unit element name

See Also:

Constant Field Values

ELEM_INT_CURRENCY_NO_UNIT

public static final String ELEM_INT_CURRENCY_NO_UNIT

Integer currency without unit element name

See Also:

Constant Field Values

KEY_ATTR

public static final String KEY_ATTR

This attribute is used with i18n:text element to indicate the key of the according message. The character data of the element will be used if no message is found by this key. E.g.:

 <i18n:text i18n:key="a_key">article_text1</i18n:text>
 

See Also:

Constant Field Values

ATTR_ATTR

public static final String ATTR_ATTR

This attribute is used with any element (even not i18n) to translate attribute values. Should contain whitespace separated attribute names that should be translated:

 <para title="first" name="article" i18n:attr="title name"/>
 

See Also:

Constant Field Values

ATTR_EXPR

public static final String ATTR_EXPR

This attribute is used with any element (even not i18n) to evaluate attribute values. Should contain whitespace separated attribute names that should be evaluated:

 <para title="first" name="{one} {two}" i18n:attr="name"/>
 

See Also:

Constant Field Values

ATTR_SRC_PATTERN

public static final String ATTR_SRC_PATTERN

This attribute is used with date and number formatting elements to indicate the pattern that should be used to parse the element value.

See Also:

ELEM_PARAM, ELEM_DATE_TIME, ELEM_DATE, ELEM_TIME, ELEM_NUMBER, Constant Field Values

ATTR_PATTERN

public static final String ATTR_PATTERN

This attribute is used with date and number formatting elements to indicate the pattern that should be used to format the element value.

See Also:

ELEM_PARAM, ELEM_DATE_TIME, ELEM_DATE, ELEM_TIME, ELEM_NUMBER, Constant Field Values

ATTR_LOCALE

public static final String ATTR_LOCALE

This attribute is used with date and number formatting elements to indicate the locale that should be used to format the element value. Also used for in-place translations.

See Also:

ELEM_PARAM, ELEM_DATE_TIME, ELEM_DATE, ELEM_TIME, ELEM_NUMBER, ELEM_WHEN, Constant Field Values

ATTR_SRC_LOCALE

public static final String ATTR_SRC_LOCALE

This attribute is used with date and number formatting elements to indicate the locale that should be used to parse the element value.

See Also:

ELEM_PARAM, ELEM_DATE_TIME, ELEM_DATE, ELEM_TIME, ELEM_NUMBER, Constant Field Values

ATTR_VALUE

public static final String ATTR_VALUE

This attribute is used with date and number formatting elements to indicate the value that should be parsed and formatted. If value attribute is not used then the character data of the element will be used.

See Also:

ELEM_PARAM, ELEM_DATE_TIME, ELEM_DATE, ELEM_TIME, ELEM_NUMBER, Constant Field Values

ATTR_TYPE

public static final String ATTR_TYPE

This attribute is used with number formatting elements to indicate the type of formatting (currency | int-currency | percent | ...)

See Also:

ELEM_NUMBER, Constant Field Values

ATTR_CURRENCY

public static final String ATTR_CURRENCY

This attribute is used to specify a different locale for the currency. When specified, this locale will be combined with the "normal" locale: e.g. the separator symbols are taken from the normal locale but the currency symbol and position will be taken from the currency locale. This enables to see a currency formatted for Euro but with US grouping and decimal char.

See Also:

Constant Field Values

ATTR_FRACTION_DIGITS

public static final String ATTR_FRACTION_DIGITS

fraction-digits attribute is used with i18:number to indicate the number of digits behind the fraction

See Also:

Constant Field Values

PARAM_LOCALE

public static final String PARAM_LOCALE

This configuration parameter specifies the default locale to be used.

See Also:

Constant Field Values

PARAM_BUNDLE

public static final String PARAM_BUNDLE

This configuration parameter specifies the resource bundle's name to be used.

See Also:

Constant Field Values

PARAM_UNTRANSLATED

public static final String PARAM_UNTRANSLATED

This configuration parameter specifies the message that should be displayed in case of a not translated text (message not found).

See Also:

Constant Field Values

PARAM_ENCODING

public static final String PARAM_ENCODING

The encoding of the resource bundle files.

See Also:

Constant Field Values

DEFAULT_ENCODING

public static final String DEFAULT_ENCODING

The default encoding of the resource bundle files.

See Also:

Constant Field Values

PARAM_PARSE_XML

public static final String PARAM_PARSE_XML

If XML inside i18n messages shall be parsed.

See Also:

Constant Field Values

PARAM_PARSE_NAMESPACE

public static final String PARAM_PARSE_NAMESPACE

The namespace for XML elements inside messages.

See Also:

Constant Field Values

DEFAULT_NAMESPACE

public static final String DEFAULT_NAMESPACE

The namespace for XML elements inside messages.

See Also:

Constant Field Values

Constructor Detail

I18nTransformer

public I18nTransformer()

Empty constructor, for usage with sitemap.

I18nTransformer

public I18nTransformer(String bundle)

I18nTransformer

public I18nTransformer(Locale locale,
                       String bundle)

I18nTransformer

public I18nTransformer(Locale locale,
                       String bundle,
                       String untranslated)

I18nTransformer

public I18nTransformer(Locale locale,
                       String bundle,
                       String untranslated,
                       String encoding)

Method Detail

setParseXml

public void setParseXml(boolean parseXml)

setParseNamespace

public void setParseNamespace(String parseNamespace)

setConfiguration

public void setConfiguration(Map<String,? extends Object> configuration)

Description copied from interface: PipelineComponent

Pass component specific configuration parameters to the pipeline component in a generic way. This is useful in environments that automatically assemble pipelines with their components and can't use the components constructors or setters.

Specified by:

setConfiguration in interface PipelineComponent

Overrides:

setConfiguration in class AbstractPipelineComponent

Parameters:

configuration - The Map of configuration parameters.

setup

public void setup(Map<String,Object> parameters)

Description copied from interface: PipelineComponent

The shared object map for this pipeline run.

Specified by:

setup in interface PipelineComponent

Overrides:

setup in class AbstractPipelineComponent

Parameters:

parameters - A Map of parameters that are available to all PipelineComponents. This is a modifiable map that can be changed by this pipeline component.

constructCacheKey

public CacheKey constructCacheKey()

Specified by:

constructCacheKey in interface CachingPipelineComponent

startElement

public void startElement(String uri,
                         String name,
                         String raw,
                         Attributes attr)
                  throws SAXException

Specified by:

startElement in interface ContentHandler

Overrides:

startElement in class AbstractSAXTransformer

Throws:

SAXException

endElement

public void endElement(String uri,
                       String name,
                       String raw)
                throws SAXException

Specified by:

endElement in interface ContentHandler

Overrides:

endElement in class AbstractSAXTransformer

Throws:

SAXException

characters

public void characters(char[] chars,
                       int start,
                       int len)
                throws SAXException

Specified by:

characters in interface ContentHandler

Overrides:

characters in class AbstractSAXTransformer

Throws:

SAXException

parseLocale

public Locale parseLocale(String localeString)

Parses given locale string to Locale object. If the string is null or empty then the given locale is returned.

Parameters:

localeString - - a string containing locale in language_country_variant format.

defaultLocale - - returned if localeString is null or ""