org.apache.cocoon.transformation
Class I18nTransformer

java.lang.Object
  |
  +--org.apache.avalon.framework.logger.AbstractLoggable
        |
        +--org.apache.cocoon.xml.AbstractXMLProducer
              |
              +--org.apache.cocoon.xml.AbstractXMLPipe
                    |
                    +--org.apache.cocoon.transformation.AbstractTransformer
                          |
                          +--org.apache.cocoon.transformation.I18nTransformer
All Implemented Interfaces:
org.apache.avalon.framework.component.Component, org.apache.avalon.framework.component.Composable, org.apache.avalon.framework.configuration.Configurable, org.xml.sax.ContentHandler, org.xml.sax.ext.LexicalHandler, org.apache.avalon.framework.logger.Loggable, org.apache.avalon.excalibur.pool.Poolable, org.apache.avalon.excalibur.pool.Recyclable, SitemapModelComponent, Transformer, XMLConsumer, XMLPipe, XMLProducer

public class I18nTransformer
extends AbstractTransformer
implements org.apache.avalon.framework.component.Composable, org.apache.avalon.excalibur.pool.Poolable, org.apache.avalon.framework.configuration.Configurable

Internationalisation transformer. Used to transform i18n markup into text based on a particular locale.

The i18n transformer works by obtaining the users locale via getLocale() in the LocaleAction. (@see org.apache.cocoon.acting.LocaleAction). It them attempts to find a message catalogue that satisifies the particular locale, and use it for for text replacement within i18n markup.

Catalogues are maintained in separate files, with a naming convention similar to that of ResourceBundle (@see java.util.ResourceBundle). ie. basename_locale, where basename can be any name, and locale can be any locale specified using ISO 639/3166 characters (eg. en_AU, de_AT, es).

Catalogues are of the following format:

 <?xml version="1.0"?>
 <!-- message catalogue file for locale ... -->

 <catalogue xml:lang="locale">
        <message key="key">text</message>
        ....
 </catalogue>
 
Where key specifies a particular message for that language.

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 message catalogue 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.

If the i18n transformer cannot find an appropriate message catalogue for the user's given locale, it will recursively try to locate a parent message catalogue, until a valid catalogue can be found. ie:

eg: Assuming a basename of messages and a locale of en_AU (no variant), the following search will occur: This allows the developer to write a hierarchy of message catalogues, at each defining messages with increasing depth of variation.

Sitemap configuration:

 <map:transformer name="i18n" src="org.apache.cocoon.transformation.I18nTransformer">
  <catalogue-name>messages</catalogue-name>
  <catalogue-location>translations</catalogue-location>
  <untranslated-text>untranslated</untranslated-text>
  <cache-at-startup>true</cache-at-startup>
 </map:transformer>
 

To use the transformer in a pipeline, simply specify it in a particular transform. eg:

 <map:match pattern="file">
  <map:generate src="file.xml"/>
  <map:transform type="i18n"/>
  <map:serialize/>
 </map:match>
 

Future work coming:

Author:
Marcus Crafter, Konstantin Piroumian, Lassi Immonen, Michael Enke

Field Summary
static java.lang.String I18N_ATTR_ATTRIBUTE
           
static java.lang.String I18N_CACHE_STARTUP
           
static java.lang.String I18N_CATALOGUE_LOCATION
           
static java.lang.String I18N_CATALOGUE_NAME
           
static java.lang.String I18N_CATALOGUE_PREFIX
           
static java.lang.String I18N_DATE_ELEMENT
           
static java.lang.String I18N_DATE_TIME_ELEMENT
           
static java.lang.String I18N_DICTIONARY_ELEMENT
           
static java.lang.String I18N_ENTRY_ELEMENT
           
static java.lang.String I18N_KEY_ATTRIBUTE
           
static java.lang.String I18N_KEY_ELEMENT
           
static java.lang.String I18N_LANG
           
static java.lang.String I18N_LOCALE_ATTRIBUTE
           
static java.lang.String I18N_NAMESPACE_URI
          The namespace for i18n is "http://apache.org/cocoon/i18n/2.0"
static java.lang.String I18N_NUMBER_ELEMENT
           
static java.lang.String I18N_PARAM_ELEMENT
           
static java.lang.String I18N_PATTERN_ATTRIBUTE
           
