Interface Localization


@ProviderType public interface Localization
Stores and retrieves localized strings from XML, and provides utility methods for updating localizations from JSON, portlet requests, and maps. Used for adding localization to strings, most often for model properties.

Localized values are cached in this class rather than in the value object since value objects get flushed from cache fairly quickly. Though lookups performed on a key based on an XML file are slower than lookups done at the value object level in general, the value object will get flushed at a rate which works against the performance gain. The cache is a soft hash map which prevents memory leaks within the system while enabling the cache to live longer than in a weak hash map.

Author:
Alexander Chow, Jorge Ferrer, Mauro Mariuzzo, Julio Camarero, Brian Wing Shun Chan
  • Method Details

    • deserialize

      Object deserialize(JSONObject jsonObject)
      Deserializes the JSON object into a map of locales and localized strings.
      Parameters:
      jsonObject - the JSON object
      Returns:
      the locales and localized strings
    • getAvailableLanguageIds

      String[] getAvailableLanguageIds(Document document)
    • getAvailableLanguageIds

      String[] getAvailableLanguageIds(String xml)
      Returns the available locales from the localizations XML.
      Parameters:
      xml - the localizations XML
      Returns:
      the language IDs of the available locales
    • getDefaultImportLocale

      Locale getDefaultImportLocale(String className, long classPK, Locale contentDefaultLocale, Locale[] contentAvailableLocales)
      Returns a valid default locale for importing a localized entity.
      Parameters:
      className - the class name of the entity
      classPK - the primary keys of the entity
      contentDefaultLocale - the default Locale of the entity
      contentAvailableLocales - the available locales of the entity
      Returns:
      the valid locale
    • getDefaultImportLocale

      Locale getDefaultImportLocale(String className, Serializable primaryKey, Locale contentDefaultLocale, Locale[] contentAvailableLocales)
      Returns a valid default locale for importing a localized entity.
      Parameters:
      className - the class name of the entity
      primaryKey - the primary keys of the entity
      contentDefaultLocale - the default Locale of the entity
      contentAvailableLocales - the available locales of the entity
      Returns:
      the valid locale
    • getDefaultLanguageId

      String getDefaultLanguageId(Document document)
    • getDefaultLanguageId

      String getDefaultLanguageId(Document document, Locale defaultLocale)
    • getDefaultLanguageId

      String getDefaultLanguageId(String xml)
      Returns the default locale from the localizations XML.
      Parameters:
      xml - the localizations XML
      Returns:
      the language ID of the default locale, or the system default locale if the default locale cannot be retrieved from the XML
    • getDefaultLanguageId

      String getDefaultLanguageId(String xml, Locale defaultLocale)
    • getLocalization

      String getLocalization(Function<String,String> localizationFunction, String requestedLanguageId, String defaultLanguageId)
    • getLocalization

      String getLocalization(String xml, String requestedLanguageId)
      Returns the localized string from the localizations XML in the language. The default language is used if no localization exists for the requested language.
      Parameters:
      xml - the localizations XML
      requestedLanguageId - the ID of the language
      Returns:
      the localized string
    • getLocalization

      String getLocalization(String xml, String requestedLanguageId, boolean useDefault)
      Returns the localized string from the localizations XML in the language, optionally using the default language if no localization exists for the requested language.
      Parameters:
      xml - the localizations XML
      requestedLanguageId - the ID of the language
      useDefault - whether to use the default language if no localization exists for the requested language
      Returns:
      the localized string, or an empty string if useDefault is false and no localization exists for the requested language
    • getLocalization

      String getLocalization(String xml, String requestedLanguageId, boolean useDefault, String defaultValue)
      Returns the localized string from the localizations XML in the language, optionally using the default language if no localization exists for the requested language. If no localization exists, the default value is returned.
      Parameters:
      xml - the localizations XML
      requestedLanguageId - the ID of the language
      useDefault - whether to use the default language if no localization exists for the requested language
      defaultValue - the value returned if no localization exists
      Returns:
      the localized string, or the defaultValue if useDefault is false and no localization exists for the requested language
    • getLocalizationMap

      Map<Locale,String> getLocalizationMap(Collection<Locale> locales, Locale defaultLocale, String key)
      Returns a map of locales and localized strings for the key. If no localization exists for a locale or the localization matches the default locale, that locale is not included in the map.
      Parameters:
      locales - the locales to be used in the map
      defaultLocale - the default locale
      key - the language key to be translated
      Returns:
      the locales and localized strings for the key
    • getLocalizationMap

      Map<Locale,String> getLocalizationMap(javax.servlet.http.HttpServletRequest httpServletRequest, String parameter)
      Returns a map of locales and localized strings for the parameter in the request.
      Parameters:
      httpServletRequest - the request
      parameter - the prefix of the parameters containing the localized strings. Each localization is loaded from a parameter with this prefix, followed by an underscore, and the language ID.
      Returns:
      the locales and localized strings
    • getLocalizationMap

      Map<Locale,String> getLocalizationMap(PortletPreferences portletPreferences, String preferenceName)
      Returns a map of locales and localized strings for the preference in the preferences container.
      Parameters:
      portletPreferences - the preferences container
      preferenceName - the prefix of the preference containing the localized strings. Each localization is loaded from a preference with this prefix, followed by an underscore, and the language ID.
      Returns:
      the locales and localized strings
    • getLocalizationMap

      Map<Locale,String> getLocalizationMap(PortletPreferences portletPreferences, String preferenceName, String propertyName)
      Returns a map of locales and localized strings for the preference in the preferences container. If no localization exists for the preference in the default locale, the value of the property is used as the localization for it.
      Parameters:
      portletPreferences - the preferences container
      preferenceName - the prefix of the preference containing the localized strings. Each localization is loaded from a preference with this prefix, followed by an underscore, and the language ID.
      propertyName - the name of the property whose value is used as the localization for the default locale, if no localization exists for it
      Returns:
      the locales and localized strings
    • getLocalizationMap

      Map<Locale,String> getLocalizationMap(PortletPreferences portletPreferences, String preferenceName, String propertyName, String defaultPropertyValue, ClassLoader classLoader)
    • getLocalizationMap

      Map<Locale,String> getLocalizationMap(PortletRequest portletRequest, String parameter)
      Returns a map of locales and localized strings for the parameter in the portlet request.
      Parameters:
      portletRequest - the portlet request
      parameter - the prefix of the parameters containing the localized strings. Each localization is loaded from a parameter with this prefix, followed by an underscore, and the language ID.
      Returns:
      the locales and localized strings
    • getLocalizationMap

      Map<Locale,String> getLocalizationMap(PortletRequest portletRequest, String parameter, Map<Locale,String> defaultValues)
    • getLocalizationMap

      Map<Locale,String> getLocalizationMap(String xml)
      Returns a map of locales and localized strings from the localizations XML.
      Parameters:
      xml - the localizations XML
      Returns:
      the locales and localized strings
    • getLocalizationMap

      Map<Locale,String> getLocalizationMap(String xml, boolean useDefault)
    • getLocalizationMap

      Map<Locale,String> getLocalizationMap(String bundleName, ClassLoader classLoader, String key, boolean includeBetaLocales)
    • getLocalizationMap

      Map<Locale,String> getLocalizationMap(String[] languageIds, String[] values)
      Returns a map of locales and localized strings for the given languageIds and values.
      Parameters:
      languageIds - the languageIds of the localized Strings
      values - the localized strings for the different languageId
      Returns:
      the map of locales and values for the given parameters
    • getLocalizationXmlFromPreferences

      String getLocalizationXmlFromPreferences(PortletPreferences portletPreferences, PortletRequest portletRequest, String parameter)
      Returns the localizations XML for the parameter from the portlet request, attempting to get data from the preferences container if it is not available in the portlet request.
      Parameters:
      portletPreferences - the preferences container
      portletRequest - the portlet request
      parameter - the prefix of the parameters containing the localized strings. Each localization is loaded from a parameter with this prefix, followed by an underscore, and the language ID.
      Returns:
      the locales and localized strings
    • getLocalizationXmlFromPreferences

      String getLocalizationXmlFromPreferences(PortletPreferences portletPreferences, PortletRequest portletRequest, String parameter, String defaultValue)
      Returns the localizations XML for the parameter from the portlet request, attempting to get data from the preferences container if it is not available in the portlet request. If no localization exists in the default locale, the default value is used as the localization for it.
      Parameters:
      portletPreferences - the preferences container
      portletRequest - the portlet request
      parameter - the prefix of the parameters containing the localized strings. Each localization is loaded from a parameter with this prefix, followed by an underscore, and the language ID.
      defaultValue - the value used as the localization for the default locale, if no localization exists for it
      Returns:
      the locales and localized strings
    • getLocalizationXmlFromPreferences

      String getLocalizationXmlFromPreferences(PortletPreferences portletPreferences, PortletRequest portletRequest, String parameter, String prefix, String defaultValue)
      Returns the localizations XML for the prefixed parameter from the portlet request, attempting to get data from the preferences container if it is not available in the portlet request. If no localization exists for the the default locale, the default value is used as the localization for it.
      Parameters:
      portletPreferences - the preferences container
      portletRequest - the portlet request
      parameter - the prefix of the parameters containing the localized strings. Each localization is loaded from a parameter with this prefix, followed by an underscore, and the language ID.
      prefix - the value used in the request to prefix the parameter name
      defaultValue - the value used as the localization for the default locale, if no localization exists for it
      Returns:
      the locales and localized strings, or the defaultValue if no localization exists
    • getLocalizedName

      String getLocalizedName(String name, String languageId)
      Returns the localized name in the language. The localized name is the name, followed by an underscore, and the language ID.
      Parameters:
      name - the name to be localized
      languageId - the ID of the language
      Returns:
      the localized name for the language
    • getMap

      Map<Locale,String> getMap(LocalizedValuesMap localizedValuesMap)
    • getPreferencesValue

      String getPreferencesValue(PortletPreferences portletPreferences, String key, String languageId)
      Returns the localized preferences value for the key in the language. The default language is used if no localization exists for the requested language.
      Parameters:
      portletPreferences - the preferences container
      key - the preferences key
      languageId - the ID of the language
      Returns:
      the localized preferences value
    • getPreferencesValue

      String getPreferencesValue(PortletPreferences portletPreferences, String key, String languageId, boolean useDefault)
      Returns the localized preferences value for the key in the language, optionally using the default language if no localization exists for the requested language.
      Parameters:
      portletPreferences - the preferences container
      key - the preferences key
      languageId - the ID of the language
      useDefault - whether to use the default language if no localization exists for the requested language
      Returns:
      the localized preferences value, or an empty string if useDefault is false and no localization exists for the requested language
    • getPreferencesValues

      String[] getPreferencesValues(PortletPreferences portletPreferences, String key, String languageId)
      Returns the localized preferences values for the key in the language. The default language is used if no localization exists for the requested language.
      Parameters:
      portletPreferences - the preferences container
      key - the preferences key
      languageId - the ID of the language
      Returns:
      the localized preferences values
    • getPreferencesValues

      String[] getPreferencesValues(PortletPreferences portletPreferences, String key, String languageId, boolean useDefault)
      Returns the localized preferences values for the key in the language, optionally using the default language if no localization exists for the requested language.
      Parameters:
      portletPreferences - the preferences container
      key - the preferences key
      languageId - the ID of the language
      useDefault - whether to use the default language if no localization exists for the requested language
      Returns:
      the localized preferences values, or an empty string if useDefault is false and no localization exists for the requested language
    • getSettingsValue

      String getSettingsValue(Settings settings, String key, String languageId)
      Returns the localized settings value for the key in the language. The default language is used if no localization exists for the requested language.
      Parameters:
      settings - the settings
      key - the settings key
      languageId - the ID of the language
      Returns:
      the localized settings value
    • getSettingsValue

      String getSettingsValue(Settings settings, String key, String languageId, boolean useDefault)
      Returns the localized settings value for the key in the language, optionally using the default language if no localization exists for the requested language.
      Parameters:
      settings - the settings
      key - the settings key
      languageId - the ID of the language
      useDefault - whether to use the default language if no localization exists for the requested language
      Returns:
      the localized settings value. If useDefault is false and no localization exists for the requested language, an empty string is returned.
    • getSettingsValues

      String[] getSettingsValues(Settings settings, String key, String languageId)
      Returns the localized settings values for the key in the language. The default language is used if no localization exists for the requested language.
      Parameters:
      settings - the settings
      key - the settings key
      languageId - the ID of the language
      Returns:
      the localized settings values
    • getSettingsValues

      String[] getSettingsValues(Settings settings, String key, String languageId, boolean useDefault)
      Returns the localized settings values for the key in the language, optionally using the default language if no localization exists for the requested language.
      Parameters:
      settings - the settings
      key - the settings key
      languageId - the ID of the language
      useDefault - whether to use the default language if no localization exists for the requested language
      Returns:
      the localized settings values. If useDefault is false and no localization exists for the requested language, an empty array is returned.
    • getXml

      String getXml(LocalizedValuesMap localizedValuesMap, String key)
    • getXml

      String getXml(Map<String,String> map, String defaultLanguageId, String key)
    • getXml

      String getXml(Map<String,String> map, String defaultLanguageId, String key, boolean cdata)
    • populateLocalizationMap

      Map<Locale,String> populateLocalizationMap(Map<Locale,String> localizationMap, String defaultLanguageId, long groupId)
    • removeLocalization

      String removeLocalization(String xml, String key, String requestedLanguageId)
      Removes the localization for the language from the localizations XML. The localized strings are stored as characters in the XML.
      Parameters:
      xml - the localizations XML
      key - the name of the localized string, such as "Title"
      requestedLanguageId - the ID of the language
      Returns:
      the localizations XML with the language removed
    • removeLocalization

      String removeLocalization(String xml, String key, String requestedLanguageId, boolean cdata)
      Removes the localization for the language from the localizations XML, optionally storing the localized strings as CDATA in the XML.
      Parameters:
      xml - the localizations XML
      key - the name of the localized string, such as "Title"
      requestedLanguageId - the ID of the language
      cdata - whether to store localized strings as CDATA in the XML
      Returns:
      the localizations XML with the language removed
    • removeLocalization

      String removeLocalization(String xml, String key, String requestedLanguageId, boolean cdata, boolean localized)
      Removes the localization for the language from the localizations XML, optionally storing the localized strings as CDATA in the XML.
      Parameters:
      xml - the localizations XML
      key - the name of the localized string, such as "Title"
      requestedLanguageId - the ID of the language
      cdata - whether to store localized strings as CDATA in the XML
      localized - whether there is a localized field
      Returns:
      the localizations XML with the language removed
    • setLocalizedPreferencesValues

      void setLocalizedPreferencesValues(PortletRequest portletRequest, PortletPreferences portletPreferences, String parameter) throws Exception
      Sets the localized preferences values for the parameter in the portlet request.
      Parameters:
      portletRequest - the portlet request
      portletPreferences - the preferences container
      parameter - the prefix of the parameters containing the localized strings. Each localization is loaded from a parameter with this prefix, followed by an underscore, and the language ID.
      Throws:
      Exception - if an exception occurred
    • setPreferencesValue

      void setPreferencesValue(PortletPreferences portletPreferences, String key, String languageId, String value) throws Exception
      Sets the localized preferences value for the key in the language.
      Parameters:
      portletPreferences - the preferences container
      key - the preferences key
      languageId - the ID of the language
      value - the localized value
      Throws:
      Exception - if an exception occurred
    • setPreferencesValues

      void setPreferencesValues(PortletPreferences portletPreferences, String key, String languageId, String[] values) throws Exception
      Sets the localized preferences values for the key in the language.
      Parameters:
      portletPreferences - the preferences container
      key - the preferences key
      languageId - the ID of the language
      values - the localized values
      Throws:
      Exception - if an exception occurred
    • updateLocalization

      String updateLocalization(Map<Locale,String> localizationMap, String xml, String key, String defaultLanguageId)
      Updates the localized string for all the available languages in the localizations XML for the map of locales and localized strings and changes the default language. The localized strings are stored as characters in the XML.
      Parameters:
      localizationMap - the locales and localized strings
      xml - the localizations XML
      key - the name of the localized string, such as "Title"
      defaultLanguageId - the ID of the default language
      Returns:
      the updated localizations XML
    • updateLocalization

      String updateLocalization(String xml, String key, String value)
      Updates the localized string for the system default language in the localizations XML. The localized strings are stored as characters in the XML.
      Parameters:
      xml - the localizations XML
      key - the name of the localized string, such as "Title"
      value - the localized string
      Returns:
      the updated localizations XML
    • updateLocalization

      String updateLocalization(String xml, String key, String value, String requestedLanguageId)
      Updates the localized string for the language in the localizations XML. The localized strings are stored as characters in the XML.
      Parameters:
      xml - the localizations XML
      key - the name of the localized string, such as "Title"
      value - the localized string
      requestedLanguageId - the ID of the language
      Returns:
      the updated localizations XML
    • updateLocalization

      String updateLocalization(String xml, String key, String value, String requestedLanguageId, String defaultLanguageId)
      Updates the localized string for the language in the localizations XML and changes the default language. The localized strings are stored as characters in the XML.
      Parameters:
      xml - the localizations XML
      key - the name of the localized string, such as "Title"
      value - the localized string
      requestedLanguageId - the ID of the language
      defaultLanguageId - the ID of the default language
      Returns:
      the updated localizations XML
    • updateLocalization

      String updateLocalization(String xml, String key, String value, String requestedLanguageId, String defaultLanguageId, boolean cdata)
      Updates the localized string for the language in the localizations XML and changes the default language, optionally storing the localized strings as CDATA in the XML.
      Parameters:
      xml - the localizations XML
      key - the name of the localized string, such as "Title"
      value - the localized string
      requestedLanguageId - the ID of the language
      defaultLanguageId - the ID of the default language
      cdata - whether to store localized strings as CDATA in the XML
      Returns:
      the updated localizations XML
    • updateLocalization

      String updateLocalization(String xml, String key, String value, String requestedLanguageId, String defaultLanguageId, boolean cdata, boolean localized)
      Updates the localized string for the language in the localizations XML and changes the default language, optionally storing the localized strings as CDATA in the XML.
      Parameters:
      xml - the localizations XML
      key - the name of the localized string, such as "Title"
      value - the localized string
      requestedLanguageId - the ID of the language
      defaultLanguageId - the ID of the default language
      cdata - whether to store localized strings as CDATA in the XML
      localized - whether there is a localized field
      Returns:
      the updated localizations XML