1 package com.atlassian.sal.api.message;
2
3 import java.io.Serializable;
4 import java.util.Locale;
5 import java.util.Map;
6
7 /**
8 * This interface is responsible for resolving a message or key/argument pairs to
9 * their internationalized message.
10 *
11 * @since 2.0
12 */
13 public interface I18nResolver
14 {
15 /**
16 * Retrieve the unformatted message text associated with this key.
17 * @param key key for the i18ned message
18 * @return the unformatted message text if key is found, otherwise returns key itself.
19 */
20 String getRawText(String key);
21
22 /**
23 * Given a key and a list of arguments:-
24 * 1) this method returns the i18ned text formatted with the arguments if the key can be resolved.
25 * 2) otherwise, the key itself will be returned (after formatting).
26 *
27 * Arguments may also be of the form {@link Message} which means they will be resolved as well before
28 * being included as an argument.
29 *
30 * @param key key for the i18ned message
31 * @param arguments Optional list of arguments for the message.
32 * @return I18ned string
33 */
34 String getText(String key, Serializable... arguments);
35
36 /**
37 * Does the same as {@link #getText(String, java.io.Serializable...)} however it is needed for velocity.
38 * @param key key for the i18ned message
39 * @return I18ned string
40 */
41 String getText(String key);
42
43 /**
44 * Given a {@link Message} this method:-
45 * 1) returns the i18ned text formatted with the message arguments if the message key can be resolved.
46 * 2) Otherwise, returns the message key (formatted with the message arguments).
47 *
48 * @param message The message to i18n
49 * @return I18ned string
50 */
51 String getText(Message message);
52
53 /**
54 * Creates an instance of Message.
55 *
56 * @param key The message key
57 * @param arguments The arguments to interpolate
58 * @return The message
59 */
60 Message createMessage(String key, Serializable... arguments);
61
62 /**
63 * @return an instance of MessageCollection.
64 */
65 MessageCollection createMessageCollection();
66
67 /**
68 * Given a prefix, this method will return all translations where the key starts with the given prefix as key ->
69 * value mappings, using the default locale.
70 *
71 * @param prefix The prefix for a particular key to start with. Empty string will match everything, which may be
72 * slow. Throws {@code NullPointerException} if {@code null}.
73 * @return A Map of i18nKey -> translation mappings where i18nKey starts with the prefix. Empty map if no matches.
74 * @throws NullPointerException if {@code link} is {@code null}
75 * @since 2.1
76 */
77 Map<String, String> getAllTranslationsForPrefix(String prefix);
78
79 /**
80 * Given a prefix, this method will return all translations where the key starts with the given prefix as key ->
81 * value mappings.
82 *
83 * @param prefix The prefix for a particular key to start with. Empty string will match everything, which may be
84 * slow. Throws {@code NullPointerException} if {@code null}.
85 * @param locale The locale for which to lookup translations. Throws {@code NullPointerException} if {@code null}.
86 * @return A Map of i18nKey -> translation mappings where i18nKey starts with the prefix. Empty map if no matches.
87 * @throws NullPointerException if {@code prefix} or {@code link} are {@code null}
88 */
89 Map<String, String> getAllTranslationsForPrefix(String prefix, Locale locale);
90 }