Public Member Functions | List of all members
BCatalog Class Reference

String localization handling. More...

Public Member Functions

 BCatalog ()
 Construct an empty BCatalog object. More...
 
 BCatalog (const entry_ref &catalogOwner, const char *language=NULL, uint32 fingerprint=0)
 Construct a BCatalog object for the given catalogOwner. More...
 
virtual ~BCatalog ()
 Destroys the BCatalog object freeing memory used by it. More...
 
int32 CountItems () const
 Gets the number of items in the catalog. More...
 
status_t GetData (const char *name, BMessage *msg)
 Get custom data from the catalog. More...
 
status_t GetData (uint32 id, BMessage *msg)
 Get custom data from the catalog. More...
 
status_t GetFingerprint (uint32 *fingerprint)
 Get the catalog fingerprint. More...
 
status_t GetLanguage (BString *language)
 Get the catalog language. More...
 
status_t GetSignature (BString *signature)
 Get the catalog mime-signature. More...
 
const char * GetString (const char *string, const char *context=NULL, const char *comment=NULL)
 Get a string from the catalog. More...
 
const char * GetString (uint32 id)
 Get a string by id from the catalog. More...
 
status_t InitCheck () const
 Check if the catalog is in a valid and usable state. More...
 
status_t SetTo (const entry_ref &catalogOwner, const char *language=NULL, uint32 fingerprint=0)
 Reload the string data. More...
 

Detailed Description

String localization handling.

BCatalog is the class that allows you to perform string localization. This means you give it a string in english, and it automatically returns the translation of this string in the user's specified language, if available.

Most of the time, you don't have to deal with BCatalog directly. You use the translation macros instead. However, there are some cases where you will have to use catalogs directly. These include :

Using the macros

You don't have to do much in your program to handle catalogs. You must first set the B_TRANSLATION_CONTEXT define to a string that identifies which part of the application the strings you will translate are in. This allows the translators to keep track of the strings in the catalog more easily, and find where they are visible in the application. then, all you have to do, is enclose any string you want to make translatable in the B_TRANSLATE() macro. This macro has two uses, it will allow your text to be replaced at run-time by the proper localized one, but it will also allow to build the base catalog, the one that you will send to the translator team, from your sourcecode.

Note that each image (application, library or add-on) using these macros must be linked with liblocalestub.a. This allows the Locale Kit to identify it and locate the matching string catalogs for translation.

Chaining of catalogs

The catalogs you get from the locale kit are designed to use a fallback system so that the user get strings in the language he's the most fluent with, depending on what catalogs are available.

For example, if the user sets his language preferences as French(France), spanish, english, when an application loads a catalog, the following rules are used:

Note that French(France) will failback to French, but then directly to the language in the source code. This avoids mixing 3 or more languages in the same application if the catalogs are incomplete and avoids confusion.

Since
Haiku R1

Constructor & Destructor Documentation

◆ BCatalog() [1/2]

BCatalog::BCatalog ( )

Construct an empty BCatalog object.

Should be followed by SetTo() method to set the catalog.

Since
Haiku R1

◆ BCatalog() [2/2]

BCatalog::BCatalog ( const entry_ref catalogOwner,
const char *  language = NULL,
uint32  fingerprint = 0 
)

Construct a BCatalog object for the given catalogOwner.

If you don't specify a language, the system default list will be used. The language is passed here as a 2 letter ISO code.

The fingerprint is a way to check that the catalog that will be loaded matches the current version of the application. A catalog made for a different version of the application can be loaded if you set the fingerprint to 0. This is usually not a problem, it only means that some strings may not be translated properly. But if you want to provide different versions of your application, it may be useful to separate their catalogs.

Parameters
catalogOwnerentry_ref for which to load a catalog.
languageThe language of the catalog to load. If NULL, the user settings will be used.
fingerprintThe fingerprint version-info for the catalog to load. If 0, the fingerprint will not be checked,and any version of the catalog will be loaded.
Since
Haiku R1

◆ ~BCatalog()

BCatalog::~BCatalog ( )
virtual

Destroys the BCatalog object freeing memory used by it.

Since
Haiku R1

Member Function Documentation

◆ CountItems()

int32 BCatalog::CountItems ( ) const

Gets the number of items in the catalog.

Returns
the number of strings in the catalog or 0 on error.
Since
Haiku R1

◆ GetData() [1/2]

