@nutin/cli 1.3.1 → 2.0.0

package/templates/base/src/core/services/globals/globals.test.js.hbs

@@ -0,0 +1,149 @@
+import { registerGlobals, hideGlobals, revealGlobals, Globals } from '#root/dist/src/core/services/globals/globals.js';
+
+function makeComponent(tag = 'div') {
+  return class {
+    constructor(mountTarget) {
+      this.mountTarget = mountTarget;
+    }
+    render() {
+      return document.createElement(tag);
+    }
+  };
+}
+
+describe('globals (registerGlobals)', () => {
+  afterEach(() => {
+    // registerGlobals mounts directly onto document.body (a sibling of the
+    // pre-existing <main id="app">), so only strip what each test added.
+    [...document.body.children].forEach((el) => {
+      if (el.id !== 'app') el.remove();
+    });
+    // Globals is a process-wide singleton (like every other Service) - drop
+    // its registered-id state so a later test's ids can't collide with an
+    // earlier one's.
+    Globals.testingResetAll();
+  });
+
+  it('is defined', () => {
+    expect(registerGlobals).toBeDefined();
+  });
+
+  it('touches nothing when called with no options', () => {
+    registerGlobals({});
+    expect(document.body.children.length).toBe(1); // just #app
+  });
+
+  it('prepends a single "before" entry ahead of the existing #app, stamping its id', () => {
+    registerGlobals({ before: [{ component: makeComponent('header'), id: 'header' }] });
+    expect(document.body.firstElementChild.tagName).toBe('HEADER');
+    expect(document.body.firstElementChild.id).toBe('header');
+    expect(document.body.children[1].id).toBe('app');
+  });
+
+  it('appends a single "after" entry behind the existing #app, stamping its id', () => {
+    registerGlobals({ after: [{ component: makeComponent('footer'), id: 'footer' }] });
+    expect(document.body.lastElementChild.tagName).toBe('FOOTER');
+    expect(document.body.lastElementChild.id).toBe('footer');
+  });
+
+  it('mounts multiple "before" entries in the given order (not reversed)', () => {
+    registerGlobals({
+      before: [
+        { component: makeComponent('div'), id: 'first' },
+        { component: makeComponent('div'), id: 'second' },
+      ],
+    });
+    const ids = [...document.body.children].filter((el) => el.id !== 'app').map((el) => el.id);
+    expect(ids).toEqual(['first', 'second']);
+  });
+
+  it('mounts multiple "after" entries in the given order (not reversed)', () => {
+    registerGlobals({
+      after: [
+        { component: makeComponent('div'), id: 'first' },
+        { component: makeComponent('div'), id: 'second' },
+      ],
+    });
+    const ids = [...document.body.children].filter((el) => el.id !== 'app').map((el) => el.id);
+    expect(ids).toEqual(['first', 'second']);
+  });
+
+  it('passes the same mountTarget value through to every constructed component', () => {
+    const seen = [];
+    class TrackingComponent {
+      constructor(mountTarget) {
+        seen.push(mountTarget);
+      }
+      render() {
+        return document.createElement('div');
+      }
+    }
+    registerGlobals({
+      before: [{ component: TrackingComponent, id: 'a' }],
+      after: [{ component: TrackingComponent, id: 'b' }],
+    });
+    expect(seen).toEqual(['body', 'body']);
+  });
+
+  it('registering a duplicate id warns and skips the second mount', () => {
+    const warnSpy = spyOn(console, 'warn');
+    warnSpy.andCallFake(() => {});
+
+    registerGlobals({ before: [{ component: makeComponent('header'), id: 'dup' }] });
+    registerGlobals({ after: [{ component: makeComponent('footer'), id: 'dup' }] });
+
+    const matches = [...document.body.children].filter((el) => el.id === 'dup');
+    expect(matches.length).toBe(1);
+    expect(matches[0].tagName).toBe('HEADER');
+    expect(warnSpy.callCount).toBe(1);
+
+    warnSpy.restore();
+  });
+});
+
+describe('globals (hideGlobals/revealGlobals)', () => {
+  afterEach(() => {
+    [...document.body.children].forEach((el) => {
+      if (el.id !== 'app') el.remove();
+    });
+  });
+
+  it('toggle display for every given id that is present', () => {
+    const header = document.createElement('div');
+    header.id = 'header';
+    document.body.appendChild(header);
+    const footer = document.createElement('div');
+    footer.id = 'footer';
+    document.body.appendChild(footer);
+
+    hideGlobals(['header', 'footer']);
+    expect(header.style.display).toBe('none');
+    expect(footer.style.display).toBe('none');
+
+    revealGlobals(['header', 'footer']);
+    expect(header.style.display).toBe('block');
+    expect(footer.style.display).toBe('block');
+  });
+
+  it('only touch the display property, leaving other inline styles intact', () => {
+    const header = document.createElement('div');
+    header.id = 'header';
+    header.style.cssText = 'background: coral; padding: 8px';
+    document.body.appendChild(header);
+
+    hideGlobals(['header']);
+    expect(header.style.display).toBe('none');
+    expect(header.style.background).toBe('coral');
+    expect(header.style.padding).toBe('8px');
+
+    revealGlobals(['header']);
+    expect(header.style.display).toBe('block');
+    expect(header.style.background).toBe('coral');
+    expect(header.style.padding).toBe('8px');
+  });
+
+  it('are no-ops for ids that are absent', () => {
+    expect(() => hideGlobals(['missing'])).not.toThrow();
+    expect(() => revealGlobals(['missing'])).not.toThrow();
+  });
+});

