1/* 2 * Copyright 2011, Haiku, Inc. All Rights Reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Axel Dörfler, axeld@pinc-software.de 7 * John Scipione, jscipione@gmail.com 8 * Oliver Tappe, zooey@hirschkaefer.de 9 * 10 * Corresponds to: 11 * /trunk/headers/os/locale/Catalog.h rev 43095 12 * /trunk/src/kits/locale/Catalog.cpp rev 43095 13 */ 14 15 16/*! 17 \file Catalog.h 18 \brief Provides the BCatalog class. 19*/ 20 21 22/*! 23 \class BCatalog 24 \ingroup locale 25 \brief Class handling string localization. 26 27 BCatalog is the class that allows you to perform string localization. This 28 means you give it a string in english, and it automatically returns the 29 translation of this string in the user's specified language, if available. 30 31 Most of the time, you don't have to deal with BCatalog directly. You use 32 the translation macros instead. However, there are some cases where you 33 will have to use catalogs directly. These include : 34 \li Tools for managing catalogs : if you want to add, remove or edit 35 entries in a catalog, you need to do it using the BCatalog class. 36 \li Accessing catalogs other than your own : the macros only grant you 37 access to the catalog linked with your application. To access 38 other catalogs (for example if you create a script interpreter and 39 want to localize the scripts), you will have to open a catalog 40 associated with your script. 41 42 \section macros Using the macros 43 You don't have to do much in your program to handle catalogs. You must 44 first set the B_TRANSLATION_CONTEXT define to a string that identifies which 45 part of the application the strings you will translate are in. This allows 46 the translators to keep track of the strings in the catalog more easily, 47 and find where they are visible in the application. then, all you have to 48 do, is enclose any string you want to make translatable in the 49 B_TRANSLATE() macro. This macro has two uses, it will allow your text to 50 be replaced at run-time by the proper localized one, but it will also 51 allow to build the base catalog, the one that you will send to the 52 translator team, from your sourcecode. 53 54 \section chaining Chaining of catalogs 55 The catalogs you get from the locale kit are designed to use a fallback 56 system so that the user get strings in the language he's the most fluent 57 with, depending on what catalogs are available. 58 59 For example, if the user sets his language preferences as french(France), 60 spanish, english, when an application loads a catalog, the following rules 61 are used : 62 \li Try to load a french(France) catalog. If it is found, this catalog 63 will automatically include strings from the generic french catalog. 64 \li Try to load a generic french catalog. 65 \li Try to load a generic spanish catalog. 66 \li Try to load a generic english catalog. 67 \li If all of them failed, use the strings that are in the source code. 68 69 Note that french(France) will failback to french, but then directly to the 70 language in the source code. This avoids mixing 3 or more languages in the 71 same application if the catalogs are incomplete and avoids confusion. 72*/ 73 74 75/*! 76 \fn BCatalog::Catalog(const entry_ref& catalogOwner, 77 const char* language = NULL, uint32 fingerprint = 0); 78 \brief Construct a catalog for the given \a catalogOwner. 79 80 If you don't specify a language, the system default list will be used. 81 The language is passed here as a 2 letter ISO code. 82 83 The fingerprint is a way to check that the catalog that will be loaded 84 matches the current version of the application. A catalog made for a 85 different version of the application can be loaded if you set the 86 fingerprint to \c 0. This is usually not a problem, it only means that 87 some strings may not be translated properly. But if you want to provide 88 different versions of your application, it may be useful to separate their 89 catalogs. 90 91 \param catalogOwner entry_ref for which to load a catalog. 92 \param language The language of the catalog to load. If \c NULL, the user 93 settings will be used. 94 \param fingerprint The fingerprint version-info for the catalog to load. 95 If \c 0, the fingerprint will not be checked,and any version of the 96 catalog will be loaded. 97*/ 98 99 100/*! 101 \fn const char* BCatalog::GetString(const char* string, 102 const char* context = NULL, const char* comment = NULL) 103 \brief Get a string from the catalog. 104 105 This method access the data of the catalog and reeturns you the translated 106 version of the string. You must pass it the context where the string is, as 107 the same string may appear somewhere else and need a differnet translation. 108 The comment is optional. It is meant as an help to translators, when the 109 string alone is not helpful enough or there are special things to note. 110 The comment is also used as a way to uniquely identify a string, so if two 111 identical strings share the same context, it is still possible to provide 112 different translations. 113 114 \param string The string to translate. 115 \param context The context where the string is located. 116 \param comment Supplementary comment for translators. 117 118 \returns The translated string, or the one passed as a parameter if no 119 translation was found. 120*/ 121 122 123/*! 124 \fn const char* BCatalog::GetString(uint32 id) 125 \brief Get a string by id from the catalog. 126 127 The id based version of this method is slightly faster, as it doesn't 128 have to compute the hash from the 3 parameters. However, it will fail 129 if there is an hash collision, so you should still fallback to the first 130 one in case of problems. Also note that the hash value may be different 131 from one catalog to another, depending on the file format they are stored 132 in, so you shouldn't rely on this method unless you are sure you can keep 133 all the catalog files under control. 134 135 \param id The identifier of the string. 136 \returns The translated string if found, or an empty string. 137*/ 138 139 140/*! 141 \fn status_t BCatalog::GetData(const char* name, BMessage* msg) 142 \brief Get custom data from the catalog. 143 144 This method allows you to localize something else than raw text. This 145 may include pictures, sounds, videos, or anything else. Note there is no 146 support for generating a catalog with such data inside, and the current 147 format may not support it. If you need to localize data that is not text, 148 it is advised to handle it by yourself. 149 150 \param name The name of the data to retrieve. 151 \param msg The BMessage to fill in with the data. 152 153 \returns An error code. 154*/ 155 156 157/*! 158 \fn status_t BCatalog::GetData(uint32 id, BMessage* msg) 159 \brief Get custom data from the catalog. 160 161 As for GetString, the id-based version may be subject to hash-collisions, 162 but is faster. 163 164 Note the current catalog format doesn't allow storing custom data in 165 catalogs, so the only way to use this method is providing your own 166 catalog add-on for storing the data. 167*/ 168 169 170/*! 171 \fn status_t BCatalog::GetSignature(BString* sig) 172 \brief Get the catalog mime-signature. 173 174 This method fills the sig string with the mime-signature associated to the 175 catalog. 176 177 \param sig The string where to copy the signature. 178 179 \returns An error code. 180*/ 181 182 183/*! 184 \fn status_t BCatalog::GetLanguage(BString* lang) 185 \brief Get the catalog language. 186 187 This method fills the lang string with the language name for the catalog. 188 189 \param lang The string where to copy the language. 190 191 \returns An error code. 192*/ 193 194 195/*! 196 \fn status_t BCatalog::GetFingerprint(uint32* fp) 197 \brief Get the catalog fingerprint. 198 199 This method setsfp to the fingerprint of the catalog. This allows you 200 to check which version of the sourcecode this catalog was generated from. 201 202 \param fp The integer to set to the fingerprint value. 203 204 \returns An error code. 205*/ 206 207 208/*! 209 \fn status_t BCatalog::SetCatalog(const entry_ref& catalogOwner, 210 uint32 fingerprint) 211 \brief Reload the string data. 212 213 This method reloads the data for the given signature and fingerprint. 214 215 \param catalogOwner The entry_ref of the catalog that you want to load. 216 \param fingerprint The fingerprint of the catalog you want to load. 217 218 \returns An error code. 219*/ 220 221 222/*! 223 \fn status_t BCatalog::InitCheck() const 224 \brief Check if the catalog is in an useable state. 225 226 \returns \c B_OK if the catalog is initialized properly. 227*/ 228 229 230/*! 231 \fn int32 BCatalog::CountItems() 232 \brief Returns the number of items in the catalog. 233 234 \returns the number of strings in the catalog. 235*/ 236 237 238/*! 239 \fn BCatalogaddOn* BCatalog::CatalogAddOn() 240 \brief Returns the internal storage for this catalog. 241 242 \returns the internal storage class used by this catalog. You should 243 not have to use it. 244*/ 245