status_t BCatalog::GetData ( const char *  name,
BMessage msg 
)

Get custom data from the catalog.

This method allows you to localize something else than raw text. This may include pictures, sounds, videos, or anything else. Note there is no support for generating a catalog with such data inside, and the current format may not support it. If you need to localize data that is not text, it is advised to handle it by yourself.

Parameters
nameThe name of the data to retrieve.
msgThe BMessage to fill in with the data.
Returns
A status code.
Return values
B_OKEverything went fine.
B_ERRORUnable to get an exclusive lock on data.
B_NO_INITCatalog is NULL.
B_NAME_NOT_FOUNDcatalog with the specified name could not be found.
Since
Haiku R1

◆ GetData() [2/2]

status_t BCatalog::GetData ( uint32  id,
BMessage msg 
)

Get custom data from the catalog.

As for GetString, the id-based version may be subject to hash-collisions, but is faster.

Note the current catalog format doesn't allow storing custom data in catalogs, so the only way to use this method is providing your own catalog add-on for storing the data.

Since
Haiku R1

◆ GetFingerprint()

status_t BCatalog::GetFingerprint ( uint32 *  fp)

Get the catalog fingerprint.

This method setsfp to the fingerprint of the catalog. This allows you to check which version of the sourcecode this catalog was generated from.

Parameters
fpThe integer to set to the fingerprint value.
Returns
An error code.
Return values
B_OKEverything went as expected.
B_ERRORCould not get exclusive lock on catalog.
B_BAD_VALUEfp is NULL.
B_NO_INITCatalog data is NULL.
Since
Haiku R1

◆ GetLanguage()

status_t BCatalog::GetLanguage ( BString lang)

Get the catalog language.

This method fills the lang string with the language name for the catalog.

Parameters
langThe string where to copy the language.
Returns
An error code.
Return values
B_OKEverything went as expected.
B_ERRORCould not get exclusive lock on catalog.
B_BAD_VALUElang is NULL.
B_NO_INITCatalog data is NULL.
Since
Haiku R1

◆ GetSignature()

status_t BCatalog::GetSignature ( BString sig)

Get the catalog mime-signature.

This method fills the sig string with the mime-signature associated to the catalog.

Parameters
sigThe string where to copy the signature.
Returns
An error code.
Since
Haiku R1

◆ GetString() [1/2]

const char * BCatalog::GetString ( const char *  string,
const char *  context = NULL,
const char *  comment = NULL 
)

Get a string from the catalog.

This method access the data of the catalog and returns you the translated version of the string. You must pass it the context where the string is, as the same string may appear somewhere else and need a different translation. The comment is optional. It is meant as an help to translators, when the string alone is not helpful enough or there are special things to note. The comment is also used as a way to uniquely identify a string, so if two identical strings share the same context, it is still possible to provide different translations.

Parameters
stringThe string to translate.
contextThe context where the string is located.
commentSupplementary comment for translators.
Returns
The translated string, or the one passed as a parameter if no translation was found.
Since
Haiku R1

◆ GetString() [2/2]

const char * BCatalog::GetString ( uint32  id)

Get a string by id from the catalog.

The id based version of this method is slightly faster, as it doesn't have to compute the hash from the 3 parameters. However, it will fail if there is an hash collision, so you should still fallback to the first one in case of problems. Also note that the hash value may be different from one catalog to another, depending on the file format they are stored in, so you shouldn't rely on this method unless you are sure you can keep all the catalog files under control.

Parameters
idThe identifier of the string.
Returns
The translated string if found, or an empty string.
Since
Haiku R1

◆ InitCheck()

status_t BCatalog::InitCheck ( ) const

Check if the catalog is in a valid and usable state.

Returns
A status code.
Return values
B_OKThe catalog is initialized properly.
B_ERRORCould not get exclusive lock on catalog.
B_NO_INITCatalog data is NULL.
Since
Haiku R1

◆ SetTo()

status_t BCatalog::SetTo ( const entry_ref catalogOwner,
const char *  language = NULL,
uint32  fingerprint = 0 
)

Reload the string data.

This method reloads the data for the given signature and fingerprint.

Parameters
catalogOwnerThe entry_ref of the catalog that you want to load.
languageThe language of the catalog to load. If NULL, the user settings will be used.
fingerprintThe fingerprint of the catalog you want to load.
Returns
A status code, B_OK on success, B_ERROR on error.
Since
Haiku R1