221 lines
8.7 KiB
Plaintext
221 lines
8.7 KiB
Plaintext
/*!
|
|
\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 :
|
|
\item 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.
|
|
\item 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 more fluent with,
|
|
depending onwhat isavailable.
|
|
|
|
For example, if the user set hislanguage preferences as french(France), spanish,
|
|
english, when an application loads a catalog, the following rules are used :
|
|
\item Try to load a french(France) catalog. If it is found, this catalog
|
|
will automatically include strings from the generic french catalog.
|
|
\item Try to load a generic french catalog.
|
|
\item Try to load a generic spanish catalog.
|
|
\item Try to load a generic english catalog.
|
|
\item If all of them failed, use the strings that ar ein 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.
|
|
*/
|