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 * <ol>
25 * <li>this method returns the i18ned text formatted with the arguments if the key can be resolved.</li>
26 * <li>otherwise, the key itself will be returned (after formatting).</li>
27 * </ol>
28 *
29 * Arguments may also be of the form {@link Message} which means they will be resolved as well before
30 * being included as an argument. Uses the default locale.
31 *
32 * @param key key for the i18ned message
33 * @param arguments Optional list of arguments for the message.
34 * @return I18ned string
35 */
36 String getText(String key, Serializable... arguments);
37
38 /**
39 * Given a key and a list of arguments:
40 * <ol>
41 * <li>this method returns the i18ned text formatted with the arguments if the key can be resolved.</li>
42 * <li>otherwise, the key itself will be returned (after formatting).</li>
43 * </ol>
44 *
45 * Arguments may also be of the form {@link Message} which means they will be resolved as well before
46 * being included as an argument.
47 *
48 * @param locale the locale to use for the i18ned text
49 * @param key key for the i18ned message
50 * @param arguments Optional list of arguments for the message.
51 * @return I18ned string
52 * @since 2.10
53 */
54 String getText(Locale locale, String key, Serializable... arguments);
55
56 /**
57 * Does the same as {@link #getText(String, java.io.Serializable...)} however it is needed for velocity.
58 * @param key key for the i18ned message
59 * @return I18ned string
60 */
61 String getText(String key);
62
63 /**
64 * Does the same as {@link #getText(Locale, String, java.io.Serializable...)} however it is needed for velocity.
65 * @param locale the locale to use for the i18ned text
66 * @param key key for the i18ned message
67 * @return I18ned string
68 * @since 2.10
69 */
70 String getText(Locale locale, String key);
71
72 /**
73 * Given a {@link Message} this method:
74 * <ol>
75 * <li>returns the i18ned text formatted with the message arguments if the message key can be resolved.</li>
76 * <li>Otherwise, returns the message key (formatted with the message arguments).</li>
77 * </ol>
78 *
79 * Uses the default locale.
80 *
81 * @param message The message to i18n
82 * @return I18ned string
83 */
84 String getText(Message message);
85
86 /**
87 * Given a {@link Message} this method:
88 * <ol>
89 * <li>returns the i18ned text formatted with the message arguments if the message key can be resolved.</li>
90 * <li>Otherwise, returns the message key (formatted with the message arguments).</li>
91 * </ol>
92 *
93 * @param locale the locale to use for the i18ned text
94 * @param message The message to i18n
95 * @return I18ned string
96 * @since 2.10
97 */
98 String getText(Locale locale, Message message);
99
100 /**
101 * Creates an instance of Message.
102 *
103 * @param key The message key
104 * @param arguments The arguments to interpolate
105 * @return The message
106 */
107 Message createMessage(String key, Serializable... arguments);
108
109 /**
110 * @return an instance of MessageCollection.
111 */
112 MessageCollection createMessageCollection();
113
114 /**
115 * Given a prefix, this method will return all translations where the key starts with the given prefix as key ->
116 * value mappings, using the default locale.
117 * <p/>
118 * Plugin developers should avoid calling this method where possible, as it cannot guarantee as good performance
119 * as the other exact key-oriented methods in this interface.
120 *
121 * @param prefix The prefix for a particular key to start with. Empty string will match everything, which may be
122 * slow. Throws {@code NullPointerException} if {@code null}.
123 * @return A Map of i18nKey -> translation mappings where i18nKey starts with the prefix. Empty map if no matches.
124 * @throws NullPointerException if {@code link} is {@code null}
125 * @since 2.1
126 */
127 Map<String, String> getAllTranslationsForPrefix(String prefix);
128
129 /**
130 * Given a prefix, this method will return all translations where the key starts with the given prefix as key ->
131 * value mappings.
132 * <p/>
133 * Plugin developers should avoid calling this method where possible, as it cannot guarantee as good performance
134 * as the other exact key-oriented methods in this interface.
135 *
136 * @param prefix The prefix for a particular key to start with. Empty string will match everything, which may be
137 * slow. Throws {@code NullPointerException} if {@code null}.
138 * @param locale The locale for which to lookup translations. Throws {@code NullPointerException} if {@code null}.
139 * @return A Map of i18nKey -> translation mappings where i18nKey starts with the prefix. Empty map if no matches.
140 * @throws NullPointerException if {@code prefix} or {@code link} are {@code null}
141 */
142 Map<String, String> getAllTranslationsForPrefix(String prefix, Locale locale);
143 }