[wxWidgets.git] / interface / wx / translation.h

/////////////////////////////////////////////////////////////////////////////
// Name:        translation.h
// Purpose:     wxTranslation class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////


/**
    This class allows to get translations for strings.

    In wxWidgets this class manages message catalogs which contain the
    translations of the strings used to the current language. Unlike wxLocale,
    it isn't bound to locale. It can be used either independently of, or in
    conjunction with wxLocale. In the latter case, you should initialize
    wxLocale (which creates wxTranslations instance) first; in the former, you
    need to create a wxTranslations object and Set() it manually.

    Only one wxTranslations instance is active at a time; it is set with the
    Set() method and obtained using Get().

    Unlike wxLocale, wxTranslations' primary mean of identifying language
    is by its "canonical name", i.e. ISO 639 code, possibly combined with
    ISO 3166 country code and additional modifiers (examples include
    "fr", "en_GB" or "ca@valencia"; see wxLocale::GetCanonicalName() for
    more information). This allows apps using wxTranslations API to use even
    languages not recognized by the operating system or not listed in
    wxLanguage enum.

    @since 2.9.1

    @see wxLocale
 */
class wxTranslations
{
public:
    /// Constructor
    wxTranslations();

    /**
        Returns current translations object, may return NULL.

        You must either call this early in app initialization code, or let
        wxLocale do it for you.
     */
    static wxTranslations *Get();

    /**
        Sets current translations object.

        Deletes previous translation object and takes ownership of @a t.
     */
    static void Set(wxTranslations *t);

    /**
        Changes loader use to read catalogs to a non-default one.

        Deletes previous loader and takes ownership of @a loader.

        @see wxTranslationsLoader, wxFileTranslationsLoader, wxResourceTranslationsLoader
     */
    void SetLoader(wxTranslationsLoader *loader);

    /**
        Sets translations language to use.

        wxLANGUAGE_DEFAULT has special meaning: best suitable translation,
        given user's preference and available translations, will be used.
     */
    void SetLanguage(wxLanguage lang);

    /**
        Sets translations language to use.

        Empty @a lang string has the same meaning as wxLANGUAGE_DEFAULT in
        SetLanguage(wxLanguage): best suitable translation, given user's
        preference and available translations, will be used.
     */
    void SetLanguage(const wxString& lang);

    /**
        Add standard wxWidgets catalogs ("wxstd" and possible port-specific
        catalogs).

        @return @true if a suitable catalog was found, @false otherwise

        @see AddCatalog()
     */
    bool AddStdCatalog();

    /**
        Add a catalog for use with the current locale.

        By default, it is searched for in standard places (see
        wxFileTranslationsLoader), but you may also prepend additional
        directories to the search path with
        wxFileTranslationsLoader::AddCatalogLookupPathPrefix().

        All loaded catalogs will be used for message lookup by GetString() for
        the current locale.

        In this overload, @c msgid strings are assumed
        to be in English and written only using 7-bit ASCII characters.
        If you have to deal with non-English strings or 8-bit characters in the
        source code, see the instructions in @ref overview_nonenglish.

        @return
            @true if catalog was successfully loaded, @false otherwise (which might
            mean that the catalog is not found or that it isn't in the correct format).
     */
    bool AddCatalog(const wxString& domain);

