Update README.md

Author: SavagingSky

README.md

@@ -37,8 +37,12 @@ Example: `"ModeSelectionMenuNormalMode": "Normal game."`
 
 The object must contain the key Culture with a two-letter language code (ISO 639-1).
 
+Example: `"Culture": "en"`
+
 There must also be a Language key containing the name of the language in lowercase.
 
+Example: `"Language": "english"`
+
 The file name is the language name in lowercase, for example, english.lng.
 
 ### pot
@@ -51,12 +55,30 @@ A translation file compatible with gettext.
 
 We use the two-letter language code as the file name, for example, ru.po.
 
+### docs
+Projects that have documentation, such as BallBouncer, have a docs directory.
+
+This directory contains subdirectories named as two-letter language codes, for example en.
+
+Each such subdirectory contains project documentation files.
+
+#### md
+md files are documentation files in markdown format, such as readme.md.
+
+#### pot
+Standard translation template file generated by the xgettext program, such a file is generated for each md file in docs/en, for example readme.pot.
+
+#### po
+A translation file compatible with gettext.
+
 ## Sequence of Adding a Translation
 ### From our side
 If resx files are used, we convert them all into an lng file with an English translation, english.lng.
 
 Then the <project name>.pot file is generated from english.lng.
 
+English documentation markdown files are processed by the mdpo program, it extracts blocks of text and forms pot files from them.
+
 ### From the translator's side
 You need to fork this repository and create a branch for the new translation.
 
@@ -65,25 +87,44 @@ Then you should choose your preferred translation method.
 #### po
 You can load the .pot file into a translation program, such as Poedit, and perform the translation there.
 
-Then the completed po file, for example, fr.po, needs to be added to the project directory and a pull request should be sent to this repository.
+Then the completed po file, for example, fr.po, needs to be added to the project directory.
+
+To translate documentation, you need to use pot files from the docs/en directory as a template.
+
+In the docs directory, you should create a subdirectory for translated files, the name should be the two-letter language code.
+
+Ready po files, for example readme.po, need to be placed in the created directory.
 
 #### lng
-You can translate the lng file directly. As a template, you can use any existing file in this repository, not necessarily english.lng.
+This is not a recommended method, because... At the moment, we cannot offer a convenient way to update and validate translations.
+
+Use it only if it is impossible  to use poedit or similar software.
+
+You can translate the lng file directly. As a template, you can use any existing file in this repository, but we recommend to translate english.lng.
 
 If you use a file other than english.lng and decide to send an unfinished translation, be sure to delete all untranslated strings so that the file contains only strings in the target translation language.
 
 For example, if you decided to translate russian.lng to French, translated half of it, and decided to send this intermediate result, delete all remaining Russian strings, leaving only the French ones.
 
+This is necessary so that the untranslated strings fallback to the english language.
+
 When using english.lng as a template, it is not necessary to delete untranslated strings.
 
 In the lng file, you need to set the correct values for the Culture and Language keys; see the section above about the lng format.
 
-Then the completed lng file, for example, french.lng, needs to be added to the project directory and a pull request should be sent to this repository.
+Then the completed lng file, for example, french.lng, needs to be added to the project directory.
 
-#### resx
-Please do not translate resx files; we do not validate them and do not accept translations in this format.
+#### resx and md
+Please do not translate resx and md files; we do not validate them and do not accept translations in this format.
 
 #### Next Steps
-Submit a pull request with your translation. We will review it, ask for changes if necessary, and if the translation is correct, we will merge it into master.
+When the translation is completed and all files are in their places, submit a pull request with your translation. We will review it, ask for changes if necessary, and if the translation is correct, we will merge it into master.
 
 After that, the translations will be added to the corresponding products and delivered to users via the update system.
+
+### Translating new/changed strings
+When we make changes to our projects, the source language files will be updated in this repository.
+
+You will need to merge the master branch into your branch, and then update your translation from the updated pot files and translate the new lines.
+
+For lng files, as stated above, we cannot offer a convenient way to update the translation, but we will try to solve this problem in the future.