From b9326f6bc3ffc160e4ff13fc14d1f193ae5af69b Mon Sep 17 00:00:00 2001
From: Ryan Miller <ryan.m@getsession.org>
Date: Thu, 22 Aug 2024 15:30:22 +1000
Subject: [PATCH] feat: add inEnglish method to i18n

---
 ts/types/Localizer.ts |  4 ++++
 ts/util/i18n.ts       | 26 ++++++++++++++++++++++++++
 ts/window.d.ts        | 14 ++++++++++++++
 3 files changed, 44 insertions(+)

diff --git a/ts/types/Localizer.ts b/ts/types/Localizer.ts
index c28779b05..f5d61f418 100644
--- a/ts/types/Localizer.ts
+++ b/ts/types/Localizer.ts
@@ -117,6 +117,10 @@ export type I18nMethods = {
   stripped: <T extends LocalizerToken, R extends LocalizerDictionary[T]>(
     ...[token, args]: GetMessageArgs<T>
   ) => R;
+  /** @see {@link window.i18n.inEnglish} */
+  inEnglish: <T extends LocalizerToken, R extends LocalizerDictionary[T]>(
+    ...[token, args]: GetMessageArgs<T>
+  ) => R | T;
   /** @see {@link window.i18n.formatMessageWithArgs */
   getRawMessage: <T extends LocalizerToken, R extends DictionaryWithoutPluralStrings[T]>(
     ...[token, args]: GetMessageArgs<T>
diff --git a/ts/util/i18n.ts b/ts/util/i18n.ts
index 8f99f8190..e267780c7 100644
--- a/ts/util/i18n.ts
+++ b/ts/util/i18n.ts
@@ -409,6 +409,32 @@ export const setupI18n = (params: {
     return deSanitizeHtmlTags(strippedString, '\u200B') as R;
   }
 
+  /** NOTE: Because of docstring limitations changes MUST be manually synced between {@link setupI18n.inEnglish } and {@link window.i18n.inEnglish } */
+  /**
+   * Retrieves a message string in the {@link en} locale, substituting variables where necessary.
+   *
+   * NOTE: This does not work for plural strings. This function should only be used for debug and
+   * non-user-facing strings. Plural string support can be added splitting out the logic for
+   * {@link setupI18n.formatMessageWithArgs} and creating a new getMessageFromDictionary, which
+   * specifies takes a dictionary as an argument. This is left as an exercise for the reader.
+   *
+   * @param token - The token identifying the message to retrieve.
+   * @param args - An optional record of substitution variables and their replacement values. This is required if the string has dynamic variables.
+   */
+  function inEnglish<T extends LocalizerToken, R extends LocalizerDictionary[T]>(
+    ...[token, args]: GetMessageArgs<T>
+  ): R | T {
+    const rawMessage = en[token] as R;
+    if (!rawMessage) {
+      i18nLog(
+        `Attempted to get forced en string for nonexistent key: '${token}' in fallback dictionary`
+      );
+      return token as T;
+    }
+    return formatMessageWithArgs<T, R>(rawMessage, args as ArgsRecord<T>);
+  }
+
+  getMessage.inEnglish = inEnglish;
   getMessage.stripped = stripped;
   getMessage.getRawMessage = getRawMessage;
   getMessage.formatMessageWithArgs = formatMessageWithArgs;
diff --git a/ts/window.d.ts b/ts/window.d.ts
index f29b89618..1117c5e8e 100644
--- a/ts/window.d.ts
+++ b/ts/window.d.ts
@@ -115,6 +115,20 @@ declare global {
        * // => 'Hello, Alice! Welcome!'
        */
       stripped: I18nMethods['stripped'];
+
+      /** NOTE: Because of docstring limitations changes MUST be manually synced between {@link setupI18n.inEnglish } and {@link window.i18n.inEnglish } */
+      /**
+       * Retrieves a message string in the {@link en} locale, substituting variables where necessary.
+       *
+       * NOTE: This does not work for plural strings. This function should only be used for debug and
+       * non-user-facing strings. Plural string support can be added splitting out the logic for
+       * {@link setupI18n.formatMessageWithArgs} and creating a new getMessageFromDictionary, which
+       * specifies takes a dictionary as an argument. This is left as an exercise for the reader.
+       *
+       * @param token - The token identifying the message to retrieve.
+       * @param args - An optional record of substitution variables and their replacement values. This is required if the string has dynamic variables.
+       */
+      inEnglish: I18nMethods['inEnglish'];
     };
     log: any;
     sessionFeatureFlags: {