    /**
        Same as AddCatalog(const wxString&), but takes an additional argument,
        @a msgIdLanguage.

        @param domain
            The catalog domain to add.

        @param msgIdLanguage
            Specifies the language of "msgid" strings in source code
            (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
            It is used if AddCatalog() cannot find any catalog for current language:
            if the language is same as source code language, then strings from source
            code are used instead.

        @return
            @true if catalog was successfully loaded, @false otherwise (which might
            mean that the catalog is not found or that it isn't in the correct format).
     */
    bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);

    /**
        Same as AddCatalog(const wxString&, wxLanguage), but takes two
        additional arguments, @a msgIdLanguage and @a msgIdCharset.

        This overload is only available in non-Unicode build.

        @param domain
            The catalog domain to add.

        @param msgIdLanguage
            Specifies the language of "msgid" strings in source code
            (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
            It is used if AddCatalog() cannot find any catalog for current language:
            if the language is same as source code language, then strings from source
            code are used instead.

        @param msgIdCharset
            Lets you specify the charset used for msgids in sources
            in case they use 8-bit characters (e.g. German or French strings).

        @return
            @true if catalog was successfully loaded, @false otherwise (which might
            mean that the catalog is not found or that it isn't in the correct format).
     */
    bool AddCatalog(const wxString& domain,
                    wxLanguage msgIdLanguage,
                    const wxString& msgIdCharset);

    /**
        Check if the given catalog is loaded, and returns @true if it is.

        According to GNU gettext tradition, each catalog normally corresponds to
        'domain' which is more or less the application name.

        @see AddCatalog()
     */
    bool IsLoaded(const wxString& domain) const;

    /**
        Retrieves the translation for a string in all loaded domains unless the @a domain
        parameter is specified (and then only this catalog/domain is searched).

        Returns original string if translation is not available (in this case an
        error message is generated the first time a string is not found; use
        wxLogNull to suppress it).

        @remarks Domains are searched in the last to first order, i.e. catalogs
                 added later override those added before.
    */
    const wxString& GetString(const wxString& origString,
                              const wxString& domain = wxEmptyString) const;

    /**
        Retrieves the translation for a string in all loaded domains unless the @a domain
        parameter is specified (and then only this catalog/domain is searched).

        Returns original string if translation is not available (in this case an
        error message is generated the first time a string is not found; use
        wxLogNull to suppress it).

        This form is used when retrieving translation of string that has different
        singular and plural form in English or different plural forms in some
        other language.
        It takes two extra arguments: @a origString parameter must contain the
        singular form of the string to be converted.

        It is also used as the key for the search in the catalog.
        The @a origString2 parameter is the plural form (in English).

        The parameter @a n is used to determine the plural form.
        If no message catalog is found @a origString is returned if 'n == 1',
        otherwise @a origString2.

        See GNU gettext manual for additional information on plural forms handling.
        This method is called by the wxGetTranslation() function and _() macro.

        @remarks Domains are searched in the last to first order, i.e. catalogs
                 added later override those added before.
    */
    const wxString& GetString(const wxString& origString,
                              const wxString& origString2,
                              unsigned n,
                              const wxString& domain = wxEmptyString) const;

    /**
        Returns the header value for header @a header.
        The search for @a header is case sensitive. If an @a domain is passed,
        this domain is searched. Else all domains will be searched until a
        header has been found.

        The return value is the value of the header if found. Else this will be empty.
    */
    wxString GetHeaderValue(const wxString& header,
                            const wxString& domain = wxEmptyString) const;
};


/**
    Abstraction of translations discovery and loading.

    This interface makes it possible to override wxWidgets' default catalogs
    loading mechanism and load MO files from locations other than the
    filesystem (e.g. embed them in executable).

    Implementations must implement the LoadCatalog() method.

    @see wxFileTranslationsLoader, wxResourceTranslationsLoader

    @since 2.9.1
 */
class wxTranslationsLoader
{
public:
    /// Constructor
    wxTranslationsLoader() {}

    /**
        Called to load requested catalog.

        If the catalog is found, LoadCatalog() should create wxMsgCatalog
        instance with its data and return it. The caller will take ownership
        of the catalog.

        @param domain        Domain to load.
        @param lang          Language to look for. This is "canonical name"
                             (see wxLocale::GetCanonicalName()), i.e. ISO 639
                             code, possibly combined with country code or
                             additional modifiers (e.g. "fr", "en_GB" or
                             "ca@valencia").

        @return Loaded catalog or NULL on failure.
     */
    virtual wxMsgCatalog *LoadCatalog(const wxString& domain,
                                      const wxString& lang) = 0;
};

