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:

• getMessage(String, Object[])
• createKeyedMessage(String, Object[])
• getMessagePattern(String)

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 and 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(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	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	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	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	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.
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.

Method Detail

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