update readme

README.md

@@ -12,7 +12,7 @@
 
 ## 🐳 Установка
 
-> перед установкой **ОБЯЗАТЕЛЬНО** прочтите [про бэкапы перед обновлением](https://docs.getoutline.com/s/hosting/doc/backups-KZtPOADCHG)
+> Перед установкой **ОБЯЗАТЕЛЬНО** прочтите [про бэкапы перед обновлением](https://docs.getoutline.com/s/hosting/doc/backups-KZtPOADCHG)
 
 Следуйте [официальной инструкции](https://docs.getoutline.com/s/hosting/doc/docker-7pfeLP5a8t), только в качестве `image` укажите `flameshikari/outline-ru:latest` (желательно зафиксировать версию, заменив `latest` на один из [доступных тегов](https://github.com/flameshikari/outline-ru/tags)). Например:
 
@@ -32,3 +32,70 @@ services:
 
   ...
 ```
+
+## 🛠️ Разработка
+
+### Описание
+
+Контейнер Outline описан в одном [Dockerfile](./Dockerfile) на основе двух оригинальных с применением [патча](./tools/language.patch) поверх исходного кода Outline (он подключен к этому репозиторию в качестве подмодуля) и копированием [файла перевода](./tools/translation.json). Патч, помимо добавления отсутствующих строк в код, меняет некоторые upstream-ссылки, чтобы Outline мониторил этот контейнер на наличие новых версий, а не оригинальный.
+
+В [docker-compose.yml](./docker-compose.yml) описаны четыре контейнера (кликабельные названия далее — это localhost-ссылки): [Outline](http://localhost:10240), Redis, Postgres и [тестовый OIDC-сервер](http://localhost:10241) (логин/пароль: `outline`). Также там описана вся конфигурация контейнеров; настраивайте под себя по желанию. После первой сборки контейнера большинство слоёв берётся из кэша, сам Outline после изменений пересобирается около полминуты-минуты (тут зависит от железа). Пайплайн примерно такой: перевёл → собрал → проверил.
+
+Скрипт [diff.py](./tools/diff.py) используется для объединения переводов [английского](https://github.com/outline/outline/blob/main/shared/i18n/locales/en_US/translation.json) с [русским](./tools/translation.json) во временный файл `./tools/translation.tmp.json`. Скрипт не имеет интерактивного режима и каких-либо аргументов/опций, он просто запускается (с выводом некоторой полезной информации) и делает следующее:
+
+- сохраняет актуальные переведённые строки
+- удаляет неактуальные переведённые строки
+- если в файле перевода есть одинаковые key/value пары, то они считаются исключениями (например, `HTML` или `API`) и переносятся как есть
+- новые непереведённые строки добавляются в конец
+
+> Возможно, для коллективного перевода стоило использовать [Crowdin](https://crowdin.com), но что-то руки не дошли ¯\\_(ツ)_/¯
+
+Во временном файле вручную делается перевод новых строк, а затем [файл перевода](./tools/translation.json) вручную заменяется временным файлом.
+
+> Если во временном файле присутствуют две одинаковые непереведённые строки, но одна из них с суффиксом `_plural` (множественное число), например:
+> 
+> ```json
+> {
+>   "{{ count }} comment": "{{ count }} comment",
+>   "{{ count }} comment_plural": "{{ count }} comments"
+> }
+> ```
+> …то нужно заменить эти строки на следующие (для справки: [множественное число](https://www.i18next.com/translation-function/plurals#languages-with-multiple-plurals) в [i18next](https://www.i18next.com) с [JSON-форматом версии 3](https://www.i18next.com/misc/json-format#i18next-json-v3)):
+> 
+> ```json
+> {
+>   "{{ count }} comment_0": "{{ count }} комментарий",
+>   "{{ count }} comment_1": "{{ count }} комментария",
+>   "{{ count }} comment_2": "{{ count }} комментариев"
+> }
+> ```
+
+### Команды
+
+0. Клонирование репозитория с подмодулем
+    ```sh
+    git clone --recurse-submodules git@github.com:flameshikari/outline-ru.git
+    ```
+
+1. Пулл изменений в подмодуле и переключение на коммит с целевой версией
+    ```sh
+    cd outline
+    git pull --rebase --tags
+    git checkout v0.85.0
+    cd -
+    ```
+
+2. Формирование временного файла с помощью [diff.py](./tools/diff.py)
+    ```sh
+    python ./tools/diff.py
+    ```
+
+3. Замена [файла перевода](./tools/translation.json) после перевода строк во временном файле
+    ```
+    cp ./tools/translation.tmp.json ./tools/translation.json
+    ```
+
+4. Сборка контейнера
+    ```sh
+    docker compose up -d --build
+    ```

tools/diff.py

@@ -48,7 +48,7 @@ for key, value in ru_json.items():
 out_json = {**translated_lines, **untranslated_lines}
 
 if (exception_lines):
-    print('Потенциально непереведённые строки или исключения:')
+    print('Исключения:')
     print(json.dumps(exception_lines, indent=2, ensure_ascii=False))
     print()