docs/user/locale/Catalog.dox

   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      hrev45083
  12  *              src/kits/locale/Catalog.cpp      hrev45083
  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 for which to load a catalog.
 113         \param language The language of the catalog to load. If \c NULL, the user
 114                settings will be used.
 115         \param fingerprint The fingerprint version-info for the catalog to load.
 116                If \c 0, the fingerprint will not be checked,and any version of the
 117                catalog will be loaded.
 118
 119         \since Haiku R1
 120 */
 121
 122
 123 /*!
 124         \fn BCatalog::~BCatalog()
 125         \brief Destroys the BCatalog object freeing memory used by it.
 126
 127         \since Haiku R1
 128 */
 129
 130
 131 /*!
 132         \fn const char* BCatalog::GetString(const char* string,
 133                 const char* context, const char* comment)
 134         \brief Get a string from the catalog.
 135
 136         This method access the data of the catalog and returns you the translated
 137         version of the string. You must pass it the context where the string is, as
 138         the same string may appear somewhere else and need a different translation.
 139         The comment is optional. It is meant as an help to translators, when the
 140         string alone is not helpful enough or there are special things to note.
 141         The comment is also used as a way to uniquely identify a string, so if two
 142         identical strings share the same context, it is still possible to provide
 143         different translations.
 144
 145         \param string The string to translate.
 146         \param context The context where the string is located.
 147         \param comment Supplementary comment for translators.
 148
 149         \returns The translated string, or the one passed as a parameter if no
 150                  translation was found.
 151
 152         \since Haiku R1
 153 */
 154
 155
 156 /*!
 157         \fn const char* BCatalog::GetString(uint32 id)
 158         \brief Get a string by id from the catalog.
 159
 160         The id based version of this method is slightly faster, as it doesn't
 161         have to compute the hash from the 3 parameters. However, it will fail
 162         if there is an hash collision, so you should still fallback to the first
 163         one in case of problems. Also note that the hash value may be different
 164         from one catalog to another, depending on the file format they are stored
 165         in, so you shouldn't rely on this method unless you are sure you can keep
 166         all the catalog files under control.
 167
 168         \param id The identifier of the string.
 169
 170         \returns The translated string if found, or an empty string.
 171
 172         \since Haiku R1
 173 */
 174
 175
 176 /*!
 177         \fn status_t BCatalog::GetData(const char* name, BMessage* msg)
 178         \brief Get custom data from the catalog.
 179
 180         This method allows you to localize something else than raw text. This
 181         may include pictures, sounds, videos, or anything else. Note there is no
 182         support for generating a catalog with such data inside, and the current
 183         format may not support it. If you need to localize data that is not text,
 184         it is advised to handle it by yourself.
 185
 186         \param name The name of the data to retrieve.
 187         \param msg The BMessage to fill in with the data.
 188
 189         \returns A status code.
 190         \retval B_OK Everything went fine.
 191         \retval B_ERROR Unable to get an exclusive lock on data.
 192         \retval B_NO_INIT Catalog is \c NULL.
 193         \retval B_NAME_NOT_FOUND catalog with the specified \a name could not be
 194                 found.
 195
 196         \since Haiku R1
 197 */
 198
 199
 200 /*!
 201         \fn status_t BCatalog::GetData(uint32 id, BMessage* msg)
 202         \brief Get custom data from the catalog.
 203
 204         As for GetString, the id-based version may be subject to hash-collisions,
 205         but is faster.
 206
 207         Note the current catalog format doesn't allow storing custom data in
 208         catalogs, so the only way to use this method is providing your own
 209         catalog add-on for storing the data.
 210
 211         \since Haiku R1
 212 */
 213
 214
 215 /*!
 216         \fn status_t BCatalog::GetSignature(BString* sig)
 217         \brief Get the catalog mime-signature.
 218
 219         This method fills the sig string with the mime-signature associated to the
 220         catalog.
 221
 222         \param sig The string where to copy the signature.
 223
 224         \returns An error code.
 225
 226         \since Haiku R1
 227 */
 228
 229
 230 /*!
 231         \fn status_t BCatalog::GetLanguage(BString* lang)
 232         \brief Get the catalog language.
 233
 234         This method fills the lang string with the language name for the catalog.
 235
 236         \param lang The string where to copy the language.
 237
 238         \returns An error code.
 239         \retval B_OK Everything went as expected.
 240         \retval B_ERROR Could not get exclusive lock on catalog.
 241         \retval B_BAD_VALUE \a lang is \c NULL.
 242         \retval B_NO_INIT Catalog data is \c NULL.
 243
 244         \since Haiku R1
 245 */
 246
 247
 248 /*!
 249         \fn status_t BCatalog::GetFingerprint(uint32* fp)
 250         \brief Get the catalog fingerprint.
 251
 252         This method setsfp to the fingerprint of the catalog. This allows you
 253         to check which version of the sourcecode this catalog was generated from.
 254
 255         \param fp The integer to set to the fingerprint value.
 256
 257         \returns An error code.
 258         \retval B_OK Everything went as expected.
 259         \retval B_ERROR Could not get exclusive lock on catalog.
 260         \retval B_BAD_VALUE \a fp is \c NULL.
 261         \retval B_NO_INIT Catalog data is \c NULL.
 262
 263         \since Haiku R1
 264 */
 265
 266
 267 /*!
 268         \fn status_t BCatalog::SetTo(const entry_ref& catalogOwner,
 269                 const char* language, uint32 fingerprint)
 270         \brief Reload the string data.
 271
 272         This method reloads the data for the given signature and fingerprint.
 273
 274         \param catalogOwner The \c entry_ref of the catalog that you want to load.
 275         \param language The language of the catalog to load. If \c NULL, the user
 276                settings will be used.
 277         \param fingerprint The fingerprint of the catalog you want to load.
 278
 279         \returns A status code, \c B_OK on success, \c B_ERROR on error.
 280
 281         \since Haiku R1
 282 */
 283
 284
 285 /*!
 286         \fn status_t BCatalog::InitCheck() const
 287         \brief Check if the catalog is in a valid and usable state.
 288
 289         \returns A status code.
 290         \retval B_OK The catalog is initialized properly.
 291         \retval B_ERROR Could not get exclusive lock on catalog.
 292         \retval B_NO_INIT Catalog data is \c NULL.
 293
 294         \since Haiku R1
 295 */
 296
 297
 298 /*!
 299         \fn int32 BCatalog::CountItems() const
 300         \brief Gets the number of items in the catalog.
 301
 302         \returns the number of strings in the catalog or 0 on error.
 303
 304         \since Haiku R1
 305 */