/**
    Standard wxTranslationsLoader implementation.

    This finds catalogs in the filesystem, using the standard Unix layout.
    This is the default unless you change the loader with
    wxTranslations::SetLoader().

    Catalogs are searched for in standard places (current directory first, then
    the system one), but you may also prepend additional directories to the
    search path with AddCatalogLookupPathPrefix().

    @since 2.9.1
 */
class wxFileTranslationsLoader : public wxTranslationsLoader
{
public:
    /**
        Add a prefix to the catalog lookup path: the message catalog files will
        be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
        (in this order).

        This only applies to subsequent invocations of
        wxTranslations::AddCatalog().
    */
    static void AddCatalogLookupPathPrefix(const wxString& prefix);
};

/**
    This loader makes it possible to load translations from Windows
    resources.

    If you wish to store translation MO files in resources, you have to
    enable this loader before calling wxTranslations::AddCatalog() or
    wxLocale::AddCatalog():

    @code
    wxTranslations::Get()->SetLoader(new wxResourceTranslationsLoader);
    @endcode

    Translations are stored in resources as compiled MO files, with type
    set to "MOFILE" (unless you override GetResourceType()) and name
    consisting of the domain, followed by underscore, followed by language
    identification. For example, the relevant part of .rc file would look
    like this:

    @code
    myapp_de     MOFILE   "catalogs/de/myapp.mo"
    myapp_fr     MOFILE   "catalogs/fr/myapp.mo"
    myapp_en_GB  MOFILE   "catalogs/en_GB/myapp.mo"
    @endcode

    This class is only available on Windows.

    @since 2.9.1
 */
class wxResourceTranslationsLoader : public wxTranslationsLoader
{
protected:
    /**
        Returns resource type to use for translations.

        Default type is "MOFILE".
     */
    virtual wxString GetResourceType() const;

    /**
        Returns handle of the module to load resources from.

        By default, the main executable is used.
     */
    virtual WXHINSTANCE GetModule() const;
};


/**
    Represents a loaded translations message catalog.

    This class should only be used directly by wxTranslationsLoader
    implementations.

    @since 2.9.1
 */
class wxMsgCatalog
{
public:
    /**
        Creates catalog loaded from a MO file.

        @param filename  Path to the MO file to load.
        @param domain    Catalog's domain. This typically matches
                         the @a filename.

        @return Successfully loaded catalog or NULL on failure.
     */
    static wxMsgCatalog *CreateFromFile(const wxString& filename,
                                        const wxString& domain);

    /**
        Creates catalog from MO file data in memory buffer.

        @param data      Data in MO file format.
        @param domain    Catalog's domain. This typically matches
                         the @a filename.

        @return Successfully loaded catalog or NULL on failure.
     */
    static wxMsgCatalog *CreateFromData(const wxScopedCharBuffer& data,
                                        const wxString& domain);
};


// ============================================================================
// Global functions/macros
// ============================================================================

/** @addtogroup group_funcmacro_string */
//@{

/**
    This macro is identical to _() but for the plural variant of
    wxGetTranslation().

    @return A const wxString.

    @header{wx/intl.h}
*/
#define wxPLURAL(string, plural, n)

/**
    This macro doesn't do anything in the program code -- it simply expands to
    the value of its argument.

    However it does have a purpose which is to mark the literal strings for the
    extraction into the message catalog created by @c xgettext program. Usually
    this is achieved using _() but that macro not only marks the string for
    extraction but also expands into a wxGetTranslation() call which means that
    it cannot be used in some situations, notably for static array
    initialization.

    Here is an example which should make it more clear: suppose that you have a
    static array of strings containing the weekday names and which have to be
    translated (note that it is a bad example, really, as wxDateTime already
    can be used to get the localized week day names already). If you write:

    @code
    static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
    ...
    // use weekdays[n] as usual
    @endcode

    The code wouldn't compile because the function calls are forbidden in the
    array initializer. So instead you should do this:

    @code
    static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
    wxTRANSLATE("Sun") };
    ...
    // use wxGetTranslation(weekdays[n])
    @endcode

    Note that although the code @b would compile if you simply omit
    wxTRANSLATE() in the above, it wouldn't work as expected because there
    would be no translations for the weekday names in the program message
    catalog and wxGetTranslation() wouldn't find them.

    @return A const wxChar*.

    @header{wx/intl.h}
*/
#define wxTRANSLATE(string)

