@feugene/fint-i18n 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# @feugene/fint-i18n
+
+[Русская версия (Russian version)](./README.ru.md)
+
+Localization library for Vue 3 with lazy-loading blocks, template compilation, and extensible plugins.
+
+## Features
+
+- **Small surface area**: The package is split into `core`, `vue`, and `plugins` entry points.
+- **Performant runtime**: Templates are compiled into functions and cached.
+- **Async blocks**: Support for splitting translations into blocks and lazy-loading them.
+- **Bridge Mode**: Transparent integration with `vue-i18n`.
+- **Plugins**: Hook system for extending functionality (persistence, logging, etc.).
+- **Simple runtime contract**: The only peer dependency is `vue`.
+
+## Documentation
+
+You can find detailed information about the library in the relevant sections:
+
+- 📦 **[Installation and Getting Started](./docs/en/installation.md)**: How to install the package and configure it in a Vue application.
+- 📂 **[Defining Messages](./docs/en/defining-messages.md)**: JSON formats, loaders, and dynamic merging.
+- 🚀 **[Usage](./docs/en/usage.md)**: How to use `t()`, `$t`, and the `v-t` directive.
+- 📘 **[API Reference](./docs/en/api.md)**: Detailed description of all functions, methods, and composables.
+- 🔌 **[Plugins](./docs/en/plugins.md)**: Extending functionality via the hook system and built-in plugins.
+- 🧱 **[Translation Blocks](./docs/en/blocks.md)**: Deep dive into the concept of blocks and memory management.
+- ⚡ **[Benchmarks and Bundle Analysis](./docs/en/bundle-analysis.md)**: How to measure the hot path and analyze the `dist` composition.
+
+---
+
+## Quick Start
+
+### 1. Initialization
+
+```typescript
+import { createApp } from 'vue'
+import { createFintI18n } from '@feugene/fint-i18n/core'
+import { installI18n } from '@feugene/fint-i18n/vue'
+import { appLocaleLoaders } from './i18n/messages'
+import { fintDsLocaleLoaders } from '@feugene/fint-ds/i18n'
+
+const i18n = createFintI18n({
+  locale: 'en',
+  fallbackLocale: 'en',
+  loaders: [appLocaleLoaders, fintDsLocaleLoaders],
+})
+
+const app = createApp(App)
+installI18n(app, i18n)
+app.mount('#app')
+```
+
+`loaders` accepts:
+
+- `LocaleLoaderCollection` — a single locale/block collection;
+- `LocaleLoaderCollection[]` — an array of collections from multiple packages;
+- for each `block`, you can pass a single loader or an array of loaders.
+
+Rules:
+
+- collections in `loaders: [...]` are merged **from left to right**;
+- if the same `block` is found in multiple collections, loaders are combined into an array;
+- loaders for a single block are executed **sequentially**;
+- in case of key conflicts in messages, the **last** loader wins;
+- when `loadBlock('pages.articles')` is called, it first looks for an exact block match, then the nearest parent block (`pages`).
+
+### 2. Usage in components
+
+```vue
+<script setup>
+import { useFintI18n, useI18nScope } from '@feugene/fint-i18n/vue'
+
+// Connect necessary blocks (they will load automatically)
+await useI18nScope(['common', 'auth'])
+
+const { t, locale, setLocale } = useFintI18n()
+
+const changeLanguage = async () => {
+  await setLocale(locale.value === 'en' ? 'ru' : 'en')
+}
+</script>
+
+<template>
+  <div>
+    <p>{{ t('common.welcome', { name: 'User' }) }}</p>
+    <button @click="changeLanguage">
+      Change Language
+    </button>
+    
+    <!-- Directive usage -->
+    <span v-t="'auth.login'" />
+  </div>
+</template>
+```

package/README.ru.md

