com.holonplatform.core.i18n

Interface LocalizationContext

public interface LocalizationContext

Main interface to handle localization and internationalization.

A LocalizationContext must be localized, i.e. initialized, using localize(Localization) or localize(Locale) before using it.

Provides methods to localize messages, numbers and temporal data. For messages localization, it relies on MessageProviders, which must be registered using LocalizationContext.Builder.messageProvider(MessageProvider) at context build time.

Since:

5.0.0

See Also:

MessageProvider

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	LocalizationContext.Builder Builder for LocalizationContext creation
static interface	LocalizationContext.LocalizationChangeEvent A localization change event.
static interface	LocalizationContext.LocalizationChangeListener A listener to listen for LocalizationContext localization change events.
static interface	LocalizationContext.MissingMessageLocalizationListener A listener which can be registered to a LocalizationContext to be notified when a message translation is missing from any of the available MessageProviders.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONTEXT_KEY Default Context resource key

Method Summary

Modifier and Type	Method and Description
Registration	addLocalizationChangeListener(LocalizationContext.LocalizationChangeListener listener) Add a LocalizationContext.LocalizationChangeListener to listen for localization changes.
MessageResolver	asMessageResolver() Get this localization context as a MessageResolver, which provides messages localization by Locale using the available MessageProviders.
static LocalizationContext.Builder	builder() Builder to create LocalizationContext instances
default String	format(Date date, TemporalType type) Format given date according to current Context Locale using default format styles.
String	format(Date date, TemporalType type, TemporalFormat dateFormat, TemporalFormat timeFormat) Format given date according to current Context Locale.
default String	format(LocalDate temporal, TemporalFormat dateFormat) Format given LocalDate according to current Context Locale using given date format style.
default String	format(LocalTime temporal, TemporalFormat timeFormat) Format given LocalTime according to current Context Locale using given time format style.
String	format(Number number, int decimalPositions, NumberFormatFeature... features) Format given number according to current Context Locale.
default String	format(Number number, NumberFormatFeature... features) Format given number according to current Context Locale.
default String	format(Temporal temporal) Format given temporal (for example a LocalDate, a LocalTime or a LocalDateTime) according to current Context Locale using default format styles.
String	format(Temporal temporal, TemporalFormat dateFormat, TemporalFormat timeFormat) Format given temporal (for example a LocalDate, a LocalTime or a LocalDateTime) according to current Context Locale.
static Optional<LocalizationContext>	getCurrent() Convenience method to obtain the current LocalizationContext made available as Context resource, using default ClassLoader.
default DateFormat	getDateFormat(TemporalType type) Get a DateFormat for Date formatting and set it up according to context Locale and Localization settings, using default format styles.
DateFormat	getDateFormat(TemporalType type, TemporalFormat dateFormat, TemporalFormat timeFormat) Get a DateFormat for Date formatting and set it up according to context Locale and Localization settings.
default DateTimeFormatter	getDateTimeFormatter(TemporalType type) Get a DateTimeFormatter for javax.time.* types formatting and set it up according to context Locale and Localization settings, using default format styles.
DateTimeFormatter	getDateTimeFormatter(TemporalType type, TemporalFormat dateFormat, TemporalFormat timeFormat) Get a DateTimeFormatter for javax.time.* types formatting and set it up according to context Locale and Localization settings.
Optional<Localizable>	getDefaultBooleanLocalization(boolean value) Gets the default Localizable message to use to localize a boolean value
Optional<Locale>	getLocale() Get Locale currently bound to this context, if any
default String	getMessage(Localizable localizable) Get the localized message for given Localizable.
String	getMessage(Localizable localizable, boolean lenient) Get a possibly localized message if the LocalizationContext is localized.
String	getMessage(String code, String defaultMessage, Object... arguments) Get a message for given code localized according to current Locale to which context is bound
Optional<String>	getMessageArgumentsPlaceholder() Get the symbol to be used as message arguments placeholder.
default NumberFormat	getNumberFormat(Class<? extends Number> numberType) Get a NumberFormat for numbers formatting and set it up according to context Locale and Localization settings.
NumberFormat	getNumberFormat(Class<? extends Number> numberType, int decimalPositions, boolean disableGrouping) Get a NumberFormat for numbers formatting and set it up according to context Locale and Localization settings.
boolean	isLocalized() Returns whether this context is localized, i.e.
default void	localize(Locale locale) Initialize context with given Locale, using Locale's default settings for numbers and dates formats and symbols.
default void	localize(Locale locale, boolean fireEvent) Initialize context with given Locale, using Locale's default settings for numbers and dates formats and symbols.
default void	localize(Localization localization) Initialize context with given Localization informations.
void	localize(Localization localization, boolean fireEvent) Initialize context with given Localization informations.
static LocalizationContext	require() Requires the current LocalizationContext.
static LocalizationContext	requireLocalized() Requires the current LocalizationContext, checking that it is localized.
void	setDefaultBooleanLocalization(boolean value, Localizable message) Sets the default Localizable message to use to localize a boolean value
void	setDefaultDateFormatStyle(TemporalFormat format) Set the default TemporalFormat style to use to format dates.
void	setDefaultTimeFormatStyle(TemporalFormat format) Set the default TemporalFormat style to use to format times.
static String	translate(Localizable localizable) Try to translate given localizable using the LocalizationContext available as Context resource through getCurrent().
static String	translate(Localizable localizable, boolean lenient) Try to translate given localizable using the LocalizationContext available as Context resource through getCurrent().
static String	translate(String messageCode, String defaultMessage) Try to translate given messageCode using the LocalizationContext available as Context resource through getCurrent().
static String	translate(String messageCode, String defaultMessage, boolean lenient) Try to translate given messageCode using the LocalizationContext available as Context resource through getCurrent().

Field Detail

CONTEXT_KEY

static final String CONTEXT_KEY

Default Context resource key

Method Detail

isLocalized

boolean isLocalized()

Returns whether this context is localized, i.e. it was initialized with Localization informations and ready to be used.

Returns:

true if context is localized

localize

default void localize(Locale locale)

Initialize context with given Locale, using Locale's default settings for numbers and dates formats and symbols.

Parameters:

locale - The new Locale to set, may be null

localize

default void localize(Locale locale,
                      boolean fireEvent)

Initialize context with given Locale, using Locale's default settings for numbers and dates formats and symbols.

Parameters:

locale - The new Locale to set, may be null

fireEvent - Whether to fire the localization change event

localize

default void localize(Localization localization)

Initialize context with given Localization informations.

Parameters:

localization - The new Localization to set, may be null

localize

void localize(Localization localization,
              boolean fireEvent)

Initialize context with given Localization informations.

Parameters:

localization - The new Localization to set, may be null

fireEvent - Whether to fire the localization change event

getLocale

Optional<Locale> getLocale()

Get Locale currently bound to this context, if any

Returns:

Optional context Locale, or an empty Optional if context is not localized

getMessageArgumentsPlaceholder

Optional<String> getMessageArgumentsPlaceholder()

Get the symbol to be used as message arguments placeholder.

Returns:

Optional message arguments placeholder

addLocalizationChangeListener

Registration addLocalizationChangeListener(LocalizationContext.LocalizationChangeListener listener)

Add a LocalizationContext.LocalizationChangeListener to listen for localization changes.

Parameters:

listener - The listener to add (not null)

Returns:

this

getMessage

String getMessage(String code,
                  String defaultMessage,
                  Object... arguments)

Get a message for given code localized according to current Locale to which context is bound

Parameters:

code - Message code (not null)

defaultMessage - Default message to return if no localized message could be found

arguments - Optional translation arguments

Returns:

Localized message, or defaultMessage if no suitable message was found

Throws:

Localizable.LocalizationException - If context is not localized

getMessage

default String getMessage(Localizable localizable)

Get the localized message for given Localizable.

Parameters:

localizable - Localizable message

Returns:

Localized message, or default Localizable.getMessage() if Localizable.getMessageCode() is null

Throws:

Localizable.LocalizationException - If context is not localized

getMessage

String getMessage(Localizable localizable,
                  boolean lenient)

Get a possibly localized message if the LocalizationContext is localized. If not and lenient is set to true, default Localizable.getMessage() is returned.

Parameters:

localizable - Localizable message

lenient - if true and the LocalizationContext is not localized, default Localizable.getMessage() is returned, otherwise a Localizable.LocalizationException is thrown

Returns:

Localized message

Throws:

Localizable.LocalizationException - If not lenient and context is not localized

setDefaultBooleanLocalization

void setDefaultBooleanLocalization(boolean value,
                                   Localizable message)

Sets the default Localizable message to use to localize a boolean value

Parameters:

value - Boolean value

message - The localizable message to use to localize given boolean value

getDefaultBooleanLocalization

Optional<Localizable> getDefaultBooleanLocalization(boolean value)

Gets the default Localizable message to use to localize a boolean value

Parameters:

value - Boolean value to localize

Returns:

Optional localizable message to use to localize given boolean value

setDefaultDateFormatStyle

void setDefaultDateFormatStyle(TemporalFormat format)

Set the default TemporalFormat style to use to format dates.

This is overriden by any Localization.getDefaultDateTemporalFormat() value.

Parameters:

format - Defalt date format style

setDefaultTimeFormatStyle

void setDefaultTimeFormatStyle(TemporalFormat format)

Set the default TemporalFormat style to use to format times.

This is overriden by any Localization.getDefaultTimeTemporalFormat() value.

Parameters:

format - Defalt time format style

format

String format(Number number,
              int decimalPositions,
              NumberFormatFeature... features)

Format given number according to current Context Locale.

Parameters:

number - Number to format (may be null)

decimalPositions - Decimal positions to use (-1 for default, i.e. display all the decimal positions of the given Number, if any)

features - Optional format features

Returns:

Formatted number, or null if given Number was null

Throws:

Localizable.LocalizationException - If context is not localized

format

default String format(Number number,
                      NumberFormatFeature... features)

Format given number according to current Context Locale.

Parameters:

number - Number to format (may be null)

features - Optional format features

Returns:

Formatted number, or null if given Number was null

Throws:

Localizable.LocalizationException - If context is not localized

getNumberFormat

NumberFormat getNumberFormat(Class<? extends Number> numberType,
                             int decimalPositions,
                             boolean disableGrouping)

Get a NumberFormat for numbers formatting and set it up according to context Locale and Localization settings.

Parameters:

numberType - Number type

decimalPositions - Decimal positions to use with decimal number types (-1 for default, i.e. display all the decimal positions, if any)

disableGrouping - true to not use grouping symbol

Returns:

NumberFormat

Throws:

Localizable.LocalizationException - If context is not localized

getNumberFormat

default NumberFormat getNumberFormat(Class<? extends Number> numberType)

Get a NumberFormat for numbers formatting and set it up according to context Locale and Localization settings.

Parameters:

numberType - Number type

Returns:

NumberFormat

Throws:

Localizable.LocalizationException - If context is not localized

format

String format(Date date,
              TemporalType type,
              TemporalFormat dateFormat,
              TemporalFormat timeFormat)

Format given date according to current Context Locale.

Parameters:

date - Date to format (may be null)

type - Date temporal type (Only a date, only a time or a date and time)

dateFormat - Date format style (null for default)

timeFormat - Time format style (null for default)

Returns:

Formatted date, or null if given date was null

Throws:

Localizable.LocalizationException - If context is not localized

format

default String format(Date date,
                      TemporalType type)

Format given date according to current Context Locale using default format styles.

Parameters:

date - Date to format (may be null)

type - Date temporal type (Only a date, only a time or a date and time)

Returns:

Formatted date, or null if given date was null

Throws:

Localizable.LocalizationException - If context is not localized

getDateFormat

DateFormat getDateFormat(TemporalType type,
                         TemporalFormat dateFormat,
                         TemporalFormat timeFormat)

Get a DateFormat for Date formatting and set it up according to context Locale and Localization settings.

Parameters:

type - Temporal type

dateFormat - Date format style, null for default

timeFormat - Time format style, null for default

Returns:

DateFormat

Throws:

Localizable.LocalizationException - If context is not localized

getDateFormat

default DateFormat getDateFormat(TemporalType type)

Get a DateFormat for Date formatting and set it up according to context Locale and Localization settings, using default format styles.

Parameters:

type - Temporal type

Returns:

DateFormat

Throws:

Localizable.LocalizationException - If context is not localized

format

String format(Temporal temporal,
              TemporalFormat dateFormat,
              TemporalFormat timeFormat)

Format given temporal (for example a LocalDate, a LocalTime or a LocalDateTime) according to current Context Locale.

Parameters:

temporal - Temporal to format (may be null)

dateFormat - Date format style (null for default)

timeFormat - Time format style (null for default)

Returns:

Formatted temporal, or null if given temporal was null

Throws:

Localizable.LocalizationException - If context is not localized

format

default String format(Temporal temporal)

Format given temporal (for example a LocalDate, a LocalTime or a LocalDateTime) according to current Context Locale using default format styles.

Parameters:

temporal - Temporal to format (may be null)

Returns:

Formatted temporal, or null if given temporal was null

Throws:

Localizable.LocalizationException - If context is not localized

format

default String format(LocalDate temporal,
                      TemporalFormat dateFormat)

Format given LocalDate according to current Context Locale using given date format style.

Parameters:

temporal - Date to format (may be null)

dateFormat - Date format style

Returns:

Formatted temporal, or null if given temporal was null

Throws:

Localizable.LocalizationException - If context is not localized

format

default String format(LocalTime temporal,
                      TemporalFormat timeFormat)

Format given LocalTime according to current Context Locale using given time format style.

Parameters:

temporal - Time to format (may be null)

timeFormat - Time format style

Returns:

Formatted temporal, or null if given temporal was null

Throws:

Localizable.LocalizationException - If context is not localized

getDateTimeFormatter

DateTimeFormatter getDateTimeFormatter(TemporalType type,
                                       TemporalFormat dateFormat,
                                       TemporalFormat timeFormat)

Get a DateTimeFormatter for javax.time.* types formatting and set it up according to context Locale and Localization settings.

Parameters:

type - Temporal type

dateFormat - Date format style, null for default

timeFormat - Time format style, null for default

Returns:

DateTimeFormatter

Throws:

Localizable.LocalizationException - If context is not localized

getDateTimeFormatter

default DateTimeFormatter getDateTimeFormatter(TemporalType type)

Get a DateTimeFormatter for javax.time.* types formatting and set it up according to context Locale and Localization settings, using default format styles.

Parameters:

type - Temporal type

Returns:

DateTimeFormatter

Throws:

Localizable.LocalizationException - If context is not localized

asMessageResolver

MessageResolver asMessageResolver()

Get this localization context as a MessageResolver, which provides messages localization by Locale using the available MessageProviders.

Returns:

this localization context as a MessageResolver

translate

static String translate(Localizable localizable,
                        boolean lenient)

Try to translate given localizable using the LocalizationContext available as Context resource through getCurrent(). The LocalizationContext must be localized.

Parameters:

localizable - Localizable to translate

lenient - if true and a LocalizationContext is not available or it is not localized, silently return default Localizable.getMessage(). If false, a Localizable.LocalizationException is thrown for that situation

Returns:

The localized message, or default Localizable.getMessage() if a localized LocalizationContext is not available and lenient is true, or Localizable.getMessageCode() is null.

translate

static String translate(Localizable localizable)

Try to translate given localizable using the LocalizationContext available as Context resource through getCurrent(). The LocalizationContext must be localized.

Parameters:

localizable - Localizable to translate

Returns:

The localized message, or default Localizable.getMessage() if Localizable.getMessageCode() is null

Throws:

Localizable.LocalizationException - If a LocalizationContext is not available as Context resource or it is not localized

translate

static String translate(String messageCode,
                        String defaultMessage,
                        boolean lenient)

Try to translate given messageCode using the LocalizationContext available as Context resource through getCurrent(). The LocalizationContext must be localized.

Parameters:

messageCode - Message code to translate

defaultMessage - Default message

lenient - if true and a LocalizationContext is not available or it is not localized, silently return default defaultMessage. If false, a Localizable.LocalizationException is thrown for that situation

Returns:

The localized message, or default defaultMessage if a localized LocalizationContext is not available and lenient is true, or messageCode is null.

translate

static String translate(String messageCode,
                        String defaultMessage)

Try to translate given messageCode using the LocalizationContext available as Context resource through getCurrent(). The LocalizationContext must be localized.

Parameters:

messageCode - Message code to translate

defaultMessage - Default message

Returns:

The localized message, or default defaultMessage if messageCode is null

Throws:

Localizable.LocalizationException - If a LocalizationContext is not available as Context resource or it is not localized

getCurrent

static Optional<LocalizationContext> getCurrent()

Convenience method to obtain the current LocalizationContext made available as Context resource, using default ClassLoader.

See Context.resource(String, Class) for details about context resources availability conditions.

Returns:

Optional LocalizationContext, empty if not available as context resource

require

static LocalizationContext require()

Requires the current LocalizationContext. If not available using getCurrent(), an IllegalStateException is thrown.

Returns:

Current LocalizationContext

Throws:

IllegalStateException - LocalizationContext is not available as a Context resource

requireLocalized

static LocalizationContext requireLocalized()

Requires the current LocalizationContext, checking that it is localized. If not available using getCurrent(), an IllegalStateException is thrown. If not localized, a Localizable.LocalizationException is thrown instead.

Returns:

Current LocalizationContext

Throws:

IllegalStateException - LocalizationContext is not available as a Context resource

Localizable.LocalizationException - A LocalizationContext is available as context resource but it is not localized

See Also:

isLocalized()

builder

static LocalizationContext.Builder builder()

Builder to create LocalizationContext instances

Returns:

LocalizationContextBuilder