/**
    This function returns the translation of @a string in the current
    @c locale(). If the string is not found in any of the loaded message
    catalogs (see @ref overview_i18n), the original string is returned. In
    debug build, an error message is logged -- this should help to find the
    strings which were not yet translated.  If @a domain is specified then only
    that domain/catalog is searched for a matching string.  As this function is
    used very often, an alternative (and also common in Unix world) syntax is
    provided: the _() macro is defined to do the same thing as
    wxGetTranslation().

    This function calls wxTranslations::GetString().

    @note This function is not suitable for literal strings in Unicode builds
          since the literal strings must be enclosed into _T() or wxT() macro
          which makes them unrecognised by @c xgettext, and so they are not
          extracted to the message catalog. Instead, use the _() and wxPLURAL()
          macro for all literal strings.

    @see wxGetTranslation(const wxString&, const wxString&, unsigned, const wxString&)

    @header{wx/intl.h}
*/
const wxString& wxGetTranslation(const wxString& string,
                                 const wxString& domain = wxEmptyString);

/**
    This is an overloaded version of
    wxGetTranslation(const wxString&, const wxString&), please see its
    documentation for general information.

    This version is used when retrieving translation of string that has
    different singular and plural forms in English or different plural forms in
    some other language. Like wxGetTranslation(const wxString&,const wxString&),
    the @a string parameter must contain the singular form of the string to be
    converted and is used as the key for the search in the catalog. The
    @a plural parameter is the plural form (in English). The parameter @a n is
    used to determine the plural form. If no message catalog is found,
    @a string is returned if "n == 1", otherwise @a plural is returned.

    See GNU gettext Manual for additional information on plural forms handling:
    <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
    For a shorter alternative see the wxPLURAL() macro.

    This function calls wxLocale::GetString().

    @header{wx/intl.h}
*/
const wxString& wxGetTranslation(const wxString& string,
                                 const wxString& plural, unsigned n,
                                 const wxString& domain = wxEmptyString);

/**
    This macro expands into a call to wxGetTranslation(), so it marks the
    message for the extraction by @c xgettext just as wxTRANSLATE() does, but
    also returns the translation of the string for the current locale during
    execution.

    Don't confuse this with _T()!

    @header{wx/intl.h}
*/
const wxString& _(const wxString& string);

