[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;

    /**
        Directly loads catalog from a file.

        It is caller's responsibility to ensure that the catalog contains
        correct language. This function is primarily intended for
        wxTranslationsLoader implementations.

        @param filename  Name of the MO file to load.
        @param domain    Domain to load the translations into (typically
                         matches file's basename).
     */
    bool LoadCatalogFile(const wxString& filename,
                         const wxString& domain = wxEmptyString);

    /**
        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,
                              size_t 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 call LoadCatalogFile()
        on @a translations to add the translation.

        @param translations  wxTranslations requesting loading.
        @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 @true on successful load, @false otherwise
     */
    virtual bool LoadCatalog(wxTranslations *translations,
                             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;
};


// ============================================================================
// 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&, size_t, 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, size_t 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
172	/**
173	Directly loads catalog from a file.
174
175	It is caller's responsibility to ensure that the catalog contains
176	correct language. This function is primarily intended for
177	wxTranslationsLoader implementations.
178
179	@param filename Name of the MO file to load.
180	@param domain Domain to load the translations into (typically
181	matches file's basename).
182	*/
183	bool LoadCatalogFile(const wxString& filename,
184	const wxString& domain = wxEmptyString);
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	@remarks Domains are searched in the last to first order, i.e. catalogs
195	added later override those added before.
196	*/
197	const wxString& GetString(const wxString& origString,
198	const wxString& domain = wxEmptyString) const;
199
200	/**
201	Retrieves the translation for a string in all loaded domains unless the @a domain
202	parameter is specified (and then only this catalog/domain is searched).
203
204	Returns original string if translation is not available (in this case an
205	error message is generated the first time a string is not found; use
206	wxLogNull to suppress it).
207
208	This form is used when retrieving translation of string that has different
209	singular and plural form in English or different plural forms in some
210	other language.
211	It takes two extra arguments: @a origString parameter must contain the
212	singular form of the string to be converted.
213
214	It is also used as the key for the search in the catalog.
215	The @a origString2 parameter is the plural form (in English).
216
217	The parameter @a n is used to determine the plural form.
218	If no message catalog is found @a origString is returned if 'n == 1',
219	otherwise @a origString2.
220
221	See GNU gettext manual for additional information on plural forms handling.
222	This method is called by the wxGetTranslation() function and _() macro.
223
224	@remarks Domains are searched in the last to first order, i.e. catalogs
225	added later override those added before.
226	*/
227	const wxString& GetString(const wxString& origString,
228	const wxString& origString2,
229	size_t n,
230	const wxString& domain = wxEmptyString) const;
231
232	/**
233	Returns the header value for header @a header.
234	The search for @a header is case sensitive. If an @a domain is passed,
235	this domain is searched. Else all domains will be searched until a
236	header has been found.
237
238	The return value is the value of the header if found. Else this will be empty.
239	*/
240	wxString GetHeaderValue(const wxString& header,
241	const wxString& domain = wxEmptyString) const;
242	};
243
244
245	/**
246	Abstraction of translations discovery and loading.
247
248	This interface makes it possible to override wxWidgets' default catalogs
249	loading mechanism and load MO files from locations other than the
250	filesystem (e.g. embed them in executable).
251
252	Implementations must implement the LoadCatalog() method.
253
bc71c3cd	254	@see wxFileTranslationsLoader, wxResourceTranslationsLoader
7ed63042 VS	255
7ed63042 VS	256	@since 2.9.1
ea144923 VS	257	*/
	258	class wxTranslationsLoader
	259	{
	260	public:
	261	/// Constructor
	262	wxTranslationsLoader() {}
	263
	264	/**
	265	Called to load requested catalog.
	266
	267	If the catalog is found, LoadCatalog() should call LoadCatalogFile()
	268	on @a translations to add the translation.
	269
	270	@param translations wxTranslations requesting loading.
	271	@param domain Domain to load.
	272	@param lang Language to look for. This is "canonical name"
	273	(see wxLocale::GetCanonicalName()), i.e. ISO 639
	274	code, possibly combined with country code or
	275	additional modifiers (e.g. "fr", "en_GB" or
	276	"ca@valencia").
	277
	278	@return @true on successful load, @false otherwise
	279	*/
	280	virtual bool LoadCatalog(wxTranslations *translations,
	281	const wxString& domain, const wxString& lang) = 0;
	282	};
	283
	284	/**
	285	Standard wxTranslationsLoader implementation.
	286
	287	This finds catalogs in the filesystem, using the standard Unix layout.
	288	This is the default unless you change the loader with
	289	wxTranslations::SetLoader().
	290
	291	Catalogs are searched for in standard places (current directory first, then
	292	the system one), but you may also prepend additional directories to the
	293	search path with AddCatalogLookupPathPrefix().
7ed63042 VS	294
7ed63042 VS	295	@since 2.9.1
ea144923 VS	296	*/
	297	class wxFileTranslationsLoader : public wxTranslationsLoader
	298	{
	299	public:
	300	/**
	301	Add a prefix to the catalog lookup path: the message catalog files will
	302	be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
	303	(in this order).
	304
	305	This only applies to subsequent invocations of
	306	wxTranslations::AddCatalog().
	307	*/
	308	static void AddCatalogLookupPathPrefix(const wxString& prefix);
	309	};
	310
