1/*! 2\class BCatalog 3\ingroup locale 4\brief Class handling string localization. 5 6BCatalog is the class that allows you to perform string localization. This means 7you give it a string in english, and it automatically returns the translation of 8this string in the user's specified language, if available. 9 10Most of the time, you don't have to deal with BCatalog directly. You use the 11translation macros instead. However, there are some cases where you will have to 12use catalogs directly. These include : 13 \item Tools for managing catalogs : if you want to add, remove or edit 14entries in a catalog, you need to do it using the BCatalog class. 15 \item Accessing catalogs other than your own : the macros only grant you 16access to the catalog linked with your application. To access other catalogs 17(for example if you create a script interpreter and want to localize the 18scripts), you will have to open a catalog associated with your script. 19 20\section macros Using the macros 21You don't have to do much in your program to handle catalogs. You must first 22set the B_TRANSLATE_CONTEXT define to a string that identifies which part of the 23application the strings you will translate are in. This allows the translators 24to keep track of the strings in the catalog more easily, and find where they are 25visible in the application. then, all you have to do, is enclose any string you 26want to make translatable in the B_TRANSLATE() macro. This macro has two uses, 27it will allow your text to be replaced at run-time by the proper localized one, 28but it will also allow to build the base catalog, the one that you will send to 29the translator team, from your sourcecode. 30 31\section chaining Chaining of catalogs 32The catalogs you get from the locale kit are designed to use a fallback system 33so that the user get strings in the language he's the more fluent with, 34depending onwhat isavailable. 35 36For example, if the user set hislanguage preferences as french(France), spanish, 37english, when an application loads a catalog, the following rules are used : 38 \item Try to load a french(France) catalog. If it is found, this catalog 39will automatically include strings from the generic french catalog. 40 \item Try to load a generic french catalog. 41 \item Try to load a generic spanish catalog. 42 \item Try to load a generic english catalog. 43 \item If all of them failed, use the strings that ar ein the source code. 44 45Note that french(France) will failback to french, but then directly to the 46language in the source code. This avoids mixing 3 or more languages in the same 47application if the catalogs are incomplete and avoids confusion. 48 49*/ 50 51/*! 52\fn BCatalog::BCatalog(const char* signature, const char* language = NULL, uint32 fingerprint = 0) 53\brief Construct a catalog for the given application. 54 55This constructor builds a catalog for the application with the given mime 56signature. In Haiku, the mime signature is used as a way to uniquely identify a 57catalog and match it with the corresponding application. 58 59If you don't specify a language, the system default list will be used. 60The language is passed here as a 2 letter ISO code. 61 62The fingerprint is a way to check that the catalog that will be loaded matches 63the current version of the application. A catalog made for a different version 64of the application can be loaded if you set the fingerprint to 0. This is 65usually not a problem, it only means that some strings may not be translated 66properly. But if you want to provide different versions of your application, it 67may be useful to separate their catalogs. 68 69*/ 70 71/*! 72\fn const char* BCatalog::GetString(const char* string, const char* context = NULL, const char* comment = NULL) 73\fn const char* GetString(uint32 id) 74\brief Get a string from the catalog. 75 76This method access the data of the catalog and reeturns you the translated 77version of the string. You must pass it the context where the string is, as 78the same string may appear somewhere else and need a differnet translation. 79The comment is optional. It is meant as an help to translators, when the string 80alone is not helpful enough or there are special things to note. The comment is 81also used as a way to uniquely identify a string, so if two identical strings 82share the same context, it is still possible to provide different translations. 83 84The id based version of this method is slightly faster, as it doesn't have to 85compute the hash from the 3 parameters. However, it will fail if there is an 86hash collision, so you should still fallback to the first one in case of 87problems. Also note that the hash value may be different from one catalog to 88another, depending on the file format they are stored in, so you shouldn't rely 89on this method unless you are sure you can keep all the catalog files under 90control. 91 92*/ 93 94/*! 95\fn const char* BCatalog::GetStringNoAutoCollate(const char* string, const char* context = NULL, const char* comment = NULL) 96\fn const char* GetStringNoAutoCollate(uint32 id) 97\brief Get a string from the catalog, without registering it for collectcatkeys. 98 99This function does exactly the same thing as GetString, except it will not be 100parsed by the collectcatkeys tool. This allows you, for example, to translate a 101string constant that you declared at another place, without getting a warning 102message from collectcatkeys. 103 104*/ 105 106 107/*! 108\fn status_t BCatalog::GetData(const char* name, BMessage* msg) 109\fn status_t BCatalog::GetData(uint32 id, BMessage* msg) 110\brief Get custom data from the catalog. 111 112This function allows you to localize something else than raw text. This may 113include pictures, sounds, videos, or anything else. Note there is no support for 114generatinga catalog with such data inside, and the current format may not 115support it. If you need to localize data that is not text, it is advised to 116handle it by yourself. 117 118*/ 119 120/*! 121\fn status_t BCatalog::GetSignature(BString* sig) 122\brief Get the catalog mime-signature. 123 124This function fills the sig string with the mime-signature associated to the 125catalog. 126 127*/ 128 129/*! 130\fn status_t BCatalog::GetLanguage(BString* lang) 131\brief Get the catalog language. 132 133This function fills the lang string with the language name for the catalog. 134*/ 135 136/*! 137\fn status_t BCatalog::GetFingerprint(uint32* fp) 138\brief Get the catalog fingerprint. 139 140This function setsfp to the fingerprint of the catalog. This allows you to check 141which version of the sourcecode this catalog was generated from. 142*/ 143 144/*! 145\fn status_t BCatalog::SetCatalog(const char* signature, uint32 fingerprint) 146\brief Reload the string data. 147 148This function reloads the data for the given signature and fingerprint. 149*/ 150 151/*! 152\fn status_t BCatalog::InitCheck() 153\brief Check if the catalog is in an useable state. 154 155This function returns B_OK if the catalog is initialized properly. 156*/ 157 158/*! 159\fn int32 BCatalog::CountItems() 160\brief Returns the number of items in the catalog. 161 162This function returns the number of strings in the catalog. 163*/ 164 165/*! 166\fn BCatalogaddOn* BCatalog::CatalogAddOn() 167\brief Returns the internal storage for this catalog. 168 169This function returns the internal storage class used by this catalog. 170You should not have to use it. 171*/ 172