//@}
Commit	Line	Data
ea144923 VS	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: translation.h
	3	// Purpose: wxTranslation class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9
	10	/**
	11	This class allows to get translations for strings.
	12
	13	In wxWidgets this class manages message catalogs which contain the
	14	translations of the strings used to the current language. Unlike wxLocale,
	15	it isn't bound to locale. It can be used either independently of, or in
	16	conjunction with wxLocale. In the latter case, you should initialize
	17	wxLocale (which creates wxTranslations instance) first; in the former, you
	18	need to create a wxTranslations object and Set() it manually.
	19
	20	Only one wxTranslations instance is active at a time; it is set with the
	21	Set() method and obtained using Get().
	22
	23	Unlike wxLocale, wxTranslations' primary mean of identifying language
	24	is by its "canonical name", i.e. ISO 639 code, possibly combined with
	25	ISO 3166 country code and additional modifiers (examples include
	26	"fr", "en_GB" or "ca@valencia"; see wxLocale::GetCanonicalName() for
	27	more information). This allows apps using wxTranslations API to use even
	28	languages not recognized by the operating system or not listed in
	29	wxLanguage enum.
	30
	31	@since 2.9.1
	32
	33	@see wxLocale
	34	*/
	35	class wxTranslations
	36	{
	37	public:
	38	/// Constructor
	39	wxTranslations();
	40
	41	/**
	42	Returns current translations object, may return NULL.
	43
	44	You must either call this early in app initialization code, or let
	45	wxLocale do it for you.
	46	*/
	47	static wxTranslations *Get();
	48
	49	/**
	50	Sets current translations object.
	51
	52	Deletes previous translation object and takes ownership of @a t.
	53	*/
	54	static void Set(wxTranslations *t);
	55
	56	/**
	57	Changes loader use to read catalogs to a non-default one.
	58
	59	Deletes previous loader and takes ownership of @a loader.
	60
bc71c3cd	61	@see wxTranslationsLoader, wxFileTranslationsLoader, wxResourceTranslationsLoader
ea144923 VS	62	*/
	63	void SetLoader(wxTranslationsLoader *loader);
	64
	65	/**
	66	Sets translations language to use.
	67
	68	wxLANGUAGE_DEFAULT has special meaning: best suitable translation,
	69	given user's preference and available translations, will be used.
	70	*/
	71	void SetLanguage(wxLanguage lang);
	72
	73	/**
	74	Sets translations language to use.
	75
	76	Empty @a lang string has the same meaning as wxLANGUAGE_DEFAULT in
	77	SetLanguage(wxLanguage): best suitable translation, given user's
	78	preference and available translations, will be used.
	79	*/
	80	void SetLanguage(const wxString& lang);
	81
	82	/**
	83	Add standard wxWidgets catalogs ("wxstd" and possible port-specific
	84	catalogs).
	85
	86	@return @true if a suitable catalog was found, @false otherwise
	87
	88	@see AddCatalog()
	89	*/
	90	bool AddStdCatalog();
	91
	92	/**
	93	Add a catalog for use with the current locale.
	94
	95	By default, it is searched for in standard places (see
	96	wxFileTranslationsLoader), but you may also prepend additional
	97	directories to the search path with
	98	wxFileTranslationsLoader::AddCatalogLookupPathPrefix().
	99
	100	All loaded catalogs will be used for message lookup by GetString() for
	101	the current locale.
	102
	103	In this overload, @c msgid strings are assumed
	104	to be in English and written only using 7-bit ASCII characters.
	105	If you have to deal with non-English strings or 8-bit characters in the
	106	source code, see the instructions in @ref overview_nonenglish.
	107
	108	@return
	109	@true if catalog was successfully loaded, @false otherwise (which might
	110	mean that the catalog is not found or that it isn't in the correct format).
	111	*/
	112	bool AddCatalog(const wxString& domain);
	113
	114	/**
	115	Same as AddCatalog(const wxString&), but takes an additional argument,
	116	@a msgIdLanguage.
	117
	118	@param domain
	119	The catalog domain to add.
	120
	121	@param msgIdLanguage
	122	Specifies the language of "msgid" strings in source code
	123	(i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
	124	It is used if AddCatalog() cannot find any catalog for current language:
	125	if the language is same as source code language, then strings from source
126	code are used instead.
127
128	@return
129	@true if catalog was successfully loaded, @false otherwise (which might
130	mean that the catalog is not found or that it isn't in the correct format).
131	*/
132	bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
133
134	/**
135	Same as AddCatalog(const wxString&, wxLanguage), but takes two
136	additional arguments, @a msgIdLanguage and @a msgIdCharset.
137
138	This overload is only available in non-Unicode build.
139
140	@param domain
141	The catalog domain to add.
142
143	@param msgIdLanguage
144	Specifies the language of "msgid" strings in source code
145	(i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
146	It is used if AddCatalog() cannot find any catalog for current language:
147	if the language is same as source code language, then strings from source
148	code are used instead.
149
150	@param msgIdCharset
151	Lets you specify the charset used for msgids in sources
152	in case they use 8-bit characters (e.g. German or French strings).
153
154	@return
155	@true if catalog was successfully loaded, @false otherwise (which might
156	mean that the catalog is not found or that it isn't in the correct format).
157	*/
158	bool AddCatalog(const wxString& domain,
159	wxLanguage msgIdLanguage,
160	const wxString& msgIdCharset);
161
162	/**
163	Check if the given catalog is loaded, and returns @true if it is.
164
165	According to GNU gettext tradition, each catalog normally corresponds to
166	'domain' which is more or less the application name.
167
168	@see AddCatalog()
169	*/
170	bool IsLoaded(const wxString& domain) const;
171
ea144923 VS	172	/**
	173	Retrieves the translation for a string in all loaded domains unless the @a domain
	174	parameter is specified (and then only this catalog/domain is searched).
	175
	176	Returns original string if translation is not available (in this case an
	177	error message is generated the first time a string is not found; use
	178	wxLogNull to suppress it).
	179
	180	@remarks Domains are searched in the last to first order, i.e. catalogs
	181	added later override those added before.
	182	*/
	183	const wxString& GetString(const wxString& origString,
	184	const wxString& domain = wxEmptyString) const;
	185
	186	/**
	187	Retrieves the translation for a string in all loaded domains unless the @a domain
	188	parameter is specified (and then only this catalog/domain is searched).
	189
	190	Returns original string if translation is not available (in this case an
	191	error message is generated the first time a string is not found; use
	192	wxLogNull to suppress it).
	193
	194	This form is used when retrieving translation of string that has different
	195	singular and plural form in English or different plural forms in some
	196	other language.
	197	It takes two extra arguments: @a origString parameter must contain the
	198	singular form of the string to be converted.
	199
	200	It is also used as the key for the search in the catalog.
	201	The @a origString2 parameter is the plural form (in English).
	202
	203	The parameter @a n is used to determine the plural form.
	204	If no message catalog is found @a origString is returned if 'n == 1',
	205	otherwise @a origString2.
	206
	207	See GNU gettext manual for additional information on plural forms handling.
	208	This method is called by the wxGetTranslation() function and _() macro.
	209
	210	@remarks Domains are searched in the last to first order, i.e. catalogs
	211	added later override those added before.
	212	*/
	213	const wxString& GetString(const wxString& origString,
	214	const wxString& origString2,
dfbb5eff	215	unsigned n,
ea144923 VS	216	const wxString& domain = wxEmptyString) const;
	217
	218	/**
	219	Returns the header value for header @a header.
	220	The search for @a header is case sensitive. If an @a domain is passed,
	221	this domain is searched. Else all domains will be searched until a
	222	header has been found.
	223
	224	The return value is the value of the header if found. Else this will be empty.
	225	*/
	226	wxString GetHeaderValue(const wxString& header,
	227	const wxString& domain = wxEmptyString) const;
	228	};
	229
	230
	231	/**
	232	Abstraction of translations discovery and loading.
	233
	234	This interface makes it possible to override wxWidgets' default catalogs
	235	loading mechanism and load MO files from locations other than the
	236	filesystem (e.g. embed them in executable).
	237
	238	Implementations must implement the LoadCatalog() method.
	239
bc71c3cd	240	@see wxFileTranslationsLoader, wxResourceTranslationsLoader
7ed63042 VS	241
7ed63042 VS	242	@since 2.9.1
ea144923 VS	243	*/
	244	class wxTranslationsLoader
	245	{
	246	public:
	247	/// Constructor
	248	wxTranslationsLoader() {}
	249
	250	/**
	251	Called to load requested catalog.
	252
611bed35 VS	253	If the catalog is found, LoadCatalog() should create wxMsgCatalog
	254	instance with its data and return it. The caller will take ownership
	255	of the catalog.
ea144923	256
ea144923 VS	257	@param domain Domain to load.
	258	@param lang Language to look for. This is "canonical name"
	259	(see wxLocale::GetCanonicalName()), i.e. ISO 639
	260	code, possibly combined with country code or
	261	additional modifiers (e.g. "fr", "en_GB" or
	262	"ca@valencia").
	263
611bed35	264	@return Loaded catalog or NULL on failure.
ea144923	265	*/
611bed35 VS	266	virtual wxMsgCatalog *LoadCatalog(const wxString& domain,
611bed35 VS	267	const wxString& lang) = 0;
ea144923 VS	268	};
	269
	270	/**
	271	Standard wxTranslationsLoader implementation.
	272
	273	This finds catalogs in the filesystem, using the standard Unix layout.
	274	This is the default unless you change the loader with
	275	wxTranslations::SetLoader().
	276
	277	Catalogs are searched for in standard places (current directory first, then
	278	the system one), but you may also prepend additional directories to the
	279	search path with AddCatalogLookupPathPrefix().
7ed63042 VS	280
7ed63042 VS	281	@since 2.9.1
ea144923 VS	282	*/
	283	class wxFileTranslationsLoader : public wxTranslationsLoader
	284	{
	285	public:
	286	/**
	287	Add a prefix to the catalog lookup path: the message catalog files will
	288	be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
	289	(in this order).
	290
	291	This only applies to subsequent invocations of
	292	wxTranslations::AddCatalog().
	293	*/
	294	static void AddCatalogLookupPathPrefix(const wxString& prefix);
	295	};
	296
