@openmrs/esm-implementer-tools-app 11.0.1-pre.6006 → 11.0.1-pre.6014

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

@@ -0,0 +1,473 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import i18next, { type BackendModule } from 'i18next';
+import { temporaryConfigStore } from '@openmrs/esm-framework/src/internal';
+import {
+  findChangedOverrides,
+  reloadTranslations,
+  resetTranslationOverride,
+  setTranslationOverride,
+  watchTranslationOverrides,
+} from './translation-overrides';
+
+const loginApp = '@openmrs/esm-login-app';
+
+const mockReloadResources = vi.fn((_lngs: unknown, _ns: unknown, done?: (error?: unknown) => void) => done?.());
+const mockHasResourceBundle = vi.fn(() => true);
+const connectorState: Record<string, number> = {};
+
+beforeEach(() => {
+  for (const key of Object.keys(connectorState)) {
+    delete connectorState[key];
+  }
+
+  window.i18next = {
+    ...window.i18next,
+    language: 'en',
+    store: { data: { en: { [loginApp]: {} } } },
+    reloadResources: mockReloadResources,
+    hasResourceBundle: mockHasResourceBundle,
+    getResourceBundle: vi.fn(() => ({})),
+    removeResourceBundle: vi.fn(),
+    addResourceBundle: vi.fn(),
+    options: { ns: [] },
+    services: { backendConnector: { state: connectorState } },
+    emit: vi.fn(),
+  } as unknown as typeof window.i18next;
+});
+
+afterEach(() => {
+  temporaryConfigStore.setState({ config: {} });
+});
+
+describe('setTranslationOverride', () => {
+  it('writes the override where the config system expects it', () => {
+    setTranslationOverride(loginApp, 'en', 'loginButton', 'Sign in');
+
+    expect(temporaryConfigStore.getState().config).toEqual({
+      [loginApp]: { 'Translation overrides': { en: { loginButton: 'Sign in' } } },
+    });
+  });
+
+  it('leaves every other pending config edit alone', () => {
+    temporaryConfigStore.setState({
+      config: {
+        '@openmrs/esm-other-app': { someSetting: 'untouched' },
+        [loginApp]: {
+          anotherSetting: 'also untouched',
+          'Translation overrides': {
+            en: { locationsHeader: 'Facilities' },
+            fr: { loginButton: 'Connexion' },
+          },
+        },
+      },
+    });
+
+    setTranslationOverride(loginApp, 'en', 'loginButton', 'Sign in');
+
+    expect(temporaryConfigStore.getState().config).toEqual({
+      '@openmrs/esm-other-app': { someSetting: 'untouched' },
+      [loginApp]: {
+        anotherSetting: 'also untouched',
+        'Translation overrides': {
+          en: { locationsHeader: 'Facilities', loginButton: 'Sign in' },
+          fr: { loginButton: 'Connexion' },
+        },
+      },
+    });
+  });
+
+  it('writes a region-qualified language tag under that tag', () => {
+    setTranslationOverride(loginApp, 'km-KH', 'loginButton', 'ចូល');
+
+    expect(temporaryConfigStore.getState().config[loginApp]['Translation overrides']).toEqual({
+      'km-KH': { loginButton: 'ចូល' },
+    });
+  });
+});
+
+describe('resetTranslationOverride', () => {
+  it('removes one override and keeps its siblings', () => {
+    temporaryConfigStore.setState({
+      config: {
+        [loginApp]: {
+          'Translation overrides': {
+            en: { loginButton: 'Sign in', locationsHeader: 'Facilities' },
+            fr: { loginButton: 'Connexion' },
+          },
+        },
+      },
+    });
+
+    resetTranslationOverride(loginApp, 'en', 'loginButton');
+
+    expect(temporaryConfigStore.getState().config[loginApp]['Translation overrides']).toEqual({
+      en: { locationsHeader: 'Facilities' },
+      fr: { loginButton: 'Connexion' },
+    });
+  });
+
+  it('does nothing for a key that was never overridden', () => {
+    temporaryConfigStore.setState({ config: { [loginApp]: { 'Translation overrides': { en: {} } } } });
+
+    expect(() => resetTranslationOverride(loginApp, 'en', 'loginButton')).not.toThrow();
+    expect(temporaryConfigStore.getState().config).toEqual({
+      [loginApp]: { 'Translation overrides': { en: {} } },
+    });
+  });
+});
+
+describe('reloadTranslations', () => {
+  it('reloads the module and every extension-scoped bundle derived from it', async () => {
+    window.i18next.store.data.en = {
+      [loginApp]: {},
+      [`${loginApp}___some-slot___some-extension`]: {},
+      [`${loginApp}___other-slot___other-extension`]: {},
+      '@openmrs/esm-other-app___slot___ext': {},
+    };
+
+    await reloadTranslations(loginApp, 'en');
+
+    expect(mockReloadResources).toHaveBeenCalledWith(
+      ['en'],
+      [loginApp, `${loginApp}___some-slot___some-extension`, `${loginApp}___other-slot___other-extension`],
+      expect.any(Function),
+    );
+  });
+
+  it('re-renders the application once the reload lands', async () => {
+    await reloadTranslations(loginApp, 'en');
+
+    expect(window.i18next.emit).toHaveBeenCalledWith('languageChanged', 'en');
+  });
+
+  it('reports a reload i18next skipped, even though the old bundle is still there', async () => {
+    // A failed load leaves the previous bundle in place and marks the pair -1, and i18next then
+    // calls back as a success, so an absent bundle is not evidence either way.
+    mockReloadResources.mockImplementationOnce((_lngs, _ns, done) => {
+      connectorState[`en|${loginApp}`] = -1;
+      return done?.();
+    });
+
+    await expect(reloadTranslations(loginApp, 'en')).rejects.toThrow(/try again/);
+    expect(window.i18next.emit).not.toHaveBeenCalled();
+  });
+
+  it('clears a previous failure so the next attempt actually runs', async () => {
+    connectorState[`en|${loginApp}`] = -1;
+
+    await reloadTranslations(loginApp, 'en');
+
+    expect(connectorState[`en|${loginApp}`]).toBe(0);
+    expect(window.i18next.emit).toHaveBeenCalledWith('languageChanged', 'en');
+  });
+
+  it('drops a reset key from the bundle, which a reload alone would leave behind', async () => {
+    // i18next's reload merges over the existing bundle, so a key the fresh payload no longer carries
+    // survives — which is what resetting an override produces for a language whose file lacks it.
+    const bundle: Record<string, string> = { loginButton: 'Sign in', locationsHeader: 'Locations' };
+    window.i18next.getResourceBundle = vi.fn(() => bundle);
+
+    await reloadTranslations(loginApp, 'en', 'loginButton');
+
+    expect(bundle).toEqual({ locationsHeader: 'Locations' });
+  });
+
+  it('leaves the bundle alone when no key is being reset', async () => {
+    const bundle: Record<string, string> = { loginButton: 'Sign in' };
+    window.i18next.getResourceBundle = vi.fn(() => bundle);
+
+    await reloadTranslations(loginApp, 'en');
+
+    expect(bundle).toEqual({ loginButton: 'Sign in' });
+  });
+
+  it('reports a reload that quietly did nothing rather than reporting success', async () => {
+    // i18next skips a language/namespace pair whose first load failed and calls back as though it
+    // had reloaded it, so an absent bundle is the only evidence the reload did nothing.
+    mockHasResourceBundle.mockReturnValue(false);
+
+    await expect(reloadTranslations(loginApp, 'en')).rejects.toThrow(/holds no/);
+    expect(window.i18next.emit).not.toHaveBeenCalled();
+  });
+
+  it('reports a failed reload rather than reporting success', async () => {
+    mockReloadResources.mockImplementationOnce((_lngs, _ns, done) => {
+      connectorState[`en|${loginApp}`] = -1;
+      return done?.(new Error('chunk 404'));
+    });
+
+    await expect(reloadTranslations(loginApp, 'en')).rejects.toThrow('chunk 404');
+    expect(window.i18next.emit).not.toHaveBeenCalled();
+  });
+
+  it('does not fail over a load error that belongs to another namespace', async () => {
+    // i18next hands every waiting request every load error, whichever pair it came from.
+    mockReloadResources.mockImplementationOnce((_lngs, _ns, done) => {
+      connectorState['en|core'] = -1;
+      return done?.([new Error('core failed')]);
+    });
+
+    await expect(reloadTranslations(loginApp, 'en')).resolves.toBeUndefined();
+    expect(window.i18next.emit).toHaveBeenCalledWith('languageChanged', 'en');
+  });
+
+  it('reports a failure in an extension-scoped bundle reloaded alongside the module', async () => {
+    const extension = `${loginApp}___some-slot___some-extension`;
+    window.i18next.store.data.en = { [loginApp]: {}, [extension]: {} };
+    mockReloadResources.mockImplementationOnce((_lngs, _ns, done) => {
+      connectorState[`en|${extension}`] = -1;
+      return done?.();
+    });
+
+    await expect(reloadTranslations(loginApp, 'en')).rejects.toThrow(extension);
+    expect(window.i18next.emit).not.toHaveBeenCalled();
+  });
+
+  it('drops a reset key from the extension-scoped bundles too', async () => {
+    const extension = `${loginApp}___some-slot___some-extension`;
+    const bundles: Record<string, Record<string, string>> = {
+      [loginApp]: { loginButton: 'Sign in' },
+      [extension]: { loginButton: 'Sign in', other: 'kept' },
+    };
+    window.i18next.store.data.en = { [loginApp]: {}, [extension]: {} };
+    window.i18next.getResourceBundle = vi.fn((_lng: string, ns: string) => bundles[ns]);
+
+    await reloadTranslations(loginApp, 'en', 'loginButton');
+
+    expect(bundles).toEqual({ [loginApp]: {}, [extension]: { other: 'kept' } });
+  });
+
+  describe('when a read never finishes', () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+
+    it('gives up, and lets the next save start a read of its own', async () => {
+      mockReloadResources.mockImplementationOnce(() => {
+        connectorState[`en|${loginApp}`] = 1;
+      });
+
+      const hung = reloadTranslations(loginApp, '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 request to the read that never ended.
+      expect(connectorState[`en|${loginApp}`]).toBeUndefined();
+
+      const next = reloadTranslations(loginApp, 'en');
+      await vi.advanceTimersByTimeAsync(0);
+
+      await expect(next).resolves.toBeUndefined();
+      expect(mockReloadResources).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not reload later for a save that already timed out waiting on an earlier read', async () => {
+      const listeners = new Set<() => void>();
+      Object.assign(window.i18next.services.backendConnector, {
+        on: (_event: string, listener: () => void) => listeners.add(listener),
+        off: (_event: string, listener: () => void) => listeners.delete(listener),
+      });
+      connectorState[`en|${loginApp}`] = 1;
+
+      const hung = reloadTranslations(loginApp, 'en');
+      const assertion = expect(hung).rejects.toThrow(/did not finish/);
+      await vi.advanceTimersByTimeAsync(15_000);
+      await assertion;
+
+      // Some other namespace finishing its load.
+      listeners.forEach((listener) => listener());
+      await vi.advanceTimersByTimeAsync(0);
+
+      expect(mockReloadResources).not.toHaveBeenCalled();
+      expect(listeners.size).toBe(0);
+    });
+  });
+});
+
+describe('findChangedOverrides', () => {
+  const overrides = (byLanguage: Record<string, Record<string, string>>) => ({
+    [loginApp]: { 'Translation overrides': byLanguage },
+  });
+
+  it('reports the languages whose overrides changed, with the keys that were removed', () => {
+    const previous = overrides({ en: { loginButton: 'Sign in', other: 'Kept' }, fr: { loginButton: 'Connexion' } });
+    const next = overrides({ en: { other: 'Kept' }, fr: { loginButton: 'Connexion' } });
+
+    expect(findChangedOverrides(previous, next)).toEqual([
+      { namespace: loginApp, language: 'en', droppedKeys: ['loginButton'] },
+    ]);
+  });
+
+  it('reports every override when the whole config is cleared', () => {
+    expect(findChangedOverrides(overrides({ en: { loginButton: 'Sign in' } }), {})).toEqual([
+      { namespace: loginApp, language: 'en', droppedKeys: ['loginButton'] },
+    ]);
+  });
+
+  it('reports an added or changed override without dropping anything', () => {
+    expect(
+      findChangedOverrides(overrides({ en: { loginButton: 'Sign in' } }), overrides({ en: { loginButton: 'Enter' } })),
+    ).toEqual([{ namespace: loginApp, language: 'en', droppedKeys: [] }]);
+  });
+
+  it('ignores config changes that leave the overrides alone', () => {
+    expect(findChangedOverrides({ [loginApp]: { someSetting: 1 } }, { [loginApp]: { someSetting: 2 } })).toEqual([]);
+  });
+});
+
+describe('watchTranslationOverrides', () => {
+  let stop: () => void;
+
+  beforeEach(() => {
+    stop = watchTranslationOverrides();
+  });
+
+  afterEach(() => {
+    stop();
+  });
+
+  it('reloads a loaded namespace whose override is removed from outside the Translations tab', async () => {
+    const bundle = { loginButton: 'Sign in' };
+    vi.mocked(window.i18next.getResourceBundle).mockReturnValue(bundle);
+    temporaryConfigStore.setState({ config: { [loginApp]: { 'Translation overrides': { en: bundle } } } });
+    mockReloadResources.mockClear();
+
+    temporaryConfigStore.setState({ config: {} });
+    await vi.waitFor(() => expect(mockReloadResources).toHaveBeenCalledWith(['en'], [loginApp], expect.any(Function)));
+
+    expect(bundle).toEqual({});
+  });
+
+  it('leaves the reload to the caller of setTranslationOverride and resetTranslationOverride', async () => {
+    setTranslationOverride(loginApp, 'en', 'loginButton', 'Sign in');
+    resetTranslationOverride(loginApp, 'en', 'loginButton');
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(mockReloadResources).not.toHaveBeenCalled();
+  });
+
+  it('does not load a namespace that is not on screen', async () => {
+    mockHasResourceBundle.mockReturnValueOnce(false);
+    temporaryConfigStore.setState({
+      config: { '@openmrs/esm-other-app': { 'Translation overrides': { en: { title: 'Other' } } } },
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(mockReloadResources).not.toHaveBeenCalled();
+  });
+});
+
+describe('reloadTranslations against i18next', () => {
+  /** Reads that have started, each settled by calling it. Overrides are collected as a read starts. */
+  let pendingReads: Array<(error?: Error) => void>;
+  let i18n: ReturnType<typeof i18next.createInstance>;
+
+  beforeEach(async () => {
+    pendingReads = [];
+
+    const backend: BackendModule = {
+      type: 'backend',
+      init() {},
+      read(language, namespace, callback) {
+        // Like the app shell, an extension-scoped namespace takes its module's overrides.
+        const moduleName = namespace.split('___')[0];
+        const overrides =
+          temporaryConfigStore.getState().config?.[moduleName]?.['Translation overrides']?.[language] ?? {};
+        pendingReads.push((error) =>
+          error ? callback(error, null) : callback(null, { loginButton: 'Log in', ...overrides }),
+        );
+      },
+    };
+
+    i18n = i18next.createInstance();
+    await i18n.use(backend).init({ lng: 'en', fallbackLng: 'en', ns: [], initAsync: false });
+    i18n.addResourceBundle('en', loginApp, { loginButton: 'Log in' });
+    window.i18next = i18n as unknown as typeof window.i18next;
+  });
+
+  /** Settles every read, including those started in response to an earlier one settling. */
+  async function settleReads() {
+    let settled: Array<() => void>;
+
+    do {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      settled = pendingReads.splice(0);
+      settled.forEach((settle) => settle());
+    } while (settled.length > 0);
+  }
+
+  it('applies an override saved while the application is already reading the namespace', async () => {
+    i18n.reloadResources(['en'], [loginApp]);
+    expect(pendingReads).toHaveLength(1);
+
+    setTranslationOverride(loginApp, 'en', 'loginButton', 'Sign in');
+    const saved = reloadTranslations(loginApp, 'en');
+    await settleReads();
+
+    await expect(saved).resolves.toBeUndefined();
+    expect(i18n.getResource('en', loginApp, 'loginButton')).toBe('Sign in');
+  });
+
+  it('applies both of two saves made in quick succession', async () => {
+    setTranslationOverride(loginApp, 'en', 'loginButton', 'Sign in');
+    const first = reloadTranslations(loginApp, 'en');
+    setTranslationOverride(loginApp, 'en', 'locationsHeader', 'Facilities');
+    const second = reloadTranslations(loginApp, 'en');
+    await settleReads();
+
+    await Promise.all([first, second]);
+    expect(i18n.getResource('en', loginApp, 'locationsHeader')).toBe('Facilities');
+  });
+
+  it('still applies a save made while an earlier read fails', async () => {
+    i18n.reloadResources(['en'], [loginApp]);
+    setTranslationOverride(loginApp, 'en', 'loginButton', 'Sign in');
+    const saved = reloadTranslations(loginApp, 'en');
+
+    pendingReads.shift()?.(new Error('chunk 404'));
+    await settleReads();
+
+    await expect(saved).resolves.toBeUndefined();
+    expect(i18n.getResource('en', loginApp, 'loginButton')).toBe('Sign in');
+  });
+
+  it('applies an override to an extension whose first read is still in flight', async () => {
+    const extension = `${loginApp}___some-slot___some-extension`;
+    i18n.reloadResources(['en'], [extension]);
+
+    setTranslationOverride(loginApp, 'en', 'loginButton', 'Sign in');
+    const saved = reloadTranslations(loginApp, 'en');
+    await settleReads();
+
+    await expect(saved).resolves.toBeUndefined();
+    expect(i18n.getResource('en', extension, 'loginButton')).toBe('Sign in');
+  });
+
+  it('removes a reset key even when an earlier read that still had it lands first', async () => {
+    setTranslationOverride(loginApp, 'en', 'extraKey', 'Only an override');
+    i18n.reloadResources(['en'], [loginApp]);
+
+    resetTranslationOverride(loginApp, 'en', 'extraKey');
+    const reset = reloadTranslations(loginApp, 'en', 'extraKey');
+    await settleReads();
+
+    await expect(reset).resolves.toBeUndefined();
+    expect(i18n.getResource('en', loginApp, 'extraKey')).toBeUndefined();
+  });
+
+  it('restores the translation file when local config is cleared', async () => {
+    const stop = watchTranslationOverrides();
+    setTranslationOverride(loginApp, 'en', 'loginButton', 'Sign in');
+    setTranslationOverride(loginApp, 'en', 'extraKey', 'Only an override');
+    const saved = reloadTranslations(loginApp, 'en');
+    await settleReads();
+    await saved;
+
+    temporaryConfigStore.setState({ config: {} });
+    await settleReads();
+    stop();
+
+    await vi.waitFor(() => expect(i18n.getResource('en', loginApp, 'loginButton')).toBe('Log in'));
+    expect(i18n.getResource('en', loginApp, 'extraKey')).toBeUndefined();
+  });
+});

package/src/translations/translation-overrides.ts

@@ -0,0 +1,197 @@
+import { cloneDeep, isEqual, set, unset } from 'lodash-es';
+import {
+  clearConfigErrors,
+  extensionNamespaceSeparator,
+  temporaryConfigStore,
+} from '@openmrs/esm-framework/src/internal';
+import {
+  clearFailedLoads,
+  findLoadFailure,
+  getNamespacesLoading,
+  releaseStalledLoads,
+  waitForLoadsInFlight,
+  withTimeout,
+} from './i18next-loads';
+import { translationOverridesKey } from './translation-catalog';
+
+/**
+ * Overrides a translation by writing to the temporary config, which is the same path the rest of
+ * the implementer tools take. The override therefore behaves exactly as it will in a distribution's
+ * config file, and is picked up by `Download config` along with every other local edit.
+ *
+ * The change only reaches the screen once `reloadTranslations` has re-read the namespace.
+ */
+export function setTranslationOverride(namespace: string, language: string, key: string, value: string) {
+  const path = [namespace, translationOverridesKey, language, key];
+  clearConfigErrors(path.join('.'));
+  writeOverrides(set(cloneDeep(temporaryConfigStore.getState()), ['config', ...path], value));
+}
+
+/** Removes a locally-made override, restoring whatever the distribution's config supplies. */
+export function resetTranslationOverride(namespace: string, language: string, key: string) {
+  const path = [namespace, translationOverridesKey, language, key];
+  clearConfigErrors(path.join('.'));
+
+  const state = cloneDeep(temporaryConfigStore.getState());
+  unset(state, ['config', ...path]);
+  writeOverrides(state);
+}
+
+/** Set while this module writes an override, whose caller reloads and reports on it. */
+let isWritingOverride = false;
+
+function writeOverrides(state: ReturnType<typeof temporaryConfigStore.getState>) {
+  isWritingOverride = true;
+
+  try {
+    temporaryConfigStore.setState(state);
+  } finally {
+    isWritingOverride = false;
+  }
+}
+
+/**
+ * Reloads the translations whose overrides change in the temporary config through anything other
+ * than `setTranslationOverride` and `resetTranslationOverride`, such as "Clear local config" or the
+ * configuration editor. Without it, the old override stays on screen until the page is reloaded.
+ *
+ * Only namespaces already loaded for the language are reloaded; any other picks up the current
+ * overrides whenever it is first read.
+ *
+ * @returns A function that stops watching.
+ */
+export function watchTranslationOverrides(): () => void {
+  return temporaryConfigStore.subscribe((state, previous) => {
+    if (isWritingOverride) {
+      return;
+    }
+
+    for (const { namespace, language, droppedKeys } of findChangedOverrides(previous.config, state.config)) {
+      const isOnScreen =
+        window.i18next?.hasResourceBundle(language, namespace) ||
+        getExtensionNamespaces(namespace, language).length > 0;
+
+      if (isOnScreen) {
+        reloadTranslations(namespace, language, ...droppedKeys).catch((error) =>
+          console.error(`Could not apply the changed translation overrides for ${namespace} in ${language}`, error),
+        );
+      }
+    }
+  });
+}
+
+interface ChangedOverrides {
+  namespace: string;
+  language: string;
+  /** The keys whose override was removed. */
+  droppedKeys: Array<string>;
+}
+
+/** Lists the namespace and language pairs whose overrides differ between two temporary configs. */
+export function findChangedOverrides(previous: unknown, next: unknown): Array<ChangedOverrides> {
+  const namespaces = new Set([...Object.keys(asRecord(previous)), ...Object.keys(asRecord(next))]);
+
+  return Array.from(namespaces).flatMap((namespace) => {
+    const before = asRecord(asRecord(asRecord(previous)[namespace])[translationOverridesKey]);
+    const after = asRecord(asRecord(asRecord(next)[namespace])[translationOverridesKey]);
+    const languages = new Set([...Object.keys(before), ...Object.keys(after)]);
+
+    return Array.from(languages)
+      .filter((language) => !isEqual(before[language], after[language]))
+      .map((language) => {
+        const kept = asRecord(after[language]);
+
+        return {
+          namespace,
+          language,
+          droppedKeys: Object.keys(asRecord(before[language])).filter((key) => !Object.hasOwn(kept, key)),
+        };
+      });
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+}
+
+/**
+ * Re-reads a namespace's translations so that a changed override takes effect without a page
+ * reload. The app shell's i18next backend merges the config's overrides in as it reads a namespace,
+ * so reloading is what applies an override for real rather than faking it into the resource store.
+ *
+ * @param droppedKeys Keys whose override was removed. A reload alone would leave their old value.
+ */
+export async function reloadTranslations(
+  namespace: string,
+  language: string,
+  ...droppedKeys: Array<string>
+): Promise<void> {
+  const i18n = window.i18next;
+  const namespaces = [namespace, ...getExtensionNamespaces(namespace, language)];
+  const abandon = new AbortController();
+
+  try {
+    await withTimeout(
+      // A read already in flight, whether an earlier save's or the application's own, collected its
+      // overrides before this one was written, and would land over anything done to the bundle now.
+      waitForLoadsInFlight([language], namespaces, abandon.signal).then(
+        () =>
+          new Promise<void>((resolve, reject) => {
+            clearFailedLoads([language], namespaces);
+
+            dropKeys(language, namespaces, droppedKeys);
+
+            const done = (error?: unknown) => {
+              const failure = findLoadFailure([language], namespaces, error);
+              return failure ? reject(failure) : resolve();
+            };
+
+            // i18next declares this callback as taking no arguments but calls it with the load error.
+            i18n.reloadResources([language], namespaces, done as () => void);
+          }),
+      ),
+      `Reloading ${namespace} for ${language} did not finish`,
+    );
+  } catch (error) {
+    abandon.abort();
+    releaseStalledLoads([language], namespaces);
+    throw error;
+  }
+
+  // Mounted components only re-read their translations on `languageChanged`; react-i18next leaves
+  // the resource store's own `added` event unbound (`bindI18nStore` defaults to '').
+  i18n.emit('languageChanged', i18n.language);
+}
+
+/**
+ * Removes keys from the loaded bundles ahead of a reload.
+ *
+ * A reload merges its payload over the existing bundle rather than replacing it, so a key the fresh
+ * payload no longer carries survives — which is exactly what resetting an override produces for a
+ * language whose own file lacks that key. Deleting just these keys leaves the rest of the bundle
+ * intact; each is missing until the reload lands, and stays missing until the page is reloaded if
+ * it fails, which is what the failure message tells the user.
+ */
+function dropKeys(language: string, namespaces: Array<string>, keys: Array<string>) {
+  for (const namespace of namespaces) {
+    const bundle = window.i18next.getResourceBundle(language, namespace);
+
+    for (const key of keys) {
+      delete bundle?.[key];
+    }
+  }
+}
+
+/**
+ * The extension-scoped bundles derived from a namespace. They are loaded separately from the
+ * module's own bundle but merge the module's overrides in, so they go stale unless reloaded
+ * alongside it. One whose first read is still in flight has no bundle yet, but that read collected
+ * the old overrides, so it counts too.
+ */
+function getExtensionNamespaces(namespace: string, language: string): Array<string> {
+  const loaded = Object.keys(window.i18next?.store?.data?.[language] ?? {});
+
+  return Array.from(new Set([...loaded, ...getNamespacesLoading(language)])).filter((candidate) =>
+    candidate.startsWith(`${namespace}${extensionNamespaceSeparator}`),
+  );
+}