Package com.atlassian.bitbucket.i18n

Interface I18nService

public interface I18nService
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.

  • Method Summary

    Modifier and Type
    Method
    Description
    KeyedMessage
    createKeyedMessage(String key, Object... arguments)
    Given a property key and a list of arguments, it returns: 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.
    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 to value mappings using the current locale.
    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.
    KeyedMessage
    getKeyedText(I18nKey i18nKey)
    Given an I18nKey it returns: 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.
    KeyedMessage
    getKeyedText(String key, String fallbackMessage, Object... arguments)
    Given a property key, a fallback message and a list of arguments, it returns: 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.
    String
    getMessage(I18nKey key)
    Given a key it returns: the localized text formatted with the given arguments if the key can be resolved.
    String
    getMessage(String key, Object... arguments)
    Given a property key and a list of arguments, it returns: the localized text formatted with the given arguments if the key can be resolved.
    String
    getMessage(Locale locale, String key, Object... arguments)
    Given a locale, a property key and a list of arguments, it returns: the localized text formatted with the given arguments if the key can be resolved.
    String
    getMessagePattern(String key)
    Given a property key it returns: the associated message pattern if the key can be resolved.
    String
    getMessagePattern(String key, String fallbackPattern)
    Given a property key and the fallback text message, it returns: the associated message pattern if the key can be resolved.
    String
    getMessagePattern(Locale locale, String key)
    Given a locale and a property key it returns: the localized message pattern if the key can be resolved.
    String
    getText(String key, String fallbackMessage, Object... arguments)
    Given a property key, the fallback text message and a list of arguments, it returns: the localized text formatted with the given arguments if the key can be resolved.
    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: the localized text formatted with the given arguments if the key can be resolved.

  • Method Details

    • createKeyedMessage

      @Nonnull KeyedMessage createKeyedMessage(@Nonnull String key, @Nonnull 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

    • getMessage

      @Nonnull String getMessage(@Nonnull String key, @Nonnull 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

    • getMessage

      @Nonnull String getMessage(@Nonnull 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

    • getMessage

      @Nonnull String getMessage(@Nonnull Locale locale, @Nonnull String key, @Nullable Object... arguments)
      Given a locale, 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
      Parameters:
      locale - the locale for the lookup
      key - the key for the i18ned message
      arguments - optional list of arguments for the message.
      Returns:
      I18ned string
      Since:
      5.3

    • getText

      @Nonnull String getText(@Nonnull Locale locale, @Nonnull String key, @Nullable String fallbackMessage, @Nonnull 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

    • getText

      @Nonnull String getText(@Nonnull String key, @Nullable String fallbackMessage, @Nonnull 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

    • getMessagePattern

      @Nullable String getMessagePattern(@Nonnull 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()

    • getMessagePattern

      @Nullable String getMessagePattern(@Nonnull String key, @Nullable 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()

    • getMessagePattern

      @Nullable String getMessagePattern(@Nonnull Locale locale, @Nonnull 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()

    • getKeyedText

      @Nonnull KeyedMessage getKeyedText(@Nonnull 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

    • getKeyedText

      @Nonnull KeyedMessage getKeyedText(@Nonnull String key, @Nullable String fallbackMessage, @Nonnull 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

    • getAllTranslationsForPrefix

      @Nonnull Map<String,String> getAllTranslationsForPrefix(@Nonnull String prefix)
      Given a property key prefix, this method will return all translations where the key starts with the given prefix as key to 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 to translation mappings where i18nKey starts with the prefix. An empty map if no matches.
      Throws:
      NullPointerException - if link is null

    • getAllTranslationsForPrefix

      @Nonnull Map<String,String> getAllTranslationsForPrefix(@Nonnull String prefix, @Nonnull 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 to translation mappings where i18nKey starts with the prefix. An empty map if no matches.
      Throws:
      NullPointerException - if prefix or link are null