OpenShot Library | OpenShotAudio  0.2.2
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 
27 namespace 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 {
77 public:
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 
94  LocalisedStrings& operator= (const LocalisedStrings&);
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 compliant 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 
192 private:
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 */
227 JUCE_API String translate (const String& stringLiteral);
228 
229 /** Uses the LocalisedStrings class to translate the given string literal.
230  @see LocalisedStrings
231 */
232 JUCE_API String translate (const char* stringLiteral);
233 
234 /** Uses the LocalisedStrings class to translate the given string literal.
235  @see LocalisedStrings
236 */
237 JUCE_API String translate (CharPointer_UTF8 stringLiteral);
238 
239 /** Uses the LocalisedStrings class to translate the given string literal.
240  @see LocalisedStrings
241 */
242 JUCE_API String translate (const String& stringLiteral, const String& resultIfNotFound);
243 
244 } // namespace juce
245 
246 /** @}*/
String getLanguageName() const
Returns the name of the language specified in the translation file.
#define JUCE_API
This macro is added to all JUCE public class declarations.
A special array for holding a list of strings.
The JUCE String class!
Definition: juce_String.h:42
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.
Represents a local file or directory.
Definition: juce_File.h:44
A container for holding a set of strings which are keyed by another string.
const StringPairArray & getMappings() const
Provides access to the actual list of mappings.
Wraps a pointer to a null-terminated UTF-8 character string, and provides various methods to operate ...