From 726a4d7fc33ee1f6c6b63ba8d897b1299259ced7 Mon Sep 17 00:00:00 2001
From: Dmitry Verkhoturov <paskal.07@gmail.com>
Date: Sun, 5 Apr 2020 14:03:37 +0200
Subject: [PATCH] add translation instructions

---
 README.md           |  7 ++++---
 docs/README.md      |  1 +
 docs/translation.md | 49 +++++++++++++++++++++++++++++++++++++++++++++
 frontend/Readme.md  |  7 ++-----
 4 files changed, 56 insertions(+), 8 deletions(-)
 create mode 100644 docs/translation.md

diff --git a/README.md b/README.md
index 67a7c85d..c67bb861 100644
--- a/README.md
+++ b/README.md
@@ -472,9 +472,10 @@ window.REMARK42.changeTheme('light');
 
 ##### Locales
 
-Right now Remark has support three locales en, ru (partial translated), de and fi.
-You can pick one using configuration object.
-Do you want support other locale? Please create [issue](https://github.com/umputun/remark42/issues).
+Right now Remark is translated to en, ru (partially), de, and fi languages.
+You can pick one using [configuration object](#setup-on-your-website).
+
+Do you want translate remark42 to other locale? Please see [this documentation](https://github.com/umputun/remark42/blob/master/docs/translation.md) for details.
 
 #### Last comments
 
diff --git a/docs/README.md b/docs/README.md
index 45989f1a..d54c0310 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,3 +4,4 @@
 - [How to configure remark42 without a subdomain](subdomain.md) with Nginx or Caddy
 - [Telegram notifications](telegram.md)
 - [Setup email authentication and\or email notifications](email.md)
+- [How to add new translation to remark42](translation.md)
diff --git a/docs/translation.md b/docs/translation.md
new file mode 100644
index 00000000..0b5af48a
--- /dev/null
+++ b/docs/translation.md
@@ -0,0 +1,49 @@
+## How to add new language translation to Remark42
+
+Translation files are stored in [/frontend/app/locales](https://github.com/umputun/remark42/tree/master/frontend/app/locales)
+directory with `.json` extension and content like following:
+
+```json
+{
+  "anonymousLoginForm.length-limit": "Username must be at least 3 characters long",
+  "anonymousLoginForm.log-in": "Log in",
+  "anonymousLoginForm.symbol-limit": "Username must start from the letter and contain only latin letters, numbers, underscores, and spaces",
+<...>
+}
+```
+
+### How to add a new translation
+
+We truly appreciate people spending time contributing their translations to remark42. Please go through the steps
+below in order to have your translation start being available to all remark42 users and included in the next release.
+
+1. create a fork of [umputun/remark42](https://github.com/umputun/remark42) repo, and if you already have one please
+pull the latest changes from the upstream master branch. It could be done like that:
+   ```shell
+   git remote add upstream https://github.com/umputun/remark42.git
+   git fetch upstream
+   git rebase upstream/master
+   git push
+   ```
+1. add new locale with [two-letter code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
+of the language you want to make the translation into to list in
+[frontend/tasks/supportedLocales.json](https://github.com/umputun/remark42/blob/master/frontend/tasks/supportedLocales.json)
+1. run `npm run generate-langs` in `frontend` folder
+1. translate all values in the newly created json file in
+[frontend/app/locales/](https://github.com/umputun/remark42/blob/master/frontend/app/locales/)
+1. commit all changes above in your fork
+1. test your changes in the interface:
+    1. uncomment `locale: "ru"` line in [frontend/index.ejs](https://github.com/umputun/remark42/blob/master/frontend/index.ejs#L133)
+    and replace `ru` with your translation language code
+    1. [run remark42 in Docker](https://github.com/umputun/remark42#development) by issuing following commands
+    from the root directory of your remark42 fork:
+
+        ```shell
+        docker-compose -f compose-dev-frontend.yml build
+        docker-compose -f compose-dev-frontend.yml up
+        ```
+    1. open [http://127.0.0.1:8080](http://127.0.0.1:8080), log in, make a comment, make a reply to a comment,
+    and make sure that your translation looks as you expect it to look
+    1. make a screenshot from [http://127.0.0.1:8080](http://127.0.0.1:8080) with your translation in place
+1. after all previous steps are done, create a [Pull Request](https://github.com/umputun/remark42/pulls) to umputun/remark42
+repo with your changes, attaching a screenshot or two from your local test instance to it
\ No newline at end of file
diff --git a/frontend/Readme.md b/frontend/Readme.md
index 0d2585ef..e2cda451 100644
--- a/frontend/Readme.md
+++ b/frontend/Readme.md
@@ -28,12 +28,9 @@
 - tests are running on push attempt
 - example tests can be found in `./app/store/user/reducers.test.ts`, `./app/components/auth-panel/auth-panel.test.tsx`
 
-### how to add new locale.
+### How to add new locale
 
-- add new item to `./tasks/supportedLocales.json`
-- run `npm run generate-langs`
-- commit all changed files
-- translate all string in new generated dictionary `./app/locale/<new-locale>.json`
+Please see [this documentation](https://github.com/umputun/remark42/blob/master/docs/translation.md).
 
 ### Notes