Локалізація Redash Admin та Redash Viewer

Сторінка технічної документації є баченням майбутньої реалізації, актуальність якого може бути застарілою.

Загальний опис

Необхідно реалізувати можливість підтримки декількох мов інтерфейсу перегляду звітів для посадових осіб (Redash Viewer) та інтерфейсу для створення та налаштування аналітичних звітів та дашбордів (Redash Admin) в залежності від обраної мови реєстру.

Актори та ролі користувачів

Технічний адміністратор Платформи
Технічний адміністратор реєстру (користувач Admin Portal, а саме Redash Admin)
Посадова особа (користувач Office Portal, а саме Redash Viewer)

Функціональні сценарії

Cтворення та налаштування аналітичних звітів та інформаційних панелей мовою реєстра.
Перегляд та маніпуляція відображенням даних реєстру на інформаційних панелях мовою реєстра.
Перегляд та аналіз даних журналу подій аудиту реєстру на інформаційних панелях мовою реєстра.

Поточна реалізація

Кожен екземпляр сервісу аналітичної звітності реєстру Redash (Viewer та Admin) розгортається українською мовою без можливості зміни при розгортанні. Вихідний Redash докер образ збирається англійською мовою. Локалізація українською мовою відбувається на етапі збірки redash-chart за допомогою додаткового main.py скрипта та заготовленого файлу з перекладом слів та словосполучень redash_localization_words.csv.

Така поточна реалізація не дозволяє встановити залежність між обраною мовою реєстру з розділу Керування реєстрами у адмінпанель Control Plane та процесом розгортання екземплярів Redash (Viewer та Admin).

Загальні принципи та положення

Redash не локалізується українською на етапі збірки redash-chart.
Існуючий файл redash_localization_words.csv з перекладом слів перейменовується у uk.csv і пакується в папку locales докер образа redash-chart на етапі збірки.
Дії по локалізації Redash виносяться з існуючого redash-chart/main.py у новий redash-chart/translate.py, що пакується в докер образ redash-chart на етапі збірки.
В values redash-chart додається global.language змінна, що визначає змінну оточення LANGUAGE темплейту розгортання Redash екземпляру.
Скрипт translate.py параметризується таким чином, щоб визначати шлях до файлу з перекладом визначеної мови локалізації на основі змінної оточення LANGUAGE.
Скрипт translate.py модифікується так, щоб не виконувати переклад, якщо LANGUAGE = "en", лишаючи Redash не локалізованим.
По можливості доповнити та виправити поточний український переклад.

Цільовий дизайн

Збірка

Наразі процес локалізації відбувається за допомогою запуску redash-chart/main.py скрипта на етапі збірки redash-chart докер образу через інструкції:

Dockerfile

FROM .../redash-master:version as source

FROM python:3.9.6 as local
COPY --from=source /app/client/dist/app.*.js /app/
...

COPY . /app
WORKDIR /app
RUN pip install pipenv
RUN pipenv install
RUN pipenv run python main.py

FROM source
COPY --from=local /app/app.*.js /app/client/dist/.
...

Необхідно винести процес локалізації в окремий translate.py скрипт. Відповідно видаливши з main.py.

translate.py

import ...

def load_excel_to_dict():
...

def wrap_as_variable(str):
...

def wrap_as_tag(str):
...

def localize(dict):
...

translations = load_excel_to_dict()
localize(translations)

Та додатково запакувати translate.py скрипт в redash-chart докер образ для подальшого виклику при розгортанні:

Dockerfile

COPY translate.py /app/

Видалити обробку app.*.js файлів з Dockerfile.

Перейменувати існуючий файл redash_localization_words.csv в uk.csv та також запакувати в redash-chart докер образ у новостворену папку locales:

Dockerfile

COPY uk.csv /app/locales/

Модифікувати translate.py скрипт, а саме:

Привести шляхи до фалів до актуального стану.
Параметризувати скрипт таким чином, щоб шлях до locales/uk.csv файлу з перекладом визначався енв змінною, наприклад, LANGUAGE.
Додати вхідну умову, що переклад здійснюється лише у випадку, коли LANGUAGE != "en"
Додати вхідну умову, що у випадку якщо LANGUAGE не визначена, тобто global.language була не задана, переклад здійснюється українською.

Розгортання

Мова визначатиметься через змінну global.language у values.yaml кожного реєстру, що наразі матиме допустимі значення uk та en та задаватиметься через Адмінпанель Control Plane. У шаблон розгортання реєстру у control-plane-gerrit, а також redash-chart значення за замовчуванням не виноситься, при необхідності задається пустим.

Скрипт по обробці файлу з перекладом запускається в процесі розгортання екземпляру Redash при старті відповідного контейнеру, наприклад, таким чином:

