feat: add middleware for useTranslations()

Author: stevenle

packages/root/src/core/core.ts

@@ -8,6 +8,10 @@ export {
   StringParamsProvider,
   useStringParams,
 } from './hooks/useStringParams.js';
+export {
+  TranslationMiddlewareProvider,
+  useTranslationMiddleware,
+} from './hooks/useTranslationsMiddleware.js';
 export {
   I18nContext,
   useI18nContext,

packages/root/src/core/hooks/useTranslations.ts

@@ -1,5 +1,6 @@
 import {I18nContext, useI18nContext} from './useI18nContext.js';
 import {useStringParams} from './useStringParams.js';
+import {useTranslationMiddleware} from './useTranslationsMiddleware.js';
 
 /**
  * A hook that returns a function that can be used to translate a string, and
@@ -23,14 +24,32 @@ export function useTranslations() {
   }
   const translations = i18nContext?.translations || {};
   const stringParams = useStringParams();
+  const middleware = useTranslationMiddleware();
   const t = (str: string, params?: Record<string, string | number>) => {
-    const key = normalizeString(str);
+    let input = str;
+    middleware.beforeTranslateFns.forEach((fn) => {
+      input = fn(input);
+    });
+    const key = normalizeString(input);
     let translation = translations[key] ?? key ?? '';
-    const allParams = {...stringParams, ...params};
-    for (const paramName of Object.keys(allParams)) {
-      const paramValue = String(allParams[paramName] ?? '');
-      translation = translation.replaceAll(`{${paramName}}`, paramValue);
+    middleware.afterTranslateFns.forEach((fn) => {
+      translation = fn(input);
+    });
+    middleware.beforeReplaceParamsFns.forEach((fn) => {
+      translation = fn(translation);
+    });
+
+    // Replace string params, e.g. "Hello, {name}".
+    if (translation.includes('{') && translation.includes('}')) {
+      translation = replaceStringParams(translation, {
+        ...stringParams,
+        ...params,
+      });
     }
+
+    middleware.afterReplaceParamsFns.forEach((fn) => {
+      translation = fn(translation);
+    });
     return translation;
   };
   return t;
@@ -54,3 +73,23 @@ function removeTrailingWhitespace(str: string) {
     .trimEnd()
     .replace(/&nbsp;$/, '');
 }
+
+/**
+ * Replaces string placeholder params, e.g.
+ *
+ * ```
+ * replaceStringParams('Hello, {name}!', {name: 'Joe'})
+ * // => 'Hello, Joe!'
+ * ```
+ */
+function replaceStringParams(
+  str: string,
+  params: Record<string, string | number>
+): string {
+  return str.replace(/{([^}]+)}/g, (match, key) => {
+    if (key in params) {
+      return String(params[key]);
+    }
+    return match;
+  });
+}

packages/root/src/core/hooks/useTranslationsMiddleware.tsx