@@ -0,0 +1,92 @@
+# @feugene/fint-i18n
+
+Библиотека локализации для Vue 3 с ленивой загрузкой блоков, компиляцией шаблонов и расширяемыми плагинами.
+
+## Особенности
+
+- **Небольшой surface area**: пакет разбит на `core`, `vue` и `plugins` энтрипойнты.
+- **Производительный runtime**: шаблоны компилируются в функции и кэшируются.
+- **Асинхронные блоки**: Поддержка разделения переводов на блоки и их ленивая загрузка.
+- **Bridge Mode**: Прозрачная интеграция с `vue-i18n`.
+- **Плагины**: Система хуков для расширения функционала (персистентность, логирование и т.д.).
+- **Простой runtime-контракт**: единственная peer dependency — `vue`.
+
+## Документация
+
+Подробную информацию о работе с библиотекой вы найдете в соответствующих разделах:
+
+- 📦 **[Установка и начало работы](./docs/ru/installation.md)**: Как установить пакет и настроить его в приложении Vue.
+- 📂 **[Определение сообщений](./docs/ru/defining-messages.md)**: Форматы JSON, лоадеры и динамический мердж.
+- 🚀 **[Использование](./docs/ru/usage.md)**: Как использовать `t()`, `$t` и директиву `v-t`.
+- 📘 **[Справочник API](./docs/ru/api.md)**: Подробное описание всех функций, методов и композаблов.
+- 🔌 **[Плагины](./docs/ru/plugins.md)**: Расширение функционала через систему хуков и встроенные плагины.
+- 🧱 **[Блоки перевода](./docs/ru/blocks.md)**: Глубокое погружение в концепцию блоков и управление памятью.
+- ⚡ **[Бенчмарки и анализ бандла](./docs/ru/bundle-analysis.md)**: Как мерить hot path и смотреть состав собранного `dist`.
+
+---
+
+## Быстрый старт
+
+### 1. Инициализация
+
+```typescript
+import { createApp } from 'vue'
+import { createFintI18n } from '@feugene/fint-i18n/core'
+import { installI18n } from '@feugene/fint-i18n/vue'
+import { appLocaleLoaders } from './i18n/messages'
+import { fintDsLocaleLoaders } from '@feugene/fint-ds/i18n'
+
+const i18n = createFintI18n({
+  locale: 'en',
+  fallbackLocale: 'en',
+  loaders: [appLocaleLoaders, fintDsLocaleLoaders],
+})
+
+const app = createApp(App)
+installI18n(app, i18n)
+app.mount('#app')
+```
+
+`loaders` принимает:
+
+- `LocaleLoaderCollection` — одна locale/block-коллекция;
+- `LocaleLoaderCollection[]` — массив коллекций из нескольких пакетов;
+- для каждого `block` можно передать один loader или массив loaders.
+
+Правила работы:
+
+- коллекции в `loaders: [...]` мерджатся **слева направо**;
+- если один и тот же `block` встречается в нескольких коллекциях, loaders объединяются в массив;
+- loaders одного блока выполняются **последовательно**;
+- при конфликте ключей в сообщениях побеждает **последний** loader;
+- при `loadBlock('pages.articles')` сначала ищется точный block, затем ближайший parent block (`pages`).
+
+### 2. Использование в компонентах
+
+```vue
+<script setup>
+import { useFintI18n, useI18nScope } from '@feugene/fint-i18n/vue'
+
+// Подключаем необходимые блоки (автоматически загрузятся)
+await useI18nScope(['common', 'auth'])
+
+const { t, locale, setLocale } = useFintI18n()
+
+const changeLanguage = async () => {
+  await setLocale(locale.value === 'en' ? 'ru' : 'en')
+}
+</script>
+
+<template>
+  <div>
+    <p>{{ t('common.welcome', { name: 'User' }) }}</p>
+    <button @click="changeLanguage">
+Change Language
+</button>
+    
+    <!-- Использование директивы -->
+    <span v-t="'auth.login'" />
+  </div>
+</template>
+```
+

package/dist/chunks/core-Dbw0feTs.js

