adnbn 0.10.0 → 0.12.0

package/dist/locale/providers/CustomLocale.js

@@ -1,7 +1,7 @@
-import { convertLocaleKey } from "../utils.js";
+import { convertLocaleKey } from "./../../shared/locale/index.js";
 import AbstractLocale from "./AbstractLocale.js";
 import { Language } from "./../../types/locale.js";
-class CustomLocale_default extends AbstractLocale {
+class CustomLocale extends AbstractLocale {
   constructor(language = Language.English, data = {}) {
     super();
     this.language = language;
@@ -23,11 +23,12 @@ class CustomLocale_default extends AbstractLocale {
   keys() {
     return new Set(Object.keys(this.data));
   }
-  languages() {
+  langs() {
     return /* @__PURE__ */ new Set([this.lang()]);
   }
   value(key) {
-    const value = this.data[convertLocaleKey(key)];
+    const name = convertLocaleKey(key);
+    const value = Object.hasOwn(this.data, name) ? this.data[name] : void 0;
     if (value === void 0) {
       return void 0;
     }
@@ -35,6 +36,6 @@ class CustomLocale_default extends AbstractLocale {
   }
 }
 export {
-  CustomLocale_default as default
+  CustomLocale as default
 };
 //# sourceMappingURL=CustomLocale.js.map

package/dist/locale/providers/CustomLocale.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/locale/providers/CustomLocale.ts"],"sourcesContent":["import {convertLocaleKey} from \"../utils\";\n\nimport AbstractLocale from \"./AbstractLocale\";\n\nimport {Language, LocaleStructure} from \"@typing/locale\";\n\nexport type CustomLocaleData = Record<string, string>;\n\nexport default class<T extends object = LocaleStructure> extends AbstractLocale<T> {\n    constructor(\n        protected language: Language = Language.English,\n        protected data: CustomLocaleData = {}\n    ) {\n        super();\n    }\n\n    public setLang(lang: Language): this {\n        this.language = lang;\n\n        return this;\n    }\n\n    public setData(data: CustomLocaleData): this {\n        this.data = data;\n\n        return this;\n    }\n\n    public lang(): Language {\n        return this.language;\n    }\n\n    public keys(): Set<keyof T> {\n        return new Set(Object.keys(this.data)) as Set<keyof T>;\n    }\n\n    public languages(): Set<Language> {\n        return new Set([this.lang()]);\n    }\n\n    protected value(key: string): string | undefined {\n        const value = this.data[convertLocaleKey(key)];\n\n        if (value === undefined) {\n            return undefined;\n        }\n\n        return value;\n    }\n}\n"],"mappings":"AAAA,SAAQ,wBAAuB;AAE/B,OAAO,oBAAoB;AAE3B,SAAQ,gBAAgC;AAIxC,MAAO,6BAA0D,eAAkB;AAAA,EAC/E,YACc,WAAqB,SAAS,SAC9B,OAAyB,CAAC,GACtC;AACE,UAAM;AAHI;AACA;AAAA,EAGd;AAAA,EAJc;AAAA,EACA;AAAA,EAKP,QAAQ,MAAsB;AACjC,SAAK,WAAW;AAEhB,WAAO;AAAA,EACX;AAAA,EAEO,QAAQ,MAA8B;AACzC,SAAK,OAAO;AAEZ,WAAO;AAAA,EACX;AAAA,EAEO,OAAiB;AACpB,WAAO,KAAK;AAAA,EAChB;AAAA,EAEO,OAAqB;AACxB,WAAO,IAAI,IAAI,OAAO,KAAK,KAAK,IAAI,CAAC;AAAA,EACzC;AAAA,EAEO,YAA2B;AAC9B,WAAO,oBAAI,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC;AAAA,EAChC;AAAA,EAEU,MAAM,KAAiC;AAC7C,UAAM,QAAQ,KAAK,KAAK,iBAAiB,GAAG,CAAC;AAE7C,QAAI,UAAU,QAAW;AACrB,aAAO;AAAA,IACX;AAEA,WAAO;AAAA,EACX;AACJ;","names":[]}
+{"version":3,"sources":["../../../src/locale/providers/CustomLocale.ts"],"sourcesContent":["import {convertLocaleKey} from \"@shared/locale\";\n\nimport AbstractLocale from \"./AbstractLocale\";\n\nimport {Language, LocaleStructure} from \"@typing/locale\";\n\nexport type CustomLocaleData = Readonly<Record<string, string>>;\n\nexport default class CustomLocale<T extends object = LocaleStructure> extends AbstractLocale<T> {\n    constructor(\n        protected language: Language = Language.English,\n        protected data: CustomLocaleData = {}\n    ) {\n        super();\n    }\n\n    public setLang(lang: Language): this {\n        this.language = lang;\n\n        return this;\n    }\n\n    public setData(data: CustomLocaleData): this {\n        this.data = data;\n\n        return this;\n    }\n\n    public lang(): Language {\n        return this.language;\n    }\n\n    public keys(): Set<keyof T> {\n        return new Set(Object.keys(this.data)) as Set<keyof T>;\n    }\n\n    public langs(): ReadonlySet<Language> {\n        return new Set([this.lang()]);\n    }\n\n    protected value(key: string): string | undefined {\n        const name = convertLocaleKey(key);\n        const value = Object.hasOwn(this.data, name) ? this.data[name] : undefined;\n\n        if (value === undefined) {\n            return undefined;\n        }\n\n        return value;\n    }\n}\n"],"mappings":"AAAA,SAAQ,wBAAuB;AAE/B,OAAO,oBAAoB;AAE3B,SAAQ,gBAAgC;AAIxC,MAAO,qBAAuE,eAAkB;AAAA,EAC5F,YACc,WAAqB,SAAS,SAC9B,OAAyB,CAAC,GACtC;AACE,UAAM;AAHI;AACA;AAAA,EAGd;AAAA,EAJc;AAAA,EACA;AAAA,EAKP,QAAQ,MAAsB;AACjC,SAAK,WAAW;AAEhB,WAAO;AAAA,EACX;AAAA,EAEO,QAAQ,MAA8B;AACzC,SAAK,OAAO;AAEZ,WAAO;AAAA,EACX;AAAA,EAEO,OAAiB;AACpB,WAAO,KAAK;AAAA,EAChB;AAAA,EAEO,OAAqB;AACxB,WAAO,IAAI,IAAI,OAAO,KAAK,KAAK,IAAI,CAAC;AAAA,EACzC;AAAA,EAEO,QAA+B;AAClC,WAAO,oBAAI,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC;AAAA,EAChC;AAAA,EAEU,MAAM,KAAiC;AAC7C,UAAM,OAAO,iBAAiB,GAAG;AACjC,UAAM,QAAQ,OAAO,OAAO,KAAK,MAAM,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI;AAEjE,QAAI,UAAU,QAAW;AACrB,aAAO;AAAA,IACX;AAEA,WAAO;AAAA,EACX;AACJ;","names":[]}

package/dist/locale/providers/DynamicLocale.d.ts

@@ -1,19 +1,26 @@
-import { type StorageProvider } from "@addon-core/storage";
-import NativeLocale, { LocaleNativeStructure } from "./NativeLocale.js";
-import CustomLocale, { CustomLocaleData } from "./CustomLocale.js";
-import { Language, LocaleDynamicProvider } from "../../types/locale.js";
-export default class<T extends object = LocaleNativeStructure> extends NativeLocale<T> implements LocaleDynamicProvider<T> {
-    protected cache: Map<Language, CustomLocaleData>;
-    protected locale?: CustomLocale<T>;
-    protected storage?: StorageProvider<Record<string, Language>>;
-    protected storageKey?: string;
+import AbstractLocale from "./AbstractLocale.js";
+import { Language, type LocaleDynamicProvider, type LocaleRegistry, type LocaleStorageDriver } from "../../types/locale.js";
+export default class DynamicLocale<T extends object = LocaleRegistry> extends AbstractLocale<T> implements LocaleDynamicProvider<T> {
+    private language;
+    private data;
+    protected storage?: LocaleStorageDriver;
     protected unsubscribe?: () => void;
-    constructor(storage?: string | false);
+    constructor(storage?: LocaleStorageDriver | false);
+    /**
+     * Selects a language synchronously without saving it.
+     * With storage enabled, a later sync() or watched storage update can replace this local selection.
+     * @throws If the language is absent from the catalogue.
+     */
+    select(lang: Language): Language;
+    /** Selects a language immediately and saves it when storage is enabled. */
     change(lang: Language): Promise<Language>;
     sync(): Promise<Language>;
     watch(handler?: (lang: Language) => void): () => void;
     unwatch(): void;
     lang(): Language;
+    /** Completed messages for the current language, with underscore keys and no substitutions applied. */
+    messages(): Readonly<Record<string, string>>;
+    keys(): Set<keyof T>;
+    langs(): ReadonlySet<Language>;
     protected value(key: Extract<keyof T, string>): string | undefined;
-    protected fetch(lang: Language): Promise<CustomLocaleData>;
 }

package/dist/locale/providers/DynamicLocale.js

@@ -1,58 +1,74 @@
-import { flattenLocaleMessages, getLocaleFilename } from "../utils.js";
-import { Storage } from "@addon-core/storage";
-import NativeLocale from "./NativeLocale.js";
-import CustomLocale from "./CustomLocale.js";
-import { LanguageCodes } from "./../../types/locale.js";
-class DynamicLocale_default extends NativeLocale {
-  cache = /* @__PURE__ */ new Map();
-  locale;
+import { getI18nMessage } from "@addon-core/browser";
+import catalogue, { keys, lang as defaultLanguage, languages } from "#adnbn/locale";
+import AbstractLocale from "./AbstractLocale.js";
+import { LocaleStorage } from "../storage/index.js";
+import { convertLocaleKey, resolveLanguage } from "./../../shared/locale/index.js";
+import {
+  LocaleCustomKeyForLanguage
+} from "./../../types/locale.js";
+class DynamicLocale extends AbstractLocale {
+  language;
+  data;
   storage;
-  storageKey;
   unsubscribe;
-  constructor(storage = "lang") {
+  constructor(storage) {
     super();
-    if (storage) {
-      this.storageKey = storage;
-      this.storage = Storage.Local();
+    let marker;
+    try {
+      marker = getI18nMessage(LocaleCustomKeyForLanguage);
+    } catch {
     }
+    this.select(resolveLanguage(marker) ?? defaultLanguage);
+    this.storage = storage === false ? void 0 : storage ?? new LocaleStorage();
   }
-  async change(lang) {
-    if (lang === this.lang()) {
-      return lang;
+  /**
+   * Selects a language synchronously without saving it.
+   * With storage enabled, a later sync() or watched storage update can replace this local selection.
+   * @throws If the language is absent from the catalogue.
+   */
+  select(lang) {
+    if (!Object.hasOwn(catalogue, lang)) {
+      throw new Error(`[DynamicLocale] Language "${lang}" is not available in the catalogue.`);
     }
-    const messages = await this.fetch(lang);
-    (this.locale ?? (this.locale = new CustomLocale())).setLang(lang).setData(messages);
-    if (this.storage && this.storageKey) {
-      await this.storage.set(this.storageKey, lang);
+    this.language = lang;
+    this.data = catalogue[lang];
+    return lang;
+  }
+  /** Selects a language immediately and saves it when storage is enabled. */
+  async change(lang) {
+    this.select(lang);
+    if (this.storage) {
+      await this.storage.set(lang);
     }
     return lang;
   }
   async sync() {
-    if (!this.storage || !this.storageKey) {
+    if (!this.storage) {
       throw new Error("Language is not saving in storage");
     }
-    const lang = await this.storage.get(this.storageKey);
+    const lang = await this.storage.get();
     if (!lang) {
       return this.lang();
     }
-    if (!LanguageCodes.has(lang)) {
+    if (!Object.hasOwn(catalogue, lang)) {
       console.warn(`Incorrect language code in storage - "${lang}"`);
       return this.lang();
     }
-    return this.change(lang);
+    return this.select(lang);
   }
   watch(handler) {
-    if (!this.storage || !this.storageKey) {
+    if (!this.storage) {
       throw new Error("Language is not saved in storage");
     }
     if (this.unsubscribe) {
       throw new Error("Already subscribed to language changes in storage");
     }
-    this.unsubscribe = this.storage.watch({
-      [this.storageKey]: (newValue) => {
-        if (newValue) {
-          this.change(newValue).then(() => handler && handler(newValue)).catch((err) => console.error("Error while changing language:", err));
-        }
+    this.unsubscribe = this.storage.watch((lang) => {
+      try {
+        this.select(lang);
+        handler == null ? void 0 : handler(lang);
+      } catch (error) {
+        console.error("Error while changing language:", error);
       }
     });
     return this.unwatch.bind(this);
@@ -63,27 +79,24 @@ class DynamicLocale_default extends NativeLocale {
     this.unsubscribe = void 0;
   }
   lang() {
-    var _a;
-    return ((_a = this.locale) == null ? void 0 : _a.lang()) || super.lang();
+    return this.language;
   }
-  value(key) {
-    var _a;
-    return ((_a = this.locale) == null ? void 0 : _a.get(key)) ?? super.value(key);
+  /** Completed messages for the current language, with underscore keys and no substitutions applied. */
+  messages() {
+    return this.data;
   }
-  async fetch(lang) {
-    let messages = this.cache.get(lang);
-    if (!messages) {
-      const response = await (await fetch(getLocaleFilename(lang))).json();
-      if (!response || typeof response !== "object") {
-        throw new Error(`Invalid or empty locale data for "${lang}"`);
-      }
-      messages = flattenLocaleMessages(response);
-      this.cache.set(lang, messages);
-    }
-    return messages;
+  keys() {
+    return new Set(keys);
+  }
+  langs() {
+    return new Set(languages);
+  }
+  value(key) {
+    const name = convertLocaleKey(key);
+    return Object.hasOwn(this.data, name) ? this.data[name] : void 0;
   }
 }
 export {
-  DynamicLocale_default as default
+  DynamicLocale as default
 };
 //# sourceMappingURL=DynamicLocale.js.map

package/dist/locale/providers/DynamicLocale.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/locale/providers/DynamicLocale.ts"],"sourcesContent":["import {flattenLocaleMessages, getLocaleFilename} from \"../utils\";\n\nimport {Storage, type StorageProvider} from \"@addon-core/storage\";\n\nimport NativeLocale, {LocaleNativeStructure} from \"./NativeLocale\";\nimport CustomLocale, {CustomLocaleData} from \"./CustomLocale\";\n\nimport {Language, LanguageCodes, LocaleDynamicProvider, LocaleMessages} from \"@typing/locale\";\n\nexport default class<T extends object = LocaleNativeStructure>\n    extends NativeLocale<T>\n    implements LocaleDynamicProvider<T>\n{\n    protected cache = new Map<Language, CustomLocaleData>();\n\n    protected locale?: CustomLocale<T>;\n\n    protected storage?: StorageProvider<Record<string, Language>>;\n    protected storageKey?: string;\n\n    protected unsubscribe?: () => void;\n\n    constructor(storage: string | false = \"lang\") {\n        super();\n\n        if (storage) {\n            this.storageKey = storage;\n            this.storage = Storage.Local();\n        }\n    }\n\n    public async change(lang: Language): Promise<Language> {\n        if (lang === this.lang()) {\n            return lang;\n        }\n\n        const messages = await this.fetch(lang);\n\n        (this.locale ??= new CustomLocale()).setLang(lang).setData(messages);\n\n        if (this.storage && this.storageKey) {\n            await this.storage.set(this.storageKey, lang);\n        }\n\n        return lang;\n    }\n\n    public async sync(): Promise<Language> {\n        if (!this.storage || !this.storageKey) {\n            throw new Error(\"Language is not saving in storage\");\n        }\n\n        const lang = await this.storage.get(this.storageKey);\n\n        if (!lang) {\n            return this.lang();\n        }\n\n        if (!LanguageCodes.has(lang)) {\n            console.warn(`Incorrect language code in storage - \"${lang}\"`);\n\n            return this.lang();\n        }\n\n        return this.change(lang);\n    }\n\n    public watch(handler?: (lang: Language) => void): () => void {\n        if (!this.storage || !this.storageKey) {\n            throw new Error(\"Language is not saved in storage\");\n        }\n\n        if (this.unsubscribe) {\n            throw new Error(\"Already subscribed to language changes in storage\");\n        }\n\n        this.unsubscribe = this.storage.watch({\n            [this.storageKey]: newValue => {\n                if (newValue) {\n                    this.change(newValue)\n                        .then(() => handler && handler(newValue))\n                        .catch(err => console.error(\"Error while changing language:\", err));\n                }\n            },\n        });\n\n        return this.unwatch.bind(this);\n    }\n\n    public unwatch(): void {\n        this.unsubscribe?.();\n        this.unsubscribe = undefined;\n    }\n\n    public lang(): Language {\n        return this.locale?.lang() || super.lang();\n    }\n\n    protected value(key: Extract<keyof T, string>): string | undefined {\n        return this.locale?.get(key) ?? super.value(key);\n    }\n\n    protected async fetch(lang: Language): Promise<CustomLocaleData> {\n        let messages = this.cache.get(lang);\n\n        if (!messages) {\n            const response: LocaleMessages = await (await fetch(getLocaleFilename(lang))).json();\n\n            if (!response || typeof response !== \"object\") {\n                throw new Error(`Invalid or empty locale data for \"${lang}\"`);\n            }\n\n            messages = flattenLocaleMessages(response);\n\n            this.cache.set(lang, messages);\n        }\n\n        return messages;\n    }\n}\n"],"mappings":"AAAA,SAAQ,uBAAuB,yBAAwB;AAEvD,SAAQ,eAAoC;AAE5C,OAAO,kBAA2C;AAClD,OAAO,kBAAsC;AAE7C,SAAkB,qBAA2D;AAE7E,MAAO,8BACK,aAEZ;AAAA,EACc,QAAQ,oBAAI,IAAgC;AAAA,EAE5C;AAAA,EAEA;AAAA,EACA;AAAA,EAEA;AAAA,EAEV,YAAY,UAA0B,QAAQ;AAC1C,UAAM;AAEN,QAAI,SAAS;AACT,WAAK,aAAa;AAClB,WAAK,UAAU,QAAQ,MAAM;AAAA,IACjC;AAAA,EACJ;AAAA,EAEA,MAAa,OAAO,MAAmC;AACnD,QAAI,SAAS,KAAK,KAAK,GAAG;AACtB,aAAO;AAAA,IACX;AAEA,UAAM,WAAW,MAAM,KAAK,MAAM,IAAI;AAEtC,KAAC,KAAK,WAAL,KAAK,SAAW,IAAI,aAAa,IAAG,QAAQ,IAAI,EAAE,QAAQ,QAAQ;AAEnE,QAAI,KAAK,WAAW,KAAK,YAAY;AACjC,YAAM,KAAK,QAAQ,IAAI,KAAK,YAAY,IAAI;AAAA,IAChD;AAEA,WAAO;AAAA,EACX;AAAA,EAEA,MAAa,OAA0B;AACnC,QAAI,CAAC,KAAK,WAAW,CAAC,KAAK,YAAY;AACnC,YAAM,IAAI,MAAM,mCAAmC;AAAA,IACvD;AAEA,UAAM,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,UAAU;AAEnD,QAAI,CAAC,MAAM;AACP,aAAO,KAAK,KAAK;AAAA,IACrB;AAEA,QAAI,CAAC,cAAc,IAAI,IAAI,GAAG;AAC1B,cAAQ,KAAK,yCAAyC,IAAI,GAAG;AAE7D,aAAO,KAAK,KAAK;AAAA,IACrB;AAEA,WAAO,KAAK,OAAO,IAAI;AAAA,EAC3B;AAAA,EAEO,MAAM,SAAgD;AACzD,QAAI,CAAC,KAAK,WAAW,CAAC,KAAK,YAAY;AACnC,YAAM,IAAI,MAAM,kCAAkC;AAAA,IACtD;AAEA,QAAI,KAAK,aAAa;AAClB,YAAM,IAAI,MAAM,mDAAmD;AAAA,IACvE;AAEA,SAAK,cAAc,KAAK,QAAQ,MAAM;AAAA,MAClC,CAAC,KAAK,UAAU,GAAG,cAAY;AAC3B,YAAI,UAAU;AACV,eAAK,OAAO,QAAQ,EACf,KAAK,MAAM,WAAW,QAAQ,QAAQ,CAAC,EACvC,MAAM,SAAO,QAAQ,MAAM,kCAAkC,GAAG,CAAC;AAAA,QAC1E;AAAA,MACJ;AAAA,IACJ,CAAC;AAED,WAAO,KAAK,QAAQ,KAAK,IAAI;AAAA,EACjC;AAAA,EAEO,UAAgB;AAzF3B;AA0FQ,eAAK,gBAAL;AACA,SAAK,cAAc;AAAA,EACvB;AAAA,EAEO,OAAiB;AA9F5B;AA+FQ,aAAO,UAAK,WAAL,mBAAa,WAAU,MAAM,KAAK;AAAA,EAC7C;AAAA,EAEU,MAAM,KAAmD;AAlGvE;AAmGQ,aAAO,UAAK,WAAL,mBAAa,IAAI,SAAQ,MAAM,MAAM,GAAG;AAAA,EACnD;AAAA,EAEA,MAAgB,MAAM,MAA2C;AAC7D,QAAI,WAAW,KAAK,MAAM,IAAI,IAAI;AAElC,QAAI,CAAC,UAAU;AACX,YAAM,WAA2B,OAAO,MAAM,MAAM,kBAAkB,IAAI,CAAC,GAAG,KAAK;AAEnF,UAAI,CAAC,YAAY,OAAO,aAAa,UAAU;AAC3C,cAAM,IAAI,MAAM,qCAAqC,IAAI,GAAG;AAAA,MAChE;AAEA,iBAAW,sBAAsB,QAAQ;AAEzC,WAAK,MAAM,IAAI,MAAM,QAAQ;AAAA,IACjC;AAEA,WAAO;AAAA,EACX;AACJ;","names":[]}
+{"version":3,"sources":["../../../src/locale/providers/DynamicLocale.ts"],"sourcesContent":["import {getI18nMessage} from \"@addon-core/browser\";\n\nimport catalogue, {keys, lang as defaultLanguage, languages} from \"#adnbn/locale\";\n\nimport AbstractLocale from \"./AbstractLocale\";\nimport {LocaleStorage} from \"../storage\";\n\nimport {convertLocaleKey, resolveLanguage} from \"@shared/locale\";\nimport {\n    Language,\n    LocaleCustomKeyForLanguage,\n    type LocaleDynamicProvider,\n    type LocaleRegistry,\n    type LocaleStorageDriver,\n} from \"@typing/locale\";\n\nexport default class DynamicLocale<T extends object = LocaleRegistry>\n    extends AbstractLocale<T>\n    implements LocaleDynamicProvider<T>\n{\n    private language!: Language;\n    private data!: Readonly<Record<string, string>>;\n\n    protected storage?: LocaleStorageDriver;\n    protected unsubscribe?: () => void;\n\n    constructor(storage?: LocaleStorageDriver | false) {\n        super();\n\n        let marker: string | undefined;\n\n        try {\n            marker = getI18nMessage(LocaleCustomKeyForLanguage);\n        } catch {\n            // MAIN has no extension i18n; use the configured language from the bundled catalogue.\n        }\n\n        this.select(resolveLanguage(marker) ?? defaultLanguage);\n\n        this.storage = storage === false ? undefined : (storage ?? new LocaleStorage());\n    }\n\n    /**\n     * Selects a language synchronously without saving it.\n     * With storage enabled, a later sync() or watched storage update can replace this local selection.\n     * @throws If the language is absent from the catalogue.\n     */\n    public select(lang: Language): Language {\n        if (!Object.hasOwn(catalogue, lang)) {\n            throw new Error(`[DynamicLocale] Language \"${lang}\" is not available in the catalogue.`);\n        }\n\n        this.language = lang;\n        this.data = catalogue[lang]!;\n\n        return lang;\n    }\n\n    /** Selects a language immediately and saves it when storage is enabled. */\n    public async change(lang: Language): Promise<Language> {\n        this.select(lang);\n\n        if (this.storage) {\n            await this.storage.set(lang);\n        }\n\n        return lang;\n    }\n\n    public async sync(): Promise<Language> {\n        if (!this.storage) {\n            throw new Error(\"Language is not saving in storage\");\n        }\n\n        const lang = await this.storage.get();\n\n        if (!lang) {\n            return this.lang();\n        }\n\n        if (!Object.hasOwn(catalogue, lang)) {\n            console.warn(`Incorrect language code in storage - \"${lang}\"`);\n\n            return this.lang();\n        }\n\n        return this.select(lang);\n    }\n\n    public watch(handler?: (lang: Language) => void): () => void {\n        if (!this.storage) {\n            throw new Error(\"Language is not saved in storage\");\n        }\n\n        if (this.unsubscribe) {\n            throw new Error(\"Already subscribed to language changes in storage\");\n        }\n\n        this.unsubscribe = this.storage.watch(lang => {\n            try {\n                this.select(lang);\n                handler?.(lang);\n            } catch (error) {\n                console.error(\"Error while changing language:\", error);\n            }\n        });\n\n        return this.unwatch.bind(this);\n    }\n\n    public unwatch(): void {\n        this.unsubscribe?.();\n        this.unsubscribe = undefined;\n    }\n\n    public lang(): Language {\n        return this.language;\n    }\n\n    /** Completed messages for the current language, with underscore keys and no substitutions applied. */\n    public messages(): Readonly<Record<string, string>> {\n        return this.data;\n    }\n\n    public keys(): Set<keyof T> {\n        return new Set(keys) as Set<keyof T>;\n    }\n\n    public langs(): ReadonlySet<Language> {\n        return new Set(languages);\n    }\n\n    protected value(key: Extract<keyof T, string>): string | undefined {\n        const name = convertLocaleKey(key);\n\n        return Object.hasOwn(this.data, name) ? this.data[name] : undefined;\n    }\n}\n"],"mappings":"AAAA,SAAQ,sBAAqB;AAE7B,OAAO,aAAY,MAAM,QAAQ,iBAAiB,iBAAgB;AAElE,OAAO,oBAAoB;AAC3B,SAAQ,qBAAoB;AAE5B,SAAQ,kBAAkB,uBAAsB;AAChD;AAAA,EAEI;AAAA,OAIG;AAEP,MAAO,sBACK,eAEZ;AAAA,EACY;AAAA,EACA;AAAA,EAEE;AAAA,EACA;AAAA,EAEV,YAAY,SAAuC;AAC/C,UAAM;AAEN,QAAI;AAEJ,QAAI;AACA,eAAS,eAAe,0BAA0B;AAAA,IACtD,QAAQ;AAAA,IAER;AAEA,SAAK,OAAO,gBAAgB,MAAM,KAAK,eAAe;AAEtD,SAAK,UAAU,YAAY,QAAQ,SAAa,WAAW,IAAI,cAAc;AAAA,EACjF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,OAAO,MAA0B;AACpC,QAAI,CAAC,OAAO,OAAO,WAAW,IAAI,GAAG;AACjC,YAAM,IAAI,MAAM,6BAA6B,IAAI,sCAAsC;AAAA,IAC3F;AAEA,SAAK,WAAW;AAChB,SAAK,OAAO,UAAU,IAAI;AAE1B,WAAO;AAAA,EACX;AAAA;AAAA,EAGA,MAAa,OAAO,MAAmC;AACnD,SAAK,OAAO,IAAI;AAEhB,QAAI,KAAK,SAAS;AACd,YAAM,KAAK,QAAQ,IAAI,IAAI;AAAA,IAC/B;AAEA,WAAO;AAAA,EACX;AAAA,EAEA,MAAa,OAA0B;AACnC,QAAI,CAAC,KAAK,SAAS;AACf,YAAM,IAAI,MAAM,mCAAmC;AAAA,IACvD;AAEA,UAAM,OAAO,MAAM,KAAK,QAAQ,IAAI;AAEpC,QAAI,CAAC,MAAM;AACP,aAAO,KAAK,KAAK;AAAA,IACrB;AAEA,QAAI,CAAC,OAAO,OAAO,WAAW,IAAI,GAAG;AACjC,cAAQ,KAAK,yCAAyC,IAAI,GAAG;AAE7D,aAAO,KAAK,KAAK;AAAA,IACrB;AAEA,WAAO,KAAK,OAAO,IAAI;AAAA,EAC3B;AAAA,EAEO,MAAM,SAAgD;AACzD,QAAI,CAAC,KAAK,SAAS;AACf,YAAM,IAAI,MAAM,kCAAkC;AAAA,IACtD;AAEA,QAAI,KAAK,aAAa;AAClB,YAAM,IAAI,MAAM,mDAAmD;AAAA,IACvE;AAEA,SAAK,cAAc,KAAK,QAAQ,MAAM,UAAQ;AAC1C,UAAI;AACA,aAAK,OAAO,IAAI;AAChB,2CAAU;AAAA,MACd,SAAS,OAAO;AACZ,gBAAQ,MAAM,kCAAkC,KAAK;AAAA,MACzD;AAAA,IACJ,CAAC;AAED,WAAO,KAAK,QAAQ,KAAK,IAAI;AAAA,EACjC;AAAA,EAEO,UAAgB;AA9G3B;AA+GQ,eAAK,gBAAL;AACA,SAAK,cAAc;AAAA,EACvB;AAAA,EAEO,OAAiB;AACpB,WAAO,KAAK;AAAA,EAChB;AAAA;AAAA,EAGO,WAA6C;AAChD,WAAO,KAAK;AAAA,EAChB;AAAA,EAEO,OAAqB;AACxB,WAAO,IAAI,IAAI,IAAI;AAAA,EACvB;AAAA,EAEO,QAA+B;AAClC,WAAO,IAAI,IAAI,SAAS;AAAA,EAC5B;AAAA,EAEU,MAAM,KAAmD;AAC/D,UAAM,OAAO,iBAAiB,GAAG;AAEjC,WAAO,OAAO,OAAO,KAAK,MAAM,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI;AAAA,EAC9D;AACJ;","names":[]}

package/dist/locale/providers/NativeLocale.d.ts

@@ -1,15 +1,12 @@
 import AbstractLocale from "./AbstractLocale.js";
-import { Language, LocaleProvider } from "../../types/locale.js";
-/** Augmented by the generated .adnbn/locale.d.ts for the current app. */
-export interface LocaleNativeStructure {
-}
-export default class NativeLocale<S extends object = LocaleNativeStructure> extends AbstractLocale<S> {
+import { Language, type LocaleRegistry } from "../../types/locale.js";
+export default class NativeLocale<S extends object = LocaleRegistry> extends AbstractLocale<S> {
     private static instance?;
-    static getInstance(): LocaleProvider<LocaleNativeStructure>;
+    static getInstance(): NativeLocale<LocaleRegistry>;
     private readonly language?;
     constructor();
     lang(): Language;
     keys(): Set<keyof S>;
-    languages(): Set<Language>;
+    langs(): ReadonlySet<Language>;
     protected value(key: Extract<keyof S, string>): string | undefined;
 }

package/dist/locale/providers/NativeLocale.js

@@ -1,6 +1,7 @@
 import { getI18nMessage } from "@addon-core/browser";
+import { keys, languages } from "#adnbn/locale";
 import AbstractLocale from "./AbstractLocale.js";
-import { convertLocaleKey, resolveLanguage } from "./../../locale/utils.js";
+import { convertLocaleKey, resolveLanguage } from "./../../shared/locale/index.js";
 import { LocaleCustomKeyForLanguage } from "./../../types/locale.js";
 class NativeLocale extends AbstractLocale {
   static instance;
@@ -27,20 +28,10 @@ class NativeLocale extends AbstractLocale {
     return this.language;
   }
   keys() {
-    try {
-      return new Set(__ADNBN_LOCALE_KEYS__);
-    } catch (e) {
-      console.error("[NativeLocale] Failed to access locale keys. Ensure the bundler plugin is active.", e);
-      return /* @__PURE__ */ new Set();
-    }
+    return new Set(keys);
   }
-  languages() {
-    try {
-      return new Set(__ADNBN_DEFINED_LOCALES__);
-    } catch (e) {
-      console.error("[NativeLocale] Failed to access defined locales. Check virtual variables configuration.", e);
-      return /* @__PURE__ */ new Set();
-    }
+  langs() {
+    return new Set(languages);
   }
   value(key) {
     const value = getI18nMessage(convertLocaleKey(key));

package/dist/locale/providers/NativeLocale.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/locale/providers/NativeLocale.ts"],"sourcesContent":["import {getI18nMessage} from \"@addon-core/browser\";\n\nimport AbstractLocale from \"./AbstractLocale\";\n\nimport {convertLocaleKey, resolveLanguage} from \"@locale/utils\";\n\nimport {Language, LocaleCustomKeyForLanguage, LocaleProvider} from \"@typing/locale\";\n\n/** Augmented by the generated .adnbn/locale.d.ts for the current app. */\nexport interface LocaleNativeStructure {}\n\nexport default class NativeLocale<S extends object = LocaleNativeStructure> extends AbstractLocale<S> {\n    private static instance?: LocaleProvider<LocaleNativeStructure>;\n\n    public static getInstance(): LocaleProvider<LocaleNativeStructure> {\n        return (NativeLocale.instance ??= new NativeLocale());\n    }\n\n    private readonly language?: Language;\n\n    constructor() {\n        super();\n\n        /**\n         Locale detection note:\n         Chrome does NOT expose an API to get the effective translation locale.\n         getUILanguage() returns browser UI language (e.g., es-MX),\n         even if extension translations fall back to default_locale (e.g., en).\n         To detect the actual language used by i18n, we read a locale marker\n         from messages.json via chrome.i18n.getMessage().\n         */\n        const markerLang = getI18nMessage(LocaleCustomKeyForLanguage);\n        const resolvedLang = resolveLanguage(markerLang);\n\n        if (!resolvedLang) {\n            console.warn(`[NativeLocale] Unsupported language detected: \"${markerLang}\".`);\n        }\n\n        if (markerLang && resolvedLang && markerLang !== resolvedLang) {\n            console.info(`[NativeLocale] Language normalized: using \"${resolvedLang}\" instead of \"${markerLang}\".`);\n        }\n\n        this.language = resolvedLang;\n    }\n\n    public lang(): Language {\n        if (!this.language) {\n            throw new Error(\"[NativeLocale] Language is not defined. Failed to determine a supported locale.\");\n        }\n\n        return this.language;\n    }\n\n    public keys(): Set<keyof S> {\n        try {\n            // @ts-expect-error: __ADNBN_LOCALE_KEYS__ is a virtual variable generated by the bundler `src/cli/plugins/locale/index.ts`\n            return new Set<string>(__ADNBN_LOCALE_KEYS__) as Set<keyof S>;\n        } catch (e) {\n            console.error(\"[NativeLocale] Failed to access locale keys. Ensure the bundler plugin is active.\", e);\n\n            return new Set<keyof S>();\n        }\n    }\n\n    public languages(): Set<Language> {\n        try {\n            // @ts-expect-error: __ADNBN_DEFINED_LOCALES__ is a virtual variable generated by the bundler `src/cli/plugins/locale/index.ts`\n            return new Set<Language>(__ADNBN_DEFINED_LOCALES__);\n        } catch (e) {\n            console.error(\"[NativeLocale] Failed to access defined locales. Check virtual variables configuration.\", e);\n\n            return new Set<Language>();\n        }\n    }\n\n    protected value(key: Extract<keyof S, string>): string | undefined {\n        const value = getI18nMessage(convertLocaleKey(key));\n\n        // Native i18n returns an empty string for missing messages too; build keys distinguish valid empty translations.\n        if (value === \"\" && !this.keys().has(key)) {\n            return undefined;\n        }\n\n        return value;\n    }\n}\n"],"mappings":"AAAA,SAAQ,sBAAqB;AAE7B,OAAO,oBAAoB;AAE3B,SAAQ,kBAAkB,uBAAsB;AAEhD,SAAkB,kCAAiD;AAKnE,MAAO,qBAA6E,eAAkB;AAAA,EAClG,OAAe;AAAA,EAEf,OAAc,cAAqD;AAC/D,WAAQ,aAAa,aAAb,aAAa,WAAa,IAAI,aAAa;AAAA,EACvD;AAAA,EAEiB;AAAA,EAEjB,cAAc;AACV,UAAM;AAUN,UAAM,aAAa,eAAe,0BAA0B;AAC5D,UAAM,eAAe,gBAAgB,UAAU;AAE/C,QAAI,CAAC,cAAc;AACf,cAAQ,KAAK,kDAAkD,UAAU,IAAI;AAAA,IACjF;AAEA,QAAI,cAAc,gBAAgB,eAAe,cAAc;AAC3D,cAAQ,KAAK,8CAA8C,YAAY,iBAAiB,UAAU,IAAI;AAAA,IAC1G;AAEA,SAAK,WAAW;AAAA,EACpB;AAAA,EAEO,OAAiB;AACpB,QAAI,CAAC,KAAK,UAAU;AAChB,YAAM,IAAI,MAAM,iFAAiF;AAAA,IACrG;AAEA,WAAO,KAAK;AAAA,EAChB;AAAA,EAEO,OAAqB;AACxB,QAAI;AAEA,aAAO,IAAI,IAAY,qBAAqB;AAAA,IAChD,SAAS,GAAG;AACR,cAAQ,MAAM,qFAAqF,CAAC;AAEpG,aAAO,oBAAI,IAAa;AAAA,IAC5B;AAAA,EACJ;AAAA,EAEO,YAA2B;AAC9B,QAAI;AAEA,aAAO,IAAI,IAAc,yBAAyB;AAAA,IACtD,SAAS,GAAG;AACR,cAAQ,MAAM,2FAA2F,CAAC;AAE1G,aAAO,oBAAI,IAAc;AAAA,IAC7B;AAAA,EACJ;AAAA,EAEU,MAAM,KAAmD;AAC/D,UAAM,QAAQ,eAAe,iBAAiB,GAAG,CAAC;AAGlD,QAAI,UAAU,MAAM,CAAC,KAAK,KAAK,EAAE,IAAI,GAAG,GAAG;AACvC,aAAO;AAAA,IACX;AAEA,WAAO;AAAA,EACX;AACJ;","names":[]}
+{"version":3,"sources":["../../../src/locale/providers/NativeLocale.ts"],"sourcesContent":["import {getI18nMessage} from \"@addon-core/browser\";\nimport {keys, languages} from \"#adnbn/locale\";\n\nimport AbstractLocale from \"./AbstractLocale\";\n\nimport {convertLocaleKey, resolveLanguage} from \"@shared/locale\";\n\nimport {Language, LocaleCustomKeyForLanguage, type LocaleRegistry} from \"@typing/locale\";\n\nexport default class NativeLocale<S extends object = LocaleRegistry> extends AbstractLocale<S> {\n    private static instance?: NativeLocale<LocaleRegistry>;\n\n    public static getInstance(): NativeLocale<LocaleRegistry> {\n        return (NativeLocale.instance ??= new NativeLocale());\n    }\n\n    private readonly language?: Language;\n\n    constructor() {\n        super();\n\n        /**\n         Locale detection note:\n         Chrome does NOT expose an API to get the effective translation locale.\n         getUILanguage() returns browser UI language (e.g., es-MX),\n         even if extension translations fall back to default_locale (e.g., en).\n         To detect the actual language used by i18n, we read a locale marker\n         from messages.json via chrome.i18n.getMessage().\n         */\n        const markerLang = getI18nMessage(LocaleCustomKeyForLanguage);\n        const resolvedLang = resolveLanguage(markerLang);\n\n        if (!resolvedLang) {\n            console.warn(`[NativeLocale] Unsupported language detected: \"${markerLang}\".`);\n        }\n\n        if (markerLang && resolvedLang && markerLang !== resolvedLang) {\n            console.info(`[NativeLocale] Language normalized: using \"${resolvedLang}\" instead of \"${markerLang}\".`);\n        }\n\n        this.language = resolvedLang;\n    }\n\n    public lang(): Language {\n        if (!this.language) {\n            throw new Error(\"[NativeLocale] Language is not defined. Failed to determine a supported locale.\");\n        }\n\n        return this.language;\n    }\n\n    public keys(): Set<keyof S> {\n        return new Set(keys) as Set<keyof S>;\n    }\n\n    public langs(): ReadonlySet<Language> {\n        return new Set(languages);\n    }\n\n    protected value(key: Extract<keyof S, string>): string | undefined {\n        const value = getI18nMessage(convertLocaleKey(key));\n\n        // Native i18n returns an empty string for missing messages too; build keys distinguish valid empty translations.\n        if (value === \"\" && !this.keys().has(key)) {\n            return undefined;\n        }\n\n        return value;\n    }\n}\n"],"mappings":"AAAA,SAAQ,sBAAqB;AAC7B,SAAQ,MAAM,iBAAgB;AAE9B,OAAO,oBAAoB;AAE3B,SAAQ,kBAAkB,uBAAsB;AAEhD,SAAkB,kCAAsD;AAExE,MAAO,qBAAsE,eAAkB;AAAA,EAC3F,OAAe;AAAA,EAEf,OAAc,cAA4C;AACtD,WAAQ,aAAa,aAAb,aAAa,WAAa,IAAI,aAAa;AAAA,EACvD;AAAA,EAEiB;AAAA,EAEjB,cAAc;AACV,UAAM;AAUN,UAAM,aAAa,eAAe,0BAA0B;AAC5D,UAAM,eAAe,gBAAgB,UAAU;AAE/C,QAAI,CAAC,cAAc;AACf,cAAQ,KAAK,kDAAkD,UAAU,IAAI;AAAA,IACjF;AAEA,QAAI,cAAc,gBAAgB,eAAe,cAAc;AAC3D,cAAQ,KAAK,8CAA8C,YAAY,iBAAiB,UAAU,IAAI;AAAA,IAC1G;AAEA,SAAK,WAAW;AAAA,EACpB;AAAA,EAEO,OAAiB;AACpB,QAAI,CAAC,KAAK,UAAU;AAChB,YAAM,IAAI,MAAM,iFAAiF;AAAA,IACrG;AAEA,WAAO,KAAK;AAAA,EAChB;AAAA,EAEO,OAAqB;AACxB,WAAO,IAAI,IAAI,IAAI;AAAA,EACvB;AAAA,EAEO,QAA+B;AAClC,WAAO,IAAI,IAAI,SAAS;AAAA,EAC5B;AAAA,EAEU,MAAM,KAAmD;AAC/D,UAAM,QAAQ,eAAe,iBAAiB,GAAG,CAAC;AAGlD,QAAI,UAAU,MAAM,CAAC,KAAK,KAAK,EAAE,IAAI,GAAG,GAAG;AACvC,aAAO;AAAA,IACX;AAEA,WAAO;AAAA,EACX;AACJ;","names":[]}

package/dist/locale/providers/ObservableLocale.d.ts

@@ -0,0 +1,35 @@
+import type { Language, LocaleDynamicProvider, LocaleNonPluralKeys, LocalePluralKeys, LocaleRegistry, LocaleSnapshot, LocaleStorageDriver, LocaleSubstitutionArgs, LocaleSubstitutionValue } from "../../types/locale.js";
+/** Dynamic translations with shared instances and subscriptions independent of any UI framework. */
+export default class ObservableLocale<T extends object = LocaleRegistry> implements LocaleDynamicProvider<T> {
+    private static defaultInstance?;
+    private static memoryInstance?;
+    private static readonly drivers;
+    static getInstance(storage?: LocaleStorageDriver | false): ObservableLocale;
+    private readonly locale;
+    private readonly storage?;
+    private readonly listeners;
+    private readonly languages;
+    private readonly languageNames;
+    private currentSnapshot;
+    private revision;
+    private writes;
+    private pendingWrites;
+    private unsubscribe?;
+    constructor(storage?: LocaleStorageDriver | false);
+    lang(): Language;
+    langs(): ReadonlySet<Language>;
+    langNames(): ReadonlyMap<Language, string>;
+    keys(): Set<keyof T>;
+    get<K extends keyof T & string>(key: K, substitutions?: Record<string, LocaleSubstitutionValue>): string;
+    trans<K extends LocaleNonPluralKeys<T>>(key: K, ...args: LocaleSubstitutionArgs<T, K>): string;
+    choice<K extends LocalePluralKeys<T>>(key: K, count: number, ...args: LocaleSubstitutionArgs<T, K>): string;
+    readonly snapshot: () => LocaleSnapshot<T>;
+    readonly subscribe: (listener: () => void) => (() => void);
+    readonly change: (lang: Language) => Promise<Language>;
+    sync(): Promise<Language>;
+    private connect;
+    private disconnect;
+    private refresh;
+    private createSnapshot;
+    private publish;
+}

package/dist/locale/providers/ObservableLocale.js

@@ -0,0 +1,179 @@
+import DynamicLocale from "./DynamicLocale.js";
+import CustomLocale from "./CustomLocale.js";
+import { LocaleStorage } from "../storage/index.js";
+class ObservableLocale {
+  static defaultInstance;
+  static memoryInstance;
+  static drivers = /* @__PURE__ */ new WeakMap();
+  static getInstance(storage) {
+    if (typeof storage === "object") {
+      let instance = this.drivers.get(storage);
+      if (!instance) {
+        instance = new ObservableLocale(storage);
+        this.drivers.set(storage, instance);
+      }
+      return instance;
+    }
+    if (storage === false) {
+      return this.memoryInstance ?? (this.memoryInstance = new ObservableLocale(false));
+    }
+    return this.defaultInstance ?? (this.defaultInstance = new ObservableLocale());
+  }
+  locale = new DynamicLocale(false);
+  storage;
+  listeners = /* @__PURE__ */ new Set();
+  languages;
+  languageNames;
+  currentSnapshot;
+  revision = 0;
+  writes = Promise.resolve();
+  pendingWrites = 0;
+  unsubscribe;
+  constructor(storage) {
+    this.storage = storage === false ? void 0 : storage ?? new LocaleStorage();
+    this.languages = this.langs();
+    this.languageNames = this.langNames();
+    this.currentSnapshot = this.createSnapshot();
+  }
+  lang() {
+    return this.locale.lang();
+  }
+  langs() {
+    return this.locale.langs();
+  }
+  langNames() {
+    return this.locale.langNames();
+  }
+  keys() {
+    return this.locale.keys();
+  }
+  get(key, substitutions) {
+    return this.locale.get(key, substitutions);
+  }
+  trans(key, ...args) {
+    return this.locale.trans(key, ...args);
+  }
+  choice(key, count, ...args) {
+    return this.locale.choice(key, count, ...args);
+  }
+  snapshot = () => this.currentSnapshot;
+  subscribe = (listener) => {
+    const notify = () => listener();
+    this.listeners.add(notify);
+    try {
+      this.connect();
+    } catch (error) {
+      this.listeners.delete(notify);
+      throw error;
+    }
+    if (this.listeners.size === 1) {
+      void this.refresh();
+    }
+    return () => {
+      this.listeners.delete(notify);
+      this.disconnect();
+    };
+  };
+  change = async (lang) => {
+    this.locale.select(lang);
+    const storage = this.storage;
+    if (!storage) {
+      this.publish();
+      return lang;
+    }
+    this.revision++;
+    this.pendingWrites++;
+    const saved = this.writes.then(() => storage.set(lang));
+    this.writes = saved.catch(() => void 0);
+    this.publish();
+    let succeeded = false;
+    try {
+      await saved;
+      succeeded = true;
+      return lang;
+    } finally {
+      if (--this.pendingWrites === 0 && succeeded) {
+        void this.refresh();
+      }
+    }
+  };
+  async sync() {
+    if (!this.storage) {
+      throw new Error("Language is not saving in storage");
+    }
+    if (this.pendingWrites) {
+      return this.lang();
+    }
+    const revision = ++this.revision;
+    const lang = await this.storage.get();
+    if (revision !== this.revision || this.pendingWrites) {
+      return this.lang();
+    }
+    if (lang === void 0) {
+      return this.lang();
+    }
+    if (!this.langs().has(lang)) {
+      console.warn(`Incorrect language code in storage - "${lang}"`);
+      return this.lang();
+    }
+    this.locale.select(lang);
+    this.publish();
+    return this.lang();
+  }
+  connect() {
+    if (!this.storage || this.unsubscribe) {
+      return;
+    }
+    this.unsubscribe = this.storage.watch(() => {
+      void this.refresh();
+    });
+  }
+  disconnect() {
+    var _a;
+    if (this.listeners.size) {
+      return;
+    }
+    this.revision++;
+    (_a = this.unsubscribe) == null ? void 0 : _a.call(this);
+    this.unsubscribe = void 0;
+  }
+  async refresh() {
+    if (!this.storage || this.pendingWrites) {
+      return;
+    }
+    try {
+      await this.sync();
+    } catch (error) {
+      console.error("[ObservableLocale] Cannot synchronize language:", error);
+    }
+  }
+  createSnapshot() {
+    const lang = this.lang();
+    const langs = this.languages;
+    const langNames = this.languageNames;
+    const reader = new CustomLocale(lang, this.locale.messages());
+    return Object.freeze({
+      lang: () => lang,
+      langs: () => langs,
+      langNames: () => langNames,
+      get: reader.get.bind(reader)
+    });
+  }
+  publish() {
+    if (this.currentSnapshot.lang() === this.lang()) {
+      return;
+    }
+    this.currentSnapshot = this.createSnapshot();
+    for (const listener of [...this.listeners]) {
+      try {
+        listener();
+      } catch (error) {
+        console.error("[ObservableLocale] Language subscriber failed:", error);
+      }
+    }
+  }
+}
+export {
+  ObservableLocale as default
+};
+//# sourceMappingURL=ObservableLocale.js.map

package/dist/locale/providers/ObservableLocale.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/locale/providers/ObservableLocale.ts"],"sourcesContent":["import DynamicLocale from \"./DynamicLocale\";\nimport CustomLocale from \"./CustomLocale\";\n\nimport {LocaleStorage} from \"../storage\";\n\nimport type {\n    Language,\n    LocaleDynamicProvider,\n    LocaleNonPluralKeys,\n    LocalePluralKeys,\n    LocaleRegistry,\n    LocaleSnapshot,\n    LocaleStorageDriver,\n    LocaleSubstitutionArgs,\n    LocaleSubstitutionValue,\n} from \"@typing/locale\";\n\n/** Dynamic translations with shared instances and subscriptions independent of any UI framework. */\nexport default class ObservableLocale<T extends object = LocaleRegistry> implements LocaleDynamicProvider<T> {\n    private static defaultInstance?: ObservableLocale;\n    private static memoryInstance?: ObservableLocale;\n\n    private static readonly drivers = new WeakMap<LocaleStorageDriver, ObservableLocale>();\n\n    public static getInstance(storage?: LocaleStorageDriver | false): ObservableLocale {\n        if (typeof storage === \"object\") {\n            let instance = this.drivers.get(storage);\n\n            if (!instance) {\n                instance = new ObservableLocale(storage);\n                this.drivers.set(storage, instance);\n            }\n\n            return instance;\n        }\n\n        if (storage === false) {\n            return (this.memoryInstance ??= new ObservableLocale(false));\n        }\n\n        return (this.defaultInstance ??= new ObservableLocale());\n    }\n\n    private readonly locale = new DynamicLocale<T>(false);\n    private readonly storage?: LocaleStorageDriver;\n    private readonly listeners = new Set<() => void>();\n    private readonly languages: ReadonlySet<Language>;\n    private readonly languageNames: ReadonlyMap<Language, string>;\n    private currentSnapshot: LocaleSnapshot<T>;\n    private revision = 0;\n    private writes: Promise<void> = Promise.resolve();\n    private pendingWrites = 0;\n    private unsubscribe?: () => void;\n\n    constructor(storage?: LocaleStorageDriver | false) {\n        this.storage = storage === false ? undefined : (storage ?? new LocaleStorage());\n        this.languages = this.langs();\n        this.languageNames = this.langNames();\n        this.currentSnapshot = this.createSnapshot();\n    }\n\n    public lang(): Language {\n        return this.locale.lang();\n    }\n\n    public langs(): ReadonlySet<Language> {\n        return this.locale.langs();\n    }\n\n    public langNames(): ReadonlyMap<Language, string> {\n        return this.locale.langNames();\n    }\n\n    public keys(): Set<keyof T> {\n        return this.locale.keys();\n    }\n\n    public get<K extends keyof T & string>(key: K, substitutions?: Record<string, LocaleSubstitutionValue>): string {\n        return this.locale.get(key, substitutions);\n    }\n\n    public trans<K extends LocaleNonPluralKeys<T>>(key: K, ...args: LocaleSubstitutionArgs<T, K>): string {\n        return this.locale.trans(key, ...args);\n    }\n\n    public choice<K extends LocalePluralKeys<T>>(key: K, count: number, ...args: LocaleSubstitutionArgs<T, K>): string {\n        return this.locale.choice(key, count, ...args);\n    }\n\n    public readonly snapshot = (): LocaleSnapshot<T> => this.currentSnapshot;\n\n    public readonly subscribe = (listener: () => void): (() => void) => {\n        // Each subscription owns its cleanup, even when the same callback is subscribed twice.\n        const notify = () => listener();\n\n        this.listeners.add(notify);\n\n        try {\n            this.connect();\n        } catch (error) {\n            this.listeners.delete(notify);\n            throw error;\n        }\n\n        if (this.listeners.size === 1) {\n            void this.refresh();\n        }\n\n        return () => {\n            this.listeners.delete(notify);\n            this.disconnect();\n        };\n    };\n\n    public readonly change = async (lang: Language): Promise<Language> => {\n        this.locale.select(lang);\n\n        const storage = this.storage;\n\n        if (!storage) {\n            this.publish();\n            return lang;\n        }\n\n        this.revision++;\n\n        // Register persistence before notifying: a subscriber may select another language immediately.\n        this.pendingWrites++;\n\n        const saved = this.writes.then(() => storage.set(lang));\n\n        this.writes = saved.catch(() => undefined);\n\n        this.publish();\n\n        let succeeded = false;\n\n        try {\n            await saved;\n            succeeded = true;\n\n            return lang;\n        } finally {\n            if (--this.pendingWrites === 0 && succeeded) {\n                void this.refresh();\n            }\n        }\n    };\n\n    public async sync(): Promise<Language> {\n        if (!this.storage) {\n            throw new Error(\"Language is not saving in storage\");\n        }\n\n        if (this.pendingWrites) {\n            return this.lang();\n        }\n\n        const revision = ++this.revision;\n        const lang = await this.storage.get();\n\n        if (revision !== this.revision || this.pendingWrites) {\n            return this.lang();\n        }\n\n        if (lang === undefined) {\n            return this.lang();\n        }\n\n        if (!this.langs().has(lang)) {\n            console.warn(`Incorrect language code in storage - \"${lang}\"`);\n\n            return this.lang();\n        }\n\n        this.locale.select(lang);\n\n        this.publish();\n\n        return this.lang();\n    }\n\n    private connect(): void {\n        if (!this.storage || this.unsubscribe) {\n            return;\n        }\n\n        this.unsubscribe = this.storage.watch(() => {\n            void this.refresh();\n        });\n    }\n\n    private disconnect(): void {\n        if (this.listeners.size) {\n            return;\n        }\n\n        this.revision++;\n\n        this.unsubscribe?.();\n        this.unsubscribe = undefined;\n    }\n\n    private async refresh(): Promise<void> {\n        if (!this.storage || this.pendingWrites) {\n            return;\n        }\n\n        try {\n            await this.sync();\n        } catch (error) {\n            console.error(\"[ObservableLocale] Cannot synchronize language:\", error);\n        }\n    }\n\n    private createSnapshot(): LocaleSnapshot<T> {\n        const lang = this.lang();\n        const langs = this.languages;\n        const langNames = this.languageNames;\n\n        const reader = new CustomLocale<T>(lang, this.locale.messages());\n\n        return Object.freeze({\n            lang: () => lang,\n            langs: () => langs,\n            langNames: () => langNames,\n            get: reader.get.bind(reader),\n        });\n    }\n\n    private publish(): void {\n        if (this.currentSnapshot.lang() === this.lang()) {\n            return;\n        }\n\n        this.currentSnapshot = this.createSnapshot();\n\n        for (const listener of [...this.listeners]) {\n            try {\n                listener();\n            } catch (error) {\n                console.error(\"[ObservableLocale] Language subscriber failed:\", error);\n            }\n        }\n    }\n}\n"],"mappings":"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","names":[]}

package/dist/locale/providers/index.d.ts

@@ -1,3 +1,4 @@
 export { default as AbstractLocale } from "./AbstractLocale.js";
 export { default as DynamicLocale } from "./DynamicLocale.js";
-export { default as NativeLocale, type LocaleNativeStructure } from "./NativeLocale.js";
+export { default as NativeLocale } from "./NativeLocale.js";
+export { default as ObservableLocale } from "./ObservableLocale.js";

package/dist/locale/providers/index.js

@@ -1,9 +1,11 @@
 import { default as default2 } from "./AbstractLocale.js";
 import { default as default3 } from "./DynamicLocale.js";
 import { default as default4 } from "./NativeLocale.js";
+import { default as default5 } from "./ObservableLocale.js";
 export {
   default2 as AbstractLocale,
   default3 as DynamicLocale,
-  default4 as NativeLocale
+  default4 as NativeLocale,
+  default5 as ObservableLocale
 };
 //# sourceMappingURL=index.js.map

package/dist/locale/providers/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/locale/providers/index.ts"],"sourcesContent":["export {default as AbstractLocale} from \"./AbstractLocale\";\nexport {default as DynamicLocale} from \"./DynamicLocale\";\nexport {default as NativeLocale, type LocaleNativeStructure} from \"./NativeLocale\";\n"],"mappings":"AAAA,SAAmB,WAAXA,gBAAgC;AACxC,SAAmB,WAAXA,gBAA+B;AACvC,SAAmB,WAAXA,gBAA0D;","names":["default"]}
+{"version":3,"sources":["../../../src/locale/providers/index.ts"],"sourcesContent":["export {default as AbstractLocale} from \"./AbstractLocale\";\nexport {default as DynamicLocale} from \"./DynamicLocale\";\nexport {default as NativeLocale} from \"./NativeLocale\";\nexport {default as ObservableLocale} from \"./ObservableLocale\";\n"],"mappings":"AAAA,SAAmB,WAAXA,gBAAgC;AACxC,SAAmB,WAAXA,gBAA+B;AACvC,SAAmB,WAAXA,gBAA8B;AACtC,SAAmB,WAAXA,gBAAkC;","names":["default"]}

package/dist/locale/storage/LocaleStorage.d.ts

@@ -0,0 +1,11 @@
+import { Language, type LocaleStorageDriver } from "../../types/locale.js";
+/** Stores the selected language in extension local storage under the framework namespace. */
+export default class LocaleStorage implements LocaleStorageDriver {
+    protected key: string;
+    private readonly storage;
+    constructor(key?: string);
+    get(): Promise<Language | undefined>;
+    set(lang: Language): Promise<void>;
+    watch(handler: (lang: Language) => void): () => void;
+    private parse;
+}