haiku/docs/user/locale/Catalog.dox

/*!
\class BCatalog
\ingroup locale
\brief Class handling string localization.

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 :
	\li Tools for managing catalogs : if you want to add, remove or edit
entries in a catalog, you need to do it using the BCatalog class.
	\li Accessing catalogs other than your own : the macros only grant you
access to the catalog linked with your application. To access other catalogs
(for example if you create a script interpreter and want to localize the
scripts), you will have to open a catalog associated with your script.

\section macros Using the macros
You don't have to do much in your program to handle catalogs. You must first
set the B_TRANSLATE_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.

\section chaining 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 :
	\li Try to load a french(France) catalog. If it is found, this catalog
		will automatically include strings from the generic french catalog.
	\li Try to load a generic french catalog.
	\li Try to load a generic spanish catalog.
	\li Try to load a generic english catalog.
	\li If all of them failed, use the strings that are in the source code.

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.

*/

/*!
\fn BCatalog::BCatalog(const char* signature, const char* language = NULL, uint32 fingerprint = 0)
\brief Construct a catalog for the given application.

This constructor builds a catalog for the application with the given mime
signature. In Haiku, the mime signature is used as a way to uniquely identify a
catalog and match it with the corresponding application.

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.

\param signature Mime-signature of the application for which to load a catalog.
\param language The language of the catalog to load. If NULL, the user settings
will be used.
\param fingerprint The 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.
*/

/*!
\fn const char* BCatalog::GetString(const char* string, const char* context = NULL, const char* comment = NULL)
\brief Get a string from the catalog.

This method access the data of the catalog and reeturns 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 differnet 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.

\returns The translated string, or the one passed as a parameter if no
translation was found.
\param string The string to translate.
\param context The context where the string is located.
\param comment Supplementary comment for translators.
*/

/*!
\fn const char* BCatalog::GetString(uint32 id)
\brief 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.

\returns The translated string if found, or an empty string.
\param id The identifier of the string.
*/

/*!
\fn const char* BCatalog::GetStringNoAutoCollate(const char* string, const char* context = NULL, const char* comment = NULL)
\fn const char* GetStringNoAutoCollate(uint32 id)
\brief Get a string from the catalog, without registering it for collectcatkeys.

This function does exactly the same thing as GetString, except it will not be
parsed by the collectcatkeys tool. This allows you, for example, to translate a
string constant that you declared at another place, without getting a warning
message from collectcatkeys.

\returns The translated string, or the one passed as a parameter if no
translation was found.
\param string The string to translate.
\param context The context where the string is located.
\param comment Supplementary comment for translators.
*/


/*!
\fn status_t BCatalog::GetData(const char* name, BMessage* msg)
\brief Get custom data from the catalog.

This function allows you to localize something else than raw text. This may
include pictures, sounds, videos, or anything else. Note there is no support for
generatinga 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.

\returns An error code.
\param name The name of the data to retrieve.
\param msg The BMessage to fill in with the data.
*/

/*!
\fn status_t BCatalog::GetData(uint32 id, BMessage* msg)
\brief 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 function is providing your own catalog add-on for
storing the data.
*/

/*!
\fn status_t BCatalog::GetSignature(BString* sig)
\brief Get the catalog mime-signature.

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

\param sig The string where to copy the signature.
\returns An error code.
*/

/*!
\fn status_t BCatalog::GetLanguage(BString* lang)
\brief Get the catalog language.

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

\param sig The string where to copy the language.
\returns An error code.
*/

/*!
\fn status_t BCatalog::GetFingerprint(uint32* fp)
\brief Get the catalog fingerprint.

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

\returns An error code.
\param fp The integer to set to the fingerprint value.
*/

/*!
\fn status_t BCatalog::SetCatalog(const char* signature, uint32 fingerprint)
\brief Reload the string data.

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

\returns An error code.
\param signature The signature of the catalog youwant to load
\param fingerprint The fingerprint of the catalog you want to load.
*/

/*!
\fn status_t BCatalog::InitCheck() const
\brief Check if the catalog is in an useable state.

This function returns B_OK if the catalog is initialized properly.
*/

/*!
\fn int32 BCatalog::CountItems()
\brief Returns the number of items in the catalog.

This function returns the number of strings in the catalog.
*/

/*!
\fn BCatalogaddOn* BCatalog::CatalogAddOn()
\brief Returns the internal storage for this catalog.

This function returns the internal storage class used by this catalog.
You should not have to use it.
*/