76 lines
3.7 KiB
Plaintext
76 lines
3.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 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.
|
||
|
|
|
||
|
|
*/
|
||
|
|
|
||
|
|
/*!
|
||
|
|
\fn 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.
|
||
|
|
|
||
|
|
*/
|
||
|
|
|
||
|
|
/*!
|
||
|
|
\fn const char* GetString(const char* string, const char* context = NULL, const char* comment = NULL)
|
||
|
|
\fn const char* GetString(uint32 id)
|
||
|
|
\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.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
*/
|
||
|
|
|