chore: merge pull request #85 from addon-stack/develop

Author: addon-owner

package-lock.json

@@ -122,8 +122,8 @@
     "@addon-core/inject-script": "^0.3.1",
     "@addon-core/storage": "^0.4.0",
     "@rsdoctor/rspack-plugin": "^1.3.11",
-    "@rspack/cli": "^1.6.5",
-    "@rspack/core": "^1.6.5",
+    "@rspack/cli": "^1.6.7",
+    "@rspack/core": "^1.6.7",
     "@svgr/webpack": "^8.1.0",
     "await-lock": "^3.0.0",
     "c12": "^3.3.2",
@@ -155,7 +155,7 @@
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@microsoft/api-extractor": "^7.53.1",
-    "@release-it/conventional-changelog": "^10.0.1",
+    "@release-it/conventional-changelog": "^10.0.4",
     "@swc/core": "^1.11.7",
     "@swc/jest": "^0.2.36",
     "@testing-library/jest-dom": "^6.6.3",
@@ -176,12 +176,12 @@
     "fs-extra": "^11.3.0",
     "globby": "^14.1.0",
     "husky": "^9.1.7",
-    "jest": "^30.0.0",
+    "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.0.0",
     "jest-webextension-mock": "^4.0.0",
     "prettier": "^3.6.2",
-    "release-it": "^19.0.5",
-    "ts-node": "^10.9.2",
+    "release-it": "^19.2.3",
+    "ts-node": "^1.7.1",
     "tsup": "^8.5.0",
     "tsx": "^4.19.2",
     "uglify-js": "^3.19.3",
@@ -206,6 +206,7 @@
     }
   },
   "overrides": {
+    "jsdom": "27.4.0",
     "html-rspack-tags-plugin": {
       "glob": "^10.4.1"
     },

package.json

@@ -43,15 +43,15 @@ export default class LocaleBuilder implements LocaleBuilderContract {
             }
         }
 
-        if (this.browser === Browser.Opera) {
-            /**
-             * The Opera browser does not support RTL languages,
-             * and for Opera you need to directly indicate what kind of language it is.
-             * interface language is always different
-             */
-
-            items.set(LocaleCustomKeyForLanguage, this.language);
-        }
+        /**
+         We inject a locale marker into each `messages.json`.
+         Chrome provides no API to query the effective i18n locale:
+         browser UI language may differ from the translation actually used
+         (Chrome silently falls back to default_locale).
+         Reading this marker via chrome.i18n.getMessage() is the only reliable way
+         to detect the language currently displayed in the extension UI.
+         */
+        items.set(LocaleCustomKeyForLanguage, this.language);
 
         return (this.items = items);
     }

src/cli/builders/locale/LocaleBuilder.ts

@@ -10,9 +10,10 @@ import {Language} from "@typing/locale";
 
 export interface LocaleProviderProps {
     storage?: string | false;
+    container?: string | Element | false;
 }
 
