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

package/src/translations/translation-exports.ts

@@ -0,0 +1,53 @@
+import { translationOverridesKey } from './translation-catalog';
+
+/**
+ * The language Transifex treats as the source for every OpenMRS resource. Its strings come from each
+ * app's `en.json` and are pushed from the code, so they are not something to upload changes for.
+ */
+export const transifexSourceLanguage = 'en';
+
+/** The local (temporary config) overrides for one namespace and language, as a flat key/value map. */
+export function getLocalEdits(
+  temporaryConfig: Record<string, any> | undefined,
+  namespace: string,
+  language: string,
+): Record<string, string> {
+  const edits = temporaryConfig?.[namespace]?.[translationOverridesKey]?.[language] ?? {};
+
+  return Object.fromEntries(
+    Object.entries(edits).filter((entry): entry is [string, string] => typeof entry[1] === 'string'),
+  );
+}
+
+/** A config file carrying the given edits, in the shape a distribution's config takes them. */
+export function toOverrideFile(namespace: string, language: string, edits: Record<string, string>) {
+  return { [namespace]: { [translationOverridesKey]: { [language]: edits } } };
+}
+
+/**
+ * The locale code Transifex and the translation files use for a language tag: `ar-SY` is stored as
+ * `ar_SY.json`.
+ */
+export function toTransifexLocale(language: string): string {
+  return language.replace(/-/g, '_');
+}
+
+/** A file name for a namespace's overrides that is safe on any file system: `openmrs-esm-login-app`. */
+export function toFileSafeName(namespace: string): string {
+  return namespace.replace(/^@/, '').replace(/[^\w.-]+/g, '-');
+}
+
+/** Saves `data` as a pretty-printed JSON file through the browser's download mechanism. */
+export function downloadJson(fileName: string, data: unknown) {
+  const url = URL.createObjectURL(new Blob([JSON.stringify(data, undefined, 2) + '\n'], { type: 'application/json' }));
+  const link = document.createElement('a');
+
+  link.href = url;
+  link.download = fileName;
+  document.body.appendChild(link);
+  link.click();
+  link.remove();
+
+  // Deferred so the download has started before its URL goes away.
+  setTimeout(() => URL.revokeObjectURL(url));
+}

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();
+  });
+});