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