Merge pull request #4319 from bruvzg/ctl_docs

[Complex Text Layouts] Update tutorials and documentation to match TextServer changes.

tutorials/i18n/internationalizing_games.rst

@@ -133,6 +133,75 @@ called the :ref:`TranslationServer <class_TranslationServer>`.
 Translations can be added or removed during run-time;
 the current language can also be changed at run-time.
 
+Bidirectional text and UI Mirroring
+-----------------------------------
+
+Arabic and Hebrew are written from right to left (except for the numbers and Latin
+words mixed in), and the user interface for these languages should be mirrored as well.
+In some languages the shape of a glyph changes depending on the surrounding characters.
+
+Support for bidirectional writing systems and UI mirroring is transparent, you don't
+usually need to change anything or have any knowledge of the specific writing system.
+
+For RTL languages, Godot will automatically do the following changes to the UI:
+
+-  Mirrors left/right anchors and margins.
+-  Swaps left and right text alignment.
+-  Mirrors horizontal order of the child controls in the containers, and items in Tree/ItemList controls.
+-  Uses mirrored order of the internal control elements (e.g. OptionButton dropdown button, checkbox alignment, List column order, Tree item icons and connecting line alignment, e.t.c.), in some cases mirrored controls use separate theme styles.
+-  Coordinate system is not mirrored, and non-UI nodes (sprites, e.t.c) are not affected.x
+
+It is possible to override text and control layout direction by using the following control properties:
+
+-  ``text_direction``, sets the base text direction. When set to "auto", direction depends on the first strong directional character in the text according to the Unicode Bidirectional Algorithm,
+-  ``language``, overrides current project locale.
+-  ``structured_text_bidi_override property`` and ``_structured_text_parser callback``, enables special handling for structured text.
+-  ``layout_direction``, overrides control mirroring.
+
+.. image:: img/ui_mirror.png
+
+Adding break iterator data to exported project
+----------------------------------------------
+
+Some languages are written without spaces, and word and line breaking requires more than rules over character sequences.
+Godot includes ICU rule and dictionary based, break iterator data, but this data is not included into exported projects by default.
+To include it go to **Project → Project Settings → Localization → Text Server Data** and click **Install support data...**. Break iterator data is about 4 MB large.
+
+.. image:: img/icu_data.png
+
+Structured text BiDi override
+-----------------------------
+
+Unicode BiDi algorithm is designed to work with natural text and it's incapable of
+handling text with the higher level order, like file names, URIs, email addresses,
+regular expressions or source code.
+
+.. image:: img/bidi_override.png
+
+For example, the path for this shown directory structure will be displayed incorrectly
+(top "LineEdit" control). "File" type structured text override splits text into segments,
+then BiDi algorithm is applied to each of them individually to correctly display directory
+names in any language and preserve correct order of the folders (bottom "LineEdit" control).
+
+Custom callbacks provide a way to override BiDi for the other types of structured text.
+
+Localizing numbers
+------------------
+
+Controls specifically designed for number input or output (e.g. ProgressBar, SpinBox)
+will use localized numbering system automatically, for the other control
+:ref:`TextServer.format_number(string, language) <class_TextServer_method_format_number>`
+can be used to convert Western Arabic numbers (0..9) to the localized numbering system
+and :ref:`TextServer.parse_number(string, language) <class_TextServer_method_parse_number>`
+to convert it back.
+
+Localizing icons and images
+---------------------------
+
+Icons with left and right pointing arrows which may need to be reversed for Arabic
+and Hebrew locales, in case they indicate movement or direction (e.g. back/forward
+buttons), otherwise they can remain the same.
+
 Command line
 ------------