24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
+
+
-
+
-
+
-
-
+
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
|
* @def OF_LOCALIZED
*
* @brief Returns the localized string for the specified ID with the specified
* arguments inserted.
*
* @param ID The ID of the localized string to retrieve
* @return The localized string with the specified arguments replaced
* @throw OFInvalidFormatException The string (either the fallback or the
* localized one) contains an invalid format
*/
#define OF_LOCALIZED(ID, ...) \
[[OFLocale currentLocale] localizedStringForID: ID \
fallback: __VA_ARGS__, nil]
@class OFMutableArray OF_GENERIC(ObjectType);
@class OFDictionary OF_GENERIC(KeyType, ObjectType);
/**
* @class OFLocale OFLocale.h ObjFW/OFLocale.h
*
* @brief A class for querying the locale and retrieving localized strings.
*/
OF_SUBCLASSING_RESTRICTED
@interface OFLocale: OFObject
{
OFString *_Nullable _language, *_Nullable _territory;
OFString *_Nullable _languageCode, *_Nullable _countryCode;
OFStringEncoding _encoding;
OFString *_decimalPoint;
OFString *_decimalSeparator;
OFMutableArray OF_GENERIC(OFDictionary OF_GENERIC(OFString *, id) *)
*_localizedStrings;
}
#ifdef OF_HAVE_CLASS_PROPERTIES
@property (class, readonly, nullable, nonatomic) OFLocale *currentLocale;
@property (class, readonly, nullable, nonatomic) OFString *language;
@property (class, readonly, nullable, nonatomic) OFString *territory;
@property (class, readonly, nullable, nonatomic) OFString *languageCode;
@property (class, readonly, nullable, nonatomic) OFString *countryCode;
@property (class, readonly, nonatomic) OFStringEncoding encoding;
@property (class, readonly, nullable, nonatomic) OFString *decimalPoint;
@property (class, readonly, nullable, nonatomic) OFString *decimalSeparator;
#endif
/**
* @brief The language of the locale for messages.
* @brief The language code of the locale for messages.
*
* If the language is unknown, it is `nil`.
*/
@property OF_NULLABLE_PROPERTY (readonly, nonatomic) OFString *language;
@property OF_NULLABLE_PROPERTY (readonly, nonatomic) OFString *languageCode;
/**
* @brief The territory of the locale for messages.
* @brief The country code of the locale for messages.
*
* If the territory is unknown, it is `nil`.
*/
@property OF_NULLABLE_PROPERTY (readonly, nonatomic) OFString *territory;
@property OF_NULLABLE_PROPERTY (readonly, nonatomic) OFString *countryCode;
/**
* @brief The native 8-bit string encoding of the locale for messages.
*
* This is useful to encode strings correctly for passing them to operating
* system calls.
*
* If the native 8-bit encoding is unknown, UTF-8 is assumed.
*/
@property (readonly, nonatomic) OFStringEncoding encoding;
/**
* @brief The decimal point of the system's locale.
* @brief The decimal separator of the locale.
*/
@property (readonly, nonatomic) OFString *decimalPoint;
@property (readonly, nonatomic) OFString *decimalSeparator;
/**
* @brief Returns the current OFLocale.
*
* @warning If you don't use @ref OFApplication, this might be `nil`! In this
* case, you need to manually allocate an instance and call
* @ref init once.
*
* @return The current OFLocale instance
*/
+ (nullable OFLocale *)currentLocale;
/**
* @brief Returns the language of the locale.
* @brief Returns the language code of the locale.
*
* If the language is unknown, `nil` is returned.
*
* @return The language of the locale.
* @return The language code of the locale.
*/
+ (nullable OFString *)language;
+ (nullable OFString *)languageCode;
/**
* @brief Returns the territory of the locale.
* @brief Returns the country code of the locale.
*
* If the territory is unknown, `nil` is returned.
* If the country is unknown, `nil` is returned.
*
* @return The territory of the locale.
* @return The country code of the locale.
*/
+ (nullable OFString *)territory;
+ (nullable OFString *)countryCode;
/**
* @brief Returns the native 8-bit string encoding for the locale.
*
* This is useful to encode strings correctly for passing them to operating
* system calls.
*
* If the native 8-bit encoding is unknown, UTF-8 is assumed.
*
* @return The native 8-bit string encoding for the locale
*/
+ (OFStringEncoding)encoding;
/**
* @brief Returns the decimal point of the system's locale.
*
* @return The decimal point of the system's locale
*/
+ (nullable OFString *)decimalPoint;
+ (nullable OFString *)decimalSeparator;
#ifdef OF_HAVE_FILES
/**
* @brief Adds a directory to scan for language files.
* @brief Adds a directory to scan for localizations.
*
* @param path The path to the directory to scan for language files
* @param path The path to the directory to scan for localizations
*/
+ (void)addLanguageDirectory: (OFString *)path;
+ (void)addLocalizationDirectory: (OFString *)path;
#endif
/**
* @brief Initializes the current OFLocale.
*
* @warning This sets the locale via `setlocale()`!
*
* @warning You should never call this yourself, except if you do not use
* @ref OFApplication. In this case, you need to allocate exactly one
* instance of OFLocale, which will become the current locale, and
* call this method.
*/
- (instancetype)init;
#ifdef OF_HAVE_FILES
/**
* @brief Adds a directory to scan for language files.
* @brief Adds a directory to scan for localizations.
*
* @param path The path to the directory to scan for language files
* @param path The path to the directory to scan for localizations
*/
- (void)addLanguageDirectory: (OFString *)path;
- (void)addLocalizationDirectory: (OFString *)path;
#endif
/**
* @brief Returns the localized string for the specified ID, using the fallback
* string if it cannot be looked up or is missing.
*
* @note This takes a variadic argument, terminated by `nil`, that consists of
* pairs of variable names and variable values, which will be replaced
* inside the localized string. For example, you can pass
* `@"name", @"foo", nil`, causing `%[name]` to be replaced with `foo` in
* the localized string.
*
* @note Generally, you want to use @ref OF_LOCALIZED instead, which also takes
* care of the `nil` sentinel automatically.
*
* @param ID The ID for the localized string
* @param fallback The fallback to use in case the localized string cannot be
* looked up or is missing. This can also be an array and use
* plural scripting, just like with the JSON language files.
* plural scripting, just like with the JSON localization files.
* @return The localized string
*/
- (OFString *)localizedStringForID: (OFConstantString *)ID
fallback: (id)fallback, ... OF_SENTINEL;
/**
* @brief Returns the localized string for the specified ID, using the fallback
|
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
-
+
+
+
|
*
* @note Generally, you want to use @ref OF_LOCALIZED instead, which also takes
* care of the `nil` sentinel automatically.
*
* @param ID The ID for the localized string
* @param fallback The fallback to use in case the localized string cannot be
* looked up or is missing. This can also be an array and use
* plural scripting, just like with the JSON language files.
* plural scripting, just like with the JSON localization files.
* @param arguments A va_list of arguments, consisting of pairs of variable
* names and values to replace in the localized string,
* terminated with `nil`
* @return The localized string
* @throw OFInvalidFormatException The string (either the fallback or the
* localized one) contains an invalid format
*/
- (OFString *)localizedStringForID: (OFConstantString *)ID
fallback: (id)fallback
arguments: (va_list)arguments;
@end
OF_ASSUME_NONNULL_END
|