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