@openmrs/esm-implementer-tools-app 11.0.1-pre.6000 → 11.0.1-pre.6010

package/src/translations/translation-catalog.test.ts

@@ -0,0 +1,306 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import i18next from 'i18next';
+import { useSession } from '@openmrs/esm-framework';
+import { implementerToolsConfigStore } from '@openmrs/esm-framework/src/internal';
+import {
+  findOverrideSource,
+  flattenBundle,
+  getLoadedNamespaces,
+  loadTranslationLanguage,
+  loadTranslationNamespace,
+  useTranslationEntries,
+  useTranslationLanguages,
+} from './translation-catalog';
+
+vi.mock('../hooks', () => ({ useFrontendModules: () => [] }));
+
+describe('flattenBundle', () => {
+  it('keeps the top-level string entries', () => {
+    expect(flattenBundle({ loginButton: 'Log in', locationsHeader: 'Locations' })).toEqual({
+      loginButton: 'Log in',
+      locationsHeader: 'Locations',
+    });
+  });
+
+  it('leaves out a nested entry, which could be listed but never overridden', () => {
+    // An override is written at the literal path given, while i18next resolves `errors.required` by
+    // walking `errors` then `required`, so editing one here could never take effect.
+    expect(flattenBundle({ loginButton: 'Log in', errors: { required: 'Required' } })).toEqual({
+      loginButton: 'Log in',
+    });
+  });
+
+  it('drops leaves that an override could not represent', () => {
+    expect(flattenBundle({ ok: 'Fine', list: ['a', 'b'], count: 3 })).toEqual({ ok: 'Fine' });
+  });
+
+  it('tolerates a missing bundle', () => {
+    expect(flattenBundle(undefined)).toEqual({});
+  });
+});
+
+describe('getLoadedNamespaces', () => {
+  it('lists the loaded namespaces, hiding extension-scoped ones', () => {
+    window.i18next = {
+      ...window.i18next,
+      store: {
+        data: {
+          en: {
+            core: {},
+            '@openmrs/esm-login-app': {},
+            '@openmrs/esm-login-app___some-slot___some-extension': {},
+          },
+        },
+      },
+    } as unknown as typeof window.i18next;
+
+    expect(getLoadedNamespaces('en')).toEqual(['core', '@openmrs/esm-login-app']);
+  });
+
+  it('returns nothing for a language with no resources', () => {
+    expect(getLoadedNamespaces('km')).toEqual([]);
+  });
+});
+
+describe('findOverrideSource', () => {
+  const overrides = {
+    en: {
+      loginButton: { _value: 'Sign in', _source: 'temporary config' },
+    },
+  };
+
+  it('reports the config an override came from', () => {
+    expect(findOverrideSource(overrides, 'en', 'loginButton')).toBe('temporary config');
+  });
+
+  it('reports nothing for a key, language, or namespace that is not overridden', () => {
+    expect(findOverrideSource(overrides, 'en', 'locationsHeader')).toBeUndefined();
+    expect(findOverrideSource(overrides, 'km', 'loginButton')).toBeUndefined();
+    expect(findOverrideSource(undefined, 'en', 'loginButton')).toBeUndefined();
+  });
+
+  it('ignores the schema’s own default, which is not a per-key leaf', () => {
+    expect(findOverrideSource({ _value: {}, _source: 'default' }, 'en', 'loginButton')).toBeUndefined();
+  });
+});
+
+describe('loadTranslationNamespace', () => {
+  it('also loads the fallback languages the namespace is missing, which the table lists keys from', async () => {
+    const loaded = new Set(['en']);
+    const reloadResources = vi.fn((lngs: Array<string>, _ns: Array<string>, done: () => void) => {
+      lngs.forEach((lng) => loaded.add(lng));
+      done();
+    });
+    window.i18next = {
+      ...window.i18next,
+      reloadResources,
+      hasResourceBundle: (lng: string) => loaded.has(lng),
+      services: { languageUtils: { toResolveHierarchy: () => ['fr-CA', 'fr', 'en'] } },
+    } as unknown as typeof window.i18next;
+
+    await loadTranslationNamespace('@openmrs/esm-login-app', 'fr-CA');
+
+    // `en` is already loaded; `fr-CA` is always fetched, since it is the language being browsed.
+    expect(reloadResources).toHaveBeenCalledWith(['fr-CA', 'fr'], ['@openmrs/esm-login-app'], expect.any(Function));
+  });
+
+  describe('with i18next’s record of each load', () => {
+    const namespace = '@openmrs/esm-login-app';
+    let state: Record<string, number>;
+    let loaded: Set<string>;
+
+    beforeEach(() => {
+      state = {};
+      loaded = new Set();
+      window.i18next = {
+        ...window.i18next,
+        hasResourceBundle: (lng: string, ns: string) => loaded.has(`${lng}|${ns}`),
+        services: { backendConnector: { state }, languageUtils: { toResolveHierarchy: () => ['en'] } },
+      } as unknown as typeof window.i18next;
+    });
+
+    it('retries a namespace that failed before, which i18next would otherwise skip', async () => {
+      state[`en|${namespace}`] = -1;
+      window.i18next.reloadResources = vi.fn((_lngs, _ns, done) => {
+        // i18next skips a pair still marked failed, so the load only happens if the mark was cleared.
+        if (state[`en|${namespace}`] >= 0) {
+          state[`en|${namespace}`] = 2;
+          loaded.add(`en|${namespace}`);
+        }
+        done?.();
+      }) as unknown as typeof window.i18next.reloadResources;
+
+      await expect(loadTranslationNamespace(namespace, 'en')).resolves.toBeUndefined();
+    });
+
+    it('reports a load that failed even though i18next called back without an error', async () => {
+      window.i18next.reloadResources = vi.fn((_lngs, _ns, done) => {
+        state[`en|${namespace}`] = -1;
+        done?.();
+      }) as unknown as typeof window.i18next.reloadResources;
+
+      await expect(loadTranslationNamespace(namespace, 'en')).rejects.toThrow(/failed; try again/);
+    });
+
+    it('ignores an error from another namespace’s load', async () => {
+      window.i18next.reloadResources = vi.fn((_lngs, _ns, done) => {
+        state[`en|${namespace}`] = 2;
+        loaded.add(`en|${namespace}`);
+        done?.([new Error('core failed')]);
+      }) as unknown as typeof window.i18next.reloadResources;
+
+      await expect(loadTranslationNamespace(namespace, 'en')).resolves.toBeUndefined();
+    });
+
+    describe('when a read never finishes', () => {
+      beforeEach(() => vi.useFakeTimers());
+      afterEach(() => vi.useRealTimers());
+
+      it('gives up, and lets the next attempt start a read of its own', async () => {
+        window.i18next.reloadResources = vi.fn(() => {
+          state[`en|${namespace}`] = 1;
+        }) as unknown as typeof window.i18next.reloadResources;
+
+        const hung = loadTranslationNamespace(namespace, 'en');
+        const assertion = expect(hung).rejects.toThrow(/did not finish/);
+        await vi.advanceTimersByTimeAsync(15_000);
+        await assertion;
+
+        // Left marked as loading, i18next would attach the next attempt to the read that never ended.
+        expect(state[`en|${namespace}`]).toBeUndefined();
+      });
+
+      it('gives up on loading a language whose namespace read hangs', async () => {
+        loaded.add(`fr|${namespace}`);
+        window.i18next.languages = ['fr'];
+        window.i18next.store = { data: { fr: { [namespace]: {} } } } as unknown as typeof window.i18next.store;
+        window.i18next.reloadResources = vi.fn(() => {
+          state[`de|${namespace}`] = 1;
+        }) as unknown as typeof window.i18next.reloadResources;
+
+        const hung = loadTranslationLanguage('de');
+        const assertion = expect(hung).rejects.toThrow(/did not finish/);
+        await vi.advanceTimersByTimeAsync(15_000);
+        await assertion;
+      });
+    });
+  });
+});
+
+describe('useTranslationEntries', () => {
+  async function setUpI18next(lng: string, resources: Record<string, Record<string, Record<string, string>>>) {
+    const i18n = i18next.createInstance();
+    await i18n.init({ lng, fallbackLng: 'en', nsSeparator: false, resources });
+    window.i18next = i18n as unknown as typeof window.i18next;
+    implementerToolsConfigStore.setState({ config: {} });
+    return i18n;
+  }
+
+  it('lists every plural form the selected language renders through, even ones no bundle has', async () => {
+    const i18n = await setUpI18next('ar', {
+      en: { mod: { items_one: '{{count}} item', items_other: '{{count}} items' } },
+      ar: { mod: {} },
+    });
+
+    const { result } = renderHook(() => useTranslationEntries(['mod'], 'ar'));
+    const listed = result.current.filter((entry) => entry.key.startsWith('items_')).map((entry) => entry.key);
+
+    // Overriding every listed form must change what Arabic renders for any count.
+    i18n.addResourceBundle('ar', 'mod', Object.fromEntries(listed.map((key) => [key, 'AR'])), true, true);
+
+    for (const count of [0, 1, 2, 3, 11, 100]) {
+      expect(i18n.t('items', { ns: 'mod', lng: 'ar', count })).toBe('AR');
+    }
+  });
+
+  it('recomputes for bundles it lists, but not for other namespaces or languages', async () => {
+    const i18n = await setUpI18next('fr', { en: { mod: { save: 'Save' } }, fr: { mod: {} } });
+
+    const { result } = renderHook(() => useTranslationEntries(['mod'], 'fr'));
+    const initial = result.current;
+
+    act(() => {
+      i18n.addResourceBundle('fr', 'mod___slot___extension', { save: 'Ext' });
+      i18n.addResourceBundle('de', 'mod', { save: 'Speichern' });
+      i18n.addResourceBundle('fr', 'other', { save: 'Autre' });
+    });
+    expect(result.current).toBe(initial);
+
+    act(() => i18n.addResourceBundle('en', 'mod', { cancel: 'Cancel' }, true));
+    expect(result.current.map((entry) => entry.key)).toEqual(['cancel', 'save']);
+  });
+
+  it('points a base key at the plural forms of the selected language', async () => {
+    await setUpI18next('ar', {
+      en: { mod: { items: 'Items', items_one: '{{count}} item', items_other: '{{count}} items' } },
+    });
+
+    const { result } = renderHook(() => useTranslationEntries(['mod'], 'ar'));
+
+    expect(result.current.find((entry) => entry.key === 'items')?.pluralForms).toEqual([
+      'items_zero',
+      'items_one',
+      'items_two',
+      'items_few',
+      'items_many',
+      'items_other',
+    ]);
+  });
+
+  it('reads a key named like a built-in object property from the bundle that has it', async () => {
+    await setUpI18next('fr', {
+      fr: { mod: { save: 'Enregistrer' } },
+      en: { mod: { save: 'Save', toString: 'Convert to text' } },
+    });
+
+    const { result } = renderHook(() => useTranslationEntries(['mod'], 'fr'));
+    const entry = result.current.find((candidate) => candidate.key === 'toString');
+
+    expect(entry?.value).toBe('Convert to text');
+    expect(entry?.sourceLanguage).toBe('en');
+  });
+
+  it('attributes a value shown from a fallback language to the override that supplies it', async () => {
+    // The backend merges the en override into the en bundle; fr has no value for the key.
+    await setUpI18next('fr', { en: { mod: { greeting: 'Overridden hello' } }, fr: { mod: {} } });
+    implementerToolsConfigStore.setState({
+      config: {
+        mod: {
+          'Translation overrides': {
+            en: { greeting: { _value: 'Overridden hello', _source: 'temporary config' } },
+          },
+        },
+      },
+    });
+
+    const { result } = renderHook(() => useTranslationEntries(['mod'], 'fr'));
+
+    expect(result.current).toEqual([
+      expect.objectContaining({
+        key: 'greeting',
+        value: 'Overridden hello',
+        sourceLanguage: 'en',
+        overrideSource: 'temporary config',
+      }),
+    ]);
+  });
+});
+
+describe('useTranslationLanguages', () => {
+  it('offers each server locale as the language i18next runs it as', async () => {
+    const i18n = i18next.createInstance();
+    await i18n.init({ lng: 'en', fallbackLng: 'en', resources: { en: { mod: {} } } });
+    window.i18next = i18n as unknown as typeof window.i18next;
+    vi.mocked(useSession).mockReturnValue({
+      authenticated: true,
+      sessionId: '',
+      allowedLocales: ['en', 'en_us', 'sw_KE', 'uz@Latn'],
+    } as ReturnType<typeof useSession>);
+
+    const { result } = renderHook(() => useTranslationLanguages('en'));
+
+    // `uz@Latn` keeps its modifier: overrides keyed `uz-Latn` would never be read.
+    expect(result.current).toEqual(['en', 'en-US', 'sw-KE', 'uz@Latn']);
+  });
+});

