Internationalisation et fuseaux horaires

Avec starlette-admin, vous pouvez localiser les chaînes de l'interface par utilisateur et convertir les dates et heures affichées vers le fuseau horaire local du visiteur, indépendamment de la manière dont votre base de données les stocke.

Exemple complet : Pour une application fonctionnelle et complète illustrant l'internationalisation et les fuseaux horaires, consultez examples/10-i18n-timezone dans le dépôt GitHub.

Installer l'extra i18n

La prise en charge des traductions nécessite Babel. Sans lui, l'admin fonctionne toujours, mais il se rabat sur l'anglais et ignore le formatage des dates et des nombres selon la locale.

pip install "starlette-admin[i18n]"

uv add "starlette-admin[i18n]"

Définir la 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 vaut None par défaut, ce qui fait fonctionner l'admin en anglais. Lorsque vous passez une I18nConfig, l'admin installe LocaleMiddleware. Ce middleware résout une locale à chaque requête et l'expose aux templates ainsi qu'aux fonctions de traduction (gettext et lazy_gettext) dans tout votre code de champs et de vues.

Le paramètre language_switcher ajoute un menu déroulant à la barre de navigation de l'admin afin que les utilisateurs puissent sélectionner leur locale. Laissez-le à None, sa valeur par défaut, pour masquer le sélecteur et vous appuyer sur default_locale et sur la détection par requête.

Référence de I18nConfig

Comment la locale est détectée

LocaleMiddleware résout la locale une fois par requête, dans cet ordre :

1. Cookie : La valeur de language_cookie_name, si elle correspond à une locale intégrée prise en charge.
2. En-tête : L'en-tête Accept-Language, ou l'en-tête que vous avez défini dans language_header_name, soumis à la même vérification de validité.
3. Défaut : La default_locale, lorsque ni le cookie ni l'en-tête ne correspondent.

Les locales intégrées prises en charge (starlette_admin.i18n.SUPPORTED_LOCALES) sont l'allemand, l'anglais, le français, le portugais, le russe, le turc, ainsi que le chinois simplifié et traditionnel. Lorsqu'un utilisateur sélectionne une langue dans la barre de navigation, le sélecteur écrit le cookie de langue, si bien que le choix persiste d'une requête à l'autre sans stockage de session côté serveur.

Fuseaux horaires

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

Comment le fuseau horaire est détecté

TimezoneMiddleware résout le fuseau horaire une fois par requête :

1. Cookie : La valeur de timezone_cookie_name, qui vaut "timezone" par défaut, si elle est présente.
2. Défaut : Le default_timezone, sinon.

Le sélecteur de fuseau horaire de la barre de navigation écrit ce cookie, exactement comme le sélecteur de langue. Les fuseaux horaires n'ont pas d'équivalent de l'en-tête Accept-Language car les navigateurs n'en envoient pas ; la détection repose donc entièrement sur les cookies. Un JavaScript côté client qui lit Intl.DateTimeFormat().resolvedOptions().timeZone définit généralement ce cookie, tout comme le sélecteur lui-même.

Comment les valeurs des champs sont converties

DateTimeField et ArrowField convertissent les valeurs entre le database_timezone et le fuseau horaire résolu du visiteur.

• Lecture (liste, détail, export) : L'admin traite une valeur naïve provenant de votre base de données comme une valeur dans le database_timezone et la convertit vers le fuseau horaire du visiteur avant de la formater.
• Écriture (formulaires de création et d'édition) : L'admin traite une valeur soumise comme une valeur dans le fuseau horaire du visiteur et la convertit vers le database_timezone avant qu'elle n'atteigne votre modèle.

Ainsi, deux administrateurs situés dans des fuseaux horaires différents peuvent modifier la même ligne et voir chacun les heures dans leur heure locale, tandis que la base de données conserve un seul fuseau horaire cohérent.

Référence de TimezoneConfig

Pour restreindre ce que les utilisateurs peuvent sélectionner, passez une liste timezone_switcher plus courte. Pour imposer un seul fuseau horaire à tous les visiteurs, définissez timezone_switcher à None et fixez directement default_timezone, par exemple à "Europe/Paris" à l'échelle de l'entreprise.

Le sélecteur de la barre de navigation affiche le nom d'affichage et le décalage UTC de chaque fuseau horaire grâce aux variables globales de template get_timezone et get_timezone_display_name. Le guide Templates documente ces variables globales ainsi que toutes les autres.

Et ensuite :

• Champs : DateTimeField, ArrowField et le reste de la référence des champs.
• Templates : Surcharger les templates et utiliser directement les globales get_timezone.
• Concepts : Comment Admin câble les middlewares et les objets de configuration.