@@ -0,0 +1,323 @@
+import { isRef as e, reactive as t, ref as n, watch as r } from "vue";
+//#region src/core/compiler.ts
+function i(e) {
+	if (!e.includes("{")) return () => e;
+	let t = [], n = 0, r = /\{(\w+)\}/g, i = r.exec(e);
+	for (; i;) i.index > n && t.push(e.slice(n, i.index)), t.push({
+		key: i[1],
+		fallback: i[0]
+	}), n = i.index + i[0].length, i = r.exec(e);
+	return n < e.length && t.push(e.slice(n)), (n) => {
+		if (!n) return e;
+		let r = "";
+		for (let e of t) if (typeof e == "string") r += e;
+		else {
+			let t = n[e.key];
+			r += t === void 0 ? e.fallback : String(t);
+		}
+		return r;
+	};
+}
+//#endregion
+//#region src/core/hooks.ts
+var a = class {
+	hooks = /* @__PURE__ */ new Map();
+	on(e, t) {
+		let n = this.hooks.get(e);
+		return n ? n.push(t) : this.hooks.set(e, [t]), () => this.off(e, t);
+	}
+	off(e, t) {
+		let n = this.hooks.get(e);
+		if (n) {
+			let r = n.indexOf(t);
+			r !== -1 && (n.splice(r, 1), n.length === 0 && this.hooks.delete(e));
+		}
+	}
+	emit(e, t) {
+		let n = this.hooks.get(e);
+		if (!n || n.length === 0) return Promise.resolve(t);
+		let r = t, i = n.slice();
+		return (async () => {
+			for (let e of i) {
+				let t = await e(r);
+				t !== void 0 && (r = t);
+			}
+			return r;
+		})();
+	}
+	emitSync(e, t) {
+		let n = this.hooks.get(e);
+		if (!n || n.length === 0) return t;
+		let r = t, i = n.slice();
+		for (let t of i) {
+			let n = t(r);
+			if (n instanceof Promise) {
+				console.warn(`[fint-i18n] Sync hook "${e}" received a promise from handler. This will be ignored in sync execution.`);
+				continue;
+			}
+			n !== void 0 && (r = n);
+		}
+		return r;
+	}
+}, o = class {
+	loaders;
+	constructor(e) {
+		this.loaders = this.normalize(e);
+	}
+	resolve(e, t) {
+		let n = this.loaders[e];
+		if (!n) return null;
+		if (n[t]) return {
+			resolvedBlockName: t,
+			loaders: n[t]
+		};
+		if (!t.includes(".")) return null;
+		let r = t.split(".");
+		for (let e = r.length - 1; e >= 1; e--) {
+			let t = r.slice(0, e).join("."), i = n[t];
+			if (i) return {
+				resolvedBlockName: t,
+				loaders: i
+			};
+		}
+		return null;
+	}
+	normalize(e) {
+		let t = Object.create(null);
+		if (!e) return t;
+		let n = Array.isArray(e) ? e : [e];
+		for (let e of n) this.mergeCollection(t, e);
+		return t;
+	}
+	mergeCollection(e, t) {
+		for (let n in t) {
+			e[n] || (e[n] = Object.create(null));
+			let r = t[n];
+			for (let t in r) {
+				let i = this.normalizeEntry(r[t]);
+				if (!e[n][t]) {
+					e[n][t] = i;
+					continue;
+				}
+				e[n][t] = [...e[n][t], ...i];
+			}
+		}
+	}
+	normalizeEntry(e) {
+		return Array.isArray(e) ? e : [e];
+	}
+};
+//#endregion
+//#region src/core/message-utils.ts
+function s(e) {
+	return !!e && typeof e == "object" && !Array.isArray(e);
+}
+function c(e, t) {
+	for (let n in t) s(t[n]) ? (s(e[n]) || (e[n] = {}), c(e[n], t[n])) : e[n] = t[n];
+}
+function l(e, n) {
+	if (s(e) && s(n)) {
+		let r = t({});
+		return c(r, e), c(r, n), r;
+	}
+	return n;
+}
+function u(e, t) {
+	let n = e, r = 0;
+	for (; n && typeof n == "object";) {
+		let e = t.indexOf(".", r), i = e === -1 ? t.slice(r) : t.slice(r, e);
+		if (n = n[i], n === void 0 || e === -1) return n;
+		r = e + 1;
+	}
+}
+//#endregion
+//#region src/core/translate-params.ts
+function d(t) {
+	if (!t) return;
+	let n;
+	for (let r in t) {
+		let i = t[r];
+		e(i) && (n ||= { ...t }, n[r] = i.value);
+	}
+	return n || t;
+}
+//#endregion
+//#region src/core/instance.ts
+var f = class {
+	locale;
+	fallbackLocale;
+	globalInstall;
+	messages = t({});
+	compiledMessages = Object.create(null);
+	loaderRegistry;
+	loadingBlocks = /* @__PURE__ */ new Map();
+	loadedBlocks = /* @__PURE__ */ new Map();
+	blockUsageCounters = /* @__PURE__ */ new Map();
+	pendingUsedBlockLoads = /* @__PURE__ */ new Map();
+	skipNextUsedBlockLoadLocale = null;
+	hooks = new a();
+	constructor(e) {
+		this.locale = n(e.locale), this.fallbackLocale = e.fallbackLocale || "", this.loaderRegistry = new o(e.loaders), this.globalInstall = e.globalInstall !== !1, e.plugins && e.plugins.forEach((e) => e.install(this)), r(this.locale, (e, t) => {
+			if (e !== t) {
+				if (this.skipNextUsedBlockLoadLocale === e) {
+					this.skipNextUsedBlockLoadLocale = null;
+					return;
+				}
+				this.loadUsedBlocks(e);
+			}
+		}), this.hooks.emitSync("afterInit", void 0);
+	}
+	t = (e, t, n) => {
+		let r = this.locale.value, i = d(t), a = this.hooks.emitSync("onTranslate", {
+			key: e,
+			params: i,
+			result: this.resolve(r, e, i) || e
+		}).result;
+		if (a === e) {
+			let t = n?.fallbackLocale || this.fallbackLocale;
+			if (t && t !== r) {
+				let n = this.resolve(t, e, i);
+				if (n !== void 0) return n;
+			}
+			this.hooks.emit("onMissingKey", {
+				key: e,
+				locale: r
+			}).catch((e) => {
+				console.error("[fint-i18n] Error in onMissingKey hook:", e);
+			});
+		}
+		return a;
+	};
+	resolve = (e, t, n) => {
+		let r = this.compiledMessages[e]?.[t];
+		if (r) return r(n);
+		let a = this.messages[e];
+		if (!a) return;
+		let o = u(a, t);
+		if (typeof o == "string") {
+			let r = i(o);
+			return this.setCompiled(e, t, r), r(n);
+		}
+		if (typeof o == "function") {
+			let r = o;
+			return this.setCompiled(e, t, r), r(n);
+		}
+		if (o != null && typeof o != "object") return String(o);
+	};
+	setCompiled = (e, t, n) => {
+		this.compiledMessages[e] || (this.compiledMessages[e] = Object.create(null)), this.compiledMessages[e][t] = n;
+	};
+	loadBlock = async (e, t) => {
+		let n = t || this.locale.value, r = `${n}:${e}`;
+		if (this.isBlockLoaded(e, n)) return;
+		if (this.loadingBlocks.has(r)) return this.loadingBlocks.get(r);
+		await this.hooks.emit("beforeLoadBlock", e);
+		let i = (async () => {
+			try {
+				let t = this.loaderRegistry.resolve(n, e);
+				if (!t) {
+					console.warn(`[fint-i18n] No loader for block "${e}" in locale "${n}"`);
+					return;
+				}
+				let r;
+				for (let e of t.loaders) {
+					let i = await e(), a = i.default || i;
+					this.mergeMessages(n, t.resolvedBlockName, a), r = r === void 0 ? a : l(r, a);
+				}
+				this.markBlockLoaded(t.resolvedBlockName, n), await this.hooks.emit("afterLoadBlock", {
+					block: t.resolvedBlockName,
+					locale: n,
+					messages: r
+				});
+			} finally {
+				this.loadingBlocks.delete(r);
+			}
+		})();
+		return this.loadingBlocks.set(r, i), i;
+	};
+	mergeMessages = (e, n, r) => {
+		this.messages[e] || (this.messages[e] = t({}));
+		let i = n.split("."), a = i[0];
+		if (i.length === 1) s(r) ? ((!this.messages[e][a] || typeof this.messages[e][a] != "object") && (this.messages[e][a] = t({})), c(this.messages[e][a], r)) : this.messages[e][a] = r;
+		else {
+			(!this.messages[e][a] || typeof this.messages[e][a] != "object") && (this.messages[e][a] = t({}));
+			let n = this.messages[e][a];
+			for (let e = 1; e < i.length; e++) {
+				let r = i[e];
+				(!n[r] || typeof n[r] != "object") && (n[r] = t({})), n = n[r];
+			}
+			c(n, r);
+		}
+		this.precompileBlock(e, n, r);
+	};
+	precompileBlock = (e, t, n) => {
+		if (typeof n == "string") {
+			let r = i(n);
+			this.setCompiled(e, t, r);
+			return;
+		}
+		if (typeof n == "function") {
+			this.setCompiled(e, t, n);
+			return;
+		}
+		if (s(n)) for (let r in n) {
+			let a = n[r], o = `${t}.${r}`;
+			if (typeof a == "string") {
+				let t = i(a);
+				this.setCompiled(e, o, t);
+			} else typeof a == "function" ? this.setCompiled(e, o, a) : s(a) && this.precompileBlock(e, o, a);
+		}
+	};
+	isBlockLoaded = (e, t) => {
+		let n = t || this.locale.value, r = this.loadedBlocks.get(n);
+		if (!r) return !1;
+		if (r.has(e)) return !0;
+		let i = e.split("."), a = "";
+		for (let e = 0; e < i.length - 1; e++) if (a = a ? `${a}.${i[e]}` : i[e], r.has(a)) return !0;
+		return !1;
+	};
+	markBlockLoaded = (e, t) => {
+		this.loadedBlocks.has(t) || this.loadedBlocks.set(t, /* @__PURE__ */ new Set()), this.loadedBlocks.get(t).add(e);
+	};
+	loadUsedBlocks = async (e) => {
+		let t = this.pendingUsedBlockLoads.get(e);
+		if (t) {
+			await t;
+			return;
+		}
+		let n = (async () => {
+			let t = [];
+			for (let [n, r] of this.blockUsageCounters.entries()) r > 0 && t.push(this.loadBlock(n, e));
+			await Promise.all(t);
+		})();
+		this.pendingUsedBlockLoads.set(e, n);
+		try {
+			await n;
+		} finally {
+			this.pendingUsedBlockLoads.delete(e);
+		}
+	};
+	setLocale = async (e) => {
+		let t = this.locale.value;
+		t !== e && (await this.loadUsedBlocks(e), this.skipNextUsedBlockLoadLocale = e, this.locale.value = e, this.hooks.emitSync("onLocaleChange", {
+			locale: e,
+			previous: t
+		}));
+	};
+	registerUsage = (e) => {
+		let t = this.blockUsageCounters.get(e) || 0;
+		this.blockUsageCounters.set(e, t + 1);
+	};
+	registerBlocks = (e) => {
+		e.forEach((e) => this.registerUsage(e));
+	};
+	unregisterUsage = (e) => {
+		let t = this.blockUsageCounters.get(e) || 0;
+		t <= 1 ? this.blockUsageCounters.delete(e) : this.blockUsageCounters.set(e, t - 1);
+	};
+};
+function p(e) {
+	return new f(e);
+}
+//#endregion
+export { i, p as n, a as r, f as t };