admin-server-deployment.yaml

apiVersion: apps/v1
kind: Deployment
...
spec:
...
  containers:
    - name: ...
      ...
      command: ["/bin/sh"]
      args: ["-c", "python ./translate.py && . /config/dynamicenv.sh && /app/bin/docker-entrypoint server"]

Також необхідно передавати значення змінної global.language у енв змінні темплейту розгортання екземпляру Redash для подальшого використання скриптом перекладу translate.py з метою визначення шляху до файлу з перекладом locales/uk.csv. Наприклад:

admin-server-deployment.yaml

apiVersion: apps/v1
kind: Deployment
...
spec:
...
  containers:
    - name: ...
      ...
      env:
        - name: LANGUAGE
          value: {{ .Values.global.language }}

Зміни на UI

В Control Plane в табі Реєстри на сторінці Загальні налаштування в розділі "Локалізація" під текстом "Кабінет адміністратора регламенту" додати фразу "Веб-інтерфейс моделювання звітів" згідно мокапів.

Отже, при зміні мови реєстру через Адмінпанель Control Plane буде створений новий запит на оновлення, що призведе до зміни параметру global.language у values.yaml та перерозгорне екземпляри redash-admin та redash-viewer із актуальним значенням змінної оточення LANGUAGE. Що в свою чергу визначить режим роботи translate.py скрипта, який виконає або ні переклад, згідно обраного csv файлу.

Компоненти системи та їх призначення в рамках дизайну рішення

У даному розділі наведено перелік компонент системи, які задіяні або потребують змін в рамках реалізації дизайну.

Підсистема	Компонент	Опис змін
Підсистема аналітичної звітності реєстру	redash-viewer	Винесення скриптів локалізації з процесу збірки докер образа на рівень розгортання. Опрацювання варіантів ввімкнення і вимкнення локалізації. Виправлення помилок поточного перекладу.
Підсистема моделювання регламенту реєстру	redash-admin
Підсистема управління Платформою та Реєстрами	control-plane-console	Розширення інтерфейсу управління реєстру коментарем.

Підсистема

Компонент

Опис змін

Підсистема аналітичної звітності реєстру

redash-viewer

Винесення скриптів локалізації з процесу збірки докер образа на рівень розгортання. Опрацювання варіантів ввімкнення і вимкнення локалізації. Виправлення помилок поточного перекладу.

Підсистема моделювання регламенту реєстру

redash-admin

Підсистема управління Платформою та Реєстрами

control-plane-console

Розширення інтерфейсу управління реєстру коментарем.

Підтримка зворотної сумісності

За замовчуванням мова локалізації не визначається ні на рівні шаблону реєстру, ні у redash-chart. При необхідності значення global.language може бути виставлене в "" або null. Для існуючих реєстрів, що не потребують переключення на англійську мову, це буде реалізовано в скрипті translate.py умовою запускати переклад uk в разі пустого значення змінної середовища LANGUAGE. Додаткових кроків для міграції реєстрів і їх компонент не потребується.

Високорівневий план розробки

Технічні експертизи

DevOps
FE

Попередній план розробки

Винести процес локалізації в окремий translate.py скрипт та запакувати в redash-chart докер образ.
Запакувати uk.csv файл локалізації в redash-chart докер образ.
Прибрати обробку app.*.js файлів з Dockerfile.
Параметризувати скрипт translate.py для визначення мови перекладу та власне запуску процесу перекладу в залежності від змінної оточення LANGUAGE.
Запускати скрипт translate.py через command.args в темплейтах розгортання redash-admin та redash-viewer.
В Control Plane в табі Реєстри на сторінці Загальні налаштування в розділі "Локалізація" під текстом "Кабінет адміністратора регламенту" додати фразу: Веб-інтерфейс моделювання звітів.
По можливості доповнити та виправити поточний український переклад.

Опційно

Стандартизувати процес інтернаціоналізації та локалізації, використовуючи для зберігання слів перекладу json формат. Для цього:

Cконвертувати файли перекладу csv у json, формату {"en_word" : "uk_word", …}.
Замінити load_excel_to_dict() на читання перекладів згідно цільового формату, наприклад, json.load().

Поза скоупом

Адміністратор платформи чи адміністратор реєстру обирає для Redash Admin та/або Viewer мову, відмінну, від мови реєстру.
Адміністратор платформи чи адміністратор реєстру обирає свою індивідуальну мову інтерфейсу.
Визначення мови користувача в "Accept-Language" заголовку запиту або у разі відсутності перекладів для мови - використання налаштувань за замовчуванням обраних на етапі встановлення екземпляру Платформи.
Локалізація елементів, недоступних для зміни після збірки Redash компонента.