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.

Fallback messages should never be specified by internal developers. All internal messages should be added to properties files for translation. The variants accepting a fallback message are intended for external plugin developers only. Internal developers should use:

Plugin developers are also encouraged to use properties files but the ability to specify the message directly in the call is provided as a convenience, especially for in-house plugins which will only be used by speakers of a single language.

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
  • a message pattern suitable 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
  • a message pattern suitable 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
  • a message pattern suitable 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