Add naming policy for scripts and l10n files to documentation

docs/source/reference/lua-scripting/api.rst

@@ -59,7 +59,8 @@ Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can overrid
 
 .. include:: tables/aux_packages.rst
 
-**Interfaces of built-in scripts**
+Interfaces of built-in scripts
+------------------------------
 
 .. list-table::
   :widths: 20 20 60

docs/source/reference/lua-scripting/overview.rst

@@ -85,7 +85,7 @@ Let's write a simple example of a `Player script`:
 
 .. code-block:: Lua
 
-    -- Save to my_lua_mod/example/player.lua
+    -- Save to my_lua_mod/scripts/example/player.lua
 
     local ui = require('openmw.ui')
 
@@ -107,7 +107,7 @@ The options are:
 1. Create text file "my_lua_mod.omwscripts" with the following line:
 ::
 
-    PLAYER: example/player.lua
+    PLAYER: scripts/example/player.lua
 
 2. (not implemented yet) Add the script in OpenMW CS on "Lua scripts" view and save as "my_lua_mod.omwaddon".
 
@@ -122,6 +122,19 @@ Enable it in ``openmw.cfg`` the same way as any other mod:
 Now every time the player presses "X" on a keyboard, a message is shown.
 
 
+Lua scripts naming policy
+=========================
+
+Technically scripts can be placed anywhere in the virtual file system, but we recommend to follow the naming policy and choose one of:
+
+- ``scripts/<ModName>/<ScriptName>.lua``: general case.
+- ``scripts/<AuthorName>/<ModName>/<ScriptName>.lua``: if "ModName" is short and can potentially collide with other mods.
+- ``scripts/<ModName>.lua``: if it is a simple mod that consists from a single script, the script can placed to ``scripts/`` without subdirs.
+
+``scripts/omw/`` is reserved for built-in scripts, don't use it in mods. Overriding built-in scripts is not recommended, prefer to adjust their behaviour via :ref:`Interfaces of built-in scripts` instead.
+
+See also naming policy of :ref:`Localisation Files`.
+
 Format of ``.omwscripts``
 =========================
 
@@ -129,20 +142,20 @@ Format of ``.omwscripts``
 
     # Lines starting with '#' are comments
 
-    GLOBAL: my_mod/some_global_script.lua
+    GLOBAL: scripts/my_mod/some_global_script.lua
 
     # Script that will be automatically attached to the player
-    PLAYER: my_mod/player.lua
+    PLAYER: scripts/my_mod/player.lua
 
     # Local script that will be automatically attached to every NPC and every creature in the game
-    NPC, CREATURE: my_mod/some_other_script.lua
+    NPC, CREATURE: scripts/my_mod/some_other_script.lua
 
     # Local script that can be attached to any object by a global script
-    CUSTOM: my_mod/something.lua
+    CUSTOM: scripts/my_mod/something.lua
 
     # Local script that will be automatically attached to any Container AND can be
     # attached to any other object by a global script.
-    CONTAINER, CUSTOM: my_mod/container.lua
+    CONTAINER, CUSTOM: scripts/my_mod/container.lua
 
 Each script is described by one line:
 ``<flags>: <path to .lua file in virtual file system>``.

docs/source/reference/modding/localisation.rst

@@ -31,11 +31,26 @@ E.g. if you include ``en_US.yaml`` and ``en_GB.yaml`` localisation files, you sh
 Note that because of the fallbacks only messages which differ between variants need to be included in the country-specific localisation files.
 
 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``.
 
+**Naming policy**
+
+"ContextName" should be in line with :ref:`Lua scripts naming policy`:
+
+- L10n files for ``scripts/<ModName>/<ScriptName>.lua`` should be placed to ``l10n/<ModName>/<Locale>.yaml``.
+- L10n files for ``scripts/<AuthorName>/<ModName>/<ScriptName>.lua`` should be placed to ``l10n/<AuthorName><ModName>/<Locale>.yaml``.
+
+In most cases one mod should have only one l10n context. Don't create a new context for each single message. Really big mods with hundreds and thousands of messages can have several l10n contexts. In this case all context names should start with the name of the mod. I.e. ``<ContextName> = <ModName><Subcontext>`` (or ``<AuthorName><ModName><Subcontext>``).
+
+L10n contexts with prefix "OMW" are reserved for the OpenMW itself (in particular for built-in scripts ``scripts/omw/``) and shouldn't be used in mods.
+
+Built-in l10n contexts "Interface" and "Calendar" don't have the "OMW" prefix because these messages are more generic and can be reused in mods.
+
+**Format**
+
 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