bc71c3cd VS	311	/**
	312	This loader makes it possible to load translations from Windows
	313	resources.
	314
	315	If you wish to store translation MO files in resources, you have to
	316	enable this loader before calling wxTranslations::AddCatalog() or
	317	wxLocale::AddCatalog():
	318
	319	@code
	320	wxTranslations::Get()->SetLoader(new wxResourceTranslationsLoader);
	321	@endcode
	322
	323	Translations are stored in resources as compiled MO files, with type
	324	set to "MOFILE" (unless you override GetResourceType()) and name
	325	consisting of the domain, followed by underscore, followed by language
	326	identification. For example, the relevant part of .rc file would look
	327	like this:
	328
	329	@code
	330	myapp_de MOFILE "catalogs/de/myapp.mo"
	331	myapp_fr MOFILE "catalogs/fr/myapp.mo"
	332	myapp_en_GB MOFILE "catalogs/en_GB/myapp.mo"
	333	@endcode
	334
	335	This class is only available on Windows.
	336
	337	@since 2.9.1
	338
	339	*/
	340	class wxResourceTranslationsLoader : public wxTranslationsLoader
	341	{
	342	protected:
	343	/**
	344	Returns resource type to use for translations.
	345
	346	Default type is "MOFILE".
	347	*/
	348	virtual wxString GetResourceType() const;
	349
	350	/**
	351	Returns handle of the module to load resources from.
	352
	353	By default, the main executable is used.
	354	*/
	355	virtual WXHINSTANCE GetModule() const;
	356	};
	357
ea144923 VS	358
	359
	360	// ============================================================================
	361	// Global functions/macros
	362	// ============================================================================
	363
	364	/** @addtogroup group_funcmacro_string */
	365	//@{
	366
	367	/**
	368	This macro is identical to _() but for the plural variant of
	369	wxGetTranslation().
	370
	371	@return A const wxString.
	372
	373	@header{wx/intl.h}
	374	*/
	375	#define wxPLURAL(string, plural, n)
	376
	377	/**
	378	This macro doesn't do anything in the program code -- it simply expands to
	379	the value of its argument.
	380
	381	However it does have a purpose which is to mark the literal strings for the
	382	extraction into the message catalog created by @c xgettext program. Usually
	383	this is achieved using _() but that macro not only marks the string for
	384	extraction but also expands into a wxGetTranslation() call which means that
	385	it cannot be used in some situations, notably for static array
	386	initialization.
	387
	388	Here is an example which should make it more clear: suppose that you have a
	389	static array of strings containing the weekday names and which have to be
	390	translated (note that it is a bad example, really, as wxDateTime already
	391	can be used to get the localized week day names already). If you write:
	392
	393	@code
	394	static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
	395	...
	396	// use weekdays[n] as usual
	397	@endcode
	398
	399	The code wouldn't compile because the function calls are forbidden in the
	400	array initializer. So instead you should do this:
	401
	402	@code
	403	static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
	404	wxTRANSLATE("Sun") };
	405	...
	406	// use wxGetTranslation(weekdays[n])
	407	@endcode
	408
	409	Note that although the code @b would compile if you simply omit
	410	wxTRANSLATE() in the above, it wouldn't work as expected because there
	411	would be no translations for the weekday names in the program message
	412	catalog and wxGetTranslation() wouldn't find them.
	413
	414	@return A const wxChar*.
	415
	416	@header{wx/intl.h}
	417	*/
	418	#define wxTRANSLATE(string)
	419
	420	/**
	421	This function returns the translation of @a string in the current
422	@c locale(). If the string is not found in any of the loaded message
423	catalogs (see @ref overview_i18n), the original string is returned. In
424	debug build, an error message is logged -- this should help to find the
425	strings which were not yet translated. If @a domain is specified then only
426	that domain/catalog is searched for a matching string. As this function is
427	used very often, an alternative (and also common in Unix world) syntax is
428	provided: the _() macro is defined to do the same thing as
429	wxGetTranslation().
430
431	This function calls wxTranslations::GetString().
432
433	@note This function is not suitable for literal strings in Unicode builds
434	since the literal strings must be enclosed into _T() or wxT() macro
435	which makes them unrecognised by @c xgettext, and so they are not
436	extracted to the message catalog. Instead, use the _() and wxPLURAL()
437	macro for all literal strings.
438
439	@see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
440
441	@header{wx/intl.h}
442	*/
443	const wxString& wxGetTranslation(const wxString& string,
444	const wxString& domain = wxEmptyString);
445
446	/**
447	This is an overloaded version of
448	wxGetTranslation(const wxString&, const wxString&), please see its
449	documentation for general information.
450
451	This version is used when retrieving translation of string that has
452	different singular and plural forms in English or different plural forms in
453	some other language. Like wxGetTranslation(const wxString&,const wxString&),
454	the @a string parameter must contain the singular form of the string to be
455	converted and is used as the key for the search in the catalog. The
456	@a plural parameter is the plural form (in English). The parameter @a n is
457	used to determine the plural form. If no message catalog is found,
458	@a string is returned if "n == 1", otherwise @a plural is returned.
459
460	See GNU gettext Manual for additional information on plural forms handling:
461	<http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
462	For a shorter alternative see the wxPLURAL() macro.
463
464	This function calls wxLocale::GetString().
465
466	@header{wx/intl.h}
467	*/
468	const wxString& wxGetTranslation(const wxString& string,
469	const wxString& plural, size_t n,
470	const wxString& domain = wxEmptyString);
471
472	/**
473	This macro expands into a call to wxGetTranslation(), so it marks the
474	message for the extraction by @c xgettext just as wxTRANSLATE() does, but
475	also returns the translation of the string for the current locale during
476	execution.
477
478	Don't confuse this with _T()!
479
480	@header{wx/intl.h}
481	*/
482	const wxString& _(const wxString& string);
483
484	//@}
485