static java.lang.String I18N_SRC_LOCALE_ATTRIBUTE
           
static java.lang.String I18N_SRC_PATTERN_ATTRIBUTE
           
static java.lang.String I18N_SUB_TYPE_ATTRIBUTE
          sub-type attribute is used with i18:number to indicate a sub-type: currency, int-currency or percent.
static java.lang.String I18N_TEXT_ELEMENT
           
static java.lang.String I18N_TIME_ELEMENT
           
static java.lang.String I18N_TRANSLATE_ELEMENT
           
static java.lang.String I18N_TRANSLATION_ELEMENT
           
static java.lang.String I18N_TYPE_ATTRIBUTE
          type attribute is used with i18:param to indicate the parameter type: date or number.
static java.lang.String I18N_UNTRANSLATED
           
static java.lang.String I18N_VALUE_ATTRIBUTE
           
protected  org.apache.avalon.framework.component.ComponentManager manager
           
 
Fields inherited from class org.apache.cocoon.xml.AbstractXMLProducer
contentHandler, lexicalHandler, xmlConsumer
 
Fields inherited from interface org.apache.cocoon.transformation.Transformer
ROLE
 
Constructor Summary
I18nTransformer()
           
 
Method Summary
 void characters(char[] ch, int start, int len)
          Receive notification of character data.
 void compose(org.apache.avalon.framework.component.ComponentManager manager)
           
 void configure(org.apache.avalon.framework.configuration.Configuration conf)
          Configure this transformer.
 void endElement(java.lang.String uri, java.lang.String name, java.lang.String raw)
          Receive notification of the end of an element.
 void setup(SourceResolver resolver, java.util.Map objectModel, java.lang.String source, org.apache.avalon.framework.parameters.Parameters parameters)
          Uses org.apache.cocoon.acting.LocaleAction.getLocale() to get language user has selected.
 void startElement(java.lang.String uri, java.lang.String name, java.lang.String raw, org.xml.sax.Attributes attr)
          Receive notification of the beginning of an element.
 
Methods inherited from class org.apache.cocoon.xml.AbstractXMLPipe
comment, endCDATA, endDocument, endDTD, endEntity, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startCDATA, startDocument, startDTD, startEntity, startPrefixMapping
 
Methods inherited from class org.apache.cocoon.xml.AbstractXMLProducer
recycle, setConsumer, setContentHandler, setLexicalHandler
 
Methods inherited from class org.apache.avalon.framework.logger.AbstractLoggable
getLogger, setLogger, setupLogger, setupLogger, setupLogger
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.xml.sax.ContentHandler
endDocument, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startPrefixMapping
 
Methods inherited from interface org.xml.sax.ext.LexicalHandler
comment, endCDATA, endDTD, endEntity, startCDATA, startDTD, startEntity
 
Methods inherited from interface org.apache.cocoon.xml.XMLProducer
setConsumer
 
Methods inherited from interface org.apache.avalon.excalibur.pool.Recyclable
recycle
 

Field Detail

manager

protected org.apache.avalon.framework.component.ComponentManager manager

I18N_NAMESPACE_URI

public static final java.lang.String I18N_NAMESPACE_URI
The namespace for i18n is "http://apache.org/cocoon/i18n/2.0"

I18N_DICTIONARY_ELEMENT

public static final java.lang.String I18N_DICTIONARY_ELEMENT

I18N_ENTRY_ELEMENT

public static final java.lang.String I18N_ENTRY_ELEMENT

I18N_KEY_ELEMENT

public static final java.lang.String I18N_KEY_ELEMENT

I18N_TRANSLATION_ELEMENT

public static final java.lang.String I18N_TRANSLATION_ELEMENT

I18N_LANG

public static final java.lang.String I18N_LANG

I18N_KEY_ATTRIBUTE

public static final java.lang.String I18N_KEY_ATTRIBUTE

I18N_ATTR_ATTRIBUTE

public static final java.lang.String I18N_ATTR_ATTRIBUTE

I18N_TEXT_ELEMENT

public static final java.lang.String I18N_TEXT_ELEMENT

I18N_TRANSLATE_ELEMENT

public static final java.lang.String I18N_TRANSLATE_ELEMENT

I18N_PARAM_ELEMENT

public static final java.lang.String I18N_PARAM_ELEMENT

I18N_DATE_ELEMENT