package/templates/base/src/core/services/globals/globals.ts.hbs

@@ -0,0 +1,95 @@
+import { Service } from '../../base-classes/index.js';
+
+export interface GlobalMountable {
+  render(): HTMLElement;
+  destroy?(): void;
+}
+
+export interface GlobalConfig<T extends GlobalMountable = GlobalMountable> {
+  /** The component's own class — constructed internally as `new component(mountTarget)`. */
+  component: new (mountTarget: HTMLElement) => T;
+  /** Stamped onto the mounted root element; pass this same id to `hideGlobals`/`revealGlobals`. */
+  id: string;
+}
+
+export interface RegisterGlobalsOptions {
+  /** Rendered and prepended to `<body>`, in the given order (e.g. a header). */
+  before?: GlobalConfig[];
+  /** Rendered and appended to `<body>`, in the given order (e.g. a footer). */
+  after?: GlobalConfig[];
+}
+
+export class Globals extends Service<Globals> {
+  private _mounted: Record<string, GlobalMountable> = {};
+
+  constructor() { super(); }
+
+  public register({ before = [], after = [] }: RegisterGlobalsOptions): void {
+    // Component subclasses generated via `nutin generate component` type their
+    // mountTarget param as HTMLElement, but DomHelper.mountElement only
+    // *appends* (rather than replacing) the target when mountTarget is a string
+    // selector. This cast satisfies the stricter constructor type while still
+    // passing the string 'body' through at runtime, so components append into
+    // <body> instead of replacing it.
+    const mountTarget = 'body' as unknown as HTMLElement;
+    const isElement = (el: HTMLElement | null): el is HTMLElement => el !== null;
+
+    const mount = ({ component: Component, id }: GlobalConfig): HTMLElement | null => {
+      if (this._mounted[id]) {
+        console.warn(`Global "${id}" is already registered - skipping.`);
+        return null;
+      }
+      const instance = new Component(mountTarget);
+      const element = instance.render();
+      element.id = id;
+      this._mounted[id] = instance;
+      return element;
+    };
+
+    document.body.prepend(...before.map(mount).filter(isElement));
+    document.body.append(...after.map(mount).filter(isElement));
+  }
+
+  public hide(globalIds: string[]): void {
+    this.setDisplay(globalIds, 'none');
+  }
+
+  public reveal(globalIds: string[]): void {
+    this.setDisplay(globalIds, 'block');
+  }
+
+  private setDisplay(globalIds: string[], display: 'none' | 'block'): void {
+    globalIds.forEach((id) => {
+      const el = document.getElementById(id) as HTMLElement | null;
+      if (el) el.style.display = display;
+    });
+  }
+
+  protected onDestroy(): void {
+    Object.values(this._mounted).forEach((instance) => instance.destroy?.());
+    this._mounted = {};
+  }
+}
+
+/**
+ * Mounts components outside the router's render target (`<main id="app">`),
+ * e.g. a header/footer that should persist across every route. Each entry's
+ * `component` is constructed internally — callers never see or handle
+ * `mountTarget` themselves — and its rendered root element is given the
+ * entry's `id`, so `hideGlobals(ids)`/`revealGlobals(ids)` can target it
+ * later by that same id. Registering an `id` that's already registered logs
+ * a `console.warn` and skips it.
+ */
+export const registerGlobals = (options: RegisterGlobalsOptions): void => {
+  Globals.getInstance().register(options);
+};
+
+/** Hide the elements with the given ids (as registered via `registerGlobals`). */
+export const hideGlobals = (globalIds: string[]): void => {
+  Globals.getInstance().hide(globalIds);
+};
+
+/** Reveal the elements with the given ids (as registered via `registerGlobals`). */
+export const revealGlobals = (globalIds: string[]): void => {
+  Globals.getInstance().reveal(globalIds);
+};