bc71c3cd VS	297	/**
	298	This loader makes it possible to load translations from Windows
	299	resources.
	300
	301	If you wish to store translation MO files in resources, you have to
	302	enable this loader before calling wxTranslations::AddCatalog() or
	303	wxLocale::AddCatalog():
	304
	305	@code
	306	wxTranslations::Get()->SetLoader(new wxResourceTranslationsLoader);
	307	@endcode
	308
	309	Translations are stored in resources as compiled MO files, with type
	310	set to "MOFILE" (unless you override GetResourceType()) and name
	311	consisting of the domain, followed by underscore, followed by language
	312	identification. For example, the relevant part of .rc file would look
	313	like this:
	314
	315	@code
	316	myapp_de MOFILE "catalogs/de/myapp.mo"
	317	myapp_fr MOFILE "catalogs/fr/myapp.mo"
	318	myapp_en_GB MOFILE "catalogs/en_GB/myapp.mo"
	319	@endcode
	320
	321	This class is only available on Windows.
	322
	323	@since 2.9.1
bc71c3cd VS	324	*/
	325	class wxResourceTranslationsLoader : public wxTranslationsLoader
	326	{
	327	protected:
	328	/**
	329	Returns resource type to use for translations.
	330
	331	Default type is "MOFILE".
	332	*/
	333	virtual wxString GetResourceType() const;
	334
	335	/**
	336	Returns handle of the module to load resources from.
	337
	338	By default, the main executable is used.
	339	*/
	340	virtual WXHINSTANCE GetModule() const;
	341	};
	342
