Internacionalización y zonas horarias

Con starlette-admin, puede localizar las cadenas de la interfaz por usuario y convertir los datetimes mostrados a la zona horaria local del visitante, independientemente de cómo su base de datos los almacene.

Ejemplo completo: Para una aplicación completa y funcional que demuestre la internacionalización y las zonas horarias, consulte examples/10-i18n-timezone en el repositorio de GitHub.

Instale el extra i18n

El soporte de traducción requiere Babel. Sin él, el panel de administración sigue funcionando, pero recurre al inglés y omite el formato de fechas y números consciente de la configuración regional.

pip install "starlette-admin[i18n]"

uv add "starlette-admin[i18n]"

Establezca la configuración regional (locale)

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 tiene como valor predeterminado None, lo que ejecuta el panel en inglés. Cuando pasa un I18nConfig, el panel instala LocaleMiddleware. El middleware resuelve un locale en cada petición y lo expone a las plantillas y a las funciones de traducción (gettext y lazy_gettext) en todo su código de campos y vistas.

El parámetro language_switcher añade un menú desplegable a la barra de navegación del panel para que los usuarios puedan seleccionar su locale. Déjelo como None, su valor predeterminado, para ocultar el selector y basarse en default_locale y en la detección por petición.

Referencia de I18nConfig

Cómo se detecta el locale

LocaleMiddleware resuelve el locale una vez por petición, en este orden:

1. Cookie: El valor de language_cookie_name, si coincide con un locale admitido integrado.
2. Cabecera: La cabecera Accept-Language, o la cabecera que usted establezca en language_header_name, sujeta a la misma comprobación de validez.
3. Predeterminado: El default_locale, cuando ni la cookie ni la cabecera coinciden.

Los locales admitidos integrados (starlette_admin.i18n.SUPPORTED_LOCALES) son alemán, inglés, francés, portugués, ruso, turco y chino tanto simplificado como tradicional. Cuando un usuario selecciona un idioma en la barra de navegación, el selector escribe la cookie de idioma, de modo que la elección persiste entre peticiones sin necesidad de almacenamiento de sesión en el servidor.

Zonas horarias

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",
)

Cómo se detecta la zona horaria

TimezoneMiddleware resuelve la zona horaria una vez por petición:

1. Cookie: El valor de timezone_cookie_name, que es "timezone" de forma predeterminada, si está presente.
2. Predeterminado: El default_timezone, en caso contrario.

El selector de zonas horarias de la barra de navegación escribe esta cookie, exactamente igual que el selector de idioma. Las zonas horarias no tienen equivalente a la cabecera Accept-Language porque los navegadores no envían una, por lo que la detección depende por completo de las cookies. Un JavaScript del lado del cliente que lea Intl.DateTimeFormat().resolvedOptions().timeZone suele encargarse de establecer la cookie, igual que el propio selector.

Cómo se convierten los valores de los campos

DateTimeField y ArrowField convierten los valores entre la database_timezone y la zona horaria resuelta del visitante.

• Lectura (lista, detalle, exportación): El panel trata un valor ingenuo procedente de su base de datos como un valor en la database_timezone y lo convierte a la zona horaria del visitante antes de formatearlo.
• Escritura (formularios de creación y edición): El panel trata un valor enviado como un valor en la zona horaria del visitante y lo convierte a la database_timezone antes de que llegue a su modelo.

Como resultado, dos administradores en zonas horarias distintas pueden editar la misma fila y cada uno verá las horas en su hora local, mientras que la base de datos mantiene una única zona horaria consistente.

Referencia de TimezoneConfig

Para restringir lo que los usuarios pueden seleccionar, pase una lista timezone_switcher más corta. Para imponer una única zona horaria a todos los visitantes, establezca timezone_switcher en None y defina directamente default_timezone, por ejemplo, con un valor corporativo como "Europe/Paris".

El selector de la barra de navegación muestra el nombre visible y el desfase UTC de cada zona horaria mediante las variables globales de plantilla get_timezone y get_timezone_display_name. La guía de Templates documenta estas variables globales junto con todas las demás.

Siguientes pasos:

• Fields: DateTimeField, ArrowField y el resto de la referencia de campos.
• Templates: Sobrescriba plantillas y utilice las variables globales get_timezone directamente.
• Concepts: Cómo Admin conecta el middleware y los objetos de configuración.