juce/source/src/text/juce_LocalisedStrings.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_LOCALISEDSTRINGS_JUCEHEADER__
  27 #define __JUCE_LOCALISEDSTRINGS_JUCEHEADER__
  28
  29 #include "juce_StringPairArray.h"
  30 #include "../core/juce_Singleton.h"
  31 #include "../io/files/juce_File.h"
  32
  33
  34 //==============================================================================
  35 /** Used in the same way as the T(text) macro, this will attempt to translate a
  36     string into a localised version using the LocalisedStrings class.
  37
  38     @see LocalisedStrings
  39 */
  40 #define TRANS(stringLiteral) \
  41     JUCE_NAMESPACE::LocalisedStrings::translateWithCurrentMappings (stringLiteral)
  42
  43
  44
  45 //==============================================================================
  46 /**
  47     Used to convert strings to localised foreign-language versions.
  48
  49     This is basically a look-up table of strings and their translated equivalents.
  50     It can be loaded from a text file, so that you can supply a set of localised
  51     versions of strings that you use in your app.
  52
  53     To use it in your code, simply call the translate() method on each string that
  54     might have foreign versions, and if none is found, the method will just return
  55     the original string.
  56
  57     The translation file should start with some lines specifying a description of
  58     the language it contains, and also a list of ISO country codes where it might
  59     be appropriate to use the file. After that, each line of the file should contain
  60     a pair of quoted strings with an '=' sign.
  61
  62     E.g. for a french translation, the file might be:
  63
  64     @code
  65     language: French
  66     countries: fr be mc ch lu
  67
  68     "hello" = "bonjour"
  69     "goodbye" = "au revoir"
  70     @endcode
  71
  72     If the strings need to contain a quote character, they can use '\"' instead, and
  73     if the first non-whitespace character on a line isn't a quote, then it's ignored,
  74     (you can use this to add comments).
  75
  76     Note that this is a singleton class, so don't create or destroy the object directly.
  77     There's also a TRANS(text) macro defined to make it easy to use the this.
  78
  79     E.g. @code
  80     printSomething (TRANS("hello"));
  81     @endcode
  82
  83     This macro is used in the Juce classes themselves, so your application has a chance to
  84     intercept and translate any internal Juce text strings that might be shown. (You can easily
  85     get a list of all the messages by searching for the TRANS() macro in the Juce source
  86     code).
  87 */
  88 class JUCE_API  LocalisedStrings
  89 {
  90 public:
  91     //==============================================================================
  92     /** Creates a set of translations from the text of a translation file.
  93
  94         When you create one of these, you can call setCurrentMappings() to make it
  95         the set of mappings that the system's using.
  96     */
  97     LocalisedStrings (const String& fileContents);
  98
  99     /** Creates a set of translations from a file.
 100
 101         When you create one of these, you can call setCurrentMappings() to make it
 102         the set of mappings that the system's using.
 103     */
 104     LocalisedStrings (const File& fileToLoad);
 105
 106     /** Destructor. */
 107     ~LocalisedStrings();
 108
 109     //==============================================================================
 110     /** Selects the current set of mappings to be used by the system.
 111
 112         The object you pass in will be automatically deleted when no longer needed, so
 113         don't keep a pointer to it. You can also pass in zero to remove the current
 114         mappings.
 115
 116         See also the TRANS() macro, which uses the current set to do its translation.
 117
 118         @see translateWithCurrentMappings
 119     */
 120     static void setCurrentMappings (LocalisedStrings* newTranslations);
 121
 122     /** Returns the currently selected set of mappings.
 123
 124         This is the object that was last passed to setCurrentMappings(). It may
 125         be 0 if none has been created.
 126     */
 127     static LocalisedStrings* getCurrentMappings();
 128
 129     /** Tries to translate a string using the currently selected set of mappings.
 130
 131         If no mapping has been set, or if the mapping doesn't contain a translation
 132         for the string, this will just return the original string.
 133
 134         See also the TRANS() macro, which uses this method to do its translation.
 135
 136         @see setCurrentMappings, getCurrentMappings
 137     */
 138     static String translateWithCurrentMappings (const String& text);
 139
 140     /** Tries to translate a string using the currently selected set of mappings.
 141
 142         If no mapping has been set, or if the mapping doesn't contain a translation
 143         for the string, this will just return the original string.
 144
 145         See also the TRANS() macro, which uses this method to do its translation.
 146
 147         @see setCurrentMappings, getCurrentMappings
 148     */
 149     static String translateWithCurrentMappings (const char* text);
 150
 151     //==============================================================================
 152     /** Attempts to look up a string and return its localised version.
 153
 154         If the string isn't found in the list, the original string will be returned.
 155     */
 156     String translate (const String& text) const;
 157
 158     /** Returns the name of the language specified in the translation file.
 159
 160         This is specified in the file using a line starting with "language:", e.g.
 161         @code
 162         language: german
 163         @endcode
 164     */
 165     String getLanguageName() const                        { return languageName; }
 166
 167     /** Returns the list of suitable country codes listed in the translation file.
 168
 169         These is specified in the file using a line starting with "countries:", e.g.
 170         @code
 171         countries: fr be mc ch lu
 172         @endcode
 173
 174         The country codes are supposed to be 2-character ISO complient codes.
 175     */
 176     const StringArray& getCountryCodes() const            { return countryCodes; }
 177
 178
 179     //==============================================================================
 180     /** Indicates whether to use a case-insensitive search when looking up a string.
 181         This defaults to true.
 182     */
 183     void setIgnoresCase (bool shouldIgnoreCase);
 184
 185 private:
 186     //==============================================================================
 187     String languageName;
 188     StringArray countryCodes;
 189     StringPairArray translations;
 190
 191     void loadFromText (const String& fileContents);
 192
 193     JUCE_LEAK_DETECTOR (LocalisedStrings);
 194 };
 195
 196
 197 #endif   // __JUCE_LOCALISEDSTRINGS_JUCEHEADER__