Moved localisation docs to dedicated page

docs/source/reference/modding/index.rst

@@ -28,3 +28,4 @@ about creating new content for OpenMW, please refer to
 	sky-system
 	extended
 	paths
+	localisation

docs/source/reference/modding/localisation.rst

@@ -0,0 +1,83 @@
+Localisation
+============
+
+OpenMW supports localisation of mods using ICU MessageFormat wrapped in YAML.
+Currently this is only possible using the
+`openmw.core.l10n <../lua-scripting/openmw_core.html##(core).l10n>`_ lua function.
+
+Locales
+-------
+
+Locales usually have the form ``{lang}_{COUNTRY}``,
+where ``{lang}`` is a lowercase two-letter language code and ``{COUNTRY}`` is an uppercase
+two-letter country code. Localisation files *must* have this exact capitalisation and separator
+to be recognized.
+
+When users request a locale using the :ref:`preferred locales` setting they do not need to match capitalisation
+and can also use hyphens instead of underscores. The locale will be normalised to the above format.
+
+Locales may also contain variants and keywords, though these usually will not be necessary.
+See `The Locale chapter of the ICU Guide <https://unicode-org.github.io/icu/userguide/locale/#language-code>`_ for full details.
+
+Localisation Files
+--------------------------
+
+Localisation files (containing the message names and translations) should be stored in the
+VFS as files of the form ``l10n/<ContextName>/<Locale>.yaml``.
+
+Messages contents have the form of ICU MessageFormat strings.
+See `the Formatting Messages chapter of the ICU Guide <https://unicode-org.github.io/icu/userguide/format_parse/messages/>`_
+for a guide to MessageFormat, and see
+`The ICU APIdoc <https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classicu_1_1MessageFormat.html>`_
+for full details of the MessageFormat syntax.
+
+Examples
+~~~~~~~~
+
+.. code-block:: yaml
+    :caption: DataFiles/l10n/MyMod/en.yaml
+
+    good_morning: 'Good morning.'
+
+    you_have_arrows: |-
+      {count, plural,
+        one {You have one arrow.}
+        other {You have {count} arrows.}
+      }
+
+.. code-block:: yaml
+    :caption: DataFiles/l10n/MyMod/de.yaml
+
+    good_morning: "Guten Morgen."
+    you_have_arrows: |-
+      {count, plural,
+        one {Du hast ein Pfeil.}
+        other {Du hast {count} Pfeile.}
+      }
+    "Hello {name}!": "Hallo {name}!"
+
+Select rules can be used to match arbitrary string arguments.
+The default keyword ``other`` must always be provided.
+
+.. code-block:: yaml
+    :caption: DataFiles/l10n/AdvancedExample/en.yaml
+
+    pc_must_come: {PCGender, select,
+        male {He is}
+        female {She is}
+        other {They are}
+      } coming with us.
+
+Numbers have various formatting options and can also be formatted with custom patterns.
+See `The ICU Guide <https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html#syntax>`_
+
+.. code-block:: yaml
+    :caption: DataFiles/l10n/AdvancedExample2/en.yaml
+
+    quest_completion: "The quest is {done, number, percent} complete."
+    # E.g. "You came in 4th place"
+    ordinal: "You came in {num, ordinal} place."
+    # E.g. "There is one thing", "There are one hundred things"
+    spellout: "There {num, plural, one{is {num, spellout} thing} other{are {num, spellout} things}}."
+    numbers: "{int} and {double, number, integer} are integers, but {double} is a double"
+    rounding: "{value, number, :: .00}"

files/lua_api/openmw/core.lua

@@ -54,25 +54,14 @@
 
 ---
 -- Return l10n formatting function for the given context.
--- Language files should be stored in VFS as `l10n/<ContextName>/<Locale>.yaml`.
+-- Localisation files (containing the message names and translations) should be stored in
+-- VFS as files of the form `l10n/<ContextName>/<Locale>.yaml`.
 --
--- Locales usually have the form {lang}_{COUNTRY},
+-- See [Localisation](../modding/localisation.html) for details of the localisation file structure.
--- where {lang} is a lowercase two-letter language code and {COUNTRY} is an uppercase
--- two-letter country code. Capitalization and the separator must have exactly
--- this format for language files to be recognized, but when users request a
--- locale they do not need to match capitalization and can use hyphens instead of
--- underscores.
 --
--- Locales may also contain variants and keywords. See https://unicode-org.github.io/icu/userguide/locale/#language-code
--- for full details.
---
--- Messages have the form of ICU MessageFormat strings.
--- See https://unicode-org.github.io/icu/userguide/format_parse/messages/
--- for a guide to MessageFormat, and see 
--- https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classicu_1_1MessageFormat.html
--- for full details of the MessageFormat syntax.
 -- @function [parent=#core] l10n
 -- @param #string context l10n context; recommended to use the name of the mod.
+--                This must match the <ContextName> directory in the VFS which stores the localisation files.
 -- @param #string fallbackLocale The source locale containing the default messages
 --                               If omitted defaults to "en"
 -- @return #function
@@ -80,39 +69,21 @@
 -- # DataFiles/l10n/MyMod/en.yaml
 -- good_morning: 'Good morning.'
 --
--- you_have_arrows: |- {count, plural,
+-- you_have_arrows: |-
+--   {count, plural,
 --     one {You have one arrow.}
 --     other {You have {count} arrows.}
 --   }
 -- @usage
 -- # DataFiles/l10n/MyMod/de.yaml
 -- good_morning: "Guten Morgen."
--- you_have_arrows: |- {count, plural,
+-- you_have_arrows: |-
+--   {count, plural,
 --     one {Du hast ein Pfeil.}
 --     other {Du hast {count} Pfeile.}
 --   }
 -- "Hello {name}!": "Hallo {name}!"
 -- @usage
--- # DataFiles/l10n/AdvancedExample/en.yaml
--- # More complicated patterns
--- # select rules can be used to match arbitrary string arguments
--- # The default keyword other must always be provided
--- pc_must_come: {PCGender, select,
---     male {He is}
---     female {She is}
---     other {They are}
---   } coming with us.
--- # Numbers have various formatting options
--- quest_completion: "The quest is {done, number, percent} complete.",
--- # E.g. "You came in 4th place"
--- ordinal: "You came in {num, ordinal} place."
--- # E.g. "There is one thing", "There are one hundred things"
--- spellout: "There {num, plural, one{is {num, spellout} thing} other{are {num, spellout} things}}."
--- numbers: "{int} and {double, number, integer} are integers, but {double} is a double"
--- # Numbers can be formatted with custom patterns
--- # See https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html#syntax
--- rounding: "{value, number, :: .00}"
--- @usage
 -- -- Usage in Lua
 -- local myMsg = core.l10n('MyMod', 'en')
 -- print( myMsg('good_morning') )