Localization: documentation

Docs/AngelScriptAPI.h

@@ -5668,6 +5668,40 @@ int weakRefs;
 int width;
 };
 
+class Localization
+{
+// Methods:
+String Get(const String&);
+String GetLanguage(int);
+int GetLanguageIndex(const String&);
+void LoadJSON(const JSONValue&);
+void LoadJSONFile(const String&);
+void Reset();
+void SendEvent(const String&, VariantMap& = VariantMap ( ));
+void SetLanguage(const String&);
+void SetLanguage(int);
+
+// Properties:
+/* readonly */
+StringHash baseType;
+/* readonly */
+String category;
+/* readonly */
+String language;
+/* readonly */
+int languageIndex;
+/* readonly */
+int numLanguages;
+/* readonly */
+int refs;
+/* readonly */
+StringHash type;
+/* readonly */
+String typeName;
+/* readonly */
+int weakRefs;
+};
+
 class Log
 {
 // Methods:
@@ -10416,6 +10450,7 @@ Array<Variant> attributeDefaults;
 /* readonly */
 Array<AttributeInfo> attributeInfos;
 Array<Variant> attributes;
+bool autoLocalizable;
 /* readonly */
 StringHash baseType;
 bool bringToBack;
@@ -13170,6 +13205,7 @@ Engine engine;
 FileSystem fileSystem;
 Graphics graphics;
 Input input;
+Localization localization;
 Log log;
 Network network;
 Node node;

Docs/LuaScriptAPI.dox

@@ -98,6 +98,7 @@ namespace Urho3D
 <a href="#Class_Light"><b>Light</b></a>
 <a href="#Class_LineEdit"><b>LineEdit</b></a>
 <a href="#Class_ListView"><b>ListView</b></a>
+<a href="#Class_Localization"><b>Localization</b></a>
 <a href="#Class_Log"><b>Log</b></a>
 <a href="#Class_LuaScriptInstance"><b>LuaScriptInstance</b></a>
 <a href="#Class_Material"><b>Material</b></a>
@@ -2983,6 +2984,29 @@ Properties:
 - bool hierarchyMode
 - int baseIndent
 
+<a name="Class_Localization"></a>
+### Localization : Object
+
+Methods:
+
+- int GetNumLanguages() const
+- int GetLanguageIndex() const
+- int GetLanguageIndex(const String language)
+- String GetLanguage()
+- String GetLanguage(int index)
+- void SetLanguage(int index)
+- void SetLanguage(const String language)
+- String Get(const String id)
+- void Reset()
+- void LoadJSON(const JSONValue& source)
+- void LoadJSONFile(const String name)
+
+Properties:
+
+- int numLanguages (readonly)
+- int languageIndex (readonly)
+- String language (readonly)
+
 <a name="Class_Log"></a>
 ### Log : Object
 
@@ -5707,6 +5731,8 @@ Methods:
 - void SetHoverColor(const Color& color)
 - void SetTextEffect(TextEffect textEffect)
 - void SetEffectColor(const Color& effectColor)
+- bool GetAutoLocalizable() const
+- void SetAutoLocalizable(bool enable)
 - Font* GetFont() const
 - int GetFontSize() const
 - const String GetText() const
@@ -5736,6 +5762,7 @@ Properties:
 - HorizontalAlignment textAlignment
 - float rowSpacing
 - bool wordwrap
+- bool autoLocalizable
 - unsigned selectionStart (readonly)
 - unsigned selectionLength (readonly)
 - Color& selectionColor
@@ -7631,6 +7658,7 @@ Properties:
 - Graphics* GetGraphics()
 - Input* GetInput()
 - String GetInternalPath(const String pathName)
+- Localization* GetLocalization()
 - Log* GetLog()
 - String GetNativePath(const String pathName)
 - Network* GetNetwork()
@@ -7658,11 +7686,11 @@ Properties:
 - void PrintLine(const String str, bool error = false)
 - int Rand()
 - float RandStandardNormal()
-- float Random()
-- float Random(float min, float max)
 - float Random(float range)
-- int RandomInt(int min, int max)
+- float Random(float min, float max)
+- float Random()
 - int RandomInt(int range)
+- int RandomInt(int min, int max)
 - float RandomNormal(float meanValue, float variance)
 - String RemoveTrailingSlash(const String pathName)
 - String ReplaceExtension(const String fullPath, const String newExtension)
@@ -7673,8 +7701,8 @@ Properties:
 - float Sign(float value)
 - float Sin(float angle)
 - float SmoothStep(float lhs, float rhs, float t)
-- void SubscribeToEvent(void* sender, const String eventName, void* functionOrFunctionName)
 - void SubscribeToEvent(const String eventName, void* functionOrFunctionName)
+- void SubscribeToEvent(void* sender, const String eventName, void* functionOrFunctionName)
 - float Tan(float angle)
 - bool ToBool(const String source)
 - Color ToColor(const String source)
@@ -7697,8 +7725,8 @@ Properties:
 - Vector4 ToVector4(const String source, bool allowMissingCoords = false)
 - void UnsubscribeFromAllEvents()
 - void UnsubscribeFromAllEventsExcept(const Vector<String>& exceptionNames)
-- void UnsubscribeFromEvent(Object* sender, const String eventName)
 - void UnsubscribeFromEvent(const String eventName)
+- void UnsubscribeFromEvent(Object* sender, const String eventName)
 - void UnsubscribeFromEvents(Object* sender)
 
 
@@ -7711,6 +7739,7 @@ Properties:
 - FileSystem* fileSystem (readonly)
 - Graphics* graphics (readonly)
 - Input* input (readonly)
+- Localization* localization (readonly)
 - Log* log (readonly)
 - Network* network (readonly)
 - Renderer* renderer (readonly)

Docs/Reference.dox

@@ -394,7 +394,90 @@ If a resource depends on other resources, writing efficient threaded loading for
 
 \page Localization Localization
 
-TODO About Localization.
+The Localization subsystem provides a simple way to creating multilingual applications.
+
+\section LocalizationInit Initialization
+
+Before using the subsystem must load a collection of strings. A common practice is to make it into function Start(). Allowed loading of multiple files.
+
+\code
+Localization* l10n = GetSubsystem<Localization>();
+l10n->LoadJSONFile("StringsEnRu.json");
+l10n->LoadJSONFile("StringsDe.json");
+\endcode
+
+JSON files must be in UTF8 encoding without BOM. Sample files are in a directory Data. The JSON files have the following format:
+
+\code
+{
+	"string id 1":{
+		"language 1":"value11",
+		"language 2":"value12",
+		"language 3":"value13"
+	},
+	"string id 2":{
+		"language 1":"value21",
+		"language 2":"value22",
+		"language 3":"value23"
+	}
+}
+\endcode
+
+It can be defined any number of languages. Remember that language names and string identifiers are case sensitive. "En" and "en" are considered different languages.
+During the loading process languages are numbered in order of finding. Indexing starts from zero. The first founded language immediately appointed as the current language.
+
+When initialization is usually also need to hook a function to be called when you change the language.
+
+\code
+SubscribeToEvent(E_CHANGELANGUAGE, HANDLER(ClassName, HandleChangeLanguage));
+\endcode
+
+\section LocalizationUsing Using
+
+The Get function returns a string with the specified string identifier in the current language.
+
+\code
+Text* t = new Text(context_);
+t->SetName("Text1");
+Localization* l10n = GetSubsystem<Localization>();
+t->SetText(l10n->Get("string 1"));
+\endcode
+
+This function returns String::EMPTY if the string id is empty. This function returns the id if translation is not found and will be added a warning into the log.
+
+It is also necessary to implement a reaction to change the language.
+
+\code
+void Game::HandleChangeLanguage(StringHash eventType, VariantMap& eventData)
+{
+    Localization* l10n = GetSubsystem<Localization>();
+    ...
+    Text* t = static_cast<Text*>(uiRoot->GetChild("Text1", true));
+    t->SetText(l10n->Get("string 1"));
+}
+\endcode
+
+Like that You can change texts, sprites and other aspects of the game when language is changed.
+
+For Text elements is possible automatic translations.
+
+\code
+Text* t2 = new Text(context_);
+t2->SetText("string 2");
+t2->SetAutoLocalizable(true);
+\endcode
+
+Wherein text value is used as an identifier. In this case, the change of text in HandleChangeLanguage is not necessary.
+
+Change the language allows function SetLanguage().
+
+\code
+Localization* l10n = GetSubsystem<Localization>();
+l10n->SetLanguage("language 2");
+l10n->SetLanguage(0);
+\endcode
+
+Also see the example 40_Localization.
 
 \page Scripting Scripting
 

Docs/ScriptAPI.dox

@@ -413,6 +413,8 @@ namespace Urho3D
 - %Success : bool
 - %Resource : Resource pointer
 
+### ChangeLanguage
+
 ## %Scene events
 
 ### SceneUpdate
@@ -1925,6 +1927,7 @@ namespace Urho3D
 - %Text %Alignment : int
 - %Row %Spacing : float
 - %Word %Wrap : bool
+- %Auto %Localizable : bool
 - %Selection %Color : Color
 - %Hover %Color : Color
 - %Text %Effect : int
@@ -2242,6 +2245,7 @@ namespace Urho3D
 <a href="#Class_Light"><b>Light</b></a>
 <a href="#Class_LineEdit"><b>LineEdit</b></a>
 <a href="#Class_ListView"><b>ListView</b></a>
+<a href="#Class_Localization"><b>Localization</b></a>
 <a href="#Class_Log"><b>Log</b></a>
 <a href="#Class_Material"><b>Material</b></a>
 <a href="#Class_Matrix3"><b>Matrix3</b></a>
@@ -7216,6 +7220,34 @@ Properties:
 - int weakRefs // readonly
 - int width
 
+<a name="Class_Localization"></a>
+
+### Localization
+
+Methods:
+
+- String Get(const String&)
+- String GetLanguage(int)
+- int GetLanguageIndex(const String&)
+- void LoadJSON(const JSONValue&)
+- void LoadJSONFile(const String&)
+- void Reset()
+- void SendEvent(const String&, VariantMap& = VariantMap ( ))
+- void SetLanguage(const String&)
+- void SetLanguage(int)
+
+Properties:
+
+- StringHash baseType // readonly
+- String category // readonly
+- String language // readonly
+- int languageIndex // readonly
+- int numLanguages // readonly
+- int refs // readonly
+- StringHash type // readonly
+- String typeName // readonly
+- int weakRefs // readonly
+
 <a name="Class_Log"></a>
 
 ### Log
@@ -11398,6 +11430,7 @@ Properties:
 - Variant[] attributeDefaults // readonly
 - AttributeInfo[] attributeInfos // readonly
 - Variant[] attributes
+- bool autoLocalizable
 - StringHash baseType // readonly
 - bool bringToBack
 - bool bringToFront
@@ -13833,6 +13866,7 @@ Properties:
 - FileSystem@ fileSystem
 - Graphics@ graphics
 - Input@ input
+- Localization@ localization
 - Log@ log
 - Network@ network
 - Node@ node