Локали
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 и переведите значения.
Установка локали
- В панели администратора перейдите в раздел Локали.
- Нажмите Загрузить локаль и укажите:
- Человекочитаемое название (например, «Français»).
- Код локали (например,
fr). Он сохраняется вusers.interface_languageдля пользователей, выбравших этот язык. - Файл
.ts(переводы фронтенда). - Файл
.json(строки бэкенда и даты).
- После загрузки файлы сохраняются на бэкенд-сервере. Нажмите Установить, чтобы закоммитить
.ts-файл в GitHub-репозиторий фронтенда и зарегистрировать локаль вlocale_config.ts. - 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, логика форматирования дат |