Package com.liferay.portal.kernel.util
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 Summary
Modifier and TypeMethodDescriptiondeserialize
(JSONObject jsonObject) Deserializes the JSON object into a map of locales and localized strings.String[]
getAvailableLanguageIds
(Document document) String[]
Returns the available locales from the localizations XML.getDefaultImportLocale
(String className, long classPK, Locale contentDefaultLocale, Locale[] contentAvailableLocales) Returns a valid default locale for importing a localized entity.getDefaultImportLocale
(String className, Serializable primaryKey, Locale contentDefaultLocale, Locale[] contentAvailableLocales) Returns a valid default locale for importing a localized entity.getDefaultLanguageId
(Document document) getDefaultLanguageId
(Document document, Locale defaultLocale) Returns the default locale from the localizations XML.getDefaultLanguageId
(String xml, Locale defaultLocale) getLocalization
(String xml, String requestedLanguageId) Returns the localized string from the localizations XML in the language.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.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.getLocalization
(Function<String, String> localizationFunction, String requestedLanguageId, String defaultLanguageId) getLocalizationMap
(String xml) Returns a map of locales and localized strings from the localizations XML.getLocalizationMap
(String[] languageIds, String[] values) Returns a map of locales and localized strings for the given languageIds and values.getLocalizationMap
(String xml, boolean useDefault) getLocalizationMap
(String bundleName, ClassLoader classLoader, String key, boolean includeBetaLocales) getLocalizationMap
(Collection<Locale> locales, Locale defaultLocale, String key) Returns a map of locales and localized strings for the key.getLocalizationMap
(PortletPreferences portletPreferences, String preferenceName) Returns a map of locales and localized strings for the preference in the preferences container.getLocalizationMap
(PortletPreferences portletPreferences, String preferenceName, String propertyName) Returns a map of locales and localized strings for the preference in the preferences container.getLocalizationMap
(PortletPreferences portletPreferences, String preferenceName, String propertyName, String defaultPropertyValue, ClassLoader classLoader) getLocalizationMap
(PortletRequest portletRequest, String parameter) Returns a map of locales and localized strings for the parameter in the portlet request.getLocalizationMap
(PortletRequest portletRequest, String parameter, Map<Locale, String> defaultValues) getLocalizationMap
(javax.servlet.http.HttpServletRequest httpServletRequest, String parameter) Returns a map of locales and localized strings for the parameter in the request.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.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.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.getLocalizedName
(String name, String languageId) Returns the localized name in the language.getMap
(LocalizedValuesMap localizedValuesMap) getPreferencesValue
(PortletPreferences portletPreferences, String key, String languageId) Returns the localized preferences value for the key in the language.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.String[]
getPreferencesValues
(PortletPreferences portletPreferences, String key, String languageId) Returns the localized preferences values for the key in the language.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.getSettingsValue
(Settings settings, String key, String languageId) Returns the localized settings value for the key in the language.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.String[]
getSettingsValues
(Settings settings, String key, String languageId) Returns the localized settings values for the key in the language.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.getXml
(LocalizedValuesMap localizedValuesMap, String key) populateLocalizationMap
(Map<Locale, String> localizationMap, String defaultLanguageId, long groupId) removeLocalization
(String xml, String key, String requestedLanguageId) Removes the localization for the language from the localizations XML.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.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.void
setLocalizedPreferencesValues
(PortletRequest portletRequest, PortletPreferences portletPreferences, String parameter) Sets the localized preferences values for the parameter in the portlet request.void
setPreferencesValue
(PortletPreferences portletPreferences, String key, String languageId, String value) Sets the localized preferences value for the key in the language.void
setPreferencesValues
(PortletPreferences portletPreferences, String key, String languageId, String[] values) Sets the localized preferences values for the key in the language.updateLocalization
(String xml, String key, String value) Updates the localized string for the system default language in the localizations XML.updateLocalization
(String xml, String key, String value, String requestedLanguageId) Updates the localized string for the language in the localizations XML.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.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.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.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.
-
Method Details
-
deserialize
Deserializes the JSON object into a map of locales and localized strings.- Parameters:
jsonObject
- the JSON object- Returns:
- the locales and localized strings
-
getAvailableLanguageIds
-
getAvailableLanguageIds
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 entityclassPK
- the primary keys of the entitycontentDefaultLocale
- the default Locale of the entitycontentAvailableLocales
- 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 entityprimaryKey
- the primary keys of the entitycontentDefaultLocale
- the default Locale of the entitycontentAvailableLocales
- the available locales of the entity- Returns:
- the valid locale
-
getDefaultLanguageId
-
getDefaultLanguageId
-
getDefaultLanguageId
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
-
getLocalization
-
getLocalization
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 XMLrequestedLanguageId
- the ID of the language- Returns:
- the localized string
-
getLocalization
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 XMLrequestedLanguageId
- the ID of the languageuseDefault
- whether to use the default language if no localization exists for the requested language- Returns:
- the localized string, or an empty string if
useDefault
isfalse
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 XMLrequestedLanguageId
- the ID of the languageuseDefault
- whether to use the default language if no localization exists for the requested languagedefaultValue
- the value returned if no localization exists- Returns:
- the localized string, or the
defaultValue
ifuseDefault
isfalse
and no localization exists for the requested language
-
getLocalizationMap
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 mapdefaultLocale
- the default localekey
- 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 requestparameter
- 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
Returns a map of locales and localized strings for the preference in the preferences container.- Parameters:
portletPreferences
- the preferences containerpreferenceName
- 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 containerpreferenceName
- 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
Returns a map of locales and localized strings for the parameter in the portlet request.- Parameters:
portletRequest
- the portlet requestparameter
- 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
-
getLocalizationMap
Returns a map of locales and localized strings from the localizations XML.- Parameters:
xml
- the localizations XML- Returns:
- the locales and localized strings
-
getLocalizationMap
-
getLocalizationMap
-
getLocalizationMap
Returns a map of locales and localized strings for the given languageIds and values.- Parameters:
languageIds
- the languageIds of the localized Stringsvalues
- 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 containerportletRequest
- the portlet requestparameter
- 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 containerportletRequest
- the portlet requestparameter
- 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 containerportletRequest
- the portlet requestparameter
- 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 namedefaultValue
- 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
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 localizedlanguageId
- the ID of the language- Returns:
- the localized name for the language
-
getMap
-
getPreferencesValue
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 containerkey
- the preferences keylanguageId
- 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 containerkey
- the preferences keylanguageId
- the ID of the languageuseDefault
- 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
isfalse
and no localization exists for the requested language
-
getPreferencesValues
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 containerkey
- the preferences keylanguageId
- 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 containerkey
- the preferences keylanguageId
- the ID of the languageuseDefault
- 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
isfalse
and no localization exists for the requested language
-
getSettingsValue
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 settingskey
- the settings keylanguageId
- the ID of the language- Returns:
- the localized settings value
-
getSettingsValue
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 settingskey
- the settings keylanguageId
- the ID of the languageuseDefault
- whether to use the default language if no localization exists for the requested language- Returns:
- the localized settings value. If
useDefault
isfalse
and no localization exists for the requested language, an empty string is returned.
-
getSettingsValues
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 settingskey
- the settings keylanguageId
- the ID of the language- Returns:
- the localized settings values
-
getSettingsValues
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 settingskey
- the settings keylanguageId
- the ID of the languageuseDefault
- whether to use the default language if no localization exists for the requested language- Returns:
- the localized settings values. If
useDefault
isfalse
and no localization exists for the requested language, an empty array is returned.
-
getXml
-
getXml
-
getXml
-
populateLocalizationMap
-
removeLocalization
Removes the localization for the language from the localizations XML. The localized strings are stored as characters in the XML.- Parameters:
xml
- the localizations XMLkey
- the name of the localized string, such as "Title"requestedLanguageId
- the ID of the language- Returns:
- the localizations XML with the language removed
-
removeLocalization
Removes the localization for the language from the localizations XML, optionally storing the localized strings as CDATA in the XML.- Parameters:
xml
- the localizations XMLkey
- the name of the localized string, such as "Title"requestedLanguageId
- the ID of the languagecdata
- 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 XMLkey
- the name of the localized string, such as "Title"requestedLanguageId
- the ID of the languagecdata
- whether to store localized strings as CDATA in the XMLlocalized
- 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 requestportletPreferences
- the preferences containerparameter
- 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 containerkey
- the preferences keylanguageId
- the ID of the languagevalue
- 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 containerkey
- the preferences keylanguageId
- the ID of the languagevalues
- 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 stringsxml
- the localizations XMLkey
- the name of the localized string, such as "Title"defaultLanguageId
- the ID of the default language- Returns:
- the updated localizations XML
-
updateLocalization
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 XMLkey
- the name of the localized string, such as "Title"value
- the localized string- Returns:
- the updated localizations XML
-
updateLocalization
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 XMLkey
- the name of the localized string, such as "Title"value
- the localized stringrequestedLanguageId
- 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 XMLkey
- the name of the localized string, such as "Title"value
- the localized stringrequestedLanguageId
- the ID of the languagedefaultLanguageId
- 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 XMLkey
- the name of the localized string, such as "Title"value
- the localized stringrequestedLanguageId
- the ID of the languagedefaultLanguageId
- the ID of the default languagecdata
- 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 XMLkey
- the name of the localized string, such as "Title"value
- the localized stringrequestedLanguageId
- the ID of the languagedefaultLanguageId
- the ID of the default languagecdata
- whether to store localized strings as CDATA in the XMLlocalized
- whether there is a localized field- Returns:
- the updated localizations XML
-