Introduce i18nContext (#31347)

* Introduce i18nContext

 * Adds a context that holds the module i1n API
 * Switches shared components to use that instead of importing it directly
 * Adds the context to MatrixChat and BaseDalog so it should be available most places in EW

This is a relatively small PR but does change the way the shared components do i18n so
just doing this one by itself (it stands by itself anyway).

This will allow shared components to use i18n when used in modules.

* Add the file

* Fix import lint

* Name the translate function _t

Then it should continue to get picked up by the script

This seems a bit flaky and ew but I'm not sure I want to get into
changing this in this PR.

* Put humanize back to calling something called _t too

* Missed one

* Add i18n context wrapper to stories

* Unused import

* Fix imports

* wrap richitem

* Wrap other richitem & richlist

* One day I will get my head around this syntax

* Fix import spacing

* Add wrapper to test

* unused import

* Hack around dependency cycle

* Make a moduleapi instance for tests

* Add i18n wrapper to jest-matrix-react

* Simple test for i18napi

* Import type

* Move i18n context wrapper to storybook template

* Unused imports & fix pill story

* Move i18n to its own provider

* Add i18ncontext wrapper to jest tests

* imports

* Bump module api to 1.7.0

* tsdoc

packages/shared-components/src/audio/AudioPlayerView/AudioPlayerView.test.tsx

@@ -14,6 +14,8 @@ import { fireEvent } from "@testing-library/dom";
 import * as stories from "./AudioPlayerView.stories.tsx";
 import { AudioPlayerView, type AudioPlayerViewActions, type AudioPlayerViewSnapshot } from "./AudioPlayerView";
 import { MockViewModel } from "../../viewmodel/MockViewModel.ts";
+import { I18nContext } from "../../utils/i18nContext.ts";
+import { I18nApi } from "../../index.ts";
 
 const { Default, NoMediaName, NoSize, HasError } = composeStories(stories);
 
@@ -64,7 +66,9 @@ describe("AudioPlayerView", () => {
             error: false,
         });
 
-        render(<AudioPlayerView vm={vm} />);
+        render(<AudioPlayerView vm={vm} />, {
+            wrapper: ({ children }) => <I18nContext.Provider value={new I18nApi()}>{children}</I18nContext.Provider>,
+        });
         await user.click(screen.getByRole("button", { name: "Play" }));
         expect(togglePlay).toHaveBeenCalled();
 

packages/shared-components/src/audio/AudioPlayerView/AudioPlayerView.tsx

@@ -14,7 +14,7 @@ import { Flex } from "../../utils/Flex";
 import styles from "./AudioPlayerView.module.css";
 import { PlayPauseButton } from "../PlayPauseButton";
 import { type PlaybackState } from "../playback";
-import { _t } from "../../utils/i18n";
+import { useI18n } from "../../utils/i18nContext";
 import { formatBytes } from "../../utils/FormattingUtils";
 import { Clock } from "../Clock";
 import { SeekBar } from "../SeekBar";
@@ -90,6 +90,8 @@ interface AudioPlayerViewProps {
  * ```
  */
 export function AudioPlayerView({ vm }: Readonly<AudioPlayerViewProps>): JSX.Element {
+    const { translate: _t } = useI18n();
+
     const {
         playbackState,
         mediaName = _t("timeline|m.audio|unnamed_audio"),

packages/shared-components/src/audio/PlayPauseButton/PlayPauseButton.tsx

@@ -11,7 +11,7 @@ import Play from "@vector-im/compound-design-tokens/assets/web/icons/play-solid"
 import Pause from "@vector-im/compound-design-tokens/assets/web/icons/pause-solid";
 
 import styles from "./PlayPauseButton.module.css";
-import { _t } from "../../utils/i18n";
+import { useI18n } from "../../utils/i18nContext";
 
 export interface PlayPauseButtonProps extends HTMLAttributes<HTMLButtonElement> {
     /**
@@ -46,6 +46,8 @@ export function PlayPauseButton({
     togglePlay,
     ...rest
 }: Readonly<PlayPauseButtonProps>): JSX.Element {
+    const { translate: _t } = useI18n();
+
     const label = playing ? _t("action|pause") : _t("action|play");
 
     return (

packages/shared-components/src/audio/SeekBar/SeekBar.tsx

@@ -10,7 +10,7 @@ import { throttle } from "lodash";
 import classNames from "classnames";
 
 import style from "./SeekBar.module.css";
-import { _t } from "../../utils/i18n";
+import { useI18n } from "../../utils/i18nContext";
 
 export interface SeekBarProps extends React.InputHTMLAttributes<HTMLInputElement> {
     /**
@@ -33,6 +33,8 @@ interface ISeekCSS extends CSSProperties {
  * ```
  */
 export function SeekBar({ value = 0, className, ...rest }: Readonly<SeekBarProps>): JSX.Element {
+    const { translate: _t } = useI18n();
+
     const [newValue, setNewValue] = useState(value);
     // Throttle the value setting to avoid excessive re-renders
     const setThrottledValue = useMemo(() => throttle(setNewValue, 10), []);

packages/shared-components/src/index.ts

@@ -23,10 +23,12 @@ export * from "./utils/Flex";
 
 // Utils
 export * from "./utils/i18n";
+export * from "./utils/i18nContext";
 export * from "./utils/humanize";
 export * from "./utils/DateUtils";
 export * from "./utils/numbers";
 export * from "./utils/FormattingUtils";
+export * from "./utils/I18nApi";
 
 // MVVM
 export * from "./viewmodel";

packages/shared-components/src/pill-input/Pill/Pill.tsx

@@ -12,7 +12,7 @@ import CloseIcon from "@vector-im/compound-design-tokens/assets/web/icons/close"
 
 import { Flex } from "../../utils/Flex";
 import styles from "./Pill.module.css";
-import { _t } from "../../utils/i18n";
+import { useI18n } from "../../utils/i18nContext";
 
 export interface PillProps extends Omit<HTMLAttributes<HTMLDivElement>, "onClick"> {
     /**
@@ -39,6 +39,7 @@ export interface PillProps extends Omit<HTMLAttributes<HTMLDivElement>, "onClick
  */
 export function Pill({ className, children, label, onClick, ...props }: PropsWithChildren<PillProps>): JSX.Element {
     const id = useId();
+    const { translate: _t } = useI18n();
 
     return (
         <Flex

packages/shared-components/src/rich-list/RichItem/RichItem.stories.tsx

@@ -8,8 +8,8 @@
 import React from "react";
 import { fn } from "storybook/test";
 
-import { RichItem } from "./RichItem";
 import type { Meta, StoryFn } from "@storybook/react-vite";
+import { RichItem } from "./RichItem";
 
 const currentTimestamp = new Date("2025-03-09T12:00:00Z").getTime();
 

packages/shared-components/src/rich-list/RichItem/RichItem.tsx

@@ -9,8 +9,8 @@ import React, { type HTMLAttributes, type JSX, memo } from "react";
 import CheckIcon from "@vector-im/compound-design-tokens/assets/web/icons/check";
 
 import styles from "./RichItem.module.css";
-import { humanizeTime } from "../../utils/humanize";
 import { Flex } from "../../utils/Flex";
+import { useI18n } from "../../utils/i18nContext";
 
 export interface RichItemProps extends HTMLAttributes<HTMLLIElement> {
     /**
@@ -63,6 +63,8 @@ export const RichItem = memo(function RichItem({
     selected,
     ...props
 }: RichItemProps): JSX.Element {
+    const i18n = useI18n();
+
     return (
         <li
             className={styles.richItem}
@@ -77,7 +79,7 @@ export const RichItem = memo(function RichItem({
             <span className={styles.description}>{description}</span>
             {timestamp && (
                 <span role="timer" className={styles.timestamp}>
-                    {humanizeTime(timestamp)}
+                    {i18n.humanizeTime(timestamp)}
                 </span>
             )}
         </li>

packages/shared-components/src/test/utils/jest-matrix-react.tsx

@@ -16,16 +16,24 @@ import React, { type ReactElement } from "react";
 import { render, type RenderOptions } from "@testing-library/react";
 import { TooltipProvider } from "@vector-im/compound-web";
 
+import { I18nApi, I18nContext } from "../..";
+
 const wrapWithTooltipProvider = (Wrapper: RenderOptions["wrapper"]) => {
     return ({ children }: { children: React.ReactNode }) => {
         if (Wrapper) {
             return (
-                <Wrapper>
-                    <TooltipProvider>{children}</TooltipProvider>
-                </Wrapper>
+                <I18nContext.Provider value={new I18nApi()}>
+                    <Wrapper>
+                        <TooltipProvider>{children}</TooltipProvider>
+                    </Wrapper>
+                </I18nContext.Provider>
             );
         } else {
-            return <TooltipProvider>{children}</TooltipProvider>;
+            return (
+                <I18nContext.Provider value={new I18nApi()}>
+                    <TooltipProvider>{children}</TooltipProvider>
+                </I18nContext.Provider>
+            );
         }
     };
 };

packages/shared-components/src/utils/I18nApi.test.ts

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2025 Element Creations Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+import { type TranslationKey } from "../i18nKeys";
+import { I18nApi } from "./I18nApi";
+
+describe("I18nApi", () => {
+    it("can register a translation and use it", () => {
+        const i18n = new I18nApi();
+        i18n.register({
+            "hello.world": {
+                en: "Hello, World!",
+            },
+        });
+
+        expect(i18n.translate("hello.world" as TranslationKey)).toBe("Hello, World!");
+    });
+});

packages/shared-components/src/utils/I18nApi.ts

@@ -0,0 +1,52 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { type I18nApi as II18nApi, type Variables, type Translations } from "@element-hq/element-web-module-api";
+
+import { humanizeTime } from "./humanize";
+import { _t, getLocale, registerTranslations } from "./i18n";
+import { type TranslationKey } from "../i18nKeys";
+
+export class I18nApi implements II18nApi {
+    /**
+     * Read the current language of the user in IETF Language Tag format
+     */
+    public get language(): string {
+        return getLocale();
+    }
+
+    /**
+     * Register translations for the module, may override app's existing translations
+     */
+    public register(translations: Partial<Translations>): void {
+        const langs: Record<string, Record<string, string>> = {};
+        for (const key in translations) {
+            for (const lang in translations[key]) {
+                langs[lang] = langs[lang] || {};
+                langs[lang][key] = translations[key][lang];
+            }
+        }
+
+        // Finally, tell counterpart about our translations
+        for (const lang in langs) {
+            registerTranslations(lang, langs[lang]);
+        }
+    }
+
+    /**
+     * Perform a translation, with optional variables
+     * @param key - The key to translate
+     * @param variables - Optional variables to interpolate into the translation
+     */
+    public translate(key: TranslationKey, variables?: Variables): string {
+        return _t(key, variables);
+    }
+
+    public humanizeTime(timeMillis: number): string {
+        return humanizeTime(timeMillis, this);
+    }
+}

packages/shared-components/src/utils/humanize.ts

@@ -6,7 +6,9 @@ SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Com
 Please see LICENSE files in the repository root for full details.
 */
 
-import { _t } from "./i18n";
+import { type I18nApi } from "@element-hq/element-web-module-api";
+
+import { _t as _tFromModule } from "./i18n";
 
 // These are the constants we use for when to break the text
 const MILLISECONDS_RECENT = 15000;
@@ -21,13 +23,15 @@ const HOURS_1_DAY = 26;
  * @param {number} timeMillis The time in millis to compare against.
  * @returns {string} The humanized time.
  */
-export function humanizeTime(timeMillis: number): string {
+export function humanizeTime(timeMillis: number, i18nApi?: I18nApi): string {
     const now = Date.now();
     let msAgo = now - timeMillis;
     const minutes = Math.abs(Math.ceil(msAgo / 60000));
     const hours = Math.ceil(minutes / 60);
     const days = Math.ceil(hours / 24);
 
+    const _t = i18nApi?.translate ?? _tFromModule;
+
     if (msAgo >= 0) {
         // Past
         if (msAgo <= MILLISECONDS_RECENT) return _t("time|few_seconds_ago");

packages/shared-components/src/utils/i18nContext.ts

@@ -0,0 +1,27 @@
+/*
+Copyright 2025 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { createContext, useContext } from "react";
+import { type I18nApi } from "@element-hq/element-web-module-api";
+
+export const I18nContext = createContext<I18nApi | null>(null);
+I18nContext.displayName = "I18nContext";
+
+/**
+ * A hook to get the i18n API from the context. Will throw if no i18n context is found.
+ * @throws If no i18n context is found
+ * @returns The i18n API from the context
+ */
+export function useI18n(): I18nApi {
+    const i18n = useContext(I18nContext);
+
+    if (!i18n) {
+        throw new Error("useI18n must be used within an I18nContext.Provider");
+    }
+
+    return i18n;
+}