public interface

I18nService

com.atlassian.stash.i18n.I18nService

Class Overview

Serves localized text from properties files. Using property files for localization is described in Internationalising your plugin.

Ordinarily in a production system, the fallback message should never be used: preference should be given to using #getMessage(String, Object...), #createKeyedMessage(String, Object...) and getMessagePattern(String).

Summary

Public Methods
@Nonnull KeyedMessage createKeyedMessage(String key, Object... arguments)
Given a property key and a list of arguments, it returns:
  1. a KeyedMessage that composes the localized and formatted message for the current locale, the localized and formatted message for the root locale and the original key for the message.
@Nonnull Map<String, String> getAllTranslationsForPrefix(String prefix, Locale locale)
Given a property key prefix, this method will return all translations where the key starts with the given prefix as key -> value mappings.
@Nonnull Map<String, String> getAllTranslationsForPrefix(String prefix)
Given a property key prefix, this method will return all translations where the key starts with the given prefix as key -> value mappings using the current locale.
@Nonnull KeyedMessage getKeyedText(String key, String fallbackMessage, Object... arguments)
Given a property key, a fallback message and a list of arguments, it returns:
  1. a KeyedMessage that composes the localized and formatted message for the current locale, the localized and formatted message for the root locale and the original key for the message.
@Nonnull KeyedMessage getKeyedText(I18nKey i18nKey)
Given an I18nKey it returns:
  1. a KeyedMessage that composes the localized and formatted message for the current locale, the localized and formatted message for the root locale and the original key for the message.
@Nonnull String getMessage(String key, Object... arguments)
Given a property key and a list of arguments, it returns:
  1. the localized text formatted with the given arguments if the key can be resolved.
@Nonnull String getMessage(I18nKey key)
Given a key it returns:
  1. the localized text formatted with the given arguments if the key can be resolved.
@Nullable String getMessagePattern(String key)
Given a property key it returns:
  1. the associated message pattern if the key can be resolved.
@Nullable String getMessagePattern(Locale locale, String key)
Given a locale and a property key it returns:
  1. the localized message pattern if the key can be resolved.
@Nullable String getMessagePattern(String key, String fallbackPattern)
Given a property key and the fallback text message, it returns:
  1. the associated message pattern if the key can be resolved.
@Nonnull String getText(Locale locale, String key, String fallbackMessage, Object... arguments)
Given a property key, a locale, a fallback text message and a list of arguments, it returns:
  1. the localized text formatted with the given arguments if the key can be resolved.
@Nonnull String getText(String key, String fallbackMessage, Object... arguments)
Given a property key, the fallback text message and a list of arguments, it returns:
  1. the localized text formatted with the given arguments if the key can be resolved.

Public Methods

@Nonnull public KeyedMessage createKeyedMessage (String key, Object... arguments)

Given a property key and a list of arguments, it returns:

  1. a KeyedMessage that composes the localized and formatted message for the current locale, the localized and formatted message for the root locale and the original key for the message. Otherwise...
  2. if the message lookup for the key fails a KeyedMessage with the given key and a string representation of the arguments supplied
The locale used is the one for the request currently in scope or the default locale if that is not available.

The KeyedMessage returned is useful for priming Exceptions where the localized and non-localized messages need to differ to ensure the end use sees the message localized in their language but the logs record the message for the root locale.

Parameters
key the key for the i18ned message
arguments optional list of arguments for the message.
Returns
  • a KeyedMessage

@Nonnull public Map<String, String> getAllTranslationsForPrefix (String prefix, Locale locale)

Given a property key prefix, this method will return all translations where the key starts with the given prefix as key -> value mappings.

Parameters
prefix the prefix for a particular key to start with. Empty string will match everything, which may be slow. Throws NullPointerException if null.
locale the locale for which to lookup translations. Throws NullPointerException if null.
Returns
  • a Map of i18nKey -> translation mappings where i18nKey starts with the prefix. An empty map if no matches.
Throws
NullPointerException if prefix or link are null

@Nonnull public Map<String, String> getAllTranslationsForPrefix (String prefix)

Given a property key prefix, this method will return all translations where the key starts with the given prefix as key -> value mappings using the current locale. The current locale used is the one for the request currently in scope or the default locale if that is not available.

Parameters
prefix the prefix for a particular key to start with. Empty string will match everything, which may be slow. Throws NullPointerException if null.
Returns
  • a Map of i18nKey -> translation mappings where i18nKey starts with the prefix. An empty map if no matches.
Throws
NullPointerException if link is null

@Nonnull public KeyedMessage getKeyedText (String key, String fallbackMessage, Object... arguments)

