Change the locale dynamically by adding &i18n-locale to URL

changelogs/fragments/7686.yml

@@ -0,0 +1,2 @@
+feat:
+- Change the locale dynamically by adding &i18n-locale to URL ([#7686](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/7686))

docs/_sidebar.md

@@ -30,6 +30,7 @@
         - public
           - application
             - [Hooks](../src/plugins/console/public/application/hooks/README.md)
+      - [Content_management](../src/plugins/content_management/README.md)
       - [Csp_handler](../src/plugins/csp_handler/README.md)
       - [Dashboard](../src/plugins/dashboard/README.md)
       - [Data](../src/plugins/data/README.md)
@@ -164,6 +165,7 @@
     - [Opensearch dashboards.release notes 2.13.0](../release-notes/opensearch-dashboards.release-notes-2.13.0.md)
     - [Opensearch dashboards.release notes 2.14.0](../release-notes/opensearch-dashboards.release-notes-2.14.0.md)
     - [Opensearch dashboards.release notes 2.15.0](../release-notes/opensearch-dashboards.release-notes-2.15.0.md)
+    - [Opensearch dashboards.release notes 2.16.0](../release-notes/opensearch-dashboards.release-notes-2.16.0.md)
     - [Opensearch dashboards.release notes 2.2.0](../release-notes/opensearch-dashboards.release-notes-2.2.0.md)
     - [Opensearch dashboards.release notes 2.2.1](../release-notes/opensearch-dashboards.release-notes-2.2.1.md)
     - [Opensearch dashboards.release notes 2.3.0](../release-notes/opensearch-dashboards.release-notes-2.3.0.md)

packages/osd-i18n/src/core/i18n.test.ts

@@ -899,8 +899,17 @@ describe('I18n engine', () => {
 
   describe('load', () => {
     let mockFetch: jest.SpyInstance;
+    let originalWindow: any;
+
     beforeEach(() => {
       mockFetch = jest.spyOn(global as any, 'fetch').mockImplementation();
+      originalWindow = global.window;
+      global.window = { ...originalWindow };
+    });
+
+    afterEach(() => {
+      global.window = originalWindow;
+      delete (window as any).__i18nWarning; // Clear the warning after each test
     });
 
     test('fails if server returns >= 300 status code', async () => {
@@ -928,7 +937,7 @@ describe('I18n engine', () => {
 
       mockFetch.mockResolvedValue({
         status: 200,
-        json: jest.fn().mockResolvedValue(translations),
+        json: jest.fn().mockResolvedValue({ translations }),
       });
 
       await expect(i18n.load('some-url')).resolves.toBeUndefined();
@@ -938,5 +947,28 @@ describe('I18n engine', () => {
 
       expect(i18n.getTranslation()).toEqual(translations);
     });
+
+    test('sets warning on window when present in response', async () => {
+      const warning = { title: 'Warning', text: 'This is a warning' };
+      mockFetch.mockResolvedValue({
+        status: 200,
+        json: jest.fn().mockResolvedValue({ translations: { locale: 'en' }, warning }),
+      });
+
+      await i18n.load('some-url');
+
+      expect((window as any).__i18nWarning).toEqual(warning);
+    });
+
+    test('does not set warning on window when not present in response', async () => {
+      mockFetch.mockResolvedValue({
+        status: 200,
+        json: jest.fn().mockResolvedValue({ translations: { locale: 'en' } }),
+      });
+
+      await i18n.load('some-url');
+
+      expect((window as any).__i18nWarning).toBeUndefined();
+    });
   });
 });

packages/osd-i18n/src/core/i18n.ts

@@ -261,5 +261,12 @@ export async function load(translationsUrl: string) {
     throw new Error(`Translations request failed with status code: ${response.status}`);
   }
 
-  init(await response.json());
+  const data = await response.json();
+
+  if (data.warning) {
+    // Store the warning to be displayed after core system setup
+    (window as any).__i18nWarning = data.warning;
+  }
+
+  init(data.translations);
 }

src/core/public/application/scoped_history.test.ts

@@ -30,8 +30,23 @@
 
 import { ScopedHistory } from './scoped_history';
 import { createMemoryHistory } from 'history';
+import { getLocaleInUrl } from '../locale_helper';
+import { i18n } from '@osd/i18n';
+
+jest.mock('../locale_helper', () => ({
+  getLocaleInUrl: jest.fn(),
+}));
+
+jest.mock('@osd/i18n', () => ({
+  i18n: {
+    getLocale: jest.fn(),
+  },
+}));
 
 describe('ScopedHistory', () => {
+  beforeEach(() => {
+    (getLocaleInUrl as jest.Mock).mockReturnValue('en');
+  });
   describe('construction', () => {
     it('succeeds if current location matches basePath', () => {
       const gh = createMemoryHistory();
@@ -358,4 +373,49 @@ describe('ScopedHistory', () => {
       expect(gh.length).toBe(4);
     });
   });
+
+  describe('locale handling', () => {
+    let originalLocation: Location;
+
+    beforeEach(() => {
+      originalLocation = window.location;
+      delete (window as any).location;
+      window.location = { href: 'http://localhost/app/wow', reload: jest.fn() } as any;
+      (i18n.getLocale as jest.Mock).mockReturnValue('en');
+    });
+
+    afterEach(() => {
+      window.location = originalLocation;
+      jest.resetAllMocks();
+    });
+
+    it('reloads the page when locale changes', () => {
+      const gh = createMemoryHistory();
+      gh.push('/app/wow');
+      const h = new ScopedHistory(gh, '/app/wow');
+      // Use the 'h' variable to trigger the listener
+      h.push('/new-page');
+
+      // Mock getLocaleInUrl to return a different locale
+      (getLocaleInUrl as jest.Mock).mockReturnValue('fr');
+
+      // Simulate navigation
+      gh.push('/app/wow/new-page');
+
+      expect(window.location.reload).toHaveBeenCalled();
+    });
+
+    it('does not reload the page when locale changes', () => {
+      const gh = createMemoryHistory();
+      gh.push('/app/wow');
+
+      // Mock getLocaleInUrl to return a different locale
+      (getLocaleInUrl as jest.Mock).mockReturnValue('en');
+
+      // Simulate navigation
+      gh.push('/app/wow/new-page');
+
+      expect(window.location.reload).not.toHaveBeenCalled();
+    });
+  });
 });

src/core/public/application/scoped_history.ts

@@ -39,6 +39,8 @@ import {
   Href,
   Action,
 } from 'history';
+import { i18n } from '@osd/i18n';
+import { getLocaleInUrl } from '../locale_helper';
 
 /**
  * A wrapper around a `History` instance that is scoped to a particular base path of the history stack. Behaves
@@ -307,6 +309,7 @@ export class ScopedHistory<HistoryLocationState = unknown>
    * state. Also forwards events to child listeners with the base path stripped from the location.
    */
   private setupHistoryListener() {
+    const currentLocale = i18n.getLocale() || 'en';
     const unlisten = this.parentHistory.listen((location, action) => {
       // If the user navigates outside the scope of this basePath, tear it down.
       if (!location.pathname.startsWith(this.basePath)) {
@@ -315,6 +318,14 @@ export class ScopedHistory<HistoryLocationState = unknown>
         return;
       }
 
+      const localeValue = getLocaleInUrl(window.location.href);
+
+      if (localeValue !== currentLocale) {
+        // Force a full page reload
+        window.location.reload();
+        return;
+      }
+
       /**
        * Track location keys using the same algorithm the browser uses internally.
        * - On PUSH, remove all items that came after the current location and append the new location.

src/core/public/locale_helper.test.ts

@@ -0,0 +1,50 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { getLocaleInUrl } from './locale_helper';
+
+describe('getLocaleInUrl', () => {
+  beforeEach(() => {
+    // Clear any warnings before each test
+    delete (window as any).__localeWarning;
+  });
+
+  it('should return the locale from a valid query string', () => {
+    const url = 'http://localhost:5603/app/home?locale=en-US';
+    expect(getLocaleInUrl(url)).toBe('en-US');
+  });
+
+  it('should return the locale from a valid hash query string', () => {
+    const url = 'http://localhost:5603/app/home#/?locale=fr-FR';
+    expect(getLocaleInUrl(url)).toBe('fr-FR');
+  });
+
+  it('should return en for a URL without locale', () => {
+    const url = 'http://localhost:5603/app/home';
+    expect(getLocaleInUrl(url)).toBe('en');
+  });
+
+  it('should return en and set a warning for an invalid locale format in hash', () => {
+    const url = 'http://localhost:5603/app/home#/&locale=de-DE';
+    expect(getLocaleInUrl(url)).toBe('en');
+    expect((window as any).__localeWarning).toBeDefined();
+    expect((window as any).__localeWarning.title).toBe('Invalid URL Format');
+  });
+
+  it('should return en for an empty locale value', () => {
+    const url = 'http://localhost:5603/app/home?locale=';
+    expect(getLocaleInUrl(url)).toBe('en');
+  });
+
+  it('should handle URLs with other query parameters', () => {
+    const url = 'http://localhost:5603/app/home?param1=value1&locale=ja-JP&param2=value2';
+    expect(getLocaleInUrl(url)).toBe('ja-JP');
+  });
+
+  it('should handle URLs with other hash parameters', () => {
+    const url = 'http://localhost:5603/app/home#/route?param1=value1&locale=zh-CN&param2=value2';
+    expect(getLocaleInUrl(url)).toBe('zh-CN');
+  });
+});

src/core/public/locale_helper.ts

@@ -0,0 +1,68 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Extracts the locale value from a given URL.
+ *
+ * This function looks for the 'locale' parameter in either the main query string
+ * or in the hash part of the URL. It supports two valid formats:
+ * 1. As a regular query parameter: "?locale=xx-XX"
+ * 2. In the hash with a proper query string: "#/?locale=xx-XX"
+ *
+ * If an invalid format is detected, it sets a warning message on the window object.
+ *
+ * @param url - The URL to extract the locale from
+ * @returns The locale value if found and valid, or null otherwise
+ */
+export function getLocaleInUrl(url: string): string | null {
+  let urlObject: URL;
+  // Attempt to parse the URL, return null if invalid
+  try {
+    urlObject = new URL(url, window.location.origin);
+  } catch (error) {
+    setInvalidUrlWarning();
+    return null;
+  }
+
+  let localeValue: string | null = null;
+
+  // Check for locale in the main query string
+  if (urlObject.searchParams.has('locale')) {
+    localeValue = urlObject.searchParams.get('locale');
+  }
+  // Check for locale in the hash, but only if it's in proper query string format
+  else if (urlObject.hash.includes('?')) {
+    const hashParams = new URLSearchParams(urlObject.hash.split('?')[1]);
+    if (hashParams.has('locale')) {
+      localeValue = hashParams.get('locale');
+    }
+  }
+
+  // Check for non standard query format:
+  if (localeValue === null && url.includes('&locale=')) {
+    setInvalidUrlWithLocaleWarning();
+    return 'en';
+  }
+
+  // Return the locale value if found, or 'en' if not found
+  return localeValue && localeValue.trim() !== '' ? localeValue : 'en';
+}
+
+function setInvalidUrlWarning(): void {
+  (window as any).__localeWarning = {
+    title: 'Invalid URL Format',
+    text: 'The provided URL is not in a valid format.',
+  };
+}
+
+function setInvalidUrlWithLocaleWarning(): void {
+  (window as any).__localeWarning = {
+    title: 'Invalid URL Format',
+    text:
+      'The locale parameter is not in a valid URL format. ' +
+      'Use either "?locale=xx-XX" in the main URL or "#/?locale=xx-XX" in the hash. ' +
+      'For example: "yourapp.com/page?locale=en-US" or "yourapp.com/page#/?locale=en-US".',
+  };
+}

src/core/public/osd_bootstrap.test.mocks.ts

@@ -31,18 +31,6 @@
 import { applicationServiceMock } from './application/application_service.mock';
 import { fatalErrorsServiceMock } from './fatal_errors/fatal_errors_service.mock';
 export const fatalErrorMock = fatalErrorsServiceMock.createSetupContract();
-export const coreSystemMock = {
-  setup: jest.fn().mockResolvedValue({
-    fatalErrors: fatalErrorMock,
-  }),
-  start: jest.fn().mockResolvedValue({
-    application: applicationServiceMock.createInternalStartContract(),
-  }),
-};
-jest.doMock('./core_system', () => ({
-  CoreSystem: jest.fn().mockImplementation(() => coreSystemMock),
-}));
-
 export const apmSystem = {
   setup: jest.fn().mockResolvedValue(undefined),
   start: jest.fn().mockResolvedValue(undefined),
@@ -53,9 +41,25 @@ jest.doMock('./apm_system', () => ({
 }));
 
 export const i18nLoad = jest.fn().mockResolvedValue(undefined);
+export const i18nSetLocale = jest.fn();
 jest.doMock('@osd/i18n', () => ({
   i18n: {
     ...jest.requireActual('@osd/i18n').i18n,
     load: i18nLoad,
+    setLocale: i18nSetLocale,
   },
 }));
+
+export const coreSystemMock = {
+  setup: jest.fn().mockResolvedValue({
+    fatalErrors: fatalErrorMock,
+  }),
+  start: jest.fn().mockResolvedValue({
+    application: applicationServiceMock.createInternalStartContract(),
+  }),
+};
+jest.doMock('./core_system', () => ({
+  CoreSystem: jest.fn().mockImplementation(() => coreSystemMock),
+}));
+
+export const consoleWarnMock = jest.spyOn(console, 'warn').mockImplementation(() => {});