Интернационализация и часовые пояса

С помощью starlette-admin вы можете локализовать строки интерфейса для каждого пользователя и преобразовывать отображаемые дату и время в часовой пояс зрителя — независимо от того, как они хранятся в вашей базе данных.

Полный пример: готовое работающее приложение, демонстрирующее интернационализацию и работу с часовыми поясами, доступно в каталоге examples/10-i18n-timezone репозитория на GitHub.

Установка дополнения i18n

Для поддержки перевода требуется Babel. Без него панель администрирования продолжает работать, но возвращается к английскому языку и пропускает форматирование дат и чисел с учётом локали.

pip install "starlette-admin[i18n]"

uv add "starlette-admin[i18n]"

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

from sqlalchemy import create_engine
from starlette_admin import I18nConfig
from starlette_admin.contrib.sqla import Admin
from starlette_admin.i18n import SUPPORTED_LOCALES

engine = create_engine("sqlite:///admin.sqlite")

admin = Admin(
    engine,
    title="My Admin",
    i18n_config=I18nConfig(
        default_locale="en",
        language_switcher=SUPPORTED_LOCALES,
    ),
    secret_key="a-long-random-string",
)

По умолчанию параметр i18n_config равен None, и панель администрирования работает на английском языке. Если передать объект I18nConfig, панель устанавливает LocaleMiddleware. Этот middleware определяет локаль при каждом запросе и предоставляет её шаблонам, а также функциям перевода (gettext и lazy_gettext) во всём коде полей и представлений.

Параметр language_switcher добавляет выпадающий список в навигационную панель, позволяя пользователям выбирать свою локаль. Оставьте значение None (по умолчанию), чтобы скрыть переключатель и полагаться на default_locale и определение локали для каждого запроса.

Справочник I18nConfig

Как определяется локаль

LocaleMiddleware определяет локаль один раз за запрос в следующем порядке:

1. Cookie: значение language_cookie_name, если оно соответствует одной из встроенных поддерживаемых локалей.
2. Заголовок: заголовок Accept-Language или заголовок, указанный в language_header_name, с той же проверкой корректности.
3. По умолчанию: значение default_locale, когда ни cookie, ни заголовок не совпали.

Встроенные поддерживаемые локали (starlette-admin.i18n.SUPPORTED_LOCALES) включают немецкий, английский, французский, португальский, русский, турецкий языки, а также китайский упрощённый и традиционный. Когда пользователь выбирает язык в навигационной панели, переключатель записывает cookie с языком, благодаря чему выбор сохраняется между запросами без серверного хранилища сессий.

Часовые пояса

from sqlalchemy import create_engine
from starlette_admin import TimezoneConfig
from starlette_admin.contrib.sqla import Admin

engine = create_engine("sqlite:///admin.sqlite")

admin = Admin(
    engine,
    title="My Admin",
    timezone_config=TimezoneConfig(
        default_timezone="UTC",
        database_timezone="UTC",
        timezone_switcher=["UTC", "Europe/Paris", "America/New_York", "Asia/Tokyo"],
    ),
    secret_key="a-long-random-string",
)

Как определяется часовой пояс

TimezoneMiddleware определяет часовой пояс один раз за запрос:

1. Cookie: значение timezone_cookie_name (по умолчанию "timezone"), если оно присутствует.
2. По умолчанию: значение default_timezone во всех остальных случаях.

Переключатель часовых поясов в навигационной панели записывает этот cookie точно так же, как переключатель языков. Для часовых поясов нет аналога заголовка Accept-Language, поскольку браузеры его не отправляют, поэтому определение полностью опирается на cookies. Обычно cookie устанавливает клиентский JavaScript, считывающий Intl.DateTimeFormat().resolvedOptions().timeZone; то же делает и сам переключатель.

Как преобразуются значения полей

DateTimeField и ArrowField преобразуют значения между database_timezone и часовым поясом, определённым для зрителя.

• Чтение (список, детальный просмотр, экспорт): панель администрирования трактует наивное значение из базы данных как значение в database_timezone и преобразует его в часовой пояс зрителя перед форматированием.
• Запись (формы создания и редактирования): панель администрирования трактует отправленное значение как значение в часовом поясе зрителя и преобразует его в database_timezone до того, как оно попадёт в вашу модель.

Благодаря этому два администратора в разных часовых поясах могут редактировать одну и ту же запись, каждый видит время в своём местном времени, а база данных хранит всё в едином согласованном часовом поясе.

Справочник TimezoneConfig

Чтобы ограничить выбор пользователей, передайте более короткий список timezone_switcher. Чтобы принудительно задать единый часовой пояс для всех зрителей, установите timezone_switcher в None и задайте default_timezone напрямую, например, на общекорпоративное значение "Europe/Paris".

Переключатель в навигационной панели отображает название каждого часового пояса и его смещение UTC с помощью глобальных переменных шаблонов get_timezone и get_timezone_display_name. Эти глобальные переменные, а также все остальные, описаны в руководстве Шаблоны.

Что дальше:

• Поля: DateTimeField, ArrowField и остальной справочник полей.
• Шаблоны: переопределение шаблонов и прямое использование глобальных переменных get_timezone.
• Концепции: как Admin подключает middleware и объекты конфигурации.