Changes from Version 1 of documentation/Localisation

Author:: peterc (IP: 203.96.63.172)
Timestamp:: 03/13/08 14:41:42 (9 years ago)
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

documentation/Localisation

v0	v1
	1	= Localisation =
	2
	3	While libRocket fully supports localisation, there are a number of issues you will need to be aware of.
	4
	5	== String encoding ==
	6
	7	libRocket assumes all data it is given, whether read in from RML or provided procedurally, is in UTF-8 encoding. This means if you're using 8-bit ASCII you don't need to change anything, but allows you to specify multi-byte Unicode characters if required.
	8
	9	Once libRocket has parsed text (and run it through the translator, see below), the strings will be converted into UCS-2, strictly for performance reasons.
	10
	11	== String tables ==
	12
	13	All raw text that libRocket reads while parsing RML (i.e., everything other than XML tags) is sent through the ''TranslateString()'' function on the [wiki:documentation/C++Manual/Interfaces#Thesysteminterface system interface]. The function is given the raw string as read, and the application can make any modifications necessary before returning the translated string (and the number of substitutions made) back to libRocket.
	14
	15	A pass-through translator would do the following:
	16
	17	{{{
	18	#include <Rocket/Core/SystemInterface.h>
	19
	20	class SampleSystemInterface : public Rocket::Core::SystemInterface
	21	{
	22	int TranslateString(EMP::Core::String& translated, const EMP::Core::String& input)
	23	{
	24	translated = input;
	25	return 0;
	26	}
	27	}}}
	28
	29	The ''TranslateString()'' method can be used in conjunction with an application's string table to make text substitutions on a document's text. For example, take the pause.rml file in the Rocket Invaders sample:
	30
	31	{{{
	32	<rml>
	33	<head>
	34	<title>Quit?</title>
	35	</head>
	36	<body>
	37	<p>Are you sure you want to end this game?</p>
	38	<button>Yes</button>
	39	<button>No!</button>
	40	</body>
	41	</rml>
	42	}}}
	43
	44	If we were to localise Rocket Invaders, we'd want to move all of the strings out from the RML and into a string table. The raw text in the RML would then be replaced with the string table tokens:
	45
	46	{{{
	47	<rml>
	48	<head>
	49	<title>[QUIT_TITLE]</title>
	50	</head>
	51	<body>
	52	<p>[QUIT_CONFIRM]</p>
	53	<button>[CONFIRM]</button>
	54	<button>[DENY]</button>
	55	</body>
	56	</rml>
	57	}}}
	58
	59	Our sample translator would then become:
	60
	61	{{{
	62	int TranslateString(EMP::Core::String& translated, const EMP::Core::String& input)
	63	{
	64	// Attempt to find the translation in the string table.
	65	if (StringTable::GetString(translated, input))
	66	return 1;
	67
	68	// No translation; return the raw input string.
	69	translated = input;
	70	return 0;
	71	}
	72	}}}
	73
	74	And now (assuming the application's StringTable::GetString() returns the appropriate string) the strings will be valid for whatever language we specify a string table for. Note that you can place RML into the translated string, and it will be parsed appropriately. For example, you could replace a token with an <img> tag to render an icon for a controller button.
	75
	76	== Font charsets ==
	77
	78	libRocket's fonts have configurable character sets. By default, a font will support only the Basic Latin characters (codepoints 32 - 126) in order to save texture space. In order to support the character sets required by non-English languages, use the 'font-charset' property. For example, to specify a character set including the Latin-1 supplement (codepoints 0x80 - 0xFF), you would set the following RCSS property:
	79
	80	{{{
	81	font-charset: U+0020-00FF;
	82	}}}
	83
	84	If libRocket renders text using a font that does not include all the necessary characters, the missing characters will be ignored. For more information on the font-charset property, see the [wiki:documentation/RCSS/Fonts#Fontcharset:thefont-charsetproperty documentation]. For information on Unicode character sets, try [http://unicode.org/charts/ unicode.org] or [http://jrgraphix.net/research/unicode_blocks.php J.R. Graphics].