Internationalisierung & Zeitzonen

Mit starlette-admin können Sie UI-Zeichenketten pro Benutzer lokalisieren und angezeigte Datums- und Zeitwerte in die lokale Zeitzone des Betrachters konvertieren – unabhängig davon, wie Ihre Datenbank sie speichert.

Vollständiges Beispiel: Eine vollständige, lauffähige Anwendung, die Internationalisierung und Zeitzonen demonstriert, finden Sie unter examples/10-i18n-timezone im GitHub-Repository.

Installation des i18n-Extras

Die Unterstützung für Übersetzungen erfordert Babel. Ohne Babel funktioniert der Admin weiterhin, fällt jedoch auf Englisch zurück und überspringt die locale-bewusste Formatierung von Datum und Zahlen.

pip install "starlette-admin[i18n]"

uv add "starlette-admin[i18n]"

Festlegen der 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 ist standardmäßig None, wodurch der Admin auf Englisch läuft. Wenn Sie ein I18nConfig übergeben, installiert der Admin die LocaleMiddleware. Die Middleware ermittelt bei jeder Anfrage eine Locale und stellt sie den Templates sowie den Übersetzungsfunktionen (gettext und lazy_gettext) in Ihrem gesamten Feld- und View-Code zur Verfügung.

Der Parameter language_switcher fügt der Navigationsleiste des Admins ein Dropdown-Menü hinzu, über das Benutzer ihre Locale auswählen können. Lassen Sie ihn auf dem Standardwert None, um den Umschalter auszublenden und sich allein auf default_locale und die Erkennung pro Anfrage zu verlassen.

Referenz zu I18nConfig

Wie die Locale ermittelt wird

LocaleMiddleware ermittelt die Locale einmal pro Anfrage, in dieser Reihenfolge:

1. Cookie: Der Wert von language_cookie_name, sofern er einer integrierten unterstützten Locale entspricht.
2. Header: Der Accept-Language-Header bzw. der Header, den Sie in language_header_name festgelegt haben, derselben Gültigkeitsprüfung unterworfen.
3. Standard: Die default_locale, wenn weder Cookie noch Header übereinstimmen.

Die integrierten unterstützten Locales (starlette_admin.i18n.SUPPORTED_LOCALES) sind Deutsch, Englisch, Französisch, Portugiesisch, Russisch, Türkisch sowie Chinesisch (vereinfacht und traditionell). Wählt ein Benutzer eine Sprache in der Navigationsleiste aus, schreibt der Umschalter das Sprach-Cookie, sodass die Auswahl über mehrere Anfragen hinweg erhalten bleibt, ohne dass serverseitige Sessionspeicherung erforderlich ist.

Zeitzonen

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

Wie die Zeitzone ermittelt wird

TimezoneMiddleware ermittelt die Zeitzone einmal pro Anfrage:

1. Cookie: Der Wert von timezone_cookie_name, der standardmäßig "timezone" lautet, sofern vorhanden.
2. Standard: Andernfalls die default_timezone.

Der Zeitzonen-Umschalter in der Navigationsleiste schreibt dieses Cookie, genau wie der Sprachumschalter. Für Zeitzonen gibt es kein Äquivalent zum Accept-Language-Header, da Browser einen solchen nicht senden; die Erkennung stützt sich daher vollständig auf Cookies. Client-seitiges JavaScript, das Intl.DateTimeFormat().resolvedOptions().timeZone ausliest, setzt dieses Cookie typischerweise, ebenso wie der Umschalter selbst.

Wie Feldwerte konvertiert werden

DateTimeField und ArrowField konvertieren Werte zwischen der database_timezone und der ermittelten Zeitzone des Betrachters.

• Lesen (Liste, Detailansicht, Export): Der Admin interpretiert einen naiven Wert aus Ihrer Datenbank als Wert in der database_timezone und konvertiert ihn in die Zeitzone des Betrachters, bevor er ihn formatiert.
• Schreiben (Erstellungs- und Bearbeitungsformulare): Der Admin interpretiert einen übermittelten Wert als Wert in der Zeitzone des Betrachters und konvertiert ihn in die database_timezone, bevor er Ihr Modell erreicht.

Auf diese Weise können zwei Administratoren in verschiedenen Zeitzonen dieselbe Zeile bearbeiten, wobei jeder die Zeiten in seiner eigenen Ortszeit sieht, während die Datenbank eine einzige, konsistente Zeitzone beibehält.

Referenz zu TimezoneConfig

Um die Auswahlmöglichkeiten für Benutzer einzuschränken, übergeben Sie eine kürzere Liste an timezone_switcher. Um eine einzige Zeitzone für alle Betrachter durchzusetzen, setzen Sie timezone_switcher auf None und legen default_timezone direkt fest, beispielsweise auf eine unternehmensweite "Europe/Paris".

Der Umschalter in der Navigationsleiste rendert den Anzeigenamen jeder Zeitzone sowie deren UTC-Versatz mithilfe der Template-Globals get_timezone und get_timezone_display_name. Diese Globals sowie alle weiteren dokumentiert der Leitfaden Templates.

Weiterführende Themen:

• Fields: DateTimeField, ArrowField und die restliche Feldreferenz.
• Templates: Templates überschreiben und die get_timezone-Globals direkt verwenden.
• Concepts: Wie Admin Middleware und Konfigurationsobjekte verdrahtet.