web: refactor locale handler into top-level context handler (#6022)

* web: begin refactoring the application for future development

This commit:

- Deletes a bit of code.
- Extracts *all* of the Locale logic into a single folder, turns management of the Locale files over
  to Lit itself, and restricts our responsibility to setting the locale on startup and when the user
  changes the locale. We do this by converting a lot of internal calls into events; a request to
  change a locale isn't a function call, it's an event emitted asking `REQUEST_LOCALE_CHANGE`. We've
  even eliminated the `DETECT_LOCALE_CHANGE` event, which redrew elements with text in them, since
  Lit's own `@localized()` decorator does that for us automagically.
- We wrap our interfaces in an `ak-locale-context` that handles the startup and listens for the
  `REQUEST_LOCALE_CHANGE` event.
- ... and that's pretty much it.  Adding `@localized()` as a default behavior to `AKElement` means
  no more custom localization is needed *anywhere*.

* web: improve the localization experience

This commit fixes the Storybook story for the localization context component,
and fixes the localization initialization pass so that it is only called once
per interface environment initialization.  Since all our interfaces share the
same environment (the Django server), this preserves functionality across
all interfaces.

---------

Co-authored-by: Jens Langhammer <jens@goauthentik.io>

web/src/elements/ak-locale-context/ak-locale-context.stories.ts

@@ -0,0 +1,51 @@
+import { EVENT_LOCALE_REQUEST } from "@goauthentik/common/constants";
+import { customEvent } from "@goauthentik/elements/utils/customEvents";
+
+import { localized, msg } from "@lit/localize";
+import { LitElement, html } from "lit";
+import { customElement } from "lit/decorators.js";
+
+import "./ak-locale-context";
+
+export default {
+    title: "Elements / Shell / Locale Context",
+};
+
+@localized()
+@customElement("ak-locale-demo-component")
+export class AKLocaleDemoComponent extends LitElement {
+    render() {
+        return html`<span>${msg("Everything is ok.")}</span>`;
+    }
+}
+
+@localized()
+@customElement("ak-locale-sensitive-demo-component")
+export class AKLocaleSensitiveDemoComponent extends LitElement {
+    render() {
+        return html`<p>${msg("Everything is ok.")}</p>`;
+    }
+}
+
+export const InFrench = () =>
+    html`<div style="background: #fff; padding: 4em">
+        <ak-locale-context locale="fr_FR"
+            ><ak-locale-demo-component
+                >Everything is not ok.</ak-locale-demo-component
+            ></ak-locale-context
+        >
+    </div>`;
+
+export const SwitchingBackAndForth = () => {
+    let lang = "en";
+    window.setInterval(() => {
+        lang = lang === "en" ? "fr_FR" : "en";
+        window.dispatchEvent(customEvent(EVENT_LOCALE_REQUEST, { locale: lang }));
+    }, 1000);
+
+    return html`<div style="background: #fff; padding: 4em">
+        <ak-locale-context locale="fr_FR">
+            <ak-locale-sensitive-demo-component></ak-locale-sensitive-demo-component
+        ></ak-locale-context>
+    </div>`;
+};

web/src/elements/ak-locale-context/ak-locale-context.ts

@@ -0,0 +1,115 @@
+import { EVENT_LOCALE_CHANGE } from "@goauthentik/common/constants";
+import { EVENT_LOCALE_REQUEST } from "@goauthentik/common/constants";
+import { customEvent, isCustomEvent } from "@goauthentik/elements/utils/customEvents";
+
+import { provide } from "@lit-labs/context";
+import { LitElement, html } from "lit";
+import { customElement, property } from "lit/decorators.js";
+
+import { initializeLocalization } from "./configureLocale";
+import type { LocaleGetter, LocaleSetter } from "./configureLocale";
+import locale from "./context";
+import {
+    DEFAULT_LOCALE,
+    autoDetectLanguage,
+    getBestMatchLocale,
+    localeCodeFromUrl,
+} from "./helpers";
+
+/**
+ * A component to manage your locale settings.
+ *
+ * ## Details
+ *
+ * This component exists to take a locale setting from several different places, find the
+ * appropriate locale file in our catalog of locales, and set the lit-localization context
+ * appropriately. If that works, it sends off an event saying so.
+ *
+ * @element ak-locale-context
+ * @slot - The content which consumes this context
+ * @fires ak-locale-change - When a valid locale has been swapped in
+ */
+@customElement("ak-locale-context")
+export class LocaleContext extends LitElement {
+    /// @attribute The text representation of the current locale */
+    @provide({ context: locale })
+    @property({ attribute: true, type: String })
+    locale = DEFAULT_LOCALE;
+
+    /// @attribute The URL parameter to look for (if any)
+    @property({ attribute: true, type: String })
+    param = "locale";
+
+    getLocale: LocaleGetter;
+
+    setLocale: LocaleSetter;
+
+    constructor(code = DEFAULT_LOCALE) {
+        super();
+        this.notifyApplication = this.notifyApplication.bind(this);
+        this.updateLocaleHandler = this.updateLocaleHandler.bind(this);
+        try {
+            const [getLocale, setLocale] = initializeLocalization();
+            this.getLocale = getLocale;
+            this.setLocale = setLocale;
+            this.setLocale(code).then(() => {
+                window.setTimeout(this.notifyApplication, 0);
+            });
+        } catch (e) {
+            throw new Error(`Developer error: Must have only one locale context per session: ${e}`);
+        }
+    }
+
+    connectedCallback() {
+        super.connectedCallback();
+        const localeRequest = autoDetectLanguage(this.locale);
+        this.updateLocale(localeRequest);
+        window.addEventListener(EVENT_LOCALE_REQUEST, this.updateLocaleHandler);
+    }
+
+    disconnectedCallback() {
+        window.removeEventListener(EVENT_LOCALE_REQUEST, this.updateLocaleHandler);
+        super.disconnectedCallback();
+    }
+
+    updateLocaleHandler(ev: Event) {
+        if (!isCustomEvent(ev)) {
+            console.warn(`Received a non-custom event at EVENT_LOCALE_REQUEST: ${ev}`);
+            return;
+        }
+        console.log("Locale update request received.");
+        this.updateLocale(ev.detail.locale);
+    }
+
+    updateLocale(code: string) {
+        const urlCode = localeCodeFromUrl(this.param);
+        const requestedLocale = urlCode ? urlCode : code;
+        const locale = getBestMatchLocale(requestedLocale);
+        if (!locale) {
+            console.warn(`authentik/locale: failed to find locale for code ${code}`);
+            return;
+        }
+        locale.locale().then(() => {
+            console.debug(`authentik/locale: Loaded locale '${code}'`);
+            if (this.getLocale() === code) {
+                return;
+            }
+            console.debug(`Setting Locale to ... ${locale.label()} (${locale.code})`);
+            this.setLocale(locale.code).then(() => {
+                window.setTimeout(this.notifyApplication, 0);
+            });
+        });
+    }
+
+    notifyApplication() {
+        // You will almost never have cause to catch this event. Lit's own `@localized()` decorator
+        // works just fine for almost every use case.
+        this.dispatchEvent(customEvent(EVENT_LOCALE_CHANGE));
+    }
+
+    render() {
+        return html`<slot></slot>`;
+    }
+}
+
+export default LocaleContext;

web/src/elements/ak-locale-context/configureLocale.ts

@@ -0,0 +1,40 @@
+import { sourceLocale, targetLocales } from "@goauthentik/app/locale-codes";
+
+import { configureLocalization } from "@lit/localize";
+
+import { getBestMatchLocale } from "./helpers";
+
+type LocaleGetter = ReturnType<typeof configureLocalization>["getLocale"];
+type LocaleSetter = ReturnType<typeof configureLocalization>["setLocale"];
+
+// Internal use only.
+//
+// This is where the lit-localization module is initialized with our loader, which associates our
+// collection of locales with its getter and setter functions.
+
+let getLocale: LocaleGetter | undefined = undefined;
+let setLocale: LocaleSetter | undefined = undefined;
+
+export function initializeLocalization(): [LocaleGetter, LocaleSetter] {
+    if (getLocale && setLocale) {
+        return [getLocale, setLocale];
+    }
+
+    ({ getLocale, setLocale } = configureLocalization({
+        sourceLocale,
+        targetLocales,
+        loadLocale: async (locale: string) => {
+            const localeDef = getBestMatchLocale(locale);
+            if (!localeDef) {
+                console.warn(`Unrecognized locale: ${localeDef}`);
+                return Promise.reject("");
+            }
+            return localeDef.locale();
+        },
+    }));
+
+    return [getLocale, setLocale];
+}
+
+export default initializeLocalization;
+export type { LocaleGetter, LocaleSetter };

web/src/elements/ak-locale-context/context.ts

@@ -0,0 +1,4 @@
+import { createContext } from "@lit-labs/context";
+
+export const localeContext = createContext<string>("locale");
+export default localeContext;

web/src/elements/ak-locale-context/definitions.ts

@@ -0,0 +1,61 @@
+import * as _enLocale from "@goauthentik/locales/en";
+
+import type { LocaleModule } from "@lit/localize";
+import { msg } from "@lit/localize";
+
+import { AkLocale, LocaleRow } from "./types";
+
+export const DEFAULT_FALLBACK = "en";
+
+const enLocale: LocaleModule = _enLocale;
+
+export { enLocale };
+
+// NOTE: This table cannot be made any shorter, despite all the repetition of syntax. Bundlers look
+// for the `await import` string as a *string target* for doing alias substitution, so putting
+// the import in some sort of abstracting function doesn't work. The same is true for the `msg()`
+// function, which `localize` uses to find strings for extraction and translation. Likewise,
+// because this is a file-level table, the `msg()` must be thunked so that they're re-run when
+// the user changes the locale.
+
+// NOTE: The matchers try to conform loosely to [RFC
+// 5646](https://www.rfc-editor.org/rfc/rfc5646.txt), "Tags for the Identification of Languages." In
+// practice, language tags have been seen using both hyphens and underscores, and the Chinese
+// language uses both "regional" and "script" suffixes. The regexes use the language and any region
+// or script.
+//
+// French is currently an oddity; the translator provided the France regional version explicitly,
+// and we fall back to that regardless of region. Sorry, Québécois.
+//
+// Chinese locales usually (but not always) use the script rather than region suffix. The default
+// (optional) fallback for Chinese (zh) is "Chinese (simplified)", which is why it has that odd
+// regex syntax at the end which means "match zh as long as it's not followed by a [:word:] token";
+// Traditional script and the Taiwanese are attempted first, and if neither matches, anything
+// beginning with that generic "zh" is mapped to "Chinese (simplified)."
+
+// - Code for Lit/Locale
+// - Regex for matching user-supplied locale.
+// - Text Label
+// - Locale loader.
+
+// prettier-ignore
+const LOCALE_TABLE: LocaleRow[] = [
+    ["en",      /^en([_-]|$)/i,      () => msg("English"),               async () => await import("@goauthentik/locales/en")],
+    ["es",      /^es([_-]|$)/i,      () => msg("Spanish"),               async () => await import("@goauthentik/locales/es")],
+    ["de",      /^de([_-]|$)/i,      () => msg("German"),                async () => await import("@goauthentik/locales/de")],
+    ["fr_FR",   /^fr([_-]|$)/i,      () => msg("French"),                async () => await import("@goauthentik/locales/fr_FR")],
+    ["pl",      /^pl([_-]|$)/i,      () => msg("Polish"),                async () => await import("@goauthentik/locales/pl")],
+    ["tr",      /^tr([_-]|$)/i,      () => msg("Turkish"),               async () => await import("@goauthentik/locales/tr")],
+    ["zh-Hant", /^zh[_-](HK|Hant)/i, () => msg("Chinese (traditional)"), async () => await import("@goauthentik/locales/zh-Hant")],
+    ["zh_TW",   /^zh[_-]TW$/i,       () => msg("Taiwanese Mandarin"),    async () => await import("@goauthentik/locales/zh_TW")],
+    ["zh-Hans", /^zh(\b|_)/i,        () => msg("Chinese (simplified)"),  async () => await import("@goauthentik/locales/zh-Hans")],
+];
+
+export const LOCALES: AkLocale[] = LOCALE_TABLE.map(([code, match, label, locale]) => ({
+    code,
+    match,
+    label,
+    locale,
+}));
+
+export default LOCALES;

web/src/elements/ak-locale-context/helpers.ts

@@ -0,0 +1,69 @@
+import { globalAK } from "@goauthentik/common/global";
+
+import { LOCALES as RAW_LOCALES, enLocale } from "./definitions";
+import { AkLocale } from "./types";
+
+export const DEFAULT_LOCALE = "en";
+
+export const EVENT_REQUEST_LOCALE = "ak-request-locale";
+
+const TOMBSTONE = "⛼⛼tombstone⛼⛼";
+
+// NOTE: This is the definition of the LOCALES table that most of the code uses. The 'definitions'
+// file is relatively pure, but here we establish that we want the English locale to loaded when an
+// application is first instantiated.
+
+export const LOCALES = RAW_LOCALES.map((locale) =>
+    locale.code === "en" ? { ...locale, locale: async () => enLocale } : locale,
+);
+
+export function getBestMatchLocale(locale: string): AkLocale | undefined {
+    return LOCALES.find((l) => l.match.test(locale));
+}
+
+// This looks weird, but it's sensible: we have several candidates, and we want to find the first
+// one that has a supported locale. Then, from *that*, we have to extract that first supported
+// locale.
+
+export function findSupportedLocale(candidates: string[]) {
+    const candidate = candidates.find((candidate: string) => getBestMatchLocale(candidate));
+    return candidate ? getBestMatchLocale(candidate) : undefined;
+}
+
+export function localeCodeFromUrl(param = "locale") {
+    const url = new URL(window.location.href);
+    return url.searchParams.get(param) || "";
+}
+
+// Get all locales we can, in order
+// - Global authentik settings (contains user settings)
+// - URL parameter
+// - A requested code passed in, if any
+// - Navigator
+// - Fallback (en)
+
+const isLocaleCandidate = (v: unknown): v is string =>
+    typeof v === "string" && v !== "" && v !== TOMBSTONE;
+
+export function autoDetectLanguage(requestedCode?: string): string {
+    const localeCandidates: string[] = [
+        globalAK()?.locale ?? TOMBSTONE,
+        localeCodeFromUrl("locale"),
+        requestedCode ?? TOMBSTONE,
+        window.navigator?.language ?? TOMBSTONE,
+        DEFAULT_LOCALE,
+    ].filter(isLocaleCandidate);
+
+    const firstSupportedLocale = findSupportedLocale(localeCandidates);
+
+    if (!firstSupportedLocale) {
+        console.debug(
+            `authentik/locale: No locale found for '[${localeCandidates}.join(',')]', falling back to ${DEFAULT_LOCALE}`,
+        );
+        return DEFAULT_LOCALE;
+    }
+
+    return firstSupportedLocale.code;
+}
+
+export default autoDetectLanguage;

web/src/elements/ak-locale-context/index.ts

@@ -0,0 +1,4 @@
+import LocaleContext from "./ak-locale-context";
+
+export { LocaleContext };
+export default LocaleContext;

web/src/elements/ak-locale-context/types.ts

@@ -0,0 +1,10 @@
+import type { LocaleModule } from "@lit/localize";
+
+export type LocaleRow = [string, RegExp, () => string, () => Promise<LocaleModule>];
+
+export type AkLocale = {
+    code: string;
+    match: RegExp;
+    label: () => string;
+    locale: () => Promise<LocaleModule>;
+};