@kylexd/remote-i18n-kit 0.0.1

package/README.md

@@ -0,0 +1,86 @@
+# @kylexd/remote-i18n-kit
+
+## Overview
+
+Remote locale loading and locale file tooling package.
+
+The runtime entry handles remote message loading, merging, and cache access. The node entry provides scripts for local locale files and generated outputs.
+
+## Install
+
+```bash
+npm install @kylexd/remote-i18n-kit
+```
+
+## Exports
+
+Runtime entry:
+
+- `createRemoteI18nLoader`
+- `createLangCache`
+- `mergeLocaleMessages`
+- `normalizeRemoteMessages`
+
+Runtime options include locale range controls such as `cacheLocales`, `requestLocales`, and `mergeLocales`.
+
+Node entry:
+
+- `syncRemoteLocales`
+- `findEmptyLocales`
+- `loadLocaleJsonByLocales`
+- `writeLocaleJsonByLocales`
+- `generateLocaleExcel`
+- `createLocaleRows`
+- `writeLocaleOutput`
+
+## Basic usage
+
+```ts
+import { createRemoteI18nLoader } from '@kylexd/remote-i18n-kit'
+
+const loader = createRemoteI18nLoader({
+  locales,
+  namespace,
+  requestRemoteMessages,
+})
+```
+
+```ts
+const loader = createRemoteI18nLoader({
+  locales,
+  namespace,
+  requestRemoteMessages,
+  requestLocales: () => [currentLocale],
+  mergeLocales: () => [currentLocale],
+})
+```
+
+```ts
+import { syncRemoteLocales } from '@kylexd/remote-i18n-kit/node'
+
+await syncRemoteLocales({
+  locales,
+  namespace,
+  apiUrl,
+  localeDir,
+  outputDir,
+  excelColumns,
+})
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Notes
+
+- The runtime entry is intended for browser code.
+- The node entry is intended for file and output generation scripts.
+- Locale keys, namespaces, cache keys, and output columns are provided by the host project.
+- Runtime locale ranges default to `locales` unless configured by the host project.
+
+## License
+
+UNLICENSED

package/dist/cache/langCache.d.ts

@@ -0,0 +1,7 @@
+import type { CachedLangsData, LangCacheOptions, LocaleKey } from '../types';
+export declare function createLangCache<L extends LocaleKey = LocaleKey>(options: LangCacheOptions<L>): {
+    getLangs: () => Promise<CachedLangsData<L> | undefined>;
+    setLangs: (data: CachedLangsData<L>) => Promise<void>;
+    clearLangs: () => Promise<void>;
+};
+export declare function validateLangsData(data: unknown): data is CachedLangsData;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './cache/langCache';
+export * from './runtime/loader';
+export * from './runtime/messageUtils';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,138 @@
+import { a as mergeLocaleMessages, i as getChangedMessages, n as flattenMessages, o as normalizeRemoteMessages, r as getChangedLocaleMessages, s as unflattenMessages, t as defaultMergeMessages } from "./messageUtils-CXPzsQ5q.js";
+import { openDB } from "idb";
+//#region src/runtime/locales.ts
+function resolveLocales(value, fallback) {
+	if (!value) return fallback;
+	return typeof value === "function" ? value() : value;
+}
+function pickLocaleMessages(locales, messages) {
+	const result = {};
+	locales.forEach((locale) => {
+		if (messages[locale]) result[locale] = messages[locale];
+	});
+	return result;
+}
+//#endregion
+//#region src/cache/langCache.ts
+function createLangCache(options) {
+	const storage = options.storage ?? globalThis.localStorage;
+	const dbName = options.dbName ?? "remote-i18n-langs";
+	const storeName = options.storeName ?? "langs";
+	const dbVersion = options.dbVersion ?? 1;
+	const getLangs = async () => {
+		if (options.useIndexedDB) return await getIdbLangs();
+		return getStorageLangs();
+	};
+	const setLangs = async (data) => {
+		const nextData = normalizeCachedData(data);
+		if (options.useIndexedDB) return await setIdbLangs(nextData);
+		setStorageLangs(nextData);
+	};
+	const clearLangs = async () => {
+		if (options.useIndexedDB) {
+			const tx = (await initDB()).transaction(storeName, "readwrite");
+			await tx.objectStore(storeName).delete(options.cacheKey);
+			await tx.done;
+			return;
+		}
+		storage.removeItem(options.cacheKey);
+	};
+	const initDB = async () => {
+		return await openDB(dbName, dbVersion, { upgrade(db) {
+			if (!db.objectStoreNames.contains(storeName)) db.createObjectStore(storeName);
+		} });
+	};
+	const setIdbLangs = async (data) => {
+		validateLangsData(data);
+		const tx = (await initDB()).transaction(storeName, "readwrite");
+		await tx.objectStore(storeName).put(data, options.cacheKey);
+		await tx.done;
+	};
+	const getIdbLangs = async () => {
+		const data = await (await initDB()).transaction(storeName, "readonly").objectStore(storeName).get(options.cacheKey);
+		return validateLangsData(data) ? data : void 0;
+	};
+	const setStorageLangs = (data) => {
+		validateLangsData(data);
+		storage.setItem(options.cacheKey, JSON.stringify(data));
+	};
+	const getStorageLangs = () => {
+		const rawData = storage.getItem(options.cacheKey);
+		if (!rawData) return void 0;
+		const data = JSON.parse(rawData);
+		return validateLangsData(data) ? data : void 0;
+	};
+	const normalizeCachedData = (data) => {
+		if (!options.locales && !options.cacheLocales) return data;
+		const fallbackLocales = options.locales ?? Object.keys(data.langs);
+		const cacheLocales = resolveLocales(options.cacheLocales, fallbackLocales);
+		const langs = pickLocaleMessages(cacheLocales, data.langs);
+		if (!options.baseMessages) return {
+			version: data.version,
+			langs
+		};
+		return {
+			version: data.version,
+			langs: getChangedLocaleMessages(cacheLocales, options.baseMessages, langs)
+		};
+	};
+	return {
+		getLangs,
+		setLangs,
+		clearLangs
+	};
+}
+function validateLangsData(data) {
+	if (!data || typeof data !== "object") return false;
+	const value = data;
+	return typeof value.version === "string" && Boolean(value.langs) && typeof value.langs === "object";
+}
+//#endregion
+//#region src/runtime/loader.ts
+function createRemoteI18nLoader(options) {
+	const loadCachedMessages = async () => {
+		const cached = await options.cache?.getLangs();
+		if (cached?.langs) mergeLocaleMessages({
+			locales: resolveLocales(options.mergeLocales, options.locales),
+			incomingMessages: cached.langs,
+			adapter: options.adapter,
+			merge: options.merge
+		});
+		return cached;
+	};
+	const loadRemoteMessages = async () => {
+		const requestLocales = resolveLocales(options.requestLocales, options.locales);
+		const response = await options.requestRemoteMessages({
+			locales: requestLocales,
+			namespace: options.namespace
+		});
+		const langs = normalizeRemoteMessages({
+			locales: requestLocales,
+			langMap: response.data.langMap,
+			unflattenOptions: options.unflattenOptions ?? { object: true }
+		});
+		return {
+			version: response.data.version ?? options.defaultVersion ?? "1.0.0",
+			langs
+		};
+	};
+	const loadAndMergeMessages = async () => {
+		await loadCachedMessages();
+		const remote = await loadRemoteMessages();
+		mergeLocaleMessages({
+			locales: resolveLocales(options.mergeLocales, options.locales),
+			incomingMessages: remote.langs,
+			adapter: options.adapter,
+			merge: options.merge
+		});
+		await options.cache?.setLangs(remote);
+		return remote;
+	};
+	return {
+		loadCachedMessages,
+		loadRemoteMessages,
+		loadAndMergeMessages
+	};
+}
+//#endregion
+export { createLangCache, createRemoteI18nLoader, defaultMergeMessages, flattenMessages, getChangedLocaleMessages, getChangedMessages, mergeLocaleMessages, normalizeRemoteMessages, unflattenMessages, validateLangsData };

package/dist/messageUtils-CXPzsQ5q.js

@@ -0,0 +1,50 @@
+import deepmerge from "deepmerge";
+import { flatten, unflatten } from "flat";
+//#region src/runtime/messageUtils.ts
+function defaultMergeMessages(current, incoming) {
+	return deepmerge(current, incoming);
+}
+function flattenMessages(messages) {
+	return flatten(messages);
+}
+function unflattenMessages(messages, options) {
+	return unflatten(messages, options);
+}
+function normalizeRemoteMessages(options) {
+	const messages = {};
+	options.locales.forEach((locale) => {
+		const flatMessages = options.langMap?.[locale];
+		if (flatMessages) messages[locale] = unflattenMessages(flatMessages, options.unflattenOptions);
+	});
+	return messages;
+}
+function getChangedMessages(base = {}, target = {}) {
+	const baseFlat = flattenMessages(base);
+	const targetFlat = flattenMessages(target);
+	const diff = {};
+	Object.keys(targetFlat).forEach((key) => {
+		if (baseFlat[key] !== targetFlat[key]) diff[key] = targetFlat[key];
+	});
+	return unflattenMessages(diff, { object: true });
+}
+function getChangedLocaleMessages(locales, baseMessages = {}, targetMessages = {}) {
+	const result = {};
+	locales.forEach((locale) => {
+		if (targetMessages[locale]) result[locale] = getChangedMessages(baseMessages[locale], targetMessages[locale]);
+	});
+	return result;
+}
+function mergeLocaleMessages(options) {
+	const merge = options.merge ?? defaultMergeMessages;
+	const mergedMessages = {};
+	options.locales.forEach((locale) => {
+		const incoming = options.incomingMessages[locale];
+		if (!incoming) return;
+		const merged = merge(options.adapter?.getLocaleMessage(locale) ?? options.currentMessages?.[locale] ?? {}, incoming);
+		mergedMessages[locale] = merged;
+		options.adapter?.setLocaleMessage(locale, merged);
+	});
+	return mergedMessages;
+}
+//#endregion
+export { mergeLocaleMessages as a, getChangedMessages as i, flattenMessages as n, normalizeRemoteMessages as o, getChangedLocaleMessages as r, unflattenMessages as s, defaultMergeMessages as t };

package/dist/node/excel.d.ts

@@ -0,0 +1,16 @@
+import type { ExcelColumn, LocaleKey, FlatLocaleMessageMap, LocaleRow } from '../types';
+export interface GenerateLocaleExcelOptions<L extends LocaleKey = LocaleKey> {
+    namespace: string;
+    data: FlatLocaleMessageMap<L>;
+    columns: Array<ExcelColumn<L>>;
+    outputDir: string;
+    outputBaseName: string;
+}
+export interface WriteLocaleOutputOptions {
+    rows: LocaleRow[];
+    writer: (rows: LocaleRow[]) => void | Promise<void>;
+}
+export declare function generateLocaleExcel<L extends LocaleKey = LocaleKey>(options: GenerateLocaleExcelOptions<L>): Promise<Record<string, unknown>[]>;
+export declare function writeLocaleOutput(options: WriteLocaleOutputOptions): Promise<void>;
+export declare function createLocaleRows<L extends LocaleKey = LocaleKey>(namespace: string, data: FlatLocaleMessageMap<L>, columns: Array<ExcelColumn<L>>): Record<string, unknown>[];
+export declare const createExcelRows: typeof createLocaleRows;

package/dist/node/localeFiles.d.ts

@@ -0,0 +1,8 @@
+import type { LocaleDirOptions, LocaleKey, LocaleMessageMap, LocaleMessages } from '../types';
+export declare function getDefaultLocaleDir<L extends LocaleKey>(localeDir: string, locale: L): string;
+export declare function loadAllJson(dir: string): Promise<LocaleMessages>;
+export declare function loadLocaleJsonByLocales<L extends LocaleKey = LocaleKey>(options: LocaleDirOptions<L>): Promise<LocaleMessageMap<L>>;
+export declare function writeJsonFiles(dir: string, data: LocaleMessages): Promise<void>;
+export declare function writeLocaleJsonByLocales<L extends LocaleKey = LocaleKey>(options: LocaleDirOptions<L> & {
+    messages: LocaleMessageMap<L>;
+}): Promise<void>;

package/dist/node/remote.d.ts

@@ -0,0 +1,2 @@
+import type { NodeRemoteRequestOptions, RemoteLangResponse, LocaleKey } from '../types';
+export declare function requestRemoteLangResult<L extends LocaleKey = LocaleKey>(options: NodeRemoteRequestOptions<L>): Promise<RemoteLangResponse<L>>;

package/dist/node/syncRemoteLocales.d.ts

@@ -0,0 +1,15 @@
+import type { FlatLocaleMessageMap, LocaleKey, LocaleMessageMap, LocaleMessages, LocaleScriptOptions, FindEmptyLocalesOptions } from '../types';
+export declare function syncRemoteLocales<L extends LocaleKey = LocaleKey>(options: LocaleScriptOptions<L>): Promise<{
+    localMessages: Partial<Record<L, LocaleMessages>>;
+    remoteMessages: Partial<Record<L, LocaleMessages>>;
+    diffMessages: Partial<Record<L, import("..").FlatLocaleMessages>>;
+    mergedMessages: Partial<Record<L, LocaleMessages>>;
+    rows: Record<string, unknown>[];
+    version: string | undefined;
+}>;
+export declare function findEmptyLocales<L extends LocaleKey = LocaleKey>(options: FindEmptyLocalesOptions<L>): Promise<{
+    emptyKeys: string[];
+    emptyMessages: Partial<Record<L, import("..").FlatLocaleMessages>>;
+    rows: Record<string, unknown>[];
+}>;
+export declare function getLocalMissingFromRemote<L extends LocaleKey = LocaleKey>(locales: L[], localMessages: LocaleMessageMap<L>, remoteFlatMessages: FlatLocaleMessageMap<L>): FlatLocaleMessageMap<L>;

package/dist/node.d.ts

@@ -0,0 +1,5 @@
+export * from './node/excel';
+export * from './node/localeFiles';
+export * from './node/remote';
+export * from './node/syncRemoteLocales';
+export * from './types';

package/dist/node.js

@@ -0,0 +1,193 @@
+import { o as normalizeRemoteMessages } from "./messageUtils-CXPzsQ5q.js";
+import deepmerge from "deepmerge";
+import { flatten } from "flat";
+import fs from "node:fs/promises";
+import path from "node:path";
+import xlsx from "xlsx";
+//#region src/node/excel.ts
+async function generateLocaleExcel(options) {
+	await fs.mkdir(options.outputDir, { recursive: true });
+	const rows = createLocaleRows(options.namespace, options.data, options.columns);
+	const workbook = xlsx.utils.book_new();
+	const worksheet = xlsx.utils.json_to_sheet(rows, { header: options.columns.map((column) => column.label) });
+	xlsx.utils.book_append_sheet(workbook, worksheet, "Sheet1");
+	xlsx.writeFile(workbook, path.join(options.outputDir, `${options.outputBaseName}.xlsx`));
+	await fs.writeFile(path.join(options.outputDir, `${options.outputBaseName}.json`), JSON.stringify(rows, null, 2));
+	return rows;
+}
+async function writeLocaleOutput(options) {
+	await options.writer(options.rows);
+}
+function createLocaleRows(namespace, data, columns) {
+	const keySet = /* @__PURE__ */ new Set();
+	Object.values(data).forEach((messages) => {
+		Object.keys(messages ?? {}).forEach((key) => keySet.add(key));
+	});
+	return Array.from(keySet).map((messageKey) => {
+		const row = {};
+		columns.forEach((column) => {
+			if (column.key === "namespace") row[column.label] = namespace;
+			else if (column.key === "key") row[column.label] = messageKey;
+			else if (column.locale) row[column.label] = data[column.locale]?.[messageKey];
+			else row[column.label] = data[column.key]?.[messageKey];
+		});
+		return row;
+	});
+}
+var createExcelRows = createLocaleRows;
+//#endregion
+//#region src/node/localeFiles.ts
+function getDefaultLocaleDir(localeDir, locale) {
+	return path.join(localeDir, locale);
+}
+async function loadAllJson(dir) {
+	const files = await fs.readdir(dir);
+	const data = {};
+	await Promise.all(files.map(async (file) => {
+		if (path.extname(file) !== ".json") return;
+		const name = path.basename(file, ".json");
+		const content = await fs.readFile(path.join(dir, file), "utf8");
+		data[name] = JSON.parse(content);
+	}));
+	return data;
+}
+async function loadLocaleJsonByLocales(options) {
+	const getLocaleDir = options.getLocaleDir ?? getDefaultLocaleDir;
+	const data = {};
+	await Promise.all(options.locales.map(async (locale) => {
+		data[locale] = await loadAllJson(getLocaleDir(options.localeDir, locale));
+	}));
+	return data;
+}
+async function writeJsonFiles(dir, data) {
+	await fs.mkdir(dir, { recursive: true });
+	const existingNames = (await fs.readdir(dir).catch(() => [])).filter((file) => path.extname(file) === ".json").map((file) => path.basename(file, ".json"));
+	const names = Array.from(new Set([...Object.keys(data), ...existingNames]));
+	await Promise.all(names.map(async (name) => {
+		await fs.writeFile(path.join(dir, `${name}.json`), `${JSON.stringify(data[name] ?? {}, null, 2)}\n`);
+	}));
+}
+async function writeLocaleJsonByLocales(options) {
+	const getLocaleDir = options.getLocaleDir ?? getDefaultLocaleDir;
+	await Promise.all(options.locales.map(async (locale) => {
+		await writeJsonFiles(getLocaleDir(options.localeDir, locale), options.messages[locale] ?? {});
+	}));
+}
+//#endregion
+//#region src/node/remote.ts
+async function requestRemoteLangResult(options) {
+	return await (await (options.fetchImpl ?? fetch)(options.apiUrl, {
+		method: "POST",
+		body: JSON.stringify({
+			locales: options.locales,
+			namespace: options.namespace
+		}),
+		headers: { "Content-Type": "application/json" }
+	})).json();
+}
+//#endregion
+//#region src/node/syncRemoteLocales.ts
+async function syncRemoteLocales(options) {
+	const localMessages = await loadLocaleJsonByLocales(options);
+	const remoteResponse = await requestRemoteLangResult(options);
+	const remoteMessages = normalizeRemoteMessages({
+		locales: options.locales,
+		langMap: remoteResponse.data.langMap,
+		unflattenOptions: options.unflattenOptions ?? { object: true }
+	});
+	const diffMessages = getLocalMissingFromRemote(options.locales, localMessages, remoteResponse.data.langMap ?? {});
+	const outputBaseName = options.outputBaseName ?? options.namespace;
+	const rows = await generateLocaleExcel({
+		namespace: options.namespace,
+		data: diffMessages,
+		columns: options.excelColumns,
+		outputDir: options.outputDir,
+		outputBaseName
+	});
+	await options.onRowsGenerated?.({
+		namespace: options.namespace,
+		rows,
+		data: diffMessages,
+		outputBaseName
+	});
+	const merge = options.merge ?? ((current, incoming) => deepmerge(current, incoming));
+	const mergedMessages = {};
+	options.locales.forEach((locale) => {
+		mergedMessages[locale] = merge(localMessages[locale] ?? {}, remoteMessages[locale] ?? {});
+	});
+	await writeLocaleJsonByLocales({
+		locales: options.locales,
+		localeDir: options.localeDir,
+		getLocaleDir: options.getLocaleDir,
+		messages: mergedMessages
+	});
+	return {
+		localMessages,
+		remoteMessages,
+		diffMessages,
+		mergedMessages,
+		rows,
+		version: remoteResponse.data.version
+	};
+}
+async function findEmptyLocales(options) {
+	const localMessages = await loadLocaleJsonByLocales(options);
+	const remoteFlat = (await requestRemoteLangResult(options)).data.langMap ?? {};
+	const mergedFlat = {};
+	options.locales.forEach((locale) => {
+		const remoteMessages = remoteFlat[locale] ?? {};
+		mergedFlat[locale] = {
+			...flatten(localMessages[locale] ?? {}),
+			...remoteMessages
+		};
+	});
+	const requiredLocales = options.requiredLocales ?? options.locales;
+	const emptyKeys = /* @__PURE__ */ new Set();
+	Object.values(mergedFlat).forEach((messages) => {
+		Object.keys(messages ?? {}).forEach((key) => {
+			if (requiredLocales.some((locale) => !mergedFlat[locale]?.[key])) emptyKeys.add(key);
+		});
+	});
+	const emptyMessages = {};
+	options.locales.forEach((locale) => {
+		const localeMessages = {};
+		emptyKeys.forEach((key) => {
+			localeMessages[key] = mergedFlat[locale]?.[key] ?? "";
+		});
+		emptyMessages[locale] = localeMessages;
+	});
+	const outputBaseName = options.outputBaseName ?? `${options.namespace}_empty`;
+	const rows = await generateLocaleExcel({
+		namespace: options.namespace,
+		data: emptyMessages,
+		columns: options.excelColumns,
+		outputDir: options.outputDir,
+		outputBaseName
+	});
+	await options.onRowsGenerated?.({
+		namespace: options.namespace,
+		rows,
+		data: emptyMessages,
+		outputBaseName
+	});
+	return {
+		emptyKeys: Array.from(emptyKeys),
+		emptyMessages,
+		rows
+	};
+}
+function getLocalMissingFromRemote(locales, localMessages, remoteFlatMessages) {
+	const diff = {};
+	locales.forEach((locale) => {
+		const localFlat = flatten(localMessages[locale] ?? {});
+		const remoteFlat = remoteFlatMessages[locale] ?? {};
+		const localeDiff = {};
+		Object.keys(localFlat).forEach((key) => {
+			if (!remoteFlat[key]) localeDiff[key] = localFlat[key];
+		});
+		diff[locale] = localeDiff;
+	});
+	return diff;
+}
+//#endregion
+export { createExcelRows, createLocaleRows, findEmptyLocales, generateLocaleExcel, getDefaultLocaleDir, getLocalMissingFromRemote, loadAllJson, loadLocaleJsonByLocales, requestRemoteLangResult, syncRemoteLocales, writeJsonFiles, writeLocaleJsonByLocales, writeLocaleOutput };

package/dist/runtime/loader.d.ts

@@ -0,0 +1,6 @@
+import type { CachedLangsData, LocaleKey, RemoteI18nLoaderOptions } from '../types';
+export declare function createRemoteI18nLoader<L extends LocaleKey = LocaleKey>(options: RemoteI18nLoaderOptions<L>): {
+    loadCachedMessages: () => Promise<CachedLangsData<L> | undefined>;
+    loadRemoteMessages: () => Promise<CachedLangsData<L>>;
+    loadAndMergeMessages: () => Promise<CachedLangsData<L>>;
+};

package/dist/runtime/locales.d.ts

@@ -0,0 +1,3 @@
+import type { LocaleKey, LocaleListOption, LocaleMessageMap } from '../types';
+export declare function resolveLocales<L extends LocaleKey>(value: LocaleListOption<L> | undefined, fallback: L[]): L[];
+export declare function pickLocaleMessages<L extends LocaleKey>(locales: L[], messages: LocaleMessageMap<L>): LocaleMessageMap<L>;

package/dist/runtime/messageUtils.d.ts

@@ -0,0 +1,9 @@
+import { unflatten } from 'flat';
+import type { FlatLocaleMessages, LocaleKey, LocaleMessageMap, LocaleMessages, MergeLocaleMessagesOptions, NormalizeRemoteMessagesOptions } from '../types';
+export declare function defaultMergeMessages(current: LocaleMessages, incoming: LocaleMessages): LocaleMessages;
+export declare function flattenMessages(messages: LocaleMessages): FlatLocaleMessages;
+export declare function unflattenMessages(messages: FlatLocaleMessages, options?: Parameters<typeof unflatten>[1]): LocaleMessages;
+export declare function normalizeRemoteMessages<L extends LocaleKey = LocaleKey>(options: NormalizeRemoteMessagesOptions<L>): LocaleMessageMap<L>;
+export declare function getChangedMessages(base?: LocaleMessages, target?: LocaleMessages): LocaleMessages;
+export declare function getChangedLocaleMessages<L extends LocaleKey = LocaleKey>(locales: L[], baseMessages?: LocaleMessageMap<L>, targetMessages?: LocaleMessageMap<L>): LocaleMessageMap<L>;
+export declare function mergeLocaleMessages<L extends LocaleKey = LocaleKey>(options: MergeLocaleMessagesOptions<L>): LocaleMessageMap<L>;

package/dist/types/index.d.ts

@@ -0,0 +1,100 @@
+import type { UnflattenOptions } from 'flat';
+export type LocaleKey = string;
+export type LocaleMessages = Record<string, unknown>;
+export type FlatLocaleMessages = Record<string, string>;
+export type LocaleMessageMap<L extends LocaleKey = LocaleKey> = Partial<Record<L, LocaleMessages>>;
+export type FlatLocaleMessageMap<L extends LocaleKey = LocaleKey> = Partial<Record<L, FlatLocaleMessages>>;
+export type LocaleListOption<L extends LocaleKey = LocaleKey> = L[] | (() => L[]);
+export interface RemoteLangRequest<L extends LocaleKey = LocaleKey> {
+    locales: L[];
+    namespace: string;
+}
+export interface RemoteLangPayload<L extends LocaleKey = LocaleKey> {
+    langMap?: FlatLocaleMessageMap<L>;
+    version?: string;
+}
+export interface RemoteLangResponse<L extends LocaleKey = LocaleKey> {
+    data: RemoteLangPayload<L>;
+}
+export type RequestRemoteMessages<L extends LocaleKey = LocaleKey> = (request: RemoteLangRequest<L>) => Promise<RemoteLangResponse<L>>;
+export interface CachedLangsData<L extends LocaleKey = LocaleKey> {
+    version: string;
+    langs: LocaleMessageMap<L>;
+}
+export interface LangCacheOptions<L extends LocaleKey = LocaleKey> {
+    cacheKey: string;
+    storage?: Storage;
+    useIndexedDB?: boolean;
+    dbName?: string;
+    storeName?: string;
+    dbVersion?: number;
+    baseMessages?: LocaleMessageMap<L>;
+    locales?: L[];
+    cacheLocales?: LocaleListOption<L>;
+}
+export interface LocaleMessageAdapter<L extends LocaleKey = LocaleKey> {
+    getLocaleMessage: (locale: L) => LocaleMessages;
+    setLocaleMessage: (locale: L, message: LocaleMessages) => void;
+}
+export interface MergeLocaleMessagesOptions<L extends LocaleKey = LocaleKey> {
+    locales: L[];
+    currentMessages?: LocaleMessageMap<L>;
+    incomingMessages: LocaleMessageMap<L>;
+    adapter?: LocaleMessageAdapter<L>;
+    merge?: (current: LocaleMessages, incoming: LocaleMessages) => LocaleMessages;
+}
+export interface NormalizeRemoteMessagesOptions<L extends LocaleKey = LocaleKey> {
+    locales: L[];
+    langMap?: FlatLocaleMessageMap<L>;
+    unflattenOptions?: UnflattenOptions;
+}
+export interface RemoteI18nLoaderOptions<L extends LocaleKey = LocaleKey> {
+    locales: L[];
+    namespace: string;
+    requestRemoteMessages: RequestRemoteMessages<L>;
+    cache?: ReturnType<typeof import('../cache/langCache').createLangCache<L>>;
+    adapter?: LocaleMessageAdapter<L>;
+    unflattenOptions?: UnflattenOptions;
+    merge?: (current: LocaleMessages, incoming: LocaleMessages) => LocaleMessages;
+    defaultVersion?: string;
+    requestLocales?: LocaleListOption<L>;
+    mergeLocales?: LocaleListOption<L>;
+}
+export interface ExcelColumn<L extends LocaleKey = LocaleKey> {
+    key: 'namespace' | 'key' | L | string;
+    label: string;
+    locale?: L;
+}
+export type LocaleRow = Record<string, unknown>;
+export interface LocaleRowsGeneratedPayload<L extends LocaleKey = LocaleKey> {
+    namespace: string;
+    rows: LocaleRow[];
+    data: FlatLocaleMessageMap<L>;
+    outputBaseName: string;
+}
+export interface NodeRemoteRequestOptions<L extends LocaleKey = LocaleKey> {
+    apiUrl: string;
+    locales: L[];
+    namespace: string;
+    fetchImpl?: typeof fetch;
+}
+export interface LocaleDirOptions<L extends LocaleKey = LocaleKey> {
+    locales: L[];
+    localeDir: string;
+    getLocaleDir?: (localeDir: string, locale: L) => string;
+}
+export interface LocaleScriptOptions<L extends LocaleKey = LocaleKey> extends LocaleDirOptions<L>, NodeRemoteRequestOptions<L> {
+    outputDir: string;
+    excelColumns: Array<ExcelColumn<L>>;
+    outputBaseName?: string;
+    unflattenOptions?: UnflattenOptions;
+    merge?: (current: LocaleMessages, incoming: LocaleMessages) => LocaleMessages;
+    onRowsGenerated?: (payload: LocaleRowsGeneratedPayload<L>) => void | Promise<void>;
+}
+export interface FindEmptyLocalesOptions<L extends LocaleKey = LocaleKey> extends LocaleDirOptions<L>, NodeRemoteRequestOptions<L> {
+    outputDir: string;
+    excelColumns: Array<ExcelColumn<L>>;
+    outputBaseName?: string;
+    requiredLocales?: L[];
+    onRowsGenerated?: (payload: LocaleRowsGeneratedPayload<L>) => void | Promise<void>;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@kylexd/remote-i18n-kit",
+  "version": "0.0.1",
+  "description": "Remote i18n runtime and locale sync utilities.",
+  "author": "kyle-z",
+  "license": "UNLICENSED",
+  "keywords": [
+    "i18n",
+    "locales",
+    "remote",
+    "xlsx"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.json --emitDeclarationOnly",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "pack:check": "npm run build && npm --cache .npm-cache pack --dry-run"
+  },
+  "dependencies": {
+    "deepmerge": "^4.3.1",
+    "flat": "^6.0.1",
+    "idb": "^8.0.3",
+    "xlsx": "^0.18.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "typescript": "~5.7.3",
+    "vite": "^8.0.14"
+  }
+}