public static final java.lang.String I18N_DATE_ELEMENT

I18N_DATE_TIME_ELEMENT

public static final java.lang.String I18N_DATE_TIME_ELEMENT

I18N_TIME_ELEMENT

public static final java.lang.String I18N_TIME_ELEMENT

I18N_NUMBER_ELEMENT

public static final java.lang.String I18N_NUMBER_ELEMENT

I18N_SRC_PATTERN_ATTRIBUTE

public static final java.lang.String I18N_SRC_PATTERN_ATTRIBUTE

I18N_PATTERN_ATTRIBUTE

public static final java.lang.String I18N_PATTERN_ATTRIBUTE

I18N_VALUE_ATTRIBUTE

public static final java.lang.String I18N_VALUE_ATTRIBUTE

I18N_LOCALE_ATTRIBUTE

public static final java.lang.String I18N_LOCALE_ATTRIBUTE

I18N_SRC_LOCALE_ATTRIBUTE

public static final java.lang.String I18N_SRC_LOCALE_ATTRIBUTE

I18N_CATALOGUE_NAME

public static final java.lang.String I18N_CATALOGUE_NAME

I18N_CATALOGUE_LOCATION

public static final java.lang.String I18N_CATALOGUE_LOCATION

I18N_CATALOGUE_PREFIX

public static final java.lang.String I18N_CATALOGUE_PREFIX

I18N_UNTRANSLATED

public static final java.lang.String I18N_UNTRANSLATED

I18N_CACHE_STARTUP

public static final java.lang.String I18N_CACHE_STARTUP

I18N_SUB_TYPE_ATTRIBUTE

public static final java.lang.String I18N_SUB_TYPE_ATTRIBUTE
sub-type attribute is used with i18:number to indicate a sub-type: currency, int-currency or percent.

I18N_TYPE_ATTRIBUTE

public static final java.lang.String I18N_TYPE_ATTRIBUTE
type attribute is used with i18:param to indicate the parameter type: date or number. If type is number then a sub-type can be used.
Constructor Detail

I18nTransformer

public I18nTransformer()
Method Detail

configure

public void configure(org.apache.avalon.framework.configuration.Configuration conf)
               throws org.apache.avalon.framework.configuration.ConfigurationException
Configure this transformer.
Specified by:
configure in interface org.apache.avalon.framework.configuration.Configurable

setup

public void setup(SourceResolver resolver,
                  java.util.Map objectModel,
                  java.lang.String source,
                  org.apache.avalon.framework.parameters.Parameters parameters)
           throws ProcessingException,
                  org.xml.sax.SAXException,
                  java.io.IOException
Uses org.apache.cocoon.acting.LocaleAction.getLocale() to get language user has selected.

compose

public void compose(org.apache.avalon.framework.component.ComponentManager manager)
Specified by:
compose in interface org.apache.avalon.framework.component.Composable

startElement

public void startElement(java.lang.String uri,
                         java.lang.String name,
                         java.lang.String raw,
                         org.xml.sax.Attributes attr)
                  throws org.xml.sax.SAXException
Description copied from class: AbstractXMLPipe
Receive notification of the beginning of an element.
Overrides:
startElement in class AbstractXMLPipe
Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe
Parameters:
uri - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
loc - The local name (without prefix), or the empty string if Namespace processing is not being performed.
raw - The raw XML 1.0 name (with prefix), or the empty string if raw names are not available.
a - The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.

endElement

public void endElement(java.lang.String uri,
                       java.lang.String name,
                       java.lang.String raw)
                throws org.xml.sax.SAXException
Description copied from class: AbstractXMLPipe
Receive notification of the end of an element.
Overrides:
endElement in class AbstractXMLPipe
Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe
Parameters:
uri - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
loc - The local name (without prefix), or the empty string if Namespace processing is not being performed.
raw - The raw XML 1.0 name (with prefix), or the empty string if raw names are not available.

characters

public void characters(char[] ch,
                       int start,
                       int len)
                throws org.xml.sax.SAXException
Description copied from class: AbstractXMLPipe
Receive notification of character data.
Overrides:
characters in class AbstractXMLPipe
Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe
Parameters:
c - The characters from the XML document.
start - The start position in the array.
len - The number of characters to read from the array.


Copyright © 1999-2001 Apache Software Foundation. All Rights Reserved.