@vixen-tech/lynguist 0.0.1 → 1.0.0

package/README.md

@@ -0,0 +1,272 @@
+# Lynguist
+
+A lightweight, type-safe internationalization (i18n) library for JavaScript/TypeScript applications with Laravel translation format support.
+
+> For Laravel version, see [vixen-tech/laravel-lynguist](https://github.com/vixen-tech/laravel-lynguist).
+
+Inspired by [laravel-translator-js](https://github.com/sergix44/laravel-translator-js) and [lingua](https://github.com/cyberwolf-studio/lingua).
+
+## Features
+
+- **Multi-language support** - 60+ languages with proper pluralization rules
+- **Runtime locale switching** - Dynamically change languages with event notifications
+- **Smart placeholders** - Laravel-style variable replacement with case transformation
+- **Advanced pluralization** - Pipe-separated and interval notation support
+- **Vite integration** - Virtual module plugin for loading JSON translation files (supports any framework)
+- **Type-safe** - Full TypeScript support with typed translation keys
+
+## Installation
+
+```bash
+npm install @vixen-tech/lynguist
+```
+```bash
+yarn install @vixen-tech/lynguist
+```
+
+## Quick Start
+
+### With Vite
+
+**1. Configure the Vite plugin:**
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { lynguist } from '@vixen-tech/lynguist/vite'
+
+export default defineConfig({
+    plugins: [
+        lynguist({
+            langPath: 'lang', // default
+            additionalLangPaths: ['vendor/package/lang'] // optional
+        })
+    ]
+})
+```
+
+**2. Create translation files:**
+
+```json
+// lang/en.json
+{
+    "greeting": "Hello :name",
+    "items": "One item|:count items",
+    "welcome": "Hello World"
+}
+```
+
+> Works best with its Laravel counterpart: [vixen-tech/laravel-lynguist](https://github.com/vixen-tech/laravel-lynguist).
+
+**3. Use in your application:**
+
+```typescript
+import { __, setLocale } from '@vixen-tech/lynguist'
+
+// Simple translation
+__('welcome') // "Hello World"
+
+// With placeholder
+__('greeting', { name: 'John' }) // "Hello John"
+
+// With pluralization
+__('items', 5) // "5 items"
+
+// Switch locale
+setLocale('de')
+```
+
+### Manual Setup
+
+```typescript
+import { Lynguist, __ } from '@vixen-tech/lynguist'
+
+Lynguist({
+    locale: 'en',
+    translations: {
+        welcome: 'Hello World',
+        greeting: 'Hello :name'
+    }
+})
+
+__('welcome') // "Hello World"
+```
+
+## Inertia.js
+
+To reactively switch locale, you can create a wrapper component that assigns current locale to document's `lang` attribute:
+
+```typescript
+const locale = usePage().props.locale
+
+if (typeof window !== 'undefined') {
+    document.documentElement.lang = locale
+}
+```
+
+Here's what it looks like in React:
+
+```typescript jsx
+export function Wrapper({ children }: PropsWithChildren) {
+    const locale = usePage<SharedData>().props.locale
+
+    if (typeof window !== 'undefined') {
+        document.documentElement.lang = locale
+    }
+
+    return <>{children}</>
+}
+```
+
+## Placeholders
+
+Lynguist supports Laravel-style placeholder replacement with automatic case transformation:
+
+```typescript
+const translations = {
+    greeting: 'Hello :name',
+    welcome: 'Welcome :Name',       // capitalized
+    shout: 'HEY :NAME'              // uppercase
+}
+
+__('greeting', { name: 'John' })    // "Hello John"
+__('welcome', { Name: 'john' })     // "Welcome John"
+__('shout', { NAME: 'john' })       // "HEY JOHN"
+```
+
+## Pluralization
+
+### Basic Pluralization
+
+Use pipe-separated values for simple plural forms:
+
+```typescript
+const translations = {
+    items: 'One item|:count items'
+}
+
+__('items', 1)  // "One item"
+__('items', 5)  // "5 items"
+```
+
+### Interval Notation
+
+For more control, use interval notation:
+
+```typescript
+const translations = {
+    apples: '{0} No apples|{1} One apple|[2,*] :count apples'
+}
+
+__('apples', 0)   // "No apples"
+__('apples', 1)   // "One apple"
+__('apples', 5)   // "5 apples"
+```
+
+### Language-Specific Rules
+
+Lynguist handles complex pluralization rules for languages like Russian, Arabic, and Polish:
+
+```typescript
+// Russian has 3 plural forms
+const translations = {
+    apples: ':count яблоко|:count яблока|:count яблок'
+}
+
+__('apples', 1)   // "1 яблоко"
+__('apples', 2)   // "2 яблока"
+__('apples', 5)   // "5 яблок"
+__('apples', 21)  // "21 яблоко"
+```
+
+## API Reference
+
+### `__(key, countOrReplace?, replace?)`
+
+Main translation function supporting both simple translations and pluralization.
+
+```typescript
+__('welcome')                        // Simple translation
+__('greeting', { name: 'John' })     // With placeholders
+__('items', 5)                       // With count
+__('items', 5, { type: 'file' })     // With count and placeholders
+```
+
+### `trans(key, replace?)`
+
+Simple translation without pluralization.
+
+```typescript
+trans('greeting', { name: 'John' })  // "Hello John"
+```
+
+### `transChoice(key, count, replace?)`
+
+Plural-aware translation.
+
+```typescript
+transChoice('items', 5)              // "5 items"
+```
+
+### `setLocale(locale)`
+
+Change the current language.
+
+```typescript
+setLocale('de')
+```
+
+### `getLocale()`
+
+Get the current language code.
+
+```typescript
+getLocale()  // "en"
+```
+
+### `getAvailableLocales()`
+
+Get all available language codes.
+
+```typescript
+getAvailableLocales()  // ["en", "de", "fr"]
+```
+
+### `getTranslations(locale?)`
+
+Get translations for a specific or current locale.
+
+```typescript
+getTranslations()       // Current locale translations
+getTranslations('de')   // German translations
+```
+
+### `onLocaleChange(callback)`
+
+Subscribe to locale change events. Returns an unsubscribe function.
+
+```typescript
+const unsubscribe = onLocaleChange((newLocale, previousLocale) => {
+    console.log(`Changed from ${previousLocale} to ${newLocale}`)
+})
+
+// Later: stop listening
+unsubscribe()
+```
+
+## Vite Plugin Options
+
+| Option                | Type       | Default     | Description                            |
+|-----------------------|------------|-------------|----------------------------------------|
+| `langPath`            | `string`   | `'lang'`    | Path to the translation directory      |
+| `additionalLangPaths` | `string[]` | `undefined` | Additional paths for translation files |
+
+## Supported Languages
+
+Lynguist supports 60+ languages with proper pluralization rules including:
+
+Afrikaans, Amharic, Arabic, Belarusian, Bengali, Bosnian, Bulgarian, Catalan, Czech, Welsh, Danish, German, Greek, English, Esperanto, Spanish, Estonian, Basque, Persian, Finnish, Filipino, French, Irish, Galician, Hebrew, Hindi, Croatian, Hungarian, Armenian, Icelandic, Italian, Japanese, Korean, Lithuanian, Latvian, Macedonian, Mongolian, Maltese, Dutch, Norwegian, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Serbian, Swedish, Tamil, Thai, Turkish, Ukrainian, Urdu, Vietnamese, Chinese, and more.
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -1,6 +1,32 @@
 import { LynguistOptions, LynguistTerm, ReplacePlaceholders } from './types';
-export type { LynguistTranslations, LynguistTerm } from './types';
+export type { LynguistTranslations, LynguistTerm, LynguistLocale, ReplacePlaceholders } from './types';
+type LocaleChangeCallback = (locale: string, previousLocale: string) => void;
+/**
+ * Initialize Lynguist with custom options.
+ * When using the Vite plugin, this is called automatically.
+ */
 export declare function Lynguist(options: LynguistOptions): void;
+/**
+ * Subscribe to locale changes.
+ * @returns Unsubscribe function
+ */
+export declare function onLocaleChange(callback: LocaleChangeCallback): () => void;
+/**
+ * Set the current locale.
+ */
+export declare function setLocale(locale: string): void;
+/**
+ * Get the current locale.
+ */
+export declare function getLocale(): string;
+/**
+ * Get all available locales.
+ */
+export declare function getAvailableLocales(): string[];
+/**
+ * Get translations for a specific locale (or current locale if not specified).
+ */
+export declare function getTranslations(locale?: string): Record<string, string>;
 export declare function __(key: LynguistTerm, replace?: ReplacePlaceholders): string;
 export declare function __(key: LynguistTerm, count: number, replace?: ReplacePlaceholders): string;
 export declare function trans(key: LynguistTerm, replace?: ReplacePlaceholders): string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAG5E,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAOjE,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAGvD;AAED,wBAAgB,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAAA;AAC5E,wBAAgB,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAAA;AAS3F,wBAAgB,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAU9E;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAcnG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,eAAe,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAK5F,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAEtG,KAAK,oBAAoB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,KAAK,IAAI,CAAA;AAqB5E;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAGvD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAIzE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAW9C;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEvE;AAED,wBAAgB,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAAA;AAC5E,wBAAgB,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAAA;AAS3F,wBAAgB,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAU9E;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CA6BnG"}

package/dist/index.js

@@ -1,11 +1,62 @@
-import { pluralIndex, replacePlaceholders } from './utils';
-let lynguist = {
-    locale: 'en',
-    translations: {},
+import { hasIntervalNotation, parseIntervalNotation, pluralIndex, replacePlaceholders } from './utils';
+// @ts-ignore - Virtual module provided by Vite plugin
+import translations from 'virtual:lynguist-translations';
+const isServer = typeof window === 'undefined';
+const listeners = new Set();
+function detectLocale() {
+    return !isServer ? document.documentElement.lang?.replace('-', '_') || 'en' : 'en';
+}
+let config = {
+    locale: detectLocale(),
+    translations: translations[detectLocale()] ?? {},
+    allTranslations: translations,
 };
+/**
+ * Initialize Lynguist with custom options.
+ * When using the Vite plugin, this is called automatically.
+ */
 export function Lynguist(options) {
-    lynguist.locale = options.locale;
-    lynguist.translations = options.translations;
+    config.locale = options.locale;
+    config.translations = options.translations;
+}
+/**
+ * Subscribe to locale changes.
+ * @returns Unsubscribe function
+ */
+export function onLocaleChange(callback) {
+    listeners.add(callback);
+    return () => listeners.delete(callback);
+}
+/**
+ * Set the current locale.
+ */
+export function setLocale(locale) {
+    if (!config.allTranslations[locale]) {
+        console.warn(`[lynguist] Locale "${locale}" not found. Available: ${Object.keys(config.allTranslations).join(', ')}`);
+        return;
+    }
+    const previousLocale = config.locale;
+    config.locale = locale;
+    config.translations = config.allTranslations[locale];
+    listeners.forEach(callback => callback(locale, previousLocale));
+}
+/**
+ * Get the current locale.
+ */
+export function getLocale() {
+    return config.locale;
+}
+/**
+ * Get all available locales.
+ */
+export function getAvailableLocales() {
+    return Object.keys(config.allTranslations);
+}
+/**
+ * Get translations for a specific locale (or current locale if not specified).
+ */
+export function getTranslations(locale) {
+    return config.allTranslations[locale ?? config.locale] ?? {};
 }
 export function __(key, countOrReplace, replace) {
     if (typeof countOrReplace === 'number') {
@@ -14,8 +65,8 @@ export function __(key, countOrReplace, replace) {
     return trans(key, countOrReplace);
 }
 export function trans(key, replace) {
-    let translation = lynguist.translations[key];
-    if (!(key in lynguist.translations) || !translation)
+    let translation = config.translations[key];
+    if (!(key in config.translations) || !translation)
         return key;
     if (replace) {
         translation = replacePlaceholders(translation, replace);
@@ -23,12 +74,26 @@ export function trans(key, replace) {
     return translation;
 }
 export function transChoice(key, count, replace) {
-    if (!(key in lynguist.translations) || !lynguist.translations[key])
+    if (!(key in config.translations) || !config.translations[key])
         return key;
-    const parts = lynguist.translations[key].split('|');
-    let index = pluralIndex(count, lynguist.locale);
-    let translation = parts[index];
-    translation = translation.replaceAll(/:count/g, count.toString());
+    const translationString = config.translations[key];
+    let translation;
+    // Check for interval notation first ({0}, {1}, [1,19], [20,*])
+    if (hasIntervalNotation(translationString)) {
+        const intervalResult = parseIntervalNotation(translationString, count);
+        if (intervalResult !== null) {
+            translation = intervalResult;
+        }
+        else {
+            translation = translationString.split('|')[0].replace(/^[{[].*?[}\]]\s*/, '');
+        }
+    }
+    else {
+        const parts = translationString.split('|');
+        const index = pluralIndex(count, config.locale);
+        translation = parts[index] ?? parts[parts.length - 1];
+    }
+    translation = translation.replace(/:count/gi, count.toString());
     if (replace) {
         translation = replacePlaceholders(translation, replace);
     }

package/dist/utils.d.ts

@@ -1,4 +1,20 @@
 import { LynguistLocale, ReplacePlaceholders } from './types';
+/**
+ * Replace placeholders in translation string with values.
+ * Supports Laravel-style case transformation:
+ * - :name → lowercase value
+ * - :Name → capitalized value
+ * - :NAME → uppercase value
+ */
 export declare function replacePlaceholders(text: string, replace: ReplacePlaceholders): string;
+/**
+ * Parse interval notation and return the matching translation part.
+ * Supports: {0}, {1}, [1,19], [20,*]
+ */
+export declare function parseIntervalNotation(translation: string, count: number): string | null;
+/**
+ * Check if a translation string uses interval notation.
+ */
+export declare function hasIntervalNotation(translation: string): boolean;
 export declare function pluralIndex(count: number, locale: LynguistLocale): number;
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAE7D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAkBtF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CA4HzE"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAE7D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,MAAM,CA0BtF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmCvF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CA4HzE"}

package/dist/utils.js

@@ -1,19 +1,70 @@
+/**
+ * Replace placeholders in translation string with values.
+ * Supports Laravel-style case transformation:
+ * - :name → lowercase value
+ * - :Name → capitalized value
+ * - :NAME → uppercase value
+ */
 export function replacePlaceholders(text, replace) {
     let translation = text;
-    for (const [placeholder, value] of Object.entries(replace)) {
-        if (value !== null && value !== undefined) {
-            let parameterValue = String(value);
+    for (const [key, value] of Object.entries(replace)) {
+        if (value === null || value === undefined)
+            continue;
+        const stringValue = String(value);
+        const lowerKey = key.toLowerCase();
+        // Match all case variants of the placeholder in the template
+        const regex = new RegExp(`:${lowerKey}`, 'gi');
+        translation = translation.replace(regex, match => {
+            const placeholder = match.slice(1); // Remove the ':'
             if (placeholder === placeholder.toUpperCase()) {
-                parameterValue = parameterValue.toUpperCase();
+                return stringValue.toUpperCase();
             }
             else if (placeholder[0] === placeholder[0].toUpperCase()) {
-                parameterValue = parameterValue.charAt(0).toUpperCase() + parameterValue.slice(1);
+                return stringValue.charAt(0).toUpperCase() + stringValue.slice(1).toLowerCase();
             }
-            translation = translation.replace(`:${placeholder}`, parameterValue);
-        }
+            else {
+                return stringValue;
+            }
+        });
     }
     return translation;
 }
+/**
+ * Parse interval notation and return the matching translation part.
+ * Supports: {0}, {1}, [1,19], [20,*]
+ */
+export function parseIntervalNotation(translation, count) {
+    const parts = translation.split('|');
+    for (const part of parts) {
+        const trimmed = part.trim();
+        // Match {n} - exact value
+        const exactMatch = trimmed.match(/^\{(\d+)\}\s*(.*)$/);
+        if (exactMatch) {
+            const exactValue = parseInt(exactMatch[1], 10);
+            if (count === exactValue) {
+                return exactMatch[2];
+            }
+            continue;
+        }
+        // Match [n,m] or [n,*] - range
+        const rangeMatch = trimmed.match(/^\[(\d+),(\d+|\*)\]\s*(.*)$/);
+        if (rangeMatch) {
+            const min = parseInt(rangeMatch[1], 10);
+            const max = rangeMatch[2] === '*' ? Infinity : parseInt(rangeMatch[2], 10);
+            if (count >= min && count <= max) {
+                return rangeMatch[3];
+            }
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Check if a translation string uses interval notation.
+ */
+export function hasIntervalNotation(translation) {
+    return /(\{[\d]+\}|\[[\d]+,[\d*]+\])/.test(translation);
+}
 export function pluralIndex(count, locale) {
     switch (locale) {
         case 'af':

package/dist/virtual-lynguist.d.ts

@@ -0,0 +1,4 @@
+declare module 'virtual:lynguist-translations' {
+    const translations: Record<string, Record<string, string>>
+    export default translations
+}

package/dist/vite.d.ts

@@ -0,0 +1,48 @@
+import type { Plugin } from './vite';
+export interface LynguistPluginOptions {
+    /**
+     * Path to the Laravel lang directory containing translation files.
+     * @default 'lang'
+     */
+    langPath?: string;
+    /**
+     * Additional paths to scan for translation files.
+     */
+    additionalLangPaths?: string[];
+}
+/**
+ * Vite plugin that loads Laravel translation files and provides them
+ * via a virtual module for use with Lynguist.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { lynguist } from '@vixen-tech/lynguist/vite'
+ *
+ * export default defineConfig({
+ *     plugins: [
+ *         lynguist({
+ *             langPath: 'lang',
+ *             additionalLangPaths: ['vendor/package/lang']
+ *         })
+ *     ]
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // In your app
+ * import { __, setLocale, getLocale, onLocaleChange } from '@vixen-tech/lynguist'
+ *
+ * // Use translations
+ * __('welcome')
+ * __('greeting', { name: 'John' })
+ * __('items', 5)
+ *
+ * // Switch locale at runtime
+ * setLocale('de')
+ * ```
+ */
+export declare function lynguist(options?: LynguistPluginOptions): Plugin;
+export default lynguist;
+//# sourceMappingURL=vite.d.ts.map

package/dist/vite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAIlC,MAAM,WAAW,qBAAqB;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAA;CACjC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CA2FpE;AAED,eAAe,QAAQ,CAAA"}

package/dist/vite.js

@@ -0,0 +1,113 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Vite plugin that loads Laravel translation files and provides them
+ * via a virtual module for use with Lynguist.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { lynguist } from '@vixen-tech/lynguist/vite'
+ *
+ * export default defineConfig({
+ *     plugins: [
+ *         lynguist({
+ *             langPath: 'lang',
+ *             additionalLangPaths: ['vendor/package/lang']
+ *         })
+ *     ]
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // In your app
+ * import { __, setLocale, getLocale, onLocaleChange } from '@vixen-tech/lynguist'
+ *
+ * // Use translations
+ * __('welcome')
+ * __('greeting', { name: 'John' })
+ * __('items', 5)
+ *
+ * // Switch locale at runtime
+ * setLocale('de')
+ * ```
+ */
+export function lynguist(options = {}) {
+    const virtualModuleId = 'virtual:lynguist-translations';
+    const resolvedVirtualModuleId = '\0' + virtualModuleId;
+    const langPath = (options.langPath ?? 'lang').replace(/[\\/]$/, '') + path.sep;
+    const additionalLangPaths = options.additionalLangPaths ?? [];
+    const paths = [langPath, ...additionalLangPaths];
+    function loadTranslations(...langPaths) {
+        const translations = {};
+        for (const lp of langPaths) {
+            if (!fs.existsSync(lp)) {
+                continue;
+            }
+            const files = fs.readdirSync(lp);
+            for (const file of files) {
+                if (!file.endsWith('.json'))
+                    continue;
+                const locale = path.basename(file, '.json');
+                const filePath = path.join(lp, file);
+                try {
+                    const content = fs.readFileSync(filePath, 'utf-8');
+                    const parsed = JSON.parse(content);
+                    // Merge with existing translations for this locale
+                    translations[locale] = {
+                        ...translations[locale],
+                        ...parsed,
+                    };
+                }
+                catch (error) {
+                    console.error(`[lynguist] Failed to load translation file: ${filePath}`, error);
+                }
+            }
+        }
+        return translations;
+    }
+    return {
+        name: 'vite-plugin-lynguist',
+        enforce: 'pre',
+        config() {
+            return {
+                optimizeDeps: {
+                    exclude: [virtualModuleId],
+                },
+                ssr: {
+                    noExternal: ['@vixen-tech/lynguist'],
+                },
+            };
+        },
+        resolveId(id) {
+            if (id === virtualModuleId) {
+                return resolvedVirtualModuleId;
+            }
+        },
+        load(id) {
+            if (id === resolvedVirtualModuleId) {
+                const translations = loadTranslations(...paths);
+                return `export default ${JSON.stringify(translations)}`;
+            }
+        },
+        handleHotUpdate(ctx) {
+            for (const lp of paths) {
+                const relative = path.relative(lp, ctx.file);
+                const isSubpath = relative && !relative.startsWith('..') && !path.isAbsolute(relative);
+                if (isSubpath && ctx.file.endsWith('.json')) {
+                    const virtualModule = ctx.server.moduleGraph.getModuleById(resolvedVirtualModuleId);
+                    if (virtualModule) {
+                        ctx.server.moduleGraph.invalidateModule(virtualModule);
+                        ctx.server.ws.send({
+                            type: 'full-reload',
+                            path: '*',
+                        });
+                    }
+                    return;
+                }
+            }
+        },
+    };
+}
+export default lynguist;

package/package.json

@@ -1,15 +1,28 @@
 {
     "name": "@vixen-tech/lynguist",
-    "version": "0.0.1",
+    "version": "1.0.0",
     "description": "",
     "type": "module",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./vite": {
+            "types": "./dist/vite.d.ts",
+            "import": "./dist/vite.js"
+        },
+        "./virtual": {
+            "types": "./dist/virtual-lynguist.d.ts"
+        }
+    },
     "files": [
         "dist"
     ],
     "scripts": {
-        "build": "tsc -p tsconfig.json && tsc-alias",
+        "build": "tsc -p tsconfig.json && tsc-alias && cp src/virtual-lynguist.d.ts dist/",
         "clean": "rm -rf dist",
         "prepublishOnly": "pnpm clean && pnpm build",
         "test": "vitest run"
@@ -21,6 +34,14 @@
     ],
     "author": "Alex Torscho <contact@alextorscho.com> (https://alextorscho.com)",
     "license": "ISC",
+    "peerDependencies": {
+        "vite": ">=5.0.0"
+    },
+    "peerDependenciesMeta": {
+        "vite": {
+            "optional": true
+        }
+    },
     "devDependencies": {
         "@types/node": "^25.0.3",
         "prettier": "^3.7.4",