package/src/translations/translation-catalog.ts

@@ -0,0 +1,302 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { useSession } from '@openmrs/esm-framework';
+import {
+  extensionNamespaceSeparator,
+  implementerToolsConfigStore,
+  useStore,
+} from '@openmrs/esm-framework/src/internal';
+import { useFrontendModules } from '../hooks';
+import { clearFailedLoads, findLoadFailure, releaseStalledLoads, withTimeout } from './i18next-loads';
+
+/** The namespace holding the framework's own translations. It belongs to no frontend module. */
+export const coreNamespace = 'core';
+
+/** The reserved config property through which translations are overridden. */
+export const translationOverridesKey = 'Translation overrides';
+
+/**
+ * The `_source` the config system attributes to values set through the implementer tools. Only those
+ * can be reset from here; anything else comes from a config the distribution supplies.
+ */
+export const temporaryConfigSource = 'temporary config';
+
+export interface TranslationNamespace {
+  name: string;
+  /** Whether i18next holds resources for this namespace, in which case its keys are browsable. */
+  isLoaded: boolean;
+}
+
+export interface TranslationEntry {
+  namespace: string;
+  key: string;
+  /** The value i18next holds for the key, before interpolation. An override, where one applies. */
+  value: string;
+  /**
+   * The name of the config that supplies an override for this key in `sourceLanguage`, if any.
+   * `undefined` means the value comes from the namespace's translation file.
+   */
+  overrideSource?: string;
+  /**
+   * The language the value was actually read from. It differs from the selected one when the key is
+   * missing from that language's bundle and i18next would fall back, which an implementer needs to
+   * see before treating the value as the text they are overriding.
+   */
+  sourceLanguage: string;
+  /**
+   * The plural forms the selected language renders this key through, when the key has any. i18next
+   * prefers a suffixed form over the base key, so overriding the base alone leaves these untouched.
+   */
+  pluralForms: Array<string>;
+}
+
+/**
+ * The plural categories i18next suffixes a key with. Context variants (`_male` and the like) are not
+ * guessed at: the suffix is arbitrary application data, so detecting one would report unrelated keys
+ * as variants of each other.
+ */
+const pluralSuffixes = ['zero', 'one', 'two', 'few', 'many', 'other'];
+
+const pluralFormPattern = new RegExp(`^(.+)_(${pluralSuffixes.join('|')})$`);
+
+/** The key a plural form belongs to, such as `items` for `items_few`. */
+function getPluralBase(key: string): string | undefined {
+  return pluralFormPattern.exec(key)?.[1];
+}
+
+/**
+ * Lists the namespaces whose translations can be browsed: everything i18next has loaded, plus every
+ * installed frontend module, so that a module the user has not visited yet can still be loaded on
+ * demand via `loadTranslationNamespace`.
+ */
+export function useTranslationNamespaces(language: string): Array<TranslationNamespace> {
+  const frontendModules = useFrontendModules();
+  const revision = useI18nextRevision(
+    (lng, namespace) => lng === language && !namespace.includes(extensionNamespaceSeparator),
+  );
+
+  return useMemo(() => {
+    const loaded = getLoadedNamespaces(language);
+    const names = new Set([coreNamespace, ...frontendModules.map((module) => module.name), ...loaded]);
+
+    return Array.from(names)
+      .sort((a, b) => a.localeCompare(b))
+      .map((name) => ({ name, isLoaded: loaded.includes(name) }));
+  }, [frontendModules, language, revision]);
+}
+
+/**
+ * Builds the browsable list of translations for the given namespaces and language.
+ *
+ * Keys are collected across i18next's whole language resolution hierarchy rather than from the
+ * selected language alone: a key that only exists in the fallback language still renders in the UI,
+ * and is still something an implementer needs to be able to override for their own language. For
+ * the same reason, every plural form the selected language needs is listed, even one no bundle has.
+ */
+export function useTranslationEntries(namespaces: Array<string>, language: string): Array<TranslationEntry> {
+  const { config } = useStore(implementerToolsConfigStore);
+  const revision = useI18nextRevision(
+    (lng, namespace) => namespaces.includes(namespace) && getResolutionHierarchy(language).includes(lng),
+  );
+
+  return useMemo(() => {
+    const languages = getResolutionHierarchy(language);
+    const pluralFormSuffixes = window.i18next?.services?.pluralResolver?.getSuffixes?.(language) ?? [];
+
+    return namespaces.flatMap((namespace) => {
+      const bundles = languages.map((lng) => flattenBundle(window.i18next?.store?.data?.[lng]?.[namespace]));
+      const bundleKeys = new Set(bundles.flatMap((bundle) => Object.keys(bundle)));
+      const pluralKeys = new Set(Array.from(bundleKeys, getPluralBase).filter((base) => base !== undefined));
+      const getPluralForms = (key: string) =>
+        pluralKeys.has(key) ? pluralFormSuffixes.map((suffix) => `${key}${suffix}`) : [];
+      const keys = Array.from(new Set([...bundleKeys, ...Array.from(pluralKeys).flatMap(getPluralForms)])).sort(
+        (a, b) => a.localeCompare(b),
+      );
+      const overrides = config?.[namespace]?.[translationOverridesKey];
+
+      return keys.map((key) => {
+        const source = bundles.findIndex((bundle) => Object.hasOwn(bundle, key));
+        const sourceLanguage = languages[source === -1 ? 0 : source];
+
+        return {
+          namespace,
+          key,
+          value: source === -1 ? '' : bundles[source][key],
+          sourceLanguage,
+          overrideSource: findOverrideSource(overrides, sourceLanguage, key),
+          pluralForms: getPluralForms(key),
+        };
+      });
+    });
+  }, [config, namespaces, language, revision]);
+}
+
+/**
+ * Loads a namespace's resources for the language being browsed, and for any of its fallback
+ * languages not loaded yet, since the table also lists the keys only a fallback language has.
+ *
+ * `reloadResources` rather than `loadNamespaces` because the latter fetches for i18next's active
+ * language, which is not necessarily the one selected here.
+ */
+export function loadTranslationNamespace(namespace: string, language: string): Promise<void> {
+  const languages = getResolutionHierarchy(language).filter(
+    (candidate) => candidate === language || !window.i18next.hasResourceBundle(candidate, namespace),
+  );
+
+  clearFailedLoads(languages, [namespace]);
+
+  return withTimeout(
+    new Promise<void>((resolve, reject) => {
+      const done = (error?: unknown) => {
+        const failure = findLoadFailure(languages, [namespace], error);
+        return failure ? reject(failure) : resolve();
+      };
+
+      // i18next declares this callback as taking no arguments but calls it with the load error.
+      // It expands a language into its fallbacks only when given a single string, so they are listed.
+      window.i18next.reloadResources(languages, [namespace], done as () => void);
+    }),
+    `Loading ${namespace} for ${language} did not finish`,
+  ).catch((error) => {
+    releaseStalledLoads(languages, [namespace]);
+    throw error;
+  });
+}
+
+/**
+ * The languages an implementer can author overrides for: every locale the server permits, plus
+ * anything i18next has already loaded, plus whatever is currently selected.
+ *
+ * The server's list is the authoritative one, and it is what makes a locale the user is not running
+ * in reachable at all. Each locale is listed as the language i18next runs it as, which is the key its
+ * `Translation overrides` are read under.
+ */
+export function useTranslationLanguages(selectedLanguage: string): Array<string> {
+  const session = useSession();
+  const revision = useI18nextRevision();
+
+  return useMemo(() => {
+    // As `setUserLanguage` does, then normalised as i18next normalises the language it runs in.
+    const allowed = (session?.allowedLocales ?? []).map((locale) => {
+      const language = locale.replaceAll('_', '-');
+      return window.i18next?.services?.languageUtils?.formatLanguageCode?.(language) ?? language;
+    });
+
+    return Array.from(new Set([...allowed, ...getLoadedLanguages(), selectedLanguage])).sort((a, b) =>
+      a.localeCompare(b),
+    );
+  }, [revision, selectedLanguage, session]);
+}
+
+/** The languages i18next currently holds resources for. */
+export function getLoadedLanguages(): Array<string> {
+  return Object.keys(window.i18next?.store?.data ?? {});
+}
+
+/**
+ * Fetches, for a language the application is not running in, the namespaces the application has
+ * loaded, which is what lets an implementer browse and override a locale other than their own.
+ *
+ * Not `loadLanguages`: it also requests i18next's default `translation` namespace, which the app
+ * shell refuses, so it always reports a failure; and it adds the language to `preload`, so every
+ * namespace the application loads afterwards is fetched in that language too.
+ */
+export async function loadTranslationLanguage(language: string): Promise<void> {
+  const namespaces = new Set((window.i18next.languages ?? []).flatMap((running) => getLoadedNamespaces(running)));
+
+  await Promise.all(Array.from(namespaces, (namespace) => loadTranslationNamespace(namespace, language)));
+}
+
+export function getLoadedNamespaces(language: string): Array<string> {
+  return Object.keys(window.i18next?.store?.data?.[language] ?? {}).filter(
+    (namespace) => !namespace.includes(extensionNamespaceSeparator),
+  );
+}
+
+/**
+ * The top-level string entries of a resource bundle.
+ *
+ * Nested entries are left out rather than flattened to `a.b`. An override is written at the literal
+ * path it is given, and i18next resolves `a.b` by walking `a` then `b` before ever looking for a
+ * flat key of that name, so a nested key could be listed and edited here but never actually
+ * overridden — offering an action that silently does nothing is worse than not listing it. O3's
+ * translation files are flat, so nothing is hidden in practice.
+ */
+export function flattenBundle(bundle: unknown): Record<string, string> {
+  if (!bundle || typeof bundle !== 'object') {
+    return {};
+  }
+
+  return Object.entries(bundle).reduce<Record<string, string>>((result, [key, value]) => {
+    if (typeof value === 'string') {
+      result[key] = value;
+    }
+
+    return result;
+  }, {});
+}
+
+/**
+ * Reports which config supplies an override for a key, or `undefined` if none does.
+ *
+ * The implementer tools config is a tree of `_value`/`_source` leaves. The config system builds
+ * that tree by recursing through every provided config, so an override always appears as a leaf at
+ * `[language][key]`, whether it came from a distribution's config file or from an edit made here.
+ */
+export function findOverrideSource(overrides: unknown, language: string, key: string): string | undefined {
+  const languageNode = isRecord(overrides) ? overrides[language] : undefined;
+  const leaf = isRecord(languageNode) ? languageNode[key] : undefined;
+  const source = isRecord(leaf) && '_value' in leaf ? leaf._source : undefined;
+
+  return typeof source === 'string' ? source : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object';
+}
+
+/**
+ * The languages i18next would consult for the one being browsed, so a key it would resolve from a
+ * fallback is listed with the value it would actually render. `i18next.languages` is not that: it is
+ * the chain for whichever language the application is running in, so browsing `es` from a French app
+ * would otherwise attribute French values to Spanish.
+ */
+function getResolutionHierarchy(language: string): Array<string> {
+  const resolved = window.i18next?.services?.languageUtils?.toResolveHierarchy?.(language) ?? [];
+  return Array.from(new Set([language, ...resolved]));
+}
+
+/**
+ * Bumps a counter whenever i18next's resources change, giving the catalog a dependency it can
+ * recompute on. i18next's resource store is not a zustand store, so it can't be read with
+ * `useStore`.
+ *
+ * @param isRelevant Limits the bumps to the bundles a caller shows, so that loads elsewhere, such as
+ *   an extension's namespace or another language, don't make it recompute. Reads the latest one
+ *   passed, so it need not be memoised.
+ */
+function useI18nextRevision(isRelevant: (language: string, namespace: string) => boolean = () => true): number {
+  const [revision, setRevision] = useState(0);
+  const isRelevantRef = useRef(isRelevant);
+  isRelevantRef.current = isRelevant;
+
+  useEffect(() => {
+    const store = window.i18next?.store;
+    if (typeof store?.on !== 'function') {
+      return;
+    }
+
+    const bump = (language: string, namespace: string) => {
+      if (isRelevantRef.current(language, namespace)) {
+        setRevision((current) => current + 1);
+      }
+    };
+    // Only `added`: nothing in this feature removes a bundle, so `removed` would never fire anyway.
+    store.on('added', bump);
+
+    return () => {
+      store.off('added', bump);
+    };
+  }, []);
+
+  return revision;
+}