@@ -0,0 +1,75 @@
+import {ComponentChildren, FunctionalComponent, createContext} from 'preact';
+import {useContext} from 'preact/hooks';
+
+type TransformFn = (str: string) => string;
+
+export interface TranslationMiddleware {
+  /** Transform the string before translation lookup. */
+  beforeTranslate?: TransformFn;
+  /** Transform the string after translation lookup. */
+  afterTranslate?: TransformFn;
+  /** Transform the string before `{param}` values are replaced. */
+  beforeReplaceParams?: TransformFn;
+  /** Transform the string after `{param}` values are replaced. */
+  afterReplaceParams?: TransformFn;
+}
+
+export interface TranslationMiddlewareContext {
+  beforeTranslateFns: TransformFn[];
+  afterTranslateFns: TransformFn[];
+  beforeReplaceParamsFns: TransformFn[];
+  afterReplaceParamsFns: TransformFn[];
+}
+
+const TRANSLATION_MIDDLEWARE_CONTEXT =
+  createContext<TranslationMiddlewareContext | null>(null);
+
+export interface TranslationMiddlewareProviderProps {
+  value?: TranslationMiddleware;
+  children?: ComponentChildren;
+}
+
+export const TranslationMiddlewareProvider: FunctionalComponent<
+  TranslationMiddlewareProviderProps
+> = (props) => {
+  const parent = useContext(TRANSLATION_MIDDLEWARE_CONTEXT) || {
+    beforeTranslateFns: [],
+    afterTranslateFns: [],
+    beforeReplaceParamsFns: [],
+    afterReplaceParamsFns: [],
+  };
+  const merged: TranslationMiddlewareContext = {
+    beforeTranslateFns: [...parent.beforeTranslateFns],
+    afterTranslateFns: [...parent.afterTranslateFns],
+    beforeReplaceParamsFns: [...parent.beforeReplaceParamsFns],
+    afterReplaceParamsFns: [...parent.afterReplaceParamsFns],
+  };
+  if (props.value?.beforeTranslate) {
+    merged.beforeTranslateFns.push(props.value.beforeTranslate);
+  }
+  if (props.value?.afterTranslate) {
+    merged.afterTranslateFns.push(props.value.afterTranslate);
+  }
+  if (props.value?.beforeReplaceParams) {
+    merged.beforeReplaceParamsFns.push(props.value.beforeReplaceParams);
+  }
+  if (props.value?.afterReplaceParams) {
+    merged.afterReplaceParamsFns.push(props.value.afterReplaceParams);
+  }
+  return (
+    <TRANSLATION_MIDDLEWARE_CONTEXT.Provider value={merged}>
+      {props.children}
+    </TRANSLATION_MIDDLEWARE_CONTEXT.Provider>
+  );
+};
+
+export function useTranslationMiddleware(): TranslationMiddlewareContext {
+  return (
+    useContext(TRANSLATION_MIDDLEWARE_CONTEXT) || {
+      beforeTranslateFns: [],
+      afterTranslateFns: [],
+      beforeReplaceParamsFns: [],
+      afterReplaceParamsFns: [],
+    }
+  );
+}

packages/root/test/fixtures/translation-middleware/root.config.ts

@@ -0,0 +1,3 @@
+export default {
+  prettyHtml: true,
+};

packages/root/test/fixtures/translation-middleware/routes/index.tsx

@@ -0,0 +1,22 @@
+import {
+  TranslationMiddlewareProvider,
+  useTranslations,
+} from '../../../../dist/core.js';
+
+export default function Page() {
+  return (
+    <TranslationMiddlewareProvider
+      value={{
+        beforeTranslate: (s: string) => s.toUpperCase(),
+        afterTranslate: (s: string) => s + '!',
+      }}
+    >
+      <Content />
+    </TranslationMiddlewareProvider>
+  );
+}
+
+function Content() {
+  const t = useTranslations();
+  return <p>{t('hello')}</p>;
+}

packages/root/test/translation-middleware.test.ts

@@ -0,0 +1,36 @@
+import {promises as fs} from 'node:fs';
+import path from 'node:path';
+import {assert, beforeEach, test, expect, afterEach} from 'vitest';
+import {fileExists} from '../src/utils/fsutils.js';
+import {Fixture, loadFixture} from './testutils.js';
+
+let fixture: Fixture;
+
+beforeEach(async () => {
+  fixture = await loadFixture('./fixtures/translation-middleware');
+});
+
+afterEach(async () => {
+  if (fixture) {
+    await fixture.cleanup();
+  }
+});
+
+test('apply translation middleware', async () => {
+  await fixture.build();
+  const indexPath = path.join(fixture.distDir, 'html/index.html');
+  assert.isTrue(await fileExists(indexPath));
+  const html = await fs.readFile(indexPath, 'utf-8');
+  expect(html).toMatchInlineSnapshot(`
+    "<!doctype html>
+    <html>
+    <head>
+    <meta charset=\\"utf-8\\">
+    </head>
+    <body>
+    <p>HELLO!</p>
+    </body>
+    </html>
+    "
+  `);
+});