refactor: i18next implementation to align with odc runtime and allow registering events and non-react usage

Author: joshunrau

.storybook/index.mdx

@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/blocks';
+import { Meta } from '@storybook/addon-docs/blocks';
 
 <Meta title="Welcome" />
 

src/hooks/useTranslation/useTranslation.ts

@@ -1,30 +1,45 @@
-import { useCallback } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 
-import { useStore } from 'zustand';
+import type {
+  TranslateFunction,
+  TranslationKey,
+  TranslationKeyForNamespace,
+  TranslationNamespace,
+  TranslatorType
+} from '@/i18n';
 
-import { translationStore } from '@/i18n';
-import type { TranslateFunction, TranslationNamespace } from '@/i18n';
-import { getTranslation } from '@/i18n/internal';
+// this is required since our storybook manager plugin cannot use vite aliases
+import { i18n } from '../../i18n';
 
-export function useTranslation<TNamespace extends TranslationNamespace | undefined = undefined>(
-  namespace?: TNamespace
-) {
-  const changeLanguage = useStore(translationStore, (store) => store.changeLanguage);
-  const fallbackLanguage = useStore(translationStore, (store) => store.fallbackLanguage);
-  const resolvedLanguage = useStore(translationStore, (store) => store.resolvedLanguage);
-  const translations = useStore(translationStore, (store) => {
-    if (namespace) {
-      return store.translations[namespace];
-    }
-    return store.translations;
-  });
+export function useTranslation(): TranslatorType<TranslationKey>;
+export function useTranslation<TNamespace extends TranslationNamespace>(
+  namespace: TNamespace
+): TranslatorType<TranslationKeyForNamespace<TNamespace>>;
+export function useTranslation(namespace?: TranslationNamespace): TranslatorType<string> {
+  const [resolvedLanguage, setResolvedLanguage] = useState(i18n.resolvedLanguage);
+  const { changeLanguage, t } = useMemo(() => {
+    const t: TranslateFunction<string> = (target, options) => {
+      if (typeof target === 'object') {
+        return i18n.t(target, options);
+      }
+      return i18n.t((namespace ? `${namespace}.${target}` : target) as TranslationKey, options);
+    };
+    return {
+      changeLanguage: i18n.changeLanguage.bind(i18n),
+      t
+    };
+  }, []);
 
-  const t: TranslateFunction<TNamespace> = useCallback(
-    (target, ...args) => {
-      return getTranslation(target, { fallbackLanguage, resolvedLanguage, translations }, ...args);
-    },
-    [fallbackLanguage, resolvedLanguage, translations]
-  );
+  useEffect(() => {
+    i18n.addEventListener('languageChange', setResolvedLanguage);
+    return () => {
+      i18n.removeEventListener('languageChange', setResolvedLanguage);
+    };
+  }, []);
 
-  return { changeLanguage, resolvedLanguage, t };
+  return {
+    changeLanguage,
+    resolvedLanguage,
+    t
+  };
 }

src/i18n/__tests__/translator.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { Translator } from '../translator';
+
+describe('Translator', () => {
+  const translator = new Translator();
+
+  it('should initially not be initialized', () => {
+    expect(translator.isInitialized).toBe(false);
+  });
+
+  it('should not allow accessing the changeLanguage method before initialization', () => {
+    expect(() => translator.changeLanguage('fr')).toThrow(
+      "Cannot access method 'changeLanguage' of Translator instance before initialization"
+    );
+  });
+
+  it('should not allow accessing the resolvedLanguage method before initialization', () => {
+    expect(() => translator.resolvedLanguage).toThrow(
+      "Cannot access getter 'resolvedLanguage' of Translator instance before initialization"
+    );
+  });
+
+  it('should allow initialization', () => {
+    translator.init({ defaultLanguage: 'en', translations: {} });
+    expect(translator.isInitialized).toBe(true);
+  });
+
+  it('should not allow reinitialization', () => {
+    expect(() => translator.init({ defaultLanguage: 'en', translations: {} })).toThrow(
+      'Cannot reinitialize Translator'
+    );
+  });
+
+  it('should have set the document language to en', () => {
+    expect(document.documentElement.getAttribute('lang')).toBe('en');
+  });
+
+  it('should allow accessing translations', () => {
+    expect(translator.t('libui.days.monday')).toBe('Monday');
+    expect(translator.t({ en: 'Yes', fr: 'Oui' })).toBe('Yes');
+  });
+
+  it('should allow changing the language', () => {
+    translator.changeLanguage('fr');
+    expect(translator.resolvedLanguage).toBe('fr');
+    expect(document.documentElement.getAttribute('lang')).toBe('fr');
+    expect(translator.t('libui.days.monday')).toBe('Lundi');
+    expect(translator.t({ en: 'Yes', fr: 'Oui' })).toBe('Oui');
+  });
+
+  it('should return the language from the defaultLanguage, if the resolvedLanguage is unavailable', () => {
+    expect(translator.resolvedLanguage).toBe('fr');
+    expect(translator.t({ en: 'Yes' })).toBe('Yes');
+  });
+
+  it('should return an empty string if no translation is available', () => {
+    vi.spyOn(console, 'error').mockImplementationOnce(() => undefined);
+    expect(translator.t({})).toBe('');
+    expect(console.error).toHaveBeenLastCalledWith("Failed to extract translation from object '{}'");
+    vi.restoreAllMocks();
+  });
+
+  it('should allow adding and removing event listeners', () => {
+    const handleLanguageChange1 = vi.fn();
+    const handleLanguageChange2 = vi.fn();
+    translator.addEventListener('languageChange', handleLanguageChange1);
+    translator.addEventListener('languageChange', handleLanguageChange2);
+    translator.changeLanguage('en');
+    expect(translator.removeEventListener('languageChange', handleLanguageChange1)).toBe(true);
+    translator.changeLanguage('fr');
+    expect(translator.removeEventListener('languageChange', handleLanguageChange2)).toBe(true);
+    expect(handleLanguageChange1).toHaveBeenCalledTimes(1);
+    expect(handleLanguageChange2).toHaveBeenCalledTimes(2);
+  });
+
+  it('should apply arguments', () => {
+    expect(translator.t({ en: 'Hello, {}' }, { args: ['World'] })).toBe('Hello, World');
+    expect(
+      translator.t(
+        { en: 'Hello, {}', fr: 'Bonjour, {}' },
+        {
+          args: {
+            en: ['World'],
+            fr: ['tout le monde']
+          }
+        }
+      )
+    ).toBe('Bonjour, tout le monde');
+  });
+});

src/i18n/index.ts

@@ -1,2 +1,5 @@
-export * from './store.ts';
+import { Translator } from './translator.ts';
+
+export const i18n = new Translator();
+
 export * from './types.ts';

src/i18n/internal.ts

@@ -0,0 +1,129 @@
+import { format } from '@douglasneuroinformatics/libjs';
+import { get } from 'lodash-es';
+import type { SetOptional } from 'type-fest';
+
+import libui from './translations/libui.json';
+
+import type {
+  Language,
+  TranslateFormatArgs,
+  TranslateOptions,
+  TranslationKey,
+  Translations,
+  TranslatorType
+} from './types';
+
+type TranslatorEventMap = {
+  languageChange: (...args: [language: Language]) => void;
+};
+
+type TranslatorConfig = {
+  defaultLanguage?: Language;
+  translations: SetOptional<Translations, 'libui'>;
+};
+
+function InitializedOnly<T extends Translator, TArgs extends any[], TReturn>(
+  target: (this: T, ...args: TArgs) => TReturn,
+  context: ClassGetterDecoratorContext<T> | ClassMethodDecoratorContext<T> | ClassSetterDecoratorContext<T>
+) {
+  const name = context.name.toString();
+  function replacementMethod(this: T, ...args: TArgs): TReturn {
+    if (!this.isInitialized) {
+      throw new Error(`Cannot access ${context.kind} '${name}' of Translator instance before initialization`);
+    }
+    return target.call(this, ...args);
+  }
+  return replacementMethod;
+}
+
+export class Translator implements TranslatorType<TranslationKey> {
+  #config: Required<TranslatorConfig>;
+  #eventHandlers: {
+    [K in keyof TranslatorEventMap]: Set<TranslatorEventMap[K]>;
+  };
+  #resolvedLanguage: Language;
+
+  constructor() {
+    // in the implementation, these should only be accessed in methods decorated with @InitializedOnly
+    this.#config = null!;
+    this.#eventHandlers = {
+      languageChange: new Set()
+    };
+    this.#resolvedLanguage = null!;
+  }
+
+  get isInitialized() {
+    return this.#config !== null;
+  }
+
+  @InitializedOnly
+  get resolvedLanguage() {
+    return this.#resolvedLanguage;
+  }
+
+  addEventListener<TKey extends keyof TranslatorEventMap>(key: TKey, handler: TranslatorEventMap[TKey]) {
+    this.#eventHandlers[key].add(handler);
+  }
+
+  @InitializedOnly
+  changeLanguage(language: Language) {
+    this.#resolvedLanguage = language;
+    document.documentElement.lang = language;
+    this.emitEvent('languageChange', [language]);
+  }
+
+  init({ defaultLanguage, translations }: TranslatorConfig) {
+    if (this.isInitialized) {
+      throw new Error('Cannot reinitialize Translator');
+    }
+    this.#config = {
+      defaultLanguage: defaultLanguage ?? 'en',
+      translations: {
+        libui,
+        ...translations
+      }
+    };
+    this.changeLanguage(this.#config.defaultLanguage);
+  }
+
+  removeEventListener<TKey extends keyof TranslatorEventMap>(key: TKey, handler: TranslatorEventMap[TKey]) {
+    return this.#eventHandlers[key].delete(handler);
+  }
+
+  @InitializedOnly
+  t(target: TranslationKey | { [L in Language]?: string }, { args }: TranslateOptions = {}): string {
+    let obj: { [key: string]: string };
+    if (typeof target === 'string') {
+      obj = (get(this.#config.translations, target) ?? {}) as { [key: string]: string };
+    } else {
+      obj = target;
+    }
+    const value = obj[this.#resolvedLanguage] ?? obj[this.#config.defaultLanguage];
+    if (!value) {
+      console.error(`Failed to extract translation from object '${JSON.stringify(obj)}'`);
+      return '';
+    }
+    if (!args) {
+      return value;
+    }
+    return format(value, ...this.getFormatArgs(args));
+  }
+
+  private emitEvent<TKey extends keyof TranslatorEventMap>(key: TKey, payload: Parameters<TranslatorEventMap[TKey]>) {
+    this.#eventHandlers[key].forEach((fn: (...args: any[]) => any) => {
+      fn(...payload);
+    });
+  }
+
+  private getFormatArgs(args: TranslateFormatArgs) {
+    if (Array.isArray(args)) {
+      return args;
+    }
+    const result = args[this.#resolvedLanguage] ?? args[this.#config.defaultLanguage];
+    if (!result) {
+      console.error(`Failed to extract args from object '${JSON.stringify(args)}'`);
+      return [];
+    }
+    return result;
+  }
+}