package/src/translations/translation-exports.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { getLocalEdits, toFileSafeName, toOverrideFile, toTransifexLocale } from './translation-exports';
+
+describe('getLocalEdits', () => {
+  const config = {
+    '@openmrs/esm-login-app': {
+      'Translation overrides': { fr: { loginButton: 'Se connecter', broken: { nested: 'x' } }, en: { other: 'y' } },
+    },
+  };
+
+  it('returns the string overrides for just that namespace and language', () => {
+    expect(getLocalEdits(config, '@openmrs/esm-login-app', 'fr')).toEqual({ loginButton: 'Se connecter' });
+  });
+
+  it('returns nothing where no edits were made', () => {
+    expect(getLocalEdits(config, '@openmrs/esm-login-app', 'ar')).toEqual({});
+    expect(getLocalEdits(config, '@openmrs/esm-other-app', 'fr')).toEqual({});
+    expect(getLocalEdits(undefined, '@openmrs/esm-login-app', 'fr')).toEqual({});
+  });
+});
+
+describe('toOverrideFile', () => {
+  it('nests the edits the way a distribution config takes them', () => {
+    expect(toOverrideFile('core', 'fr', { save: 'Enregistrer' })).toEqual({
+      core: { 'Translation overrides': { fr: { save: 'Enregistrer' } } },
+    });
+  });
+});
+
+describe('toTransifexLocale', () => {
+  it('uses the underscore form the translation files are named with', () => {
+    expect(toTransifexLocale('ar-SY')).toBe('ar_SY');
+    expect(toTransifexLocale('ar')).toBe('ar');
+  });
+});
+
+describe('toFileSafeName', () => {
+  it('drops the scope marker and path separator', () => {
+    expect(toFileSafeName('@openmrs/esm-login-app')).toBe('openmrs-esm-login-app');
+    expect(toFileSafeName('core')).toBe('core');
+  });
+});