Given a property key, a fallback message and a list of arguments, it returns:

  1. a KeyedMessage that composes the localized and formatted message for the current locale, the localized and formatted message for the root locale and the original key for the message. Otherwise...
  2. if the message lookup for the key fails for either the current locale or the root locale, the formatted fallback message is used if non-null. Otherwise...
  3. a KeyedMessage with the given key and a string representation of the arguments supplied
The current locale used is the one for the request currently in scope or the default locale if that is not available.

The KeyedMessage returned is useful for priming Exceptions where the localized and non-localized messages need to differ to ensure the end user sees the message localized in their language but the logs record the message for the root locale.

Parameters
key the key for the i18ned message
fallbackMessage the optional message to fallback to if lookup fails
arguments optional list of arguments for the message.
Returns
  • a KeyedMessage

@Nonnull public KeyedMessage getKeyedText (I18nKey i18nKey)

Given an I18nKey it returns:

  1. a KeyedMessage that composes the localized and formatted message for the current locale, the localized and formatted message for the root locale and the original key for the message. Otherwise...
  2. if the message lookup for the key fails a KeyedMessage with the given key and a string representation of the arguments supplied
The locale used is the one for the request currently in scope or the default locale if that is not available.

The KeyedMessage returned is useful for priming Exceptions where the localized and non-localized messages need to differ to ensure the end use sees the message localized in their language but the logs record the message for the root locale. The result of this method should be the same as calling #createKeyedMessage(i18nKey.getKey(), i18nKey.getArguments())

Parameters
i18nKey the key for the i18ned message
Returns
  • a KeyedMessage

@Nonnull public String getMessage (String key, Object... arguments)

Given a property key and a list of arguments, it returns:

  1. the localized text formatted with the given arguments if the key can be resolved. Otherwise...
  2. the key and a string representation of the arguments supplied
The locale used is the one for the request currently in scope or the default locale if that is not available

Parameters
key the key for the i18ned message
arguments optional list of arguments for the message.
Returns
  • I18ned string

@Nonnull public String getMessage (I18nKey key)

Given a key it returns:

  1. the localized text formatted with the given arguments if the key can be resolved. Otherwise...
  2. the key and a string representation of the arguments supplied
The locale used is the one for the request currently in scope or the default locale if that is not available

Parameters
key the key for the i18ned message
Returns
  • I18ned string

@Nullable public String getMessagePattern (String key)

Given a property key it returns:

  1. the associated message pattern if the key can be resolved. Otherwise...
  2. null
The locale used is the one for the request currently in scope or the default locale if that is not available

Parameters
key the key for the i18n pattern
Returns
  • the message pattern for use with java.text.MessageFormat or with AJS.format()

@Nullable public String getMessagePattern (Locale locale, String key)

Given a locale and a property key it returns:

  1. the localized message pattern if the key can be resolved. Otherwise...
  2. null

Parameters
locale the locale for the lookup
key the key for the i18n pattern
Returns
  • the localized message pattern for use with java.text.MessageFormat or with AJS.format()

@Nullable public String getMessagePattern (String key, String fallbackPattern)

Given a property key and the fallback text message, it returns:

  1. the associated message pattern if the key can be resolved. Otherwise...
  2. the fallbackPattern
The locale used is the one for the request currently in scope or the default locale if that is not available

Parameters
key the key for the i18n pattern
fallbackPattern the optional pattern to fallback to if lookup fails
Returns
  • the message pattern for use with java.text.MessageFormat or with AJS.format()

@Nonnull public String getText (Locale locale, String key, String fallbackMessage, Object... arguments)

Given a property key, a locale, a fallback text message and a list of arguments, it returns:

  1. the localized text formatted with the given arguments if the key can be resolved. Otherwise...
  2. the fallbackMessage formatted with the arguments will be returned if non-null. Otherwise...
  3. the key and a string representation of the arguments supplied

Parameters
locale the locale for the lookup
key key for the i18ned message
fallbackMessage the optional message to fallback to if lookup fails
arguments optional list of arguments for the message.
Returns
  • I18ned string

@Nonnull public String getText (String key, String fallbackMessage, Object... arguments)

Given a property key, the fallback text message and a list of arguments, it returns:

  1. the localized text formatted with the given arguments if the key can be resolved. Otherwise...
  2. the fallbackMessage formatted with the arguments will be returned if non-null. Otherwise...
  3. the key and a string representation of the arguments supplied
The locale used is the one for the request currently in scope or the default locale if that is not available

Parameters
key the key for the i18ned message
fallbackMessage the optional message to fallback to if lookup fails
arguments optional list of arguments for the message.
Returns
  • I18ned string