Merge pull request #227 from element-hq/florianduros/i18n-tags

packages/element-web-module-api/src/api/i18n.ts

@@ -5,6 +5,8 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE files in the repository root for full details.
 */
 
+import { type ReactNode } from "react";
+
 /**
  * The translations for the module.
  * @public
@@ -16,6 +18,17 @@ export type Translations = Record<
     }
 >;
 
+/**
+ * The value a variable or tag can take for a translation interpolation.
+ *
+ * When used as a function, `sub` is the text content wrapped between the tag
+ * in the translation string. For example, given `"Click <a>here</a>"`, the
+ * function receives `"here"` and should return a `ReactNode` wrapping it.
+ *
+ * @public
+ */
+export type SubstitutionValue = number | string | ReactNode | ((sub: string) => ReactNode);
+
 /**
  * Variables to interpolate into a translation.
  * @public
@@ -25,9 +38,16 @@ export type Variables = {
      * The number of items to count for pluralised translations
      */
     count?: number;
-    [key: string]: number | string | undefined;
+    [key: string]: SubstitutionValue;
 };
 
+/**
+ * Tags to interpolate into a translation, where the value is a ReactNode or a function that returns a ReactNode.
+ * This allows for more complex interpolations, such as links or formatted text.
+ * @public
+ */
+export type Tags = Record<string, SubstitutionValue>;
+
 /**
  * The API for interacting with translations.
  * @public
@@ -49,6 +69,13 @@ export interface I18nApi {
      * @param variables - Optional variables to interpolate into the translation
      */
     translate(this: void, key: keyof Translations, variables?: Variables): string;
+    /**
+     * Perform a translation, with optional variables
+     * @param key - The key to translate
+     * @param variables - Optional variables to interpolate into the translation
+     * @param tags - Optional tags to interpolate into the translation
+     */
+    translate(this: void, key: keyof Translations, variables: Variables | undefined, tags: Tags): ReactNode;
 
     /**
      * Convert a timestamp into a translated, human-readable time,

packages/element-web-module-api/src/index.ts

@@ -8,7 +8,7 @@ Please see LICENSE files in the repository root for full details.
 export { ModuleLoader, ModuleIncompatibleError } from "./loader";
 export type { Api, Module, ModuleFactory } from "./api";
 export type { Config, ConfigApi } from "./api/config";
-export type { I18nApi, Variables, Translations } from "./api/i18n";
+export type { I18nApi, Variables, Translations, SubstitutionValue, Tags } from "./api/i18n";
 export type * from "./models/event";
 export type * from "./models/Room";
 export type * from "./api/custom-components";