Programming Reference:Localization - Revision history

Mellinger: /* Further implementation details */

2007-11-08T17:26:27Z

Further implementation details

← Older revision		Revision as of 17:26, 8 November 2007
Line 95:		Line 95:

	* Encoding of non-ASCII characters follows the UTF8 convention. To ensure platform independent readability of source code files, there are macros that define HTML character names to their UTF8 encoded strings. This allows you to write<br /><tt>"Sm" oslash "rrebr" oslash "d"</tt><br />for "Smørrebrød" (cf. table 1).		* Encoding of non-ASCII characters follows the UTF8 convention. To ensure platform independent readability of source code files, there are macros that define HTML character names to their UTF8 encoded strings. This allows you to write<br /><tt>"Sm" oslash "rrebr" oslash "d"</tt><br />for "Smørrebrød" (cf. table 1).

			[[Category:Framework API]][[Category:Development]]

Admin: Technical Reference:Localization moved to Programming Reference:Localization

2007-10-31T10:35:54Z

Technical Reference:Localization moved to Programming Reference:Localization

← Older revision		Revision as of 10:35, 31 October 2007
(No difference)

Admin: User Reference:Localization moved to Technical Reference:Localization: Match content.

2007-10-31T10:20:52Z

User Reference:Localization moved to Technical Reference:Localization: Match content.

← Older revision		Revision as of 10:20, 31 October 2007
(No difference)

Mellinger: Language Localization moved to User Reference:Localization: Consistency

2007-10-09T13:59:58Z

Language Localization moved to User Reference:Localization: Consistency

← Older revision		Revision as of 13:59, 9 October 2007
(No difference)

Mellinger at 12:34, 10 July 2007

2007-07-10T12:34:28Z