ea144923	343
611bed35 VS	344	/**
	345	Represents a loaded translations message catalog.
	346
	347	This class should only be used directly by wxTranslationsLoader
	348	implementations.
	349
	350	@since 2.9.1
	351	*/
	352	class wxMsgCatalog
	353	{
	354	public:
	355	/**
	356	Creates catalog loaded from a MO file.
	357
	358	@param filename Path to the MO file to load.
	359	@param domain Catalog's domain. This typically matches
	360	the @a filename.
	361
	362	@return Successfully loaded catalog or NULL on failure.
	363	*/
	364	static wxMsgCatalog *CreateFromFile(const wxString& filename,
	365	const wxString& domain);
	366
	367	/**
	368	Creates catalog from MO file data in memory buffer.
	369
	370	@param data Data in MO file format.
	371	@param domain Catalog's domain. This typically matches
	372	the @a filename.
	373
	374	@return Successfully loaded catalog or NULL on failure.
	375	*/
	376	static wxMsgCatalog *CreateFromData(const wxScopedCharBuffer& data,
	377	const wxString& domain);
	378	};
	379
ea144923 VS	380
	381	// ============================================================================
	382	// Global functions/macros
	383	// ============================================================================
	384
	385	/** @addtogroup group_funcmacro_string */
	386	//@{
	387
	388	/**
	389	This macro is identical to _() but for the plural variant of
	390	wxGetTranslation().
	391
	392	@return A const wxString.
	393
	394	@header{wx/intl.h}
	395	*/
	396	#define wxPLURAL(string, plural, n)
	397
	398	/**
	399	This macro doesn't do anything in the program code -- it simply expands to
	400	the value of its argument.
	401
	402	However it does have a purpose which is to mark the literal strings for the
	403	extraction into the message catalog created by @c xgettext program. Usually
	404	this is achieved using _() but that macro not only marks the string for
	405	extraction but also expands into a wxGetTranslation() call which means that
	406	it cannot be used in some situations, notably for static array
	407	initialization.
	408
	409	Here is an example which should make it more clear: suppose that you have a
	410	static array of strings containing the weekday names and which have to be
	411	translated (note that it is a bad example, really, as wxDateTime already
	412	can be used to get the localized week day names already). If you write:
	413
	414	@code
	415	static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
	416	...
	417	// use weekdays[n] as usual
	418	@endcode
	419
	420	The code wouldn't compile because the function calls are forbidden in the
	421	array initializer. So instead you should do this:
	422
	423	@code
	424	static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
	425	wxTRANSLATE("Sun") };
	426	...
	427	// use wxGetTranslation(weekdays[n])
	428	@endcode
	429
	430	Note that although the code @b would compile if you simply omit
	431	wxTRANSLATE() in the above, it wouldn't work as expected because there
	432	would be no translations for the weekday names in the program message
	433	catalog and wxGetTranslation() wouldn't find them.
	434
	435	@return A const wxChar*.
	436
	437	@header{wx/intl.h}
	438	*/
	439	#define wxTRANSLATE(string)
	440
	441	/**
	442	This function returns the translation of @a string in the current
	443	@c locale(). If the string is not found in any of the loaded message
444	catalogs (see @ref overview_i18n), the original string is returned. In
445	debug build, an error message is logged -- this should help to find the
446	strings which were not yet translated. If @a domain is specified then only
447	that domain/catalog is searched for a matching string. As this function is
448	used very often, an alternative (and also common in Unix world) syntax is
449	provided: the _() macro is defined to do the same thing as
450	wxGetTranslation().
451
452	This function calls wxTranslations::GetString().
453
454	@note This function is not suitable for literal strings in Unicode builds
455	since the literal strings must be enclosed into _T() or wxT() macro
456	which makes them unrecognised by @c xgettext, and so they are not
457	extracted to the message catalog. Instead, use the _() and wxPLURAL()
458	macro for all literal strings.
459
dfbb5eff	460	@see wxGetTranslation(const wxString&, const wxString&, unsigned, const wxString&)
ea144923 VS	461
	462	@header{wx/intl.h}
	463	*/
	464	const wxString& wxGetTranslation(const wxString& string,
	465	const wxString& domain = wxEmptyString);
	466
	467	/**
	468	This is an overloaded version of
	469	wxGetTranslation(const wxString&, const wxString&), please see its
	470	documentation for general information.
	471
	472	This version is used when retrieving translation of string that has
	473	different singular and plural forms in English or different plural forms in
	474	some other language. Like wxGetTranslation(const wxString&,const wxString&),
	475	the @a string parameter must contain the singular form of the string to be
	476	converted and is used as the key for the search in the catalog. The
	477	@a plural parameter is the plural form (in English). The parameter @a n is
	478	used to determine the plural form. If no message catalog is found,
	479	@a string is returned if "n == 1", otherwise @a plural is returned.
	480
	481	See GNU gettext Manual for additional information on plural forms handling:
	482	<http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
	483	For a shorter alternative see the wxPLURAL() macro.
	484
	485	This function calls wxLocale::GetString().
	486
	487	@header{wx/intl.h}
	488	*/
	489	const wxString& wxGetTranslation(const wxString& string,
dfbb5eff	490	const wxString& plural, unsigned n,
ea144923 VS	491	const wxString& domain = wxEmptyString);
	492
	493	/**
	494	This macro expands into a call to wxGetTranslation(), so it marks the
	495	message for the extraction by @c xgettext just as wxTRANSLATE() does, but
	496	also returns the translation of the string for the current locale during
	497	execution.
	498
	499	Don't confuse this with _T()!
	500
	501	@header{wx/intl.h}
	502	*/
	503	const wxString& _(const wxString& string);
	504
	505	//@}
	506