OpenShot Library | libopenshot-audio 0.2.0
juce_LocalisedStrings.h
1
2/** @weakgroup juce_core-text
3 * @{
4 */
5/*
6 ==============================================================================
7
8 This file is part of the JUCE library.
9 Copyright (c) 2017 - ROLI Ltd.
10
11 JUCE is an open source library subject to commercial or open-source
12 licensing.
13
14 The code included in this file is provided under the terms of the ISC license
15 http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16 To use, copy, modify, and/or distribute this software for any purpose with or
17 without fee is hereby granted provided that the above copyright notice and
18 this permission notice appear in all copies.
19
20 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22 DISCLAIMED.
23
24 ==============================================================================
25*/
26
27namespace juce
28{
29
30//==============================================================================
31/**
32 Used to convert strings to localised foreign-language versions.
33
34 This is basically a look-up table of strings and their translated equivalents.
35 It can be loaded from a text file, so that you can supply a set of localised
36 versions of strings that you use in your app.
37
38 To use it in your code, simply call the translate() method on each string that
39 might have foreign versions, and if none is found, the method will just return
40 the original string.
41
42 The translation file should start with some lines specifying a description of
43 the language it contains, and also a list of ISO country codes where it might
44 be appropriate to use the file. After that, each line of the file should contain
45 a pair of quoted strings with an '=' sign.
46
47 E.g. for a french translation, the file might be:
48
49 @code
50 language: French
51 countries: fr be mc ch lu
52
53 "hello" = "bonjour"
54 "goodbye" = "au revoir"
55 @endcode
56
57 If the strings need to contain a quote character, they can use '\"' instead, and
58 if the first non-whitespace character on a line isn't a quote, then it's ignored,
59 (you can use this to add comments).
60
61 Note that this is a singleton class, so don't create or destroy the object directly.
62 There's also a TRANS(text) macro defined to make it easy to use the this.
63
64 E.g. @code
65 printSomething (TRANS("hello"));
66 @endcode
67
68 This macro is used in the JUCE classes themselves, so your application has a chance to
69 intercept and translate any internal JUCE text strings that might be shown. (You can easily
70 get a list of all the messages by searching for the TRANS() macro in the JUCE source
71 code).
72
73 @tags{Core}
74*/
76{
77public:
78 //==============================================================================
79 /** Creates a set of translations from the text of a translation file.
80
81 When you create one of these, you can call setCurrentMappings() to make it
82 the set of mappings that the system's using.
83 */
84 LocalisedStrings (const String& fileContents, bool ignoreCaseOfKeys);
85
86 /** Creates a set of translations from a file.
87
88 When you create one of these, you can call setCurrentMappings() to make it
89 the set of mappings that the system's using.
90 */
91 LocalisedStrings (const File& fileToLoad, bool ignoreCaseOfKeys);
92
95
96 /** Destructor. */
98
99 //==============================================================================
100 /** Selects the current set of mappings to be used by the system.
101
102 The object you pass in will be automatically deleted when no longer needed, so
103 don't keep a pointer to it. You can also pass in nullptr to remove the current
104 mappings.
105
106 See also the TRANS() macro, which uses the current set to do its translation.
107
108 @see translateWithCurrentMappings
109 */
110 static void setCurrentMappings (LocalisedStrings* newTranslations);
111
112 /** Returns the currently selected set of mappings.
113
114 This is the object that was last passed to setCurrentMappings(). It may
115 be nullptr if none has been created.
116 */
117 static LocalisedStrings* getCurrentMappings();
118
119 /** Tries to translate a string using the currently selected set of mappings.
120
121 If no mapping has been set, or if the mapping doesn't contain a translation
122 for the string, this will just return the original string.
123
124 See also the TRANS() macro, which uses this method to do its translation.
125
126 @see setCurrentMappings, getCurrentMappings
127 */
128 static String translateWithCurrentMappings (const String& text);
129
130 /** Tries to translate a string using the currently selected set of mappings.
131
132 If no mapping has been set, or if the mapping doesn't contain a translation
133 for the string, this will just return the original string.
134
135 See also the TRANS() macro, which uses this method to do its translation.
136
137 @see setCurrentMappings, getCurrentMappings
138 */
139 static String translateWithCurrentMappings (const char* text);
140
141 //==============================================================================
142 /** Attempts to look up a string and return its localised version.
143 If the string isn't found in the list, the original string will be returned.
144 */
145 String translate (const String& text) const;
146
147 /** Attempts to look up a string and return its localised version.
148 If the string isn't found in the list, the resultIfNotFound string will be returned.
149 */
150 String translate (const String& text, const String& resultIfNotFound) const;
151
152 /** Returns the name of the language specified in the translation file.
153
154 This is specified in the file using a line starting with "language:", e.g.
155 @code
156 language: german
157 @endcode
158 */
159 String getLanguageName() const { return languageName; }
160
161 /** Returns the list of suitable country codes listed in the translation file.
162
163 These is specified in the file using a line starting with "countries:", e.g.
164 @code
165 countries: fr be mc ch lu
166 @endcode
167
168 The country codes are supposed to be 2-character ISO complient codes.
169 */
170 const StringArray& getCountryCodes() const { return countryCodes; }
171
172 /** Provides access to the actual list of mappings. */
173 const StringPairArray& getMappings() const { return translations; }
174
175 //==============================================================================
176 /** Adds and merges another set of translations into this set.
177
178 Note that the language name and country codes of the new LocalisedStrings
179 object must match that of this object - an assertion will be thrown if they
180 don't match.
181
182 Any existing values will have their mappings overwritten by the new ones.
183 */
184 void addStrings (const LocalisedStrings&);
185
186 /** Gives this object a set of strings to use as a fallback if a string isn't found.
187 The object that is passed-in will be owned and deleted by this object
188 when no longer needed. It can be nullptr to clear the existing fallback object.
189 */
190 void setFallback (LocalisedStrings* fallbackStrings);
191
192private:
193 //==============================================================================
194 String languageName;
195 StringArray countryCodes;
196 StringPairArray translations;
197 std::unique_ptr<LocalisedStrings> fallback;
198
199 void loadFromText (const String&, bool ignoreCase);
200
201 JUCE_LEAK_DETECTOR (LocalisedStrings)
202};
203
204//==============================================================================
205#ifndef TRANS
206 /** Uses the LocalisedStrings class to translate the given string literal.
207 This macro is provided for backwards-compatibility, and just calls the translate()
208 function. In new code, it's recommended that you just call translate() directly
209 instead, and avoid using macros.
210 @see translate(), LocalisedStrings
211 */
212 #define TRANS(stringLiteral) juce::translate (stringLiteral)
213#endif
214
215/** A dummy version of the TRANS macro, used to indicate a string literal that should be
216 added to the translation file by source-code scanner tools.
217
218 Wrapping a string literal in this macro has no effect, but by using it around strings
219 that your app needs to translate at a later stage, it lets automatic code-scanning tools
220 find this string and add it to the list of strings that need translation.
221*/
222#define NEEDS_TRANS(stringLiteral) (stringLiteral)
223
224/** Uses the LocalisedStrings class to translate the given string literal.
225 @see LocalisedStrings
226*/
227JUCE_API String translate (const String& stringLiteral);
228
229/** Uses the LocalisedStrings class to translate the given string literal.
230 @see LocalisedStrings
231*/
232JUCE_API String translate (const char* stringLiteral);
233
234/** Uses the LocalisedStrings class to translate the given string literal.
235 @see LocalisedStrings
236*/
237JUCE_API String translate (CharPointer_UTF8 stringLiteral);
238
239/** Uses the LocalisedStrings class to translate the given string literal.
240 @see LocalisedStrings
241*/
242JUCE_API String translate (const String& stringLiteral, const String& resultIfNotFound);
243
244} // namespace juce
245
246/** @}*/
Holds a resizable array of primitive or copy-by-value objects.
Definition juce_Array.h:60
Represents a local file or directory.
Definition juce_File.h:45
Used to convert strings to localised foreign-language versions.
const StringArray & getCountryCodes() const
Returns the list of suitable country codes listed in the translation file.
const StringPairArray & getMappings() const
Provides access to the actual list of mappings.
String getLanguageName() const
Returns the name of the language specified in the translation file.
A special array for holding a list of strings.
A container for holding a set of strings which are keyed by another string.
The JUCE String class!
Definition juce_String.h:43
#define JUCE_API
This macro is added to all JUCE public class declarations.