1/* 2 * Copyright 2011-2012 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 * headers/os/locale/Catalog.h hrev54533 12 * src/kits/locale/Catalog.cpp hrev54533 13 */ 14 15 16/*! 17 \file Catalog.h 18 \ingroup locale 19 \ingroup libbe 20 \brief Provides the BCatalog class. 21*/ 22 23 24/*! 25 \class BCatalog 26 \ingroup locale 27 \ingroup libbe 28 \brief String localization handling. 29 30 BCatalog is the class that allows you to perform string localization. This 31 means you give it a string in english, and it automatically returns the 32 translation of this string in the user's specified language, if available. 33 34 Most of the time, you don't have to deal with BCatalog directly. You use 35 the translation macros instead. However, there are some cases where you 36 will have to use catalogs directly. These include : 37 - Tools for managing catalogs : if you want to add, remove or edit 38 entries in a catalog, you need to do it using the BCatalog class. 39 - Accessing catalogs other than your own : the macros only grant you 40 access to the catalog linked with your application. To access 41 other catalogs (for example if you create a script interpreter and 42 want to localize the scripts), you will have to open a catalog 43 associated with your script. 44 45 \section macros Using the macros 46 47 You don't have to do much in your program to handle catalogs. You must 48 first set the B_TRANSLATION_CONTEXT define to a string that identifies which 49 part of the application the strings you will translate are in. This allows 50 the translators to keep track of the strings in the catalog more easily, 51 and find where they are visible in the application. then, all you have to 52 do, is enclose any string you want to make translatable in the 53 B_TRANSLATE() macro. This macro has two uses, it will allow your text to 54 be replaced at run-time by the proper localized one, but it will also 55 allow to build the base catalog, the one that you will send to the 56 translator team, from your sourcecode. 57 58 Note that each image (application, library or add-on) using these macros 59 must be linked with liblocalestub.a. This allows the Locale Kit to identify 60 it and locate the matching string catalogs for translation. 61 62 \section chaining Chaining of catalogs 63 64 The catalogs you get from the locale kit are designed to use a fallback 65 system so that the user get strings in the language he's the most fluent 66 with, depending on what catalogs are available. 67 68 For example, if the user sets his language preferences as French(France), 69 spanish, english, when an application loads a catalog, the following rules 70 are used: 71 - Try to load a French(France) catalog. If it is found, this catalog 72 will automatically include strings from the generic french catalog. 73 - Try to load a generic french catalog. 74 - Try to load a generic spanish catalog. 75 - Try to load a generic english catalog. 76 - If all of them failed, use the strings that are in the source code. 77 78 Note that French(France) will failback to French, but then directly to the 79 language in the source code. This avoids mixing 3 or more languages in the 80 same application if the catalogs are incomplete and avoids confusion. 81 82 \since Haiku R1 83*/ 84 85 86/*! 87 \fn BCatalog::BCatalog() 88 \brief Construct an empty BCatalog object. 89 90 Should be followed by SetTo() method to set the catalog. 91 92 \since Haiku R1 93*/ 94 95 96/*! 97 \fn BCatalog::BCatalog(const entry_ref& catalogOwner, const char* language, 98 uint32 fingerprint) 99 \brief Construct a BCatalog object for the given \a catalogOwner. 100 101 If you don't specify a language, the system default list will be used. 102 The language is passed here as a 2 letter ISO code. 103 104 The fingerprint is a way to check that the catalog that will be loaded 105 matches the current version of the application. A catalog made for a 106 different version of the application can be loaded if you set the 107 fingerprint to \c 0. This is usually not a problem, it only means that 108 some strings may not be translated properly. But if you want to provide 109 different versions of your application, it may be useful to separate their 110 catalogs. 111 112 \param catalogOwner entry_ref or application, add-on or library for which 113 to load a catalog. 114 \param language The language of the catalog to load. If \c NULL, the user 115 settings will be used. 116 \param fingerprint The fingerprint version-info for the catalog to load. 117 If \c 0, the fingerprint will not be checked,and any version of the 118 catalog will be loaded. 119 120 \since Haiku R1 121*/ 122 123 124/*! 125 \fn BCatalog::BCatalog(const char* signature, const char* language) 126 \brief Construct a BCatalog object for the given application \a signature. 127 128 If you don't specify a language, the system default list will be used. 129 The language is passed here as a 2 letter ISO code. 130 131 This constructor is used to load catalogs that are not related to an 132 executable or library file (so there is no entry_ref usable to identify the 133 catalog). As it uses only the MIME signature, it cannot load catalogs from 134 application resources or a catalog file located next to the application. 135 Only the catalogs in the standard system directories (data/locale/catalogs) 136 are checked. Moreover, only the default catalog format is available, not 137 custom formats from catalog add-ons. 138 139 \param signature MIME signature for which to load a catalog. 140 \param language The language of the catalog to load. If \c NULL, the user 141 settings will be used. 142 143 \since Haiku R1 144*/ 145 146 147/*! 148 \fn BCatalog::~BCatalog() 149 \brief Destroys the BCatalog object freeing memory used by it. 150 151 \since Haiku R1 152*/ 153 154 155/*! 156 \fn const char* BCatalog::GetString(const char* string, 157 const char* context, const char* comment) 158 \brief Get a string from the catalog. 159 160 This method access the data of the catalog and returns you the translated 161 version of the string. You must pass it the context where the string is, as 162 the same string may appear somewhere else and need a different translation. 163 The comment is optional. It is meant as an help to translators, when the 164 string alone is not helpful enough or there are special things to note. 165 The comment is also used as a way to uniquely identify a string, so if two 166 identical strings share the same context, it is still possible to provide 167 different translations. 168 169 \param string The string to translate. 170 \param context The context where the string is located. 171 \param comment Supplementary comment for translators. 172 173 \returns The translated string, or the one passed as a parameter if no 174 translation was found. 175 176 \since Haiku R1 177*/ 178 179 180/*! 181 \fn const char* BCatalog::GetString(uint32 id) 182 \brief Get a string by id from the catalog. 183 184 The id based version of this method is slightly faster, as it doesn't 185 have to compute the hash from the 3 parameters. However, it will fail 186 if there is an hash collision, so you should still fallback to the first 187 one in case of problems. Also note that the hash value may be different 188 from one catalog to another, depending on the file format they are stored 189 in, so you shouldn't rely on this method unless you are sure you can keep 190 all the catalog files under control. 191 192 \param id The identifier of the string. 193 194 \returns The translated string if found, or an empty string. 195 196 \since Haiku R1 197*/ 198 199 200/*! 201 \fn status_t BCatalog::GetData(const char* name, BMessage* msg) 202 \brief Get custom data from the catalog. 203 204 This method allows you to localize something else than raw text. This 205 may include pictures, sounds, videos, or anything else. Note there is no 206 support for generating a catalog with such data inside, and the current 207 format may not support it. If you need to localize data that is not text, 208 it is advised to handle it by yourself. 209 210 \param name The name of the data to retrieve. 211 \param msg The BMessage to fill in with the data. 212 213 \returns A status code. 214 \retval B_OK Everything went fine. 215 \retval B_ERROR Unable to get an exclusive lock on data. 216 \retval B_NO_INIT Catalog is \c NULL. 217 \retval B_NAME_NOT_FOUND catalog with the specified \a name could not be 218 found. 219 220 \since Haiku R1 221*/ 222 223 224/*! 225 \fn status_t BCatalog::GetData(uint32 id, BMessage* msg) 226 \brief Get custom data from the catalog. 227 228 As for GetString, the id-based version may be subject to hash-collisions, 229 but is faster. 230 231 Note the current catalog format doesn't allow storing custom data in 232 catalogs, so the only way to use this method is providing your own 233 catalog add-on for storing the data. 234 235 \since Haiku R1 236*/ 237 238 239/*! 240 \fn status_t BCatalog::GetSignature(BString* sig) 241 \brief Get the catalog mime-signature. 242 243 This method fills the sig string with the mime-signature associated to the 244 catalog. 245 246 \param sig The string where to copy the signature. 247 248 \returns An error code. 249 250 \since Haiku R1 251*/ 252 253 254/*! 255 \fn status_t BCatalog::GetLanguage(BString* lang) 256 \brief Get the catalog language. 257 258 This method fills the lang string with the language name for the catalog. 259 260 \param lang The string where to copy the language. 261 262 \returns An error code. 263 \retval B_OK Everything went as expected. 264 \retval B_ERROR Could not get exclusive lock on catalog. 265 \retval B_BAD_VALUE \a lang is \c NULL. 266 \retval B_NO_INIT Catalog data is \c NULL. 267 268 \since Haiku R1 269*/ 270 271 272/*! 273 \fn status_t BCatalog::GetFingerprint(uint32* fp) 274 \brief Get the catalog fingerprint. 275 276 This method setsfp to the fingerprint of the catalog. This allows you 277 to check which version of the sourcecode this catalog was generated from. 278 279 \param fp The integer to set to the fingerprint value. 280 281 \returns An error code. 282 \retval B_OK Everything went as expected. 283 \retval B_ERROR Could not get exclusive lock on catalog. 284 \retval B_BAD_VALUE \a fp is \c NULL. 285 \retval B_NO_INIT Catalog data is \c NULL. 286 287 \since Haiku R1 288*/ 289 290 291/*! 292 \fn status_t BCatalog::SetTo(const entry_ref& catalogOwner, 293 const char* language, uint32 fingerprint) 294 \brief Reload the string data. 295 296 This method reloads the data for the given file, language and fingerprint. 297 298 \param catalogOwner The \c entry_ref of the application, add-on or library 299 for which you want to load a catalog. 300 \param language The language of the catalog to load. If \c NULL, the user 301 settings will be used. 302 \param fingerprint The fingerprint of the catalog you want to load. 303 304 \returns A status code, \c B_OK on success, \c B_ERROR on error. 305 306 \since Haiku R1 307*/ 308 309 310/*! 311 \fn status_t BCatalog::SetTo(const char* signature, 312 const char* language = \c NULL) 313 \brief Reload the string data. 314 315 This method reloads the data for the given signature and language. 316 317 \param signature The MIME signature identifying the catalog to load. 318 \param language The language of the catalog to load. If \c NULL, the user 319 settings will be used. 320 321 \returns A status code, \c B_OK on success, \c B_ERROR on error. 322 323 \since Haiku R1 324*/ 325 326 327/*! 328 \fn status_t BCatalog::InitCheck() const 329 \brief Check if the catalog is in a valid and usable state. 330 331 \returns A status code. 332 \retval B_OK The catalog is initialized properly. 333 \retval B_ERROR Could not get exclusive lock on catalog. 334 \retval B_NO_INIT Catalog data is \c NULL. 335 336 \since Haiku R1 337*/ 338 339 340/*! 341 \fn int32 BCatalog::CountItems() const 342 \brief Gets the number of items in the catalog. 343 344 \returns the number of strings in the catalog or 0 on error. 345 346 \since Haiku R1 347*/ 348