package/templates/base/src/core/services/http-client/helpers/http-builder.helper.test.js.hbs

@@ -75,6 +75,11 @@ describe('HttpBuilder', () => {
     expect(url.search).toBe('?page=1&limit=10');
   });
 
+  it('buildRequestUrl leaves an existing query in the endpoint untouched when no new params are passed', () => {
+    const url = HttpBuilder.buildRequestUrl('https://api.example.com?page=1');
+    expect(url.search).toBe('?page=1');
+  });
+
   // Tests for buildRequestOptions
   it('buildRequestOptions sets GET without body', () => {
     const options = HttpBuilder.buildRequestOptions(
@@ -106,4 +111,24 @@ describe('HttpBuilder', () => {
     expect(options.body).toBeUndefined();
     expect(options.headers).toBeUndefined();
   });
+
+  it('buildRequestOptions sets PUT with body', () => {
+    const data = { id: 1, name: 'Updated' };
+    const options = HttpBuilder.buildRequestOptions('PUT', data, {}, mockAbortSignal);
+    expect(options.method).toBe('PUT');
+    expect(options.body).toBe(JSON.stringify(data));
+  });
+
+  it('buildRequestOptions sets PATCH with body', () => {
+    const data = { name: 'Patched' };
+    const options = HttpBuilder.buildRequestOptions('PATCH', data, {}, mockAbortSignal);
+    expect(options.method).toBe('PATCH');
+    expect(options.body).toBe(JSON.stringify(data));
+  });
+
+  it('buildRequestOptions sets DELETE without body', () => {
+    const options = HttpBuilder.buildRequestOptions('DELETE', undefined, {}, mockAbortSignal);
+    expect(options.method).toBe('DELETE');
+    expect(options.body).toBeUndefined();
+  });
 })

package/templates/base/src/core/services/http-client/helpers/http-manager.helper.test.js.hbs

@@ -55,6 +55,26 @@ describe('HttpManager', () => {
     expect(thrown).toBe(true);
   });
 
+  it('should throw HttpError with a null response body when the error body is not valid JSON', async () => {
+    const mockResponse = new Response('plain text failure', {
+      status: 500,
+      statusText: 'Internal Server Error',
+      headers: { 'Content-Type': 'text/plain' }
+    });
+
+    let thrown = false;
+    try {
+      await HttpManager.validateResponse(mockResponse);
+    } catch (e) {
+      thrown = true;
+      expect(e).toBeInstanceOf(HttpError);
+      expect(e.status).toBe(500);
+      expect(e.statusText).toBe('Internal Server Error');
+      expect(e.response).toBe(null);
+    }
+    expect(thrown).toBe(true);
+  });
+
   it('should detect JSON content types', () => {
     expect(HttpManager.isJsonResponse('application/json')).toBe(true);
     expect(HttpManager.isJsonResponse('application/json; charset=utf-8')).toBe(true);

package/templates/base/src/core/services/http-client/http-client.test.js.hbs

@@ -204,6 +204,49 @@ describe('HttpClient', () => {
     expect(lastCall.options.headers['Authorization']).toBe('Bearer custom-token');
   });
 
+  it('should invoke request interceptors with the final url and options before sending', async () => {
+    fetchMock.mockJsonResponse('https://api.example.com/users', []);
+    const calls = [];
+    httpClient.addRequestInterceptor((url, options) => calls.push({ url, options }));
+
+    await httpClient.get('https://api.example.com/users');
+
+    expect(calls.length).toBe(1);
+    expect(calls[0].url).toBe('https://api.example.com/users');
+    expect(calls[0].options.method).toBe('GET');
+  });
+
+  it('should invoke response interceptors with the raw fetch response', async () => {
+    fetchMock.mockJsonResponse('https://api.example.com/users', []);
+    const received = [];
+    httpClient.addResponseInterceptor((response) => received.push(response));
+
+    await httpClient.get('https://api.example.com/users');
+
+    expect(received.length).toBe(1);
+    expect(received[0].ok).toBe(true);
+  });
+
+  it('should propagate a non-timeout error thrown while parsing the response', async () => {
+    fetchMock.mockResponse('https://api.example.com/broken', {
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      headers: { get: () => 'application/json' },
+      json: () => Promise.reject(new Error('Malformed JSON')),
+      text: () => Promise.resolve('not json'),
+    });
+
+    let thrown = false;
+    try {
+      await httpClient.get('https://api.example.com/broken');
+    } catch (error) {
+      thrown = true;
+      expect(error.message).toBe('Malformed JSON');
+    }
+    expect(thrown).toBe(true);
+  });
+
   it('should handle HTTP errors', async () => {
     fetchMock.mockError('https://api.example.com/users', 404, { message: 'Not found' });
         

package/templates/base/src/core/services/i18n/i18n.test.js.hbs

@@ -0,0 +1,270 @@
+import { I18nService, AppEventBus } from '#root/dist/src/core/services/index.js';
+import { CONFIG } from '#root/dist/src/core/config.js';
+
+class FetchMock {
+  constructor() {
+    this.originalFetch = global.fetch;
+    this.mockResponses = new Map();
+  }
+  
+  mockTranslation(lang, data) {
+    this.mockResponses.set(`/locales/${lang}.json`, {
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(data)
+    });
+    return this;
+  }
+
+  mockError(url, status = 404) {
+    this.mockResponses.set(url, {
+      ok: false,
+      status,
+      json: () => Promise.reject(new Error(`HTTP ${status}`))
+    });
+    return this;
+  }
+  
+  install() {
+    global.fetch = (url) => {      
+      if (this.mockResponses.has(url)) {
+        const response = this.mockResponses.get(url);
+        return Promise.resolve(response);
+      }
+
+      return this.originalFetch ? this.originalFetch(url) : Promise.reject(new Error('fetch not available'));
+    };
+    return this;
+  }
+  
+  restore() {
+    global.fetch = this.originalFetch;
+    this.mockResponses.clear();
+  }
+}
+
+const fetchMock = new FetchMock();
+
+describe('i18n module', async () => {
+  let originalLanguage;
+
+  beforeEach(async () => {
+    I18nService.resetTranslations();
+    fetchMock
+      .mockTranslation('en', { home: { title : 'My App', subtitle: "English subtitle" }})
+      .mockTranslation('fr', { home: { title : 'Mon App' }})
+      .install();
+  });
+  afterEach(() => {
+    fetchMock.restore();
+    localStorage.removeItem(I18nService.localStorageKey)
+  });
+
+  beforeAll(() =>{
+    originalLanguage = navigator.language;    
+    Object.defineProperty(navigator, 'language', {
+      writable: true,
+      configurable: true,
+      value: "en-US"
+    });
+    I18nService['_LANGUAGES'] = [ 'en', 'fr' ];
+    I18nService['_DEFAULT_LANGUAGE'] = 'en';
+  });
+  afterAll(() => {    
+    Object.defineProperty(navigator, 'language', {
+      writable: true,
+      configurable: true,
+      value: originalLanguage
+    });
+  });
+
+  it('should load and use English translations', async () => {
+    await I18nService.initTranslations();
+    expect(I18nService.currentLanguage).toBe('en');
+    expect(I18nService.translate('home.title')).toBe('My App');
+  });
+
+  it('should load and use French translations', async () => {
+    Object.defineProperty(navigator, 'language', {
+      writable: true,
+      configurable: true,
+      value: "fr-FR"
+    });
+    await I18nService.initTranslations();
+    expect(I18nService.currentLanguage).toBe('fr');
+    expect(I18nService.translate('home.title')).toBe('Mon App');
+  });
+
+  it('should default to English translations', async () => {
+    // missing locale
+    Object.defineProperty(navigator, 'language', {
+      writable: true,
+      configurable: true,
+      value: "de-DE"
+    });
+    await I18nService.initTranslations();
+    expect(navigator.language).toBe('de-DE');
+    expect(I18nService.currentLanguage).toBe('en');
+    expect(I18nService.translate('home.title')).toBe('My App');
+    I18nService.resetTranslations();
+
+    // missing translation
+    Object.defineProperty(navigator, 'language', {
+      writable: true,
+      configurable: true,
+      value: "fr-FR"
+    });
+    await I18nService.initTranslations();
+    expect(navigator.language).toBe('fr-FR');
+    expect(I18nService.currentLanguage).toBe('fr');
+    expect(I18nService.translate('home.title')).toBe('Mon App');
+    expect(I18nService.translate('home.subtitle')).toBe('English subtitle');
+  });
+
+  it('should return key when translation is missing', () => {
+    expect(I18nService.translate('non.existent.key')).toBe('non.existent.key');
+  });
+
+  it('setCurrentLanguage updates the language, persists it and loads its translations', async () => {
+    await I18nService.setCurrentLanguage('fr');
+
+    expect(I18nService.currentLanguage).toBe('fr');
+    expect(I18nService.translate('home.title')).toBe('Mon App');
+    expect(localStorage.getItem(I18nService.localStorageKey)).toBe('fr');
+  });
+
+  it('setCurrentLanguage emits a language-changed event with the new language', async () => {
+    const received = [];
+    const callback = (data) => received.push(data);
+    I18nService.onLanguageChange(callback);
+
+    await I18nService.setCurrentLanguage('fr');
+
+    expect(received).toEqual([{ lang: 'fr' }]);
+    AppEventBus.off('language-changed', callback);
+  });
+
+  it('getTranslationObject returns the nested value for the current language', async () => {
+    Object.defineProperty(navigator, 'language', { writable: true, configurable: true, value: 'en-US' });
+    await I18nService.initTranslations();
+    expect(I18nService.getTranslationObject('home')).toEqual({ title: 'My App', subtitle: 'English subtitle' });
+  });
+
+  it('getTranslationObject falls back to the default language when missing in the current language', async () => {
+    Object.defineProperty(navigator, 'language', { writable: true, configurable: true, value: 'fr-FR' });
+    await I18nService.initTranslations();
+    expect(I18nService.getTranslationObject('home.subtitle')).toBe('English subtitle');
+  });
+
+  it('getTranslationObject returns null when the key is not found anywhere', async () => {
+    Object.defineProperty(navigator, 'language', { writable: true, configurable: true, value: 'en-US' });
+    await I18nService.initTranslations();
+    expect(I18nService.getTranslationObject('does.not.exist')).toBe(null);
+  });
+
+  it('honors a locale prefix in the URL path when CONFIG.i18n is enabled', async () => {
+    CONFIG.i18n = true;
+    window.history.pushState({}, '', '/fr/some/page');
+    try {
+      await I18nService.initTranslations();
+      expect(I18nService.currentLanguage).toBe('fr');
+    } finally {
+      CONFIG.i18n = false;
+      window.history.pushState({}, '', '/');
+    }
+  });
+
+  it('ignores a locale prefix in the URL path when CONFIG.i18n is disabled (default)', async () => {
+    Object.defineProperty(navigator, 'language', { writable: true, configurable: true, value: 'en-US' });
+    window.history.pushState({}, '', '/fr/some/page');
+    try {
+      await I18nService.initTranslations();
+      expect(I18nService.currentLanguage).toBe('en');
+    } finally {
+      window.history.pushState({}, '', '/');
+    }
+  });
+
+  it('initTranslations falls back to the default language when the resolved preferred language is unsupported', async () => {
+    const original = I18nService.getPreferredLanguage;
+    I18nService.getPreferredLanguage = () => 'zz';
+    try {
+      await I18nService.initTranslations();
+      expect(I18nService.currentLanguage).toBe('en');
+    } finally {
+      I18nService.getPreferredLanguage = original;
+    }
+  });
+
+  it('getLocaleFromUrl returns null when the URL locale segment is not supported', () => {
+    CONFIG.i18n = true;
+    window.history.pushState({}, '', '/xx/page');
+    try {
+      expect(I18nService.getLocaleFromUrl()).toBe(null);
+    } finally {
+      CONFIG.i18n = false;
+      window.history.pushState({}, '', '/');
+    }
+  });
+
+  it('loadDefaultTranslations logs and leaves default translations empty when the fetch fails', async () => {
+    Object.defineProperty(navigator, 'language', { writable: true, configurable: true, value: 'fr-FR' });
+    const errSpy = spyOn(console, 'error');
+    errSpy.andCallFake(() => {});
+    fetchMock.mockError('/locales/en.json', 500);
+
+    await I18nService.initTranslations();
+
+    // loadDefaultTranslations is attempted twice: once explicitly by initTranslations,
+    // and again from within loadTranslations('fr') since _defaultTranslations is still
+    // empty after the first failure — each attempt logs its own error.
+    expect(errSpy.callCount).toBe(2);
+    expect(I18nService.currentLanguage).toBe('fr');
+
+    errSpy.restore();
+  });
+
+  it('honors a previously saved language preference from localStorage', async () => {
+    localStorage.setItem(I18nService.localStorageKey, 'fr');
+    await I18nService.initTranslations();
+    expect(I18nService.currentLanguage).toBe('fr');
+  });
+
+  it('loadTranslations logs and leaves the language unchanged when the fetch rejects', async () => {
+    Object.defineProperty(navigator, 'language', { writable: true, configurable: true, value: 'en-US' });
+    const errSpy = spyOn(console, 'error');
+    errSpy.andCallFake(() => {});
+    global.fetch = () => Promise.reject(new Error('network down'));
+
+    await I18nService.initTranslations();
+
+    expect(errSpy.callCount).toBe(1);
+    expect(I18nService.currentLanguage).toBe('en');
+
+    errSpy.restore();
+  });
+
+  it('loadTranslations logs and leaves state unchanged when the response is not ok', async () => {
+    Object.defineProperty(navigator, 'language', { writable: true, configurable: true, value: 'en-US' });
+    const errSpy = spyOn(console, 'error');
+    errSpy.andCallFake(() => {});
+    fetchMock.mockError('/locales/en.json', 500);
+
+    await I18nService.initTranslations();
+
+    expect(errSpy.callCount).toBe(1);
+    expect(I18nService.currentLanguage).toBe('en');
+
+    errSpy.restore();
+  });
+
+  it('onDestroy resets translations and disposes the instance', async () => {
+    await I18nService.initTranslations();
+    expect(I18nService.translate('home.title')).toBe('My App');
+
+    I18nService.onDestroy();
+
+    expect(I18nService.translate('home.title')).toBe('home.title');
+    expect(localStorage.getItem(I18nService.localStorageKey)).toBe(null);
+  });
+});

package/templates/{features/i18n → base}/src/core/services/i18n/i18n.ts.hbs

@@ -1,5 +1,6 @@
 import { DEFAULT_LANGUAGE, LANGUAGES, Language, Translations } from './languages.js';
 import { AppEventBus, Service } from '../../index.js';
+import { CONFIG } from '../../config.js';
 
 export class I18n extends Service<I18n> {
   private readonly _DEFAULT_LANGUAGE: Language = DEFAULT_LANGUAGE;
@@ -35,7 +36,11 @@ export class I18n extends Service<I18n> {
     this._currentLanguage = lang;
     this.savePreferences();
     await this.loadTranslations(lang);
-    AppEventBus.emit('language-changed');
+    AppEventBus.emit('language-changed', { lang });
+  }
+
+  public onLanguageChange(callback: (payload: { lang: string }) => void) {
+    AppEventBus.subscribe('language-changed', callback);
   }
 
   public async loadTranslations(lang: Language): Promise<void> {
@@ -99,6 +104,7 @@ export class I18n extends Service<I18n> {
   public resetTranslations(): void {
     this._translations = {};
     this._defaultTranslations = {};
+    localStorage.removeItem(this._localStorageKey);
     this._currentLanguage = this._DEFAULT_LANGUAGE;
   }
 
@@ -107,9 +113,21 @@ export class I18n extends Service<I18n> {
     this.dispose();
   }
 
-  private getPreferredLanguage() {
-    return this.getPreferences() || navigator.language.split('-')[0] as Language;
-  };
+  private getPreferredLanguage(): Language {
+    const urlLocale = this.getLocaleFromUrl();
+    if (urlLocale) return urlLocale;
+    const stored = this.getPreferences();
+    if (stored && this._LANGUAGES.includes(stored as Language)) return stored as Language;
+    const browserLang = navigator.language.split('-')[0] as Language;
+    return this._LANGUAGES.includes(browserLang) ? browserLang : this._DEFAULT_LANGUAGE;
+  }
+
+  private getLocaleFromUrl(): Language | null {
+    if (!CONFIG.i18n) return null;
+
+    const first = window.location.pathname.split('/').filter(Boolean)[0] as Language;
+    return first && this._LANGUAGES.includes(first) ? first : null;
+  }
 
   private async loadDefaultTranslations(): Promise<void> {
     try {