245 lines
8.3 KiB
Plaintext
245 lines
8.3 KiB
Plaintext
/*
|
|
* Copyright 2011, Haiku, Inc. All Rights Reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* Axel Dörfler, axeld@pinc-software.de
|
|
* John Scipione, jscipione@gmail.com
|
|
* Oliver Tappe, zooey@hirschkaefer.de
|
|
*
|
|
* Corresponds to:
|
|
* /trunk/headers/os/locale/Catalog.h rev 43095
|
|
* /trunk/src/kits/locale/Catalog.cpp rev 43095
|
|
*/
|
|
|
|
|
|
/*!
|
|
\file Catalog.h
|
|
\brief Provides the BCatalog class.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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::Catalog(const entry_ref& catalogOwner,
|
|
const char* language = NULL, uint32 fingerprint = 0);
|
|
\brief Construct a catalog for the given \a 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 \c 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 catalogOwner entry_ref for which to load a catalog.
|
|
\param language The language of the catalog to load. If \c NULL, the user
|
|
settings will be used.
|
|
\param fingerprint The fingerprint version-info for the catalog to load.
|
|
If \c 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.
|
|
|
|
\param string The string to translate.
|
|
\param context The context where the string is located.
|
|
\param comment Supplementary comment for translators.
|
|
|
|
\returns The translated string, or the one passed as a parameter if no
|
|
translation was found.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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.
|
|
|
|
\param id The identifier of the string.
|
|
\returns The translated string if found, or an empty string.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BCatalog::GetData(const char* name, BMessage* msg)
|
|
\brief 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.
|
|
|
|
\param name The name of the data to retrieve.
|
|
\param msg The BMessage to fill in with the data.
|
|
|
|
\returns An error code.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 method 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 method 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 method fills the lang string with the language name for the catalog.
|
|
|
|
\param lang The string where to copy the language.
|
|
|
|
\returns An error code.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BCatalog::GetFingerprint(uint32* fp)
|
|
\brief 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.
|
|
|
|
\param fp The integer to set to the fingerprint value.
|
|
|
|
\returns An error code.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BCatalog::SetCatalog(const entry_ref& catalogOwner,
|
|
uint32 fingerprint)
|
|
\brief Reload the string data.
|
|
|
|
This method reloads the data for the given signature and fingerprint.
|
|
|
|
\param catalogOwner The entry_ref of the catalog that you want to load.
|
|
\param fingerprint The fingerprint of the catalog you want to load.
|
|
|
|
\returns An error code.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BCatalog::InitCheck() const
|
|
\brief Check if the catalog is in an useable state.
|
|
|
|
\returns \c B_OK if the catalog is initialized properly.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BCatalog::CountItems()
|
|
\brief Returns the number of items in the catalog.
|
|
|
|
\returns the number of strings in the catalog.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BCatalogaddOn* BCatalog::CatalogAddOn()
|
|
\brief Returns the internal storage for this catalog.
|
|
|
|
\returns the internal storage class used by this catalog. You should
|
|
not have to use it.
|
|
*/
|