Version 4.10.0

hirondelle.web4j.ui.translate
Class Translation

Object
  extended by hirondelle.web4j.ui.translate.Translation
All Implemented Interfaces:
Comparable<Translation>

public final class Translation
extends Object
implements Comparable<Translation>

Model Object for a translation.

This class is provided as a convenience. Implementations of Translator are not required to use this class.

As one of its StartupTasks, a typical implementation of Translator may fetch a List<Translation> from some source (usually a database, perhaps some properties files), and keep a cache in memory.

For looking up translations, the following nested Map structure is useful :

   Map[BaseText, Map[Locale, Translation]]
 
Here, BaseText and Translation are ordinary unescaped Strings, not SafeText. This is because the various translation tags in this package always first perform translation using ordinary unescaped Strings, and then perform any necessary escaping on the result of the translation.

(See Translator for definition of 'base text'.)

The asNestedMap(Collection) method will modify a List<Translation> into just such a structure. As well, lookUp(String, Locale, Map) provides a simple default method for performing the typical lookup with such a structure, given base text and target locale.

Usually String, but sometimes SafeText

The following style will remain consistent, and will not escape special characters twice : The translation text usually remains as a String, yet SafeText is available when working with the data directly in a web page, in a form or listing.


Nested Class Summary
static class Translation.LookupResult
          The result of lookUp(String, Locale, Map).
 
Constructor Summary
Translation(SafeText aBaseText, Locale aLocale, SafeText aTranslation)
          Constructor with no explicit foreign keys.
Translation(SafeText aBaseText, Locale aLocale, SafeText aTranslation, Id aBaseTextId, Id aLocaleId)
          Constructor with explict foreign keys.
 
Method Summary
static Map<String,Map<String,String>> asNestedMap(Collection<Translation> aTranslations)
          Return a Map having a structure typically needed for looking up translations.
 int compareTo(Translation aThat)
           
 boolean equals(Object aThat)
           
 SafeText getBaseText()
          Return the base text passed to the constructor.
 Id getBaseTextId()
          Return the base text id passed to the constructor.
 Locale getLocale()
          Return the locale passed to the constructor.
 Id getLocaleId()
          Return the locale id passed to the constructor.
 SafeText getTranslation()
          Return the localized translation passed to the constructor.
 int hashCode()
           
static Translation.LookupResult lookUp(String aBaseText, Locale aLocale, Map<String,Map<String,String>> aTranslations)
          Look up a translation using a simple policy.
 String toString()
          Intended for debugging only.
 
Methods inherited from class Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Translation

public Translation(SafeText aBaseText,
                   Locale aLocale,
                   SafeText aTranslation)
            throws ModelCtorException
Constructor with no explicit foreign keys.

Parameters:
aBaseText - item to be translated (required). See Translator for definition of 'base text'.
aLocale - target locale for the translation (required)
aTranslation - translation of the base text into the target locale (required)
Throws:
ModelCtorException

Translation

public Translation(SafeText aBaseText,
                   Locale aLocale,
                   SafeText aTranslation,
                   Id aBaseTextId,
                   Id aLocaleId)
            throws ModelCtorException
Constructor with explict foreign keys.

This constructor allows carrying the foreign keys directly, instead of performing lookup later on. (If the database does not support subselects, then use of this constructor will likely reduce trivial lookup operations.)

Parameters:
aBaseText - item to be translated (required). See Translator for definition of 'base text'.
aLocale - target locale for the translation (required)
aTranslation - translation of the base text into the target locale (required)
aBaseTextId - foreign key representing a BaseText item, 1..50 characters (optional)
aLocaleId - foreign key representing a Locale, 1..50 characters (optional)
Throws:
ModelCtorException
Method Detail

getBaseText

public SafeText getBaseText()
Return the base text passed to the constructor.


getLocale

public Locale getLocale()
Return the locale passed to the constructor.


getTranslation

public SafeText getTranslation()
Return the localized translation passed to the constructor.


getBaseTextId

public Id getBaseTextId()
Return the base text id passed to the constructor.


getLocaleId

public Id getLocaleId()
Return the locale id passed to the constructor.


asNestedMap

public static Map<String,Map<String,String>> asNestedMap(Collection<Translation> aTranslations)
Return a Map having a structure typically needed for looking up translations.

The caller will use the returned Map to look up first using BaseText, and then using Locale. See lookUp(String, Locale, Map).

Parameters:
aTranslations - Collection of Translation objects.
Returns:
Map of a structure suitable for looking up translations.

lookUp

public static Translation.LookupResult lookUp(String aBaseText,
                                              Locale aLocale,
                                              Map<String,Map<String,String>> aTranslations)
Look up a translation using a simple policy.

If aBaseText is not known, or if there is no explicit translation for the exact Locale, then return aBaseText as is, without translation or alteration.

The policy used here is simple. It may not be desirable for some applications. In particular, if there is a need to implement a "best match" to aLocale (after the style of ResourceBundle), then this method cannot be used.

Parameters:
aBaseText - text to be translated. See Translator for a definition of 'base text'.
aLocale - whose toString result will be used to find the localized translation of aBaseText.
aTranslations - has the structure suitable for look up.
Returns:
Translation.LookupResult carrying the text of the successful translation, or, in the case of a failed lookup, information about the nature of the failure.

toString

public String toString()
Intended for debugging only.

Overrides:
toString in class Object

compareTo

public int compareTo(Translation aThat)
Specified by:
compareTo in interface Comparable<Translation>

equals

public boolean equals(Object aThat)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

Version 4.10.0

Copyright Hirondelle Systems. Published October 19, 2013 - User Guide - All Docs.