package/dist/core.js

@@ -0,0 +1,2 @@
+import { i as e, n as t, r as n, t as r } from "./chunks/core-Dbw0feTs.js";
+export { r as FintI18n, n as HookManager, e as compileTemplate, t as createFintI18n };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { i as e, n as t, r as n, t as r } from "./chunks/core-Dbw0feTs.js";
+import { FINT_I18N_KEY as i, createVTDirective as a, installI18n as o, useFintI18n as s, useI18nScope as c } from "./vue.js";
+import { BridgePlugin as l, HookLoggerPlugin as u, PersistencePlugin as d } from "./plugins.js";
+export { l as BridgePlugin, i as FINT_I18N_KEY, r as FintI18n, u as HookLoggerPlugin, n as HookManager, d as PersistencePlugin, e as compileTemplate, t as createFintI18n, a as createVTDirective, o as installI18n, s as useFintI18n, c as useI18nScope };

package/dist/plugins.js

@@ -0,0 +1,69 @@
+import { watch as e } from "vue";
+//#region src/plugins/persistence.ts
+var t = class {
+	name = "persistence";
+	options;
+	constructor(e = {}) {
+		this.options = {
+			key: "fint-i18n-locale",
+			syncTabs: !0,
+			...e
+		};
+	}
+	install(e) {
+		let t = this.options.key, n = this.options.storage || (typeof window < "u" ? window.localStorage : void 0);
+		if (!n) return;
+		let r = n.getItem(t);
+		r && (e.locale.value = r), e.hooks.on("onLocaleChange", ({ locale: e }) => {
+			n.setItem(t, e);
+		}), this.options.syncTabs && typeof window < "u" && window.addEventListener("storage", (n) => {
+			n.key === t && n.newValue && n.newValue !== e.locale.value && (e.locale.value = n.newValue);
+		});
+	}
+}, n = class {
+	name = "bridge";
+	options;
+	constructor(e) {
+		this.options = e;
+	}
+	install(t) {
+		let n = this.options.i18n;
+		e(() => n.locale.value || n.locale, (e) => {
+			t.locale.value !== e && (t.locale.value = e);
+		}, { immediate: !0 }), t.hooks.on("onLocaleChange", ({ locale: e }) => {
+			typeof n.locale == "object" ? n.locale.value = e : n.locale = e;
+		}), t.hooks.on("onTranslate", (e) => {
+			let t = e.params ? n.t(e.key, e.params) : n.t(e.key);
+			return t === e.key ? e : {
+				...e,
+				result: t
+			};
+		});
+	}
+}, r = [
+	"beforeInit",
+	"afterInit",
+	"onLocaleChange",
+	"beforeLoadBlock",
+	"afterLoadBlock",
+	"onMissingKey",
+	"onTranslate"
+], i = class {
+	name = "hook-logger";
+	options;
+	constructor(e = {}) {
+		this.options = {
+			logger: console.log,
+			prefix: "[fint-i18n] Hook",
+			...e
+		};
+	}
+	install(e) {
+		r.forEach((t) => this.registerHook(e, t));
+	}
+	registerHook(e, t) {
+		e.hooks.on(t, (e) => (this.options.logger(`${this.options.prefix} "${t}" called`, e), e));
+	}
+};
+//#endregion
+export { n as BridgePlugin, i as HookLoggerPlugin, t as PersistencePlugin };