-const LocaleProvider = ({children, storage}: PropsWithChildren<LocaleProviderProps>) => {
+const LocaleProvider = ({children, storage, container = "html"}: PropsWithChildren<LocaleProviderProps>) => {
     const locale = useMemo(() => new DynamicLocale(storage), []);
 
     const [lang, setLang] = useState<Language>(locale.lang());
@@ -26,15 +27,28 @@ const LocaleProvider = ({children, storage}: PropsWithChildren<LocaleProviderPro
     }, []);
 
     const change: LocaleContract["change"] = useCallback((lang): void => {
-        locale.change(lang).catch(err => console.error(`Cannot find locale file for "${lang}" language`, err));
+        locale
+            .change(lang)
+            .catch(err => console.error(`[LocaleProvider] Cannot find locale file for "${lang}" language`, err));
     }, []);
 
     useEffect(() => {
-        const html = document.querySelector("html");
-
-        html?.setAttribute("lang", lang);
-        html?.setAttribute("dir", getLocaleDir(lang));
-    }, [lang]);
+        if (container === false) {
+            return;
+        }
+
+        const element = typeof container === "string" ? document.querySelector(container) : container;
+
+        if (element) {
+            element.setAttribute("lang", lang);
+            element.setAttribute("dir", getLocaleDir(lang));
+
+            return () => {
+                element.removeAttribute("lang");
+                element.removeAttribute("dir");
+            };
+        }
+    }, [lang, container]);
 
     useEffect(() => {
         locale.sync().then(lang => setLang(lang));

src/locale/adapters/react/LocaleProvider.tsx

@@ -1,13 +1,10 @@
-import {getI18nMessage, getI18nUILanguage} from "@addon-core/browser";
+import {getI18nMessage} from "@addon-core/browser";
 
 import AbstractLocale from "./AbstractLocale";
 
-import {convertLocaleKey} from "@locale/utils";
+import {convertLocaleKey, resolveLanguage} from "@locale/utils";
 
-import {isBrowser} from "@main/env";
-
-import {Language, LanguageCodes, LocaleCustomKeyForLanguage, LocaleProvider, LocaleStructure} from "@typing/locale";
-import {Browser} from "@typing/browser";
+import {Language, LocaleCustomKeyForLanguage, LocaleProvider, LocaleStructure} from "@typing/locale";
 
 export interface LocaleNativeStructure extends LocaleStructure {}
 
@@ -18,37 +15,47 @@ export default class NativeLocale extends AbstractLocale<LocaleNativeStructure>
         return (NativeLocale.instance ??= new NativeLocale());
     }
 
-    public lang(): Language {
-        let lang: Language | undefined;
+    private readonly language?: Language;
+
+    constructor() {
+        super();
 
         /**
-         * The Opera browser does not support RTL languages,
-         * and for Opera you need to directly indicate what kind of language it is.
-         * interface language is always different
+         Locale detection note:
+         Chrome does NOT expose an API to get the effective translation locale.
+         getUILanguage() returns browser UI language (e.g., es-MX),
+         even if extension translations fall back to default_locale (e.g., en).
+         To detect the actual language used by i18n, we read a locale marker
+         from messages.json via chrome.i18n.getMessage().
          */
-        if (isBrowser(Browser.Opera)) {
-            lang = getI18nMessage(LocaleCustomKeyForLanguage) as Language;
+        const markerLang = getI18nMessage(LocaleCustomKeyForLanguage);
+        const resolvedLang = resolveLanguage(markerLang);
 
-            if (LanguageCodes.has(lang)) {
-                return lang;
-            }
+        if (!resolvedLang) {
+            console.warn(`[NativeLocale] Unsupported language detected: "${markerLang}".`);
         }
 
-        lang = getI18nUILanguage() as Language;
+        if (markerLang && resolvedLang && markerLang !== resolvedLang) {
+            console.info(`[NativeLocale] Language normalized: using "${resolvedLang}" instead of "${markerLang}".`);
+        }
 
-        if (!lang) {
-            throw new Error("Locale Native: Unable to get UI language");
+        this.language = resolvedLang;
+    }
+
+    public lang(): Language {
+        if (!this.language) {
+            throw new Error("[NativeLocale] Language is not defined. Failed to determine a supported locale.");
         }
 
-        return lang;
+        return this.language;
     }
 
     public keys(): Set<keyof LocaleNativeStructure> {
         try {
             // @ts-expect-error: __ADNBN_LOCALE_KEYS__ is a virtual variable generated by the bundler `src/cli/plugins/locale/index.ts`
             return new Set<string>(__ADNBN_LOCALE_KEYS__);
         } catch (e) {
-            console.error("Locale Native: Unable to get keys", e);
+            console.error("[NativeLocale] Failed to access locale keys. Ensure the bundler plugin is active.", e);
 
             return new Set<string>();
         }
@@ -59,7 +66,7 @@ export default class NativeLocale extends AbstractLocale<LocaleNativeStructure>
             // @ts-expect-error: __ADNBN_DEFINED_LOCALES__ is a virtual variable generated by the bundler `src/cli/plugins/locale/index.ts`
             return new Set<Language>(__ADNBN_DEFINED_LOCALES__);
         } catch (e) {
-            console.error("Locale Native: Unable to get defined locales", e);
+            console.error("[NativeLocale] Failed to access defined locales. Check virtual variables configuration.", e);
 
             return new Set<Language>();
         }

src/locale/providers/NativeLocale.ts

@@ -1,5 +1,6 @@
 import {
     Language,
+    LanguageCodes,
     LocaleDir,
     LocaleKeyMarker,
     LocaleKeysSeparator,
@@ -55,3 +56,17 @@ export const getLocaleDir = (lang: Language): LocaleDir => {
 export const flattenLocaleMessages = (messages: LocaleMessages): Record<string, string> => {
     return Object.fromEntries(Object.entries(messages).map(([key, value]) => [key, value.message]));
 };
+
+export const resolveLanguage = (language?: string): Language | undefined => {
+    if (!language) {
+        return undefined;
+    }
+
+    if (LanguageCodes.has(language as Language)) {
+        return language as Language;
+    }
+
+    const shortLang = language.slice(0, 2) as Language;
+
+    return LanguageCodes.has(shortLang) ? shortLang : undefined;
+};

src/locale/utils.ts

@@ -11,9 +11,10 @@ import {
     MessageType,
 } from "@typing/message";
 
-export default abstract class AbstractMessage<T extends MessageDictionary, TOptions>
-    implements MessageProvider<T, TOptions>
-{
+export default abstract class AbstractMessage<T extends MessageDictionary, TOptions> implements MessageProvider<
+    T,
+    TOptions
+> {
     public abstract send<K extends MessageType<T>>(
         type: K,
         data: MessageData<T, K>,

src/message/providers/AbstractMessage.ts

@@ -53,8 +53,7 @@ export type OffscreenMainHandler<T extends TransportType> = (
 ) => Awaiter<void>;
 
 export interface OffscreenDefinition<T extends TransportType>
-    extends TransportDefinition<OffscreenOptions, T>,
-        OffscreenEntrypointOptions {
+    extends TransportDefinition<OffscreenOptions, T>, OffscreenEntrypointOptions {
     main?: OffscreenMainHandler<T>;
 }
 

src/types/offscreen.ts

@@ -27,7 +27,8 @@ export type RelayMainHandler<T extends TransportType> = (
 ) => Awaiter<void>;
 
 export interface RelayDefinition<T extends TransportType>
-    extends Omit<TransportDefinition<RelayOptions, T>, "main">,
+    extends
+        Omit<TransportDefinition<RelayOptions, T>, "main">,
         Omit<ContentScriptDefinition, "main">,
         RelayEntrypointOptions {
     main?: RelayMainHandler<T>;