feat(core): add translation middleware

Author: stevenle

packages/root/src/core/core.ts

@@ -8,6 +8,11 @@ export {
   StringParamsProvider,
   useStringParams,
 } from './hooks/useStringParams.js';
+export {
+  TranslationMiddlewareProvider,
+  useTranslationMiddleware,
+  TRANSLATION_MIDDLEWARE_CONTEXT,
+} 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,22 @@ 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.pre.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.post.forEach((fn) => {
+      translation = fn(translation);
+    });
     return translation;
   };
   return t;

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

@@ -0,0 +1,45 @@
+import {ComponentChildren, FunctionalComponent, createContext} from 'preact';
+import {useContext} from 'preact/hooks';
+
+export interface TranslationMiddleware {
+  /** Transform the source string before translation lookup. */
+  pre?: (str: string) => string;
+  /** Transform the translated string before returning it. */
+  post?: (str: string) => string;
+}
+
+export interface TranslationMiddlewareContext {
+  pre: Array<(str: string) => string>;
+  post: Array<(str: string) => string>;
+}
+
+export 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) || {pre: [], post: []};
+  const merged: TranslationMiddlewareContext = {
+    pre: [...parent.pre],
+    post: [...parent.post],
+  };
+  if (props.value?.pre) {
+    merged.pre.push(props.value.pre);
+  }
+  if (props.value?.post) {
+    // Apply post transforms from child first then parent.
+    merged.post.unshift(props.value.post);
+  }
+  return (
+    <TRANSLATION_MIDDLEWARE_CONTEXT.Provider value={merged}>
+      {props.children}
+    </TRANSLATION_MIDDLEWARE_CONTEXT.Provider>
+  );
+};
+
+export function useTranslationMiddleware(): TranslationMiddlewareContext {
+  return useContext(TRANSLATION_MIDDLEWARE_CONTEXT) || {pre: [], post: []};
+}

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,21 @@
+import {
+  TranslationMiddlewareProvider,
+  useTranslations,
+} from '../../../../dist/core';
+
+export default function Page() {
+  return (
+    <TranslationMiddlewareProvider
+      value={{
+        pre: (s) => s.toUpperCase(),
+        post: (s) => 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>
+    "
+  `);
+});