← Older revision		Revision as of 12:34, 10 July 2007
Line 1:		Line 1:
	== ~~'''~~Introduction~~'''~~ ==		== Introduction ==
	As BCI2000 modules are being used in various countries, there emerges some need to adapt user interface elements to regional customs. Most notably, text that gives information to the subject requires translation into the subject's native language, as often a knowledge of English cannot be assumed. Even with a knowledge of ~~Englisn~~, reading text in a foreign language is a distracting factor that makes the already demanding task of operating a BCI even more difficult.		As BCI2000 modules are being used in various countries, there emerges some need to adapt user interface elements to regional customs. Most notably, text that gives information to the subject requires translation into the subject's native language, as often a knowledge of English cannot be assumed. Even with a knowledge of English, reading text in a foreign language is a distracting factor that makes the already demanding task of operating a BCI even more difficult.

	This document explains the approach taken to manage localized (translated) user interface strings in BCI2000 application modules, trying to meet the following goals:		This document explains the approach taken to manage localized (translated) user interface strings in BCI2000 application modules, trying to meet the following goals:

	*'''Flexibility:''' For the end user (operator), it should be possible to add translations into a ~~language that are not provided inside an application module~~, and to modify translations he does not feel to be appropriate. This should be achievable without making changes to the source code and recompiling the application module.		*'''Flexibility:''' For the end user (operator), it should be possible to add translations into a additional languages, and to modify translations he does not feel to be appropriate. This should be achievable without making changes to the source code and recompiling the application module.
	*'''Separability:''' For the user, switching languages should be done at a central place, i.e., by changing a single parameter. For the programmer, adding localization capabilities to existing modules should be possible with minimal changes to existing code. When writing new application modules, there should be no need to consider localization issues in advance.		*'''Separability:''' For the user, switching languages should be done at a central place, i.e., by changing a single parameter. For the programmer, adding localization capabilities to existing modules should be possible with minimal changes to existing code. When writing new application modules, there should be no need to consider localization issues in advance.
	*'''Documentation:''' Documenting and providing a collection of existing translations into various languages should be possible inside a module's source code.		*'''Documentation:''' Documenting and providing a collection of existing translations into various languages should be possible inside a module's source code.


	== ~~'''~~Strategies~~'''~~ ==		== Strategies ==

	For a number of text values that have always been set from parameters (such as the Speller module's <tt>~~Goal~~</tt> parameter that holds the text the user is told to spell in copy spelling mode), localization is not an issue because the user may just change the value as seems appropriate.		For a number of text values that have always been set from parameters (such as the Speller module's <tt>TextToSpell</tt> parameter that holds the text the user is told to spell in copy spelling mode), localization is not an issue because the user may just change the value as seems appropriate.

	The remaining text items, according to the way they are specified, fall into two categories:		The remaining text items, according to the way they are specified, fall into two categories:
Line 27:		Line 27:


	== ~~'''~~Implementation~~'''~~ ==		== Implementation ==

	The implementation is centered around a <tt>Localization</tt> class declared in <tt>Application/shared/Localization.h</tt>.		The implementation is centered around a <tt>Localization</tt> class declared in <tt>Application/shared/Localization.h</tt>.

	=== ~~'''~~Interface to the operator user~~'''~~ ===		=== Interface to the operator user ===

	The <tt>Localization</tt> class adds two parameters to the system that govern its localization		The <tt>Localization</tt> class adds two parameters to the system that govern its localization
	behavior:		behavior:
	~~'''~~*~~'''~~ <tt>Language</tt> defines the language into which strings are translated; if its value matches one of the <tt>LocalizedStrings</tt> row labels, translations will be taken from that row; otherwise, strings will not be translated. A value of <tt>Default</tt> results in all strings keeping their original values.		*<tt>Language</tt> defines the language into which strings are translated; if its value matches one of the <tt>LocalizedStrings</tt> row labels, translations will be taken from that row; otherwise, strings will not be translated. A value of <tt>Default</tt> results in all strings keeping their original values.
	~~'''~~*~~'''~~ <tt>LocalizedStrings</tt> defines string translations. Strings that do not appear as a column label will not be translated. Also, strings with an empty translation entry in <tt>LocalizedStrings</tt> will not be translated.		*<tt>LocalizedStrings</tt> defines string translations. Strings that do not appear as a column label will not be translated. Also, strings with an empty translation entry in <tt>LocalizedStrings</tt> will not be translated.

	===~~'''~~Interface to the programmer~~'''~~===		===Interface to the programmer===

	The <tt>LocalizedStrings</tt> parameter is empty by default. Although a user may add translations in desired languages to the empty matrix by manually using the matrix editor of the operator module, translations will preferably be provided in a filter constructor by listing them as in the following example:		The <tt>LocalizedStrings</tt> parameter is empty by default. Although a user may add translations in desired languages to the empty matrix by manually using the matrix editor of the operator module, translations will preferably be provided in a filter constructor by listing them as in the following example:
Line 62:		Line 62:
	If the <tt>LocalizedStrings</tt> matrix was empty before the <tt>TTask</tt> constructor gets called, it will have these entries after execution of the constructor:		If the <tt>LocalizedStrings</tt> matrix was empty before the <tt>TTask</tt> constructor gets called, it will have these entries after execution of the constructor:

	{\|		{\|border="1"
	\|		\|
	\|Yes		\|Yes
Line 81:		Line 81:
	Once entered, the translations contained in <tt>LocalizedStrings</tt> are applied via two mechanisms:		Once entered, the translations contained in <tt>LocalizedStrings</tt> are applied via two mechanisms:

	*The function <tt>LocalizableString()</tt> takes a string as an argument and returns the appropriate entry from <tt>LocalizedStrings</tt>, or the unmodified string if no entry can be found. For example, instead of		*The function <tt>LocalizableString()</tt> takes a string as an argument and returns the appropriate entry from <tt>LocalizedStrings</tt>, or the unmodified string if no entry can be found. For example, instead of <br /><tt>TellUser( "Well done!" );</tt><br />one would write<br /><tt>#include "Localization.h"<br />...<br />TellUser( LocalizableString( "Well done!" ) );</tt><br />to have a translation for "Well done!" looked up in <tt>LocalizedStrings</tt>.
	<tt>TellUser( "Well done!" );</tt><br>one would write<br><tt>#include "Localization.h"<br>...<br>TellUser( LocalizableString( "Well done!" ) );<br></tt>to have a translation for "Well done!" looked up in <tt>LocalizedStrings</tt>.

	* The function <tt>ApplyLocalizations()</tt> takes a pointer to a GUI object (~~usually~~ a ~~VCL~~ <tt>TForm*</tt>) and translates all localizable text contained within it. This function must be called during <tt>GenericFilter:: Initialize</tt> for each GUI object generated from a resource file.		* The function <tt>ApplyLocalizations()</tt> takes a pointer to a GUI object (for the Borland VCL, this would be a <tt>TForm*</tt>) and translates all localizable text contained within it. This function must be called during <tt>GenericFilter:: Initialize</tt> for each GUI object generated from a resource file.

	===~~'''~~Further implementation details~~'''~~===		===Further implementation details===

	~~'''~~*~~'''~~ You should not use <tt>LocalizableString()</tt> on string constants used before the first call to <tt>GenericFilter::Initialize()</tt> or for initializing static or global objects of any kind because localization information used will not be available at global initialization time, and local static variables, once initialized, will not be updated appropriately.		* You should not use <tt>LocalizableString()</tt> on string constants used before the first call to <tt>GenericFilter::Initialize()</tt> or for initializing static or global objects of any kind because localization information used will not be available at global initialization time, and local static variables, once initialized, will not be updated appropriately.

	~~'''~~*~~'''~~ Language names are case-insensitive. You may use any string for a language name but as a convention we suggest its most common English name, as in <tt>Italian, Dutch, French, German</tt>, with international country abbreviations as optional regional qualifiers as in <tt>EnglishUS, EnglishGB, GermanA, GermanCH</tt> if necessary.		* Language names are case-insensitive. You may use any string for a language name but as a convention we suggest its most common English name, as in <tt>Italian, Dutch, French, German</tt>, with international country abbreviations as optional regional qualifiers as in <tt>EnglishUS, EnglishGB, GermanA, GermanCH</tt> if necessary.

	[[Image:table.png\|center\|thumb\|300px\|table]]		[[Image:table.png\|center\|thumb\|300px\|table]]


	~~'''~~*~~'''~~ Encoding of non-ASCII characters follows the UTF8 convention. To ensure platform independent readability of source code files, there are macros that define HTML character names to their UTF8 encoded strings. This allows you to write		* Encoding of non-ASCII characters follows the UTF8 convention. To ensure platform independent readability of source code files, there are macros that define HTML character names to their UTF8 encoded strings. This allows you to write<br /><tt>"Sm" oslash "rrebr" oslash "d"</tt><br />for "Smørrebrød" (cf. table 1).

	<tt>"Sm" oslash "rrebr" oslash "d"</tt>

	for "Smørrebrød" (cf. table 1).

Atennissen at 14:21, 9 May 2007

2007-05-09T14:21:16Z

Atennissen at 16:06, 7 March 2007

2007-03-07T16:06:00Z

← Older revision		Revision as of 16:06, 7 March 2007
Line 1:		Line 1:
	== '''Introduction''' ==		== '''Introduction''' ==
	As BCI2000 modules are being used in various countries, there emerges some need		As BCI2000 modules are being used in various countries, there emerges some need to adapt user interface elements to regional customs. Most notably, text that gives information to the subject requires translation into the subject's native language, as often a knowledge of English cannot be assumed. Even with a knowledge of Englisn, reading text in a foreign language is a distracting factor that makes the already demanding task of operating a BCI even more difficult.
	to adapt user interface elements to regional customs. Most notably, text that
	gives information to the subject requires translation into the subject's native
	language, as often a knowledge of English cannot be assumed~~, and if so~~, reading
	text in a foreign language is a distracting factor that makes the already demanding
	task of operating a BCI even more difficult.

	This document explains the approach taken to manage localized (translated) user interface		This document explains the approach taken to manage localized (translated) user interface strings in BCI2000 application modules, trying to meet the following goals:
	strings in BCI2000 application modules, trying to meet the following goals:

	*'''Flexibility:''' For the end user (operator), it should be possible to add translations into a language that is not provided inside an application module, and to modify translations he does not feel to be appropriate. This should be achievable without making changes to the source code and recompiling the application module.		*'''Flexibility:''' For the end user (operator), it should be possible to add translations into a language that are not provided inside an application module, and to modify translations he does not feel to be appropriate. This should be achievable without making changes to the source code and recompiling the application module.
	*'''Separability:''' For the user, switching languages should be done at a central place, i.e. by changing a single parameter. For the programmer, adding localization capabilities to existing modules should be possible with minimal changes to existing code. When writing new application modules, there should be no need to consider localization issues in advance.		*'''Separability:''' For the user, switching languages should be done at a central place, i.e. by changing a single parameter. For the programmer, adding localization capabilities to existing modules should be possible with minimal changes to existing code. When writing new application modules, there should be no need to consider localization issues in advance.
	*'''Documentation:''' Documenting and providing a collection of existing translations into various languages should be possible inside a module's source code.		*'''Documentation:''' Documenting and providing a collection of existing translations into various languages should be possible inside a module's source code.
Line 27:		Line 21:
	the target language against row labels. If no match is found, it will leave the text unchanged.		the target language against row labels. If no match is found, it will leave the text unchanged.

	For string literals in <tt>*.cpp</tt> files, the strategy is to simply put a function layer around the string, i.e. to send it through a function that checks for a translation		For string literals in <tt>*.cpp</tt> files, the strategy is to simply put a function layer around the string, i.e. to send it through a function that checks for a translation and exchanges the text if there is a match. Introducing localizability into existing code, implies only a very small amount of change compared to, e.g., introducing a separate parameter for each string. In the former case, one needs only wrap the string literal into a function call in-place; in the latter case, one would have to add a parameter line to a possibly remote filter class constructor, read that parameter from inside that filter's <tt>Initialize()</tt> call, and put it into the object that actually holds the string which might require introduction of additional accessor functions.
	and exchanges the text if there is a match. ~~When introducing~~ localizability into existing code, ~~this~~ implies only a very small amount of ~~changes~~ compared to, e.g., introducing
	a separate parameter for each string. In the former case, one needs only wrap the string literal into a function call in-place; in the latter case, one would have to add a parameter line to a possibly remote filter class constructor, read that parameter from inside that filter's <tt>Initialize()</tt> call, and put it into the object that actually holds the string which might require introduction of additional accessor functions.

	For strings specified in GUI resource files, the strategy is to supply a function that, very generally, examines string properties of GUI objects, replacing them with their localized versions if applicable.		For strings specified in GUI resource files, the strategy is to supply a function that, very generally, examines string properties of GUI objects, replacing them with their localized versions if applicable.
Line 48:		Line 40:
	==='''Interface to the programmer'''===		==='''Interface to the programmer'''===

	The <tt>LocalizedStrings</tt> parameter is empty by default.		The <tt>LocalizedStrings</tt> parameter is empty by default. Although a user may add translations in desired languages to the empty matrix by manually using the operator module's matrix editor, translations will preferably be provided in a filter constructor by listing them as in the following example:
	Although a user may add translations in desired languages to the empty matrix by ~~hand --~~ using the operator module's matrix editor --,
	translations will preferably be provided in a filter constructor by listing them as in the following example:

	#include "Localization.h"		#include "Localization.h"
Line 87:		Line 77:


	There may be any number of translation tables inside filter constructors, with their		There may be any number of translation tables inside filter constructors, with their entries being added to the existing ones, or overriding entries that already exist.
	entries being added to the existing ones, or overriding entries that already exist.

	Once entered, the translations contained in <tt>LocalizedStrings</tt> are applied via two ~~mechanisms~~:		Once entered, the translations contained in <tt>LocalizedStrings</tt> are applied via two echanisms:

	*The function <tt>LocalizableString()</tt> takes a string as an argument and returns the appropriate entry from <tt>LocalizedStrings</tt>, or the unmodified string if no entry can be found. E.g., instead of		*The function <tt>LocalizableString()</tt> takes a string as an argument and returns the appropriate entry from <tt>LocalizedStrings</tt>, or the unmodified string if no entry can be found. E.g., instead of

Atennissen at 20:20, 5 March 2007

2007-03-05T20:20:59Z

@@ Line 103: / Line 103: @@
 '''*''' Language names are case-insensitive. You may use any string for a language name but as a convention we suggest its most common English name, as in <tt>Italian, Dutch, French, German</tt>, with international country abbreviations as optional regional qualifiers as in <tt>EnglishUS, EnglishGB, GermanA, GermanCH</tt> if necessary.
+[[Image:table.png|center|thumb|300px|table]]
-\begin{table}
 '''*''' Encoding of non-ASCII characters follows the UTF8 convention. To ensure platform independent readability of source code files, there are macros that define HTML character names to their UTF8 encoded strings. This allows you to write

Gschalk: /* '''Interface to the programmer''' */

2007-03-05T18:19:17Z

'''Interface to the programmer'''

← Older revision		Revision as of 18:19, 5 March 2007
Line 52:		Line 52:
	translations will preferably be provided in a filter constructor by listing them as in the following example:		translations will preferably be provided in a filter constructor by listing them as in the following example:

	#include "Localization.h"		#include "Localization.h"
	...		...
	TTask::TTask()		TTask::TTask()
	{		{
	...		...
	LANGUAGES "Italian",		LANGUAGES "Italian",
	"French",		"French",
	BEGIN_LOCALIZED_STRINGS		BEGIN_LOCALIZED_STRINGS
	"Yes",		"Yes",
	"Si",		"Si",
	"Oui",		"Oui",
	"No",		"No",
	"No",		"No",
	"Non",		"Non",
	END_LOCALIZED_STRINGS		END_LOCALIZED_STRINGS
	...		...
	}		}

	If the <tt>LocalizedStrings</tt> matrix was empty before the <tt>TTask</tt> constructor gets called, it will have these entries after execution of the constructor:		If the <tt>LocalizedStrings</tt> matrix was empty before the <tt>TTask</tt> constructor gets called, it will have these entries after execution of the constructor:
Line 95:		Line 95:
	<tt>TellUser( "Well done!" );</tt><br>one would write<br><tt>#include "Localization.h"<br>...<br>TellUser( LocalizableString( "Well done!" ) );<br></tt>to have a translation for "Well done!" looked up in <tt>LocalizedStrings</tt>.		<tt>TellUser( "Well done!" );</tt><br>one would write<br><tt>#include "Localization.h"<br>...<br>TellUser( LocalizableString( "Well done!" ) );<br></tt>to have a translation for "Well done!" looked up in <tt>LocalizedStrings</tt>.

	* The function <tt>ApplyLocalizations()</tt> takes a pointer to a GUI object (usually a VCL <tt>TForm*</tt>) and translates all localizable text contained within it. This function must be called during <tt>GenericFilter:: Initialize</tt> for each GUI object generated from a resource file.		* The function <tt>ApplyLocalizations()</tt> takes a pointer to a GUI object (usually a VCL <tt>TForm*</tt>) and translates all localizable text contained within it. This function must be called during <tt>GenericFilter:: Initialize</tt> for each GUI object generated from a resource file.

	==='''Further implementation details'''===		==='''Further implementation details'''===

Gschalk: /* '''Interface to the programmer''' */

2007-03-03T19:59:17Z

'''Interface to the programmer'''

← Older revision		Revision as of 19:59, 3 March 2007
Line 97:		Line 97:
	* The function <tt>ApplyLocalizations()</tt> takes a pointer to a GUI object (usually a VCL <tt>TForm*</tt>) and translates all localizable text contained within it. This function must be called during <tt>GenericFilter:: Initialize</tt> for each GUI object generated from a resource file.		* The function <tt>ApplyLocalizations()</tt> takes a pointer to a GUI object (usually a VCL <tt>TForm*</tt>) and translates all localizable text contained within it. This function must be called during <tt>GenericFilter:: Initialize</tt> for each GUI object generated from a resource file.

	'''~~3.3~~ Further implementation details'''		==='''Further implementation details'''===

	'''*''' You should not use <tt>LocalizableString()</tt> on string constants used before the first call to <tt>GenericFilter::Initialize()</tt> or for initializing static or global objects of any kind because localization information used will not be available at global initialization time, and local static variables, once initialized, will not be updated appropriately.		'''*''' You should not use <tt>LocalizableString()</tt> on string constants used before the first call to <tt>GenericFilter::Initialize()</tt> or for initializing static or global objects of any kind because localization information used will not be available at global initialization time, and local static variables, once initialized, will not be updated appropriately.

← Older revision		Revision as of 14:21, 9 May 2007
Line 5:		Line 5:

	*'''Flexibility:''' For the end user (operator), it should be possible to add translations into a language that are not provided inside an application module, and to modify translations he does not feel to be appropriate. This should be achievable without making changes to the source code and recompiling the application module.		*'''Flexibility:''' For the end user (operator), it should be possible to add translations into a language that are not provided inside an application module, and to modify translations he does not feel to be appropriate. This should be achievable without making changes to the source code and recompiling the application module.
	*'''Separability:''' For the user, switching languages should be done at a central place, i.e. by changing a single parameter. For the programmer, adding localization capabilities to existing modules should be possible with minimal changes to existing code. When writing new application modules, there should be no need to consider localization issues in advance.		*'''Separability:''' For the user, switching languages should be done at a central place, i.e., by changing a single parameter. For the programmer, adding localization capabilities to existing modules should be possible with minimal changes to existing code. When writing new application modules, there should be no need to consider localization issues in advance.
	*'''Documentation:''' Documenting and providing a collection of existing translations into various languages should be possible inside a module's source code.		*'''Documentation:''' Documenting and providing a collection of existing translations into various languages should be possible inside a module's source code.

Line 11:		Line 11:
	== '''Strategies''' ==		== '''Strategies''' ==

	For a number of text values that have always been set from parameters (such as the Speller module's <tt>Goal</tt> parameter that holds the text the user is told to spell in copy spelling mode), localization is not an issue because the user may just change the value as it seems appropriate.		For a number of text values that have always been set from parameters (such as the Speller module's <tt>Goal</tt> parameter that holds the text the user is told to spell in copy spelling mode), localization is not an issue because the user may just change the value as seems appropriate.

	The remaining text items, according to the way they are specified, fall into two categories:		The remaining text items, according to the way they are specified, fall into two categories:
Line 18:		Line 18:
	# text fields in GUI resource files (such as Borland <tt>*.dfm</tt> files).		# text fields in GUI resource files (such as Borland <tt>*.dfm</tt> files).

	For both categories, translations are kept in a single matrix type parameter that uses string labels, i.e. row and column titles. Each column title represents the native English version of a text; row titles represent languages for which translations exist. The user chooses amongst languages by specifying the desired language in a second parameter; the BCI2000 framework will then use this table to look up a text's translation, matching the text itself against column labels, and		For both categories, translations are kept in a single matrix type parameter that uses string labels, i.e., row and column titles. Each column title represents the native English version of a text; row titles represent languages for which translations exist. The user chooses amongst languages by specifying the desired language in a second parameter; the BCI2000 framework will then use this table to look up a text's translation, matching the text itself against column labels, and
	the target language against row labels. If no match is found, it will leave the text unchanged.		the target language against row labels. If no match is found, it will leave the text unchanged.

	For string literals in <tt>*.cpp</tt> files, the strategy is to simply put a function layer around the string, i.e. to send it through a function that checks for a translation and exchanges the text if there is a match. Introducing localizability into existing code, implies only a very small amount of change compared to, e.g., introducing a separate parameter for each string. In the former case, one needs only wrap the string literal into a function call in-place; in the latter case, one would have to add a parameter line to a possibly remote filter class constructor, read that parameter from inside that filter's <tt>Initialize()</tt> call, and put it into the object that actually holds the string which might require introduction of additional accessor functions.		For string literals in <tt>*.cpp</tt> files, the strategy is to simply put a function layer around the string, i.e., to send it through a function that checks for a translation and exchanges the text if there is a match. Introducing localizability into existing code implies only a very small amount of change compared to, e.g., introducing a separate parameter for each string. In the former case, one needs only wrap the string literal into a function call in-place; in the latter case, one would have to add a parameter line to a possibly remote filter class constructor, read that parameter from inside that filter's <tt>Initialize()</tt> call, and put it into the object that actually holds the string which might require introduction of additional accessor functions.

	For strings specified in GUI resource files, the strategy is to supply a function that, very generally, examines string properties of GUI objects, replacing them with their localized versions if applicable.		For strings specified in GUI resource files, the strategy is to supply a function that, very generally, examines string properties of GUI objects, replacing them with their localized versions if applicable.
Line 36:		Line 36:
	behavior:		behavior:
	'''*''' <tt>Language</tt> defines the language into which strings are translated; if its value matches one of the <tt>LocalizedStrings</tt> row labels, translations will be taken from that row; otherwise, strings will not be translated. A value of <tt>Default</tt> results in all strings keeping their original values.		'''*''' <tt>Language</tt> defines the language into which strings are translated; if its value matches one of the <tt>LocalizedStrings</tt> row labels, translations will be taken from that row; otherwise, strings will not be translated. A value of <tt>Default</tt> results in all strings keeping their original values.
	'''*''' <tt>LocalizedStrings</tt> defines string translations. Strings that ~~don't~~ appear as a column label will not be translated. Also, strings with an empty translation entry in <tt>LocalizedStrings</tt> will not be translated.		'''*''' <tt>LocalizedStrings</tt> defines string translations. Strings that do not appear as a column label will not be translated. Also, strings with an empty translation entry in <tt>LocalizedStrings</tt> will not be translated.

	==='''Interface to the programmer'''===		==='''Interface to the programmer'''===

	The <tt>LocalizedStrings</tt> parameter is empty by default. Although a user may add translations in desired languages to the empty matrix by manually using the operator module~~'s matrix editor~~, translations will preferably be provided in a filter constructor by listing them as in the following example:		The <tt>LocalizedStrings</tt> parameter is empty by default. Although a user may add translations in desired languages to the empty matrix by manually using the matrix editor of the operator module, translations will preferably be provided in a filter constructor by listing them as in the following example:

	#include "Localization.h"		#include "Localization.h"
Line 79:		Line 79:
	There may be any number of translation tables inside filter constructors, with their entries being added to the existing ones, or overriding entries that already exist.		There may be any number of translation tables inside filter constructors, with their entries being added to the existing ones, or overriding entries that already exist.

	Once entered, the translations contained in <tt>LocalizedStrings</tt> are applied via two ~~echanisms~~:		Once entered, the translations contained in <tt>LocalizedStrings</tt> are applied via two mechanisms:

	*The function <tt>LocalizableString()</tt> takes a string as an argument and returns the appropriate entry from <tt>LocalizedStrings</tt>, or the unmodified string if no entry can be found. ~~E.g.~~, instead of		*The function <tt>LocalizableString()</tt> takes a string as an argument and returns the appropriate entry from <tt>LocalizedStrings</tt>, or the unmodified string if no entry can be found. For example, instead of
	<tt>TellUser( "Well done!" );</tt><br>one would write<br><tt>#include "Localization.h"<br>...<br>TellUser( LocalizableString( "Well done!" ) );<br></tt>to have a translation for "Well done!" looked up in <tt>LocalizedStrings</tt>.		<tt>TellUser( "Well done!" );</tt><br>one would write<br><tt>#include "Localization.h"<br>...<br>TellUser( LocalizableString( "Well done!" ) );<br></tt>to have a translation for "Well done!" looked up in <tt>LocalizedStrings</tt>.

Line 94:		Line 94:
	[[Image:table.png\|center\|thumb\|300px\|table]]		[[Image:table.png\|center\|thumb\|300px\|table]]


	'''*''' Encoding of non-ASCII characters follows the UTF8 convention. To ensure platform independent readability of source code files, there are macros that define HTML character names to their UTF8 encoded strings. This allows you to write		'''*''' Encoding of non-ASCII characters follows the UTF8 convention. To ensure platform independent readability of source code files, there are macros that define HTML character names to their UTF8 encoded strings. This allows you to write