package/dist/types/core/compiler.d.ts

@@ -0,0 +1,6 @@
+export type MessageFunction = (params?: Record<string, any>) => string;
+/**
+ * JIT-компилятор шаблонов.
+ * Преобразует строку "Привет, {name}!" в функцию (p) => "Привет, " + p.name + "!"
+ */
+export declare function compileTemplate(template: string): MessageFunction;

package/dist/types/core/hooks.d.ts

@@ -0,0 +1,34 @@
+import type { Locale } from './types';
+export type HookFn<T = any> = (arg: T) => void | T | Promise<void | T>;
+type HookPayload<K extends keyof FintI18nHooks> = Parameters<FintI18nHooks[K]>[0];
+export interface FintI18nHooks {
+    'beforeInit': HookFn<any>;
+    'afterInit': HookFn<void>;
+    'onLocaleChange': HookFn<{
+        locale: Locale;
+        previous: Locale;
+    }>;
+    'beforeLoadBlock': HookFn<string>;
+    'afterLoadBlock': HookFn<{
+        block: string;
+        locale: Locale;
+        messages: any;
+    }>;
+    'onMissingKey': HookFn<{
+        key: string;
+        locale: Locale;
+    }>;
+    'onTranslate': HookFn<{
+        key: string;
+        params?: any;
+        result: string;
+    }>;
+}
+export declare class HookManager {
+    private hooks;
+    on<K extends keyof FintI18nHooks>(name: K, fn: FintI18nHooks[K]): () => void;
+    off<K extends keyof FintI18nHooks>(name: K, fn: FintI18nHooks[K]): void;
+    emit<K extends keyof FintI18nHooks>(name: K, arg: HookPayload<K>): Promise<HookPayload<K>>;
+    emitSync<K extends keyof FintI18nHooks>(name: K, arg: HookPayload<K>): HookPayload<K>;
+}
+export {};

package/dist/types/core/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './instance';
+export * from './hooks';
+export * from './compiler';

package/dist/types/core/instance.d.ts

@@ -0,0 +1,32 @@
+import { type Ref } from 'vue';
+import { HookManager } from './hooks';
+import type { FintI18nOptions, Locale, MessageValue, TranslateOptions } from './types';
+export declare class FintI18n {
+    locale: Ref<Locale>;
+    fallbackLocale: Locale;
+    globalInstall: boolean;
+    readonly messages: Record<Locale, any>;
+    private compiledMessages;
+    private readonly loaderRegistry;
+    private loadingBlocks;
+    private loadedBlocks;
+    private blockUsageCounters;
+    private pendingUsedBlockLoads;
+    private skipNextUsedBlockLoadLocale;
+    hooks: HookManager;
+    constructor(options: FintI18nOptions);
+    t: (key: string, params?: Record<string, any>, options?: TranslateOptions) => string;
+    private resolve;
+    private setCompiled;
+    loadBlock: (blockName: string, locale?: Locale) => Promise<void>;
+    mergeMessages: (locale: Locale, blockName: string, messages: MessageValue) => void;
+    private precompileBlock;
+    isBlockLoaded: (blockName: string, locale?: Locale) => boolean;
+    markBlockLoaded: (blockName: string, locale: Locale) => void;
+    loadUsedBlocks: (locale: Locale) => Promise<void>;
+    setLocale: (newLocale: Locale) => Promise<void>;
+    registerUsage: (blockName: string) => void;
+    registerBlocks: (blockNames: string[]) => void;
+    unregisterUsage: (blockName: string) => void;
+}
+export declare function createFintI18n(options: FintI18nOptions): FintI18n;

package/dist/types/core/loader-registry.d.ts

@@ -0,0 +1,13 @@
+import type { Locale, LocaleBlockLoader, LocaleLoaderSource } from './types';
+export interface ResolvedLocaleBlockLoaders {
+    resolvedBlockName: string;
+    loaders: LocaleBlockLoader[];
+}
+export declare class LocaleLoaderRegistry {
+    private readonly loaders;
+    constructor(source?: LocaleLoaderSource);
+    resolve(locale: Locale, blockName: string): ResolvedLocaleBlockLoaders | null;
+    private normalize;
+    private mergeCollection;
+    private normalizeEntry;
+}

package/dist/types/core/message-utils.d.ts

@@ -0,0 +1,5 @@
+import type { MessageSchema, MessageValue } from './types';
+export declare function isMessageObject(value: unknown): value is MessageSchema;
+export declare function deepMerge(target: any, source: any): void;
+export declare function mergeMessageValues(target: MessageValue, source: MessageValue): MessageValue;
+export declare function getMessageValue(messages: Record<string, any>, key: string): unknown;

package/dist/types/core/translate-params.d.ts

@@ -0,0 +1 @@
+export declare function normalizeTranslateParams(params?: Record<string, any>): Record<string, any> | undefined;

package/dist/types/core/types.d.ts

@@ -0,0 +1,26 @@
+import type { MessageFunction } from './compiler';
+import type { FintI18n } from './instance';
+export type Locale = string;
+export type LocaleBlockLoader = () => Promise<any>;
+export type LocaleBlockLoaders = LocaleBlockLoader | LocaleBlockLoader[];
+export type LocaleLoaderCollection = Record<Locale, Record<string, LocaleBlockLoaders>>;
+export type LocaleLoaderSource = LocaleLoaderCollection | LocaleLoaderCollection[];
+export interface FintI18nPlugin {
+    name: string;
+    install: (instance: FintI18n) => void;
+}
+export interface FintI18nOptions {
+    locale: Locale;
+    fallbackLocale?: Locale;
+    loaders?: LocaleLoaderSource;
+    plugins?: FintI18nPlugin[];
+    globalInstall?: boolean;
+}
+export type MessagePrimitive = string | number | boolean;
+export interface MessageSchema {
+    [key: string]: MessagePrimitive | MessageFunction | MessageSchema;
+}
+export type MessageValue = MessagePrimitive | MessageFunction | MessageSchema;
+export interface TranslateOptions {
+    fallbackLocale?: Locale;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './core';
+export * from './vue';
+export * from './plugins';

package/dist/types/plugins/bridge.d.ts

@@ -0,0 +1,10 @@
+import type { FintI18n, FintI18nPlugin } from '@/core';
+export interface BridgeOptions {
+    i18n: any;
+}
+export declare class BridgePlugin implements FintI18nPlugin {
+    name: string;
+    private options;
+    constructor(options: BridgeOptions);
+    install(fintI18n: FintI18n): void;
+}

package/dist/types/plugins/hook-logger.d.ts

@@ -0,0 +1,14 @@
+import type { FintI18n, FintI18nPlugin } from '@/core';
+type LoggerFn = (message?: any, ...optionalParams: any[]) => void;
+export interface HookLoggerPluginOptions {
+    logger?: LoggerFn;
+    prefix?: string;
+}
+export declare class HookLoggerPlugin implements FintI18nPlugin {
+    name: string;
+    private options;
+    constructor(options?: HookLoggerPluginOptions);
+    install(i18n: FintI18n): void;
+    private registerHook;
+}
+export {};

package/dist/types/plugins/index.d.ts

@@ -0,0 +1,3 @@
+export * from './persistence';
+export * from './bridge';
+export * from './hook-logger';

package/dist/types/plugins/persistence.d.ts

@@ -0,0 +1,12 @@
+import type { FintI18n, FintI18nPlugin } from '@/core';
+export interface PersistenceOptions {
+    key?: string;
+    storage?: Storage;
+    syncTabs?: boolean;
+}
+export declare class PersistencePlugin implements FintI18nPlugin {
+    name: string;
+    private options;
+    constructor(options?: PersistenceOptions);
+    install(i18n: FintI18n): void;
+}

package/dist/types/vue/directive.d.ts

@@ -0,0 +1,18 @@
+import type { Directive } from 'vue';
+import type { FintI18n } from '@/core';
+export type VTDirectiveValue = string | {
+    path: string;
+    params?: Record<string, any>;
+};
+export interface VTDirectiveModifiers {
+    once?: boolean;
+    preserve?: boolean;
+}
+/**
+ * Create v-t directive.
+ *
+ * Modifiers:
+ * - `.once`: render only once
+ * - `.preserve`: keep current text if key not found
+ */
+export declare function createVTDirective(i18n: FintI18n): Directive<HTMLElement, VTDirectiveValue>;

package/dist/types/vue/index.d.ts

@@ -0,0 +1,25 @@
+export * from './scope';
+export * from './inject';
+export * from './directive';
+export * from './plugin';
+import type { FintI18n } from '@/core';
+import type { Directive } from 'vue';
+import type { VTDirectiveValue } from './directive';
+declare module '@vue/runtime-core' {
+    interface GlobalDirectives {
+        vT: Directive<HTMLElement, VTDirectiveValue>;
+    }
+    interface ComponentCustomProperties {
+        $t: FintI18n['t'];
+        $i18n: FintI18n;
+    }
+}
+declare module 'vue' {
+    interface GlobalDirectives {
+        vT: Directive<HTMLElement, VTDirectiveValue>;
+    }
+    interface ComponentCustomProperties {
+        $t: FintI18n['t'];
+        $i18n: FintI18n;
+    }
+}

package/dist/types/vue/inject.d.ts

@@ -0,0 +1,4 @@
+import { type InjectionKey } from 'vue';
+import type { FintI18n } from '@/core';
+export declare const FINT_I18N_KEY: InjectionKey<FintI18n>;
+export declare function useFintI18n(): FintI18n;

package/dist/types/vue/plugin.d.ts

@@ -0,0 +1,5 @@
+import type { App } from 'vue';
+import type { FintI18n } from '@/core';
+export declare function installI18n(app: App, i18n: FintI18n, options?: {
+    directive?: string | boolean;
+}): void;

package/dist/types/vue/scope.d.ts

@@ -0,0 +1,5 @@
+export declare function useI18nScope(blocks: string | string[]): Promise<{
+    t: (key: string, params?: Record<string, any>) => string;
+    locale: import("vue").Ref<string, string>;
+    setLocale: (l: string) => Promise<void>;
+}>;

package/dist/vue.js

@@ -0,0 +1,51 @@
+import { inject as e, onUnmounted as t } from "vue";
+//#region src/vue/inject.ts
+var n = Symbol("FintI18n");
+function r() {
+	let t = e(n);
+	if (!t) throw Error("[fint-i18n] Instance not found. Did you call installI18n(app, i18n)?");
+	return t;
+}
+//#endregion
+//#region src/vue/scope.ts
+async function i(e) {
+	let n = r(), i = Array.isArray(e) ? e : [e];
+	t(() => {
+		i.forEach((e) => n.unregisterUsage(e));
+	});
+	let a = i.map((e) => (n.registerUsage(e), n.loadBlock(e)));
+	return await Promise.all(a), {
+		t: (e, t) => n.t(e, t),
+		locale: n.locale,
+		setLocale: (e) => n.setLocale(e)
+	};
+}
+//#endregion
+//#region src/vue/directive.ts
+function a(e) {
+	return {
+		mounted(t, n) {
+			o(t, n, e);
+		},
+		updated(t, n) {
+			n.modifiers.once || o(t, n, e);
+		}
+	};
+}
+function o(e, t, n) {
+	let { value: r, modifiers: i } = t, a, o;
+	if (typeof r == "string") a = r;
+	else if (r && typeof r == "object") a = r.path, o = r.params;
+	else return;
+	let s = n.t(a, o);
+	s === a && i.preserve || (e.textContent = s);
+}
+//#endregion
+//#region src/vue/plugin.ts
+function s(e, t, r = {}) {
+	e.provide(n, t), t.globalInstall && (e.config.globalProperties.$t = t.t, e.config.globalProperties.$i18n = t);
+	let i = r.directive === !1 ? null : typeof r.directive == "string" ? r.directive : "t";
+	i && e.directive(i, a(t));
+}
+//#endregion
+export { n as FINT_I18N_KEY, a as createVTDirective, s as installI18n, r as useFintI18n, i as useI18nScope };

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@feugene/fint-i18n",
+  "version": "0.1.0",
+  "description": "Lightweight Vue 3 i18n library with lazy-loading blocks and template caching",
+  "author": "feugene <feugene@example.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/efureev/fint-i18n#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/efureev/fint-i18n.git"
+  },
+  "bugs": {
+    "url": "https://github.com/efureev/fint-i18n/issues"
+  },
+  "keywords": [
+    "vue",
+    "i18n",
+    "localization",
+    "lazy-loading",
+    "vue3",
+    "translation"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/types/core/index.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./vue": {
+      "types": "./dist/types/vue/index.d.ts",
+      "import": "./dist/vue.js"
+    },
+    "./plugins": {
+      "types": "./dist/types/plugins/index.d.ts",
+      "import": "./dist/plugins.js"
+    }
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "vue": "^3.5.32"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^7.7.3",
+    "@iconify-json/lucide": "^1.2.101",
+    "@types/node": "^25.5.2",
+    "@unocss/eslint-plugin": "^66.6.7",
+    "@unocss/reset": "^66.6.7",
+    "@vitejs/plugin-vue": "^6.0.5",
+    "@vue/test-utils": "^2.4.6",
+    "eslint": "^10.2.0",
+    "globals": "^17.4.0",
+    "jsdom": "^29.0.1",
+    "rollup-plugin-visualizer": "^7.0.1",
+    "typescript": "^5.9.3",
+    "unocss": "^66.6.7",
+    "vite": "^8.0.5",
+    "vitest": "^4.1.2",
+    "vue": "^3.5.32",
+    "vue-tsc": "^3.2.6"
+  },
+  "scripts": {
+    "dev": "vite --config playground/vite.config.ts",
+    "playground": "vite --config playground/vite.config.ts",
+    "playground:build": "vite build --config playground/vite.config.ts",
+    "build:analyze": "ANALYZE=true vite build && vue-tsc -p tsconfig.build.json",
+    "build": "vite build && vue-tsc -p tsconfig.build.json",
+    "prepublishOnly": "yarn build",
+    "bench": "mkdir -p dist/analysis && vitest bench --run --config vite.config.ts --environment node --outputJson dist/analysis/bench-results.json bench/core.bench.ts",
+    "type-check": "vue-tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  }
+}