Локали

Cuento поставляется с английским и русским языками. Дополнительные локали создаются как два текстовых файла и устанавливаются через панель администратора — без изменения кода и без доступа к серверу.

Как это работает

Каждая локаль состоит из двух файлов:

  • Фронтенд-файл .ts — TypeScript-объект со всеми строками интерфейса Angular-приложения.
  • Бэкенд-файл .json — JSON-объект для текстов, которые формирует Go-бэкенд: правила форматирования дат, названия источников валюты и другие строки, генерируемые сервером до отправки в браузер.

Оба файла должны иметь одинаковое базовое имя (например, fr.ts и fr.json для французского).

Бэкенд загружает все .json-файлы из директории locales/ при старте и после каждой операции установки/удаления — перезапуск сервера не требуется. Фронтенд загружает .ts-файл лениво при первом обращении через динамический import.

Если ключ отсутствует в локали, бэкенд автоматически использует английскую версию.


Предустановленные локали

Код Язык Примечание
en-CA Английский По умолчанию. Нельзя удалить или деинсталлировать.
ru Русский Предустановлен.

Создание локали — фронтенд-файл .ts

Фронтенд-файл должен экспортировать именованную константу с именем TRANSLATIONS_ и базовым именем файла в верхнем регистре. Для файла fr.ts:

export const TRANSLATIONS_FR = {
  "home.forum": "Forum",
  "home.topics": "Sujets",
  ...
}

Ключи — строки в формате namespace.key через точку. Полный перечень необходимых ключей находится в cuento-frontend/src/locale/en.ts (источник истины). Переведите каждый ключ из этого файла. Ключи должны быть упорядочены алфавитно внутри каждого пространства имён.

Функция addLocaleBlock выводит имя экспортируемой константы и путь импорта из имени файла, поэтому имя файла и имя константы должны совпадать.


Создание локали — бэкенд-файл .json

Бэкенд-файл — плоский JSON-объект. Он должен содержать как минимум ключи форматирования дат, поскольку они управляют отображением каждой метки времени на форуме:

{
  "date.format": "2 Jan 2006",
  "date.today": "Сегодня",
  "date.yesterday": "Вчера",
  "date.usePm": "false"
}

Справочник по ключам дат

Ключ Назначение Значение EN Значение RU
date.format Шаблон даты в формате Go "2 Jan 2006" "02.01.2006"
date.today Подставляется, если дата — сегодня "Today" "Сегодня"
date.yesterday Подставляется, если дата — вчера "Yesterday" "Вчера"
date.usePm "true" = 12-часовой формат AM/PM, "false" = 24-часовой "true" "false"

Установите date.today или date.yesterday в "", чтобы отключить подстановку и всегда показывать форматированную дату.

Справочник по шаблонам дат Go

Go использует фиксированное эталонное время — Mon Jan 2 15:04:05 MST 2006 — для описания шаблонов формата. Каждый компонент соответствует своей позиции в этом эталоне:

Компонент Эталон Пример
День без ведущего нуля 2 7
День с ведущим нулём 02 07
Аббревиатура месяца Jan Apr
Номер месяца без ведущего нуля 1 4
Номер месяца с ведущим нулём 01 04
Год четырьмя цифрами 2006 2025
Год двумя цифрами 06 25
Час 24ч 15 14
Час 12ч 3 2
Минуты 04 09

Таким образом, "2 Jan 2006" даёт 7 Apr 2025, а "02.01.2006" — 07.04.2025.

Прочие бэкенд-ключи

Файл .json также содержит названия и описания источников начисления валюты (отображаются в настройках администратора). Скопируйте структуру из cuento-backend/locales/en.json и переведите значения.


Установка локали

  1. В панели администратора перейдите в раздел Локали.
  2. Нажмите Загрузить локаль и укажите:
    • Человекочитаемое название (например, «Français»).
    • Код локали (например, fr). Он сохраняется в users.interface_language для пользователей, выбравших этот язык.
    • Файл .ts (переводы фронтенда).
    • Файл .json (строки бэкенда и даты).
  3. После загрузки файлы сохраняются на бэкенд-сервере. Нажмите Установить, чтобы закоммитить .ts-файл в GitHub-репозиторий фронтенда и зарегистрировать локаль в locale_config.ts.
  4. CI-пайплайн фронтенда подхватит коммит и пересоберёт приложение — локаль станет доступной в настройках аккаунта после завершения сборки.

Поддержка Angular-локали: Для языков из встроенного списка Angular (русский, китайский, немецкий, французский, испанский, португальский, итальянский, японский, корейский, польский, украинский, турецкий, арабский) при установке в конфигурационную запись добавляется подсказка angularLocale. Это включает нативное форматирование Angular для чисел и дат — разделители и прочие соглашения задаются самим фреймворком.


Деинсталляция и удаление

Деинсталляция удаляет .ts-файл из GitHub-репозитория фронтенда и пересобирает приложение — локаль исчезает из переключателя языков. Файлы остаются на бэкенд-сервере.

Удаление удаляет файлы с бэкенд-сервера и запись из базы данных. Перед удалением локаль должна быть деинсталлирована. Локаль English (en-CA) по умолчанию нельзя деинсталлировать или удалить.


Ключевые файлы

Файл Назначение
cuento-frontend/src/locale/en.ts Полный перечень всех ключей интерфейса (источник истины)
cuento-frontend/src/locale_config_default.ts Шаблон массива LOCALES — locale_config.ts генерируется на его основе
cuento-backend/locales/en.ts Копия фронтенд-файла EN, синхронизируется вручную
cuento-backend/locales/en.json Строки бэкенда + форматирование дат для английского
cuento-backend/locales/ru.ts / ru.json Русские переводы
cuento-backend/src/Services/i18n.go InitI18n, ReloadI18n, T, TData, TPlural
cuento-backend/src/Controllers/locale.go Эндпоинты загрузки, установки, деинсталляции, удаления
cuento-backend/src/Middlewares/locale.go UserLocaleMiddleware — прикрепляет локаль пользователя к каждому запросу
cuento-backend/src/Services/user_service.go LocalizeTime, LocalizeDateOnly, логика форматирования дат