feat: add inEnglish method to i18n

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>

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;

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: {