[wxWidgets.git] / docs / doxygen / overviews / internationalization.h

/////////////////////////////////////////////////////////////////////////////
// Name:        internationalization
// Purpose:     topic overview
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/*!

 @page internationalization_overview Internationalization

 Although internationalization of an application (i18n for short) involves far
 more than just translating its text messages to another message - date, time and
 currency formats need changing too, some languages are written left to right
 and others right to left, character encoding may differ and many other things
 may need changing too - it is a necessary first step. wxWidgets provides
 facilities for message translation with its
 #wxLocale class and is itself fully translated into several
 languages. Please consult wxWidgets home page for the most up-to-date
 translations - and if you translate it into one of the languages not done
 yet, your translations would be gratefully accepted for inclusion into future
 versions of the library!
 The wxWidgets approach to i18n closely follows the GNU gettext package. wxWidgets uses the
 message catalogs which are binary compatible with gettext catalogs and this
 allows to use all of the programs in this package to work with them. But note
 that no additional libraries are needed during run-time, however, so you
 have only the message catalogs to distribute and nothing else.
 During program development you will need the gettext package for
 working with message catalogs. @b Warning: gettext versions  0.10 are known
 to be buggy, so you should find a later version of it!
 There are two kinds of message catalogs: source catalogs which are text files
 with extension .po and binary catalogs which are created from the source ones
 with @e msgfmt program (part of gettext package) and have the extension .mo.
 Only the binary files are needed during program execution.
 The program i18n involves several steps:


  Translating the strings in the program text using
 #wxGetTranslation or equivalently the
 #_() macro.
  Extracting the strings to be translated from the program: this uses the
 work done in the previous step because @c xgettext program used for string
 extraction recognises the standard _() as well as (using its @c -k option)
 our wxGetTranslation and extracts all strings inside the calls to these
 functions. Alternatively, you may use @c -a option to extract all the
 strings, but it will usually result in many strings being found which don't
 have to be translated at all. This will create a text message catalog - a .po
 file.
  Translating the strings extracted in the previous step to other
 language(s). It involves editing the .po file.
  Compiling the .po file into .mo file to be used by the program.
  Installing the .mo files with your application in the appropriate
 location for the target system which is the one returned by
 wxStandardPaths::GetLocalizedResourcesDir(wxStandardPaths::ResourceCat_Messages).
 If the message catalogs are not installed in this default location you may
 explicitly use #AddCatalogLookupPathPrefix() to
 still allow wxWidgets to find them but it is strongly recommended to use the
 default directory.
  Setting the appropriate locale in your program to use the strings for the
 given language: see #wxLocale.


 See also the http://www.gnu.org/software/gettext/manual/gettext.html.
 See also @ref nonenglish_overview.
 It focuses on handling charsets related problems.
 Finally, take a look at the @ref sampleinternat_overview which shows
 you how all this looks in practice.
 @b Translating menu accelerators
 If you translate the accelerator modifier names (Ctrl, Alt and Shift) in your menu labels, you may find
 the accelerators no longer work. In your message catalogs, you need to provide individual translations
 of these modifiers from their lower case names (ctrl, alt, shift) so that the wxWidgets accelerator
 code can recognise them even when translated. wxWidgets does not provide translations for all of these
 currently. wxWidgets does not yet handle translated special key names such as Backspace,
 End, Insert, etc.

 */
Commit	Line	Data
15b6757b FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: internationalization
	3	// Purpose: topic overview
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/*!
36c9828f	10
15b6757b	11	@page internationalization_overview Internationalization
36c9828f	12
15b6757b FM	13	Although internationalization of an application (i18n for short) involves far
	14	more than just translating its text messages to another message - date, time and
	15	currency formats need changing too, some languages are written left to right
	16	and others right to left, character encoding may differ and many other things
	17	may need changing too - it is a necessary first step. wxWidgets provides
36c9828f	18	facilities for message translation with its
15b6757b FM	19	#wxLocale class and is itself fully translated into several
	20	languages. Please consult wxWidgets home page for the most up-to-date
	21	translations - and if you translate it into one of the languages not done
	22	yet, your translations would be gratefully accepted for inclusion into future
	23	versions of the library!
	24	The wxWidgets approach to i18n closely follows the GNU gettext package. wxWidgets uses the
	25	message catalogs which are binary compatible with gettext catalogs and this
	26	allows to use all of the programs in this package to work with them. But note
	27	that no additional libraries are needed during run-time, however, so you
	28	have only the message catalogs to distribute and nothing else.
	29	During program development you will need the gettext package for
	30	working with message catalogs. @b Warning: gettext versions 0.10 are known
	31	to be buggy, so you should find a later version of it!
	32	There are two kinds of message catalogs: source catalogs which are text files
	33	with extension .po and binary catalogs which are created from the source ones
	34	with @e msgfmt program (part of gettext package) and have the extension .mo.
	35	Only the binary files are needed during program execution.
	36	The program i18n involves several steps:
36c9828f FM	37
	38
	39	Translating the strings in the program text using
	40	#wxGetTranslation or equivalently the
15b6757b FM	41	#_() macro.
	42	Extracting the strings to be translated from the program: this uses the
	43	work done in the previous step because @c xgettext program used for string
	44	extraction recognises the standard _() as well as (using its @c -k option)
	45	our wxGetTranslation and extracts all strings inside the calls to these
	46	functions. Alternatively, you may use @c -a option to extract all the
	47	strings, but it will usually result in many strings being found which don't
	48	have to be translated at all. This will create a text message catalog - a .po
	49	file.
	50	Translating the strings extracted in the previous step to other
	51	language(s). It involves editing the .po file.
	52	Compiling the .po file into .mo file to be used by the program.
	53	Installing the .mo files with your application in the appropriate
36c9828f	54	location for the target system which is the one returned by
15b6757b FM	55	wxStandardPaths::GetLocalizedResourcesDir(wxStandardPaths::ResourceCat_Messages).
	56	If the message catalogs are not installed in this default location you may
	57	explicitly use #AddCatalogLookupPathPrefix() to
	58	still allow wxWidgets to find them but it is strongly recommended to use the
	59	default directory.
	60	Setting the appropriate locale in your program to use the strings for the
	61	given language: see #wxLocale.
36c9828f FM	62
36c9828f FM	63
15b6757b FM	64	See also the http://www.gnu.org/software/gettext/manual/gettext.html.
	65	See also @ref nonenglish_overview.
	66	It focuses on handling charsets related problems.
	67	Finally, take a look at the @ref sampleinternat_overview which shows
	68	you how all this looks in practice.
	69	@b Translating menu accelerators
	70	If you translate the accelerator modifier names (Ctrl, Alt and Shift) in your menu labels, you may find
	71	the accelerators no longer work. In your message catalogs, you need to provide individual translations
	72	of these modifiers from their lower case names (ctrl, alt, shift) so that the wxWidgets accelerator
	73	code can recognise them even when translated. wxWidgets does not provide translations for all of these
	74	currently. wxWidgets does not yet handle translated special key names such as Backspace,
	75	End, Insert, etc.
36c9828f	76
15b6757b	77	*/
36c9828f FM	78
36c9828f FM	79