Aren/haiku
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
b0e5bfeab5
haiku/docs/user/locale/Catalog.dox
John Scipione 820dca4df6 Big docs cleanup. 
* Fixed headers including:
  - All rights reserved not All Rights Reserved.
  - name, email@domain.com not name <email@domain.com>
  - tabs and spaces
  - Authors: not Documented by:
* Renamed string.dox to String.dox
* Renamed midixxx.dox files to MidiXxx.dox
* Moved images into images subdirectories and updated Doxfile.
* Re-format all files with tabs instead of spaces.
* Fix many spelling mistakes.
* Added all files, classes, structs, and enums to libbe group.
2013-02-07 02:01:19 -05:00

272 lines
9.2 KiB
Plaintext
Raw Blame History

/*
* Copyright 2011-2012 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:
* headers/os/locale/Catalog.h hrev45083
* src/kits/locale/Catalog.cpp hrev45083
*/
/*!
\file Catalog.h
\ingroup locale
\ingroup libbe
\brief Provides the BCatalog class.
*/
/*!
\class BCatalog
\ingroup locale
\ingroup libbe
\brief 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 :
- 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.
- 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_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.
\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:
- Try to load a french(France) catalog. If it is found, this catalog
will automatically include strings from the generic french catalog.
- Try to load a generic french catalog.
- Try to load a generic spanish catalog.
- Try to load a generic english catalog.
- 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()
\brief Construct an empty BCatalog object.
Should be followed by SetTo() method to set the catalog.
*/
/*!
\fn BCatalog::BCatalog(const entry_ref& catalogOwner, const char* language,
uint32 fingerprint)
\brief Construct a BCatalog object 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 BCatalog::~BCatalog()
\brief Destroys the BCatalog object freeing memory used by it.
*/
/*!
\fn const char* BCatalog::GetString(const char* string,
const char* context, const char* comment)
\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 A status code.
\retval B_OK Everything went fine.
\retval B_ERROR Unable to get an exclusive lock on data.
\retval B_NO_INIT Catalog is \c NULL.
\retval B_NAME_NOT_FOUND catalog with the specified \a name could not be
found.
*/
/*!
\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.
\retval B_OK Everything went as expected.
\retval B_ERROR Could not get exclusive lock on catalog.
\retval B_BAD_VALUE \a lang is \c NULL.
\retval B_NO_INIT Catalog data is \c NULL.
*/
/*!
\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.
\retval B_OK Everything went as expected.
\retval B_ERROR Could not get exclusive lock on catalog.
\retval B_BAD_VALUE \a fp is \c NULL.
\retval B_NO_INIT Catalog data is \c NULL.
*/
/*!
\fn status_t BCatalog::SetTo(const entry_ref& catalogOwner,
const char* language, uint32 fingerprint)
\brief Reload the string data.
This method reloads the data for the given signature and fingerprint.
\param catalogOwner The \c entry_ref of the catalog that you want to load.
\param language The language of the catalog to load. If \c NULL, the user
settings will be used.
\param fingerprint The fingerprint of the catalog you want to load.
\returns A status code, \c B_OK on success, \c B_ERROR on error.
*/
/*!
\fn status_t BCatalog::InitCheck() const
\brief Check if the catalog is in a valid and usable state.
\returns A status code.
\retval B_OK The catalog is initialized properly.
\retval B_ERROR Could not get exclusive lock on catalog.
\retval B_NO_INIT Catalog data is \c NULL.
*/
/*!
\fn int32 BCatalog::CountItems()
\brief Gets the number of items in the catalog.
\returns the number of strings in the catalog or 0 on error.
*/
Reference in New Issue View Git Blame Copy Permalink