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 `MessageProvider`s, 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 `MessageProvider`s.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONTEXT_KEY` Default `Context` resource key

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    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 `MessageProvider`s.
    `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. it was initialized with `Localization` informations and ready to be used.
    `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 `MessageProvider`s.
      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

Copyright © 2019 The Holon Platform. All rights reserved.