i18n-turbo 1.0.0 → 1.0.2

package/README.md

@@ -7,44 +7,89 @@
 
 - ⚡ **Blazing Fast**: Asynchronous, parallel file processing for large codebases.
 - 🎯 **Smart Extraction**: Detects strings in JSX text, attributes, and variables.
+- ⚛️ **React Integration**: Built-in `I18nProvider` and `useTranslation` hook for type-safe internalization.
 - 📁 **Namespaces**: Organize translations into multiple files (e.g., `auth.json`, `common.json`) based on file paths.
 - 💬 **Context Support**: Extract comments (`i18n: ...`) as translation context for translators.
-- 🔢 **Pluralization**: Automatically detects singular/plural patterns in ternary operators.
-- 🔧 **Configs**: Flexible `i18n-turbo.config.js` for custom key strategies, exclusions, and more.
+- 🤖 **Auto Translation**: Automatically translate missing keys to other languages (e.g. `--lang es`) using Google Translate.
+- 🔧 **Configs**: Flexible `i18n-turbo.config.js` for custom key strategies, namespaces, and exclusions.
 - 🔄 **Reverse Mode**: Revert `t('key')` back to original strings (great for refactoring).
 
 ## Install
 
 ```bash
-npm install -g i18n-turbo
+npm install i18n-turbo
 ```
 
-## Usage
+## React Integration
+
+Wrap your app with `I18nProvider` and use the `useTranslation` hook.
+
+```tsx
+// src/App.tsx
+import { I18nProvider, useTranslation } from 'i18n-turbo';
+import en from './locales/en.json';
+import es from './locales/es.json';
+
+const translations = { en, es };
+
+export default function App() {
+  return (
+    <I18nProvider translations={translations} defaultLocale="en">
+      <MyComponent />
+    </I18nProvider>
+  );
+}
+
+function MyComponent() {
+  const { t, lang, setLang } = useTranslation();
+  
+  return (
+    <div>
+      <h1>{t("hello_world")}</h1>
+      <button onClick={() => setLang('es')}>Español</button>
+    </div>
+  );
+}
+```
+
+## CLI Usage
+
+Run the CLI to extract strings and manage translations.
 
 ```bash
-i18n-turbo <input-dir> <output-file> [options]
+npx i18n-turbo <input-dir> <output-file> [options]
 ```
 
 ### Examples
 
 **Basic Extraction:**
+Extract strings from `./src` to `./locales/en.json`.
 ```bash
-i18n-turbo ./src ./locales/en.json
+npx i18n-turbo ./src ./locales/en.json
 ```
 
-**Translate to French:**
+**Add a New Language:**
+Translate extracted strings to French (`fr`).
 ```bash
-i18n-turbo ./src ./locales/en.json --lang fr
+npx i18n-turbo ./src ./locales/en.json --lang fr
 ```
 
-**Dry Run (Preview changes):**
+**Update Translations:**
+Merge new keys without overwriting existing manual translations.
 ```bash
-i18n-turbo ./src ./locales/en.json --dry-run
+npx i18n-turbo ./src ./locales/en.json --merge
 ```
 
-**Update existing translations:**
+**Force Update:**
+Re-translate all keys (overwrite everything).
 ```bash
-i18n-turbo ./src ./locales/en.json --merge
+npx i18n-turbo ./src ./locales/en.json --force
+```
+
+**Reverse Extraction:**
+Restore original text from keys (undo `t('key')` replacement).
+```bash
+npx i18n-turbo ./src ./locales/en.json --reverse
 ```
 
 ## Configuration
@@ -73,29 +118,13 @@ module.exports = {
     'src/features/dashboard/**': 'dashboard',
     'src/components/**': 'common',
   },
-
-  // Default target language for machine translation
-  targetLang: 'es'
 };
 ```
 
 ## Advanced Features
 
-### Namespaces
-Control where your strings go by defining namespaces.
-If you configure `namespaces`, `i18n-turbo` will output separate files in the output directory instead of a single file.
-
-```javascript
-// config
-namespaces: {
-  'src/auth/**': 'auth',
-}
-// Output: locales/auth.json, locales/common.json
-```
-
 ### Context Extraction
 Provide context to translators by adding comments starting with `i18n:`.
-The tool is smart enough to find comments attached to the node or its JSX siblings.
 
 **Input:**
 ```tsx
@@ -116,7 +145,7 @@ const label = "Submit"; // i18n: Button label
 ```
 
 ### Pluralization
-`i18n-turbo` detects simple pluralization patterns in your code.
+`i18n-turbo` detects simple ternary plurals.
 
 **Input:**
 ```tsx
@@ -124,18 +153,7 @@ const label = "Submit"; // i18n: Button label
 ```
 
 **Output:**
-Replaces with `t('one_item')` and `t('many_items')` (Base support).
-*Future updates will implement automatic `t('key', { count })` merging.*
-
-## Key Generation Strategies
-
-- **snake_case**: `Hello World` -> `hello_world` (Default)
-- **camelCase**: `Hello World` -> `helloWorld`
-- **hash**: `Hello World` -> `a1b2c3d4` (Useful for stable keys regardless of content)
-- **Custom**:
-  ```javascript
-  keyGenerationStrategy: (text) => text.toUpperCase().replace(/\s+/g, '_')
-  ```
+Replaces with `t('one_item')` and `t('many_items')`.
 
 ## License
 

package/dist/bin/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bin/cli.js

@@ -1,5 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
 // bin/cli.ts
-const cli_1 = require("../src/cli");
-(0, cli_1.runCLI)();
+import { runCLI } from '../src/cli.js';
+runCLI();

package/dist/src/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCLI(): Promise<void>;

package/dist/src/cli.js

@@ -1,16 +1,10 @@
-"use strict";
 // bin/cli.ts or src/cli.ts
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.runCLI = runCLI;
-const path_1 = __importDefault(require("path"));
-const extractor_1 = require("./extractor");
-const reverser_1 = require("./reverser");
-const config_1 = require("./config");
-async function runCLI() {
-    const config = (0, config_1.loadConfig)();
+import path from 'path';
+import { extractStringsFromDirectory } from './extractor.js';
+import { reverseStringsFromDirectory } from './reverser.js';
+import { loadConfig } from './config.js';
+export async function runCLI() {
+    const config = loadConfig();
     const args = process.argv.slice(2);
     const inputDir = args[0] || './src';
     const outputFile = args[1] || './locales/en.json';
@@ -28,13 +22,14 @@ async function runCLI() {
         dryRun: args.includes('--dry-run'),
         merge: args.includes('--merge'),
         lang,
+        force: args.includes('--force'),
         config,
     };
-    const resolvedInputDir = path_1.default.resolve(inputDir);
-    const resolvedOutputFile = path_1.default.resolve(outputFile);
+    const resolvedInputDir = path.resolve(inputDir);
+    const resolvedOutputFile = path.resolve(outputFile);
     if (args.includes('--reverse')) {
-        await (0, reverser_1.reverseStringsFromDirectory)(resolvedInputDir, resolvedOutputFile, fnName);
+        await reverseStringsFromDirectory(resolvedInputDir, resolvedOutputFile, fnName);
         process.exit(0);
     }
-    await (0, extractor_1.extractStringsFromDirectory)(resolvedInputDir, resolvedOutputFile, options);
+    await extractStringsFromDirectory(resolvedInputDir, resolvedOutputFile, options);
 }

package/dist/src/config.d.ts

@@ -0,0 +1,9 @@
+export interface I18nTurboConfig {
+    translationFunction?: string;
+    minStringLength?: number;
+    excludePatterns?: string[];
+    keyGenerationStrategy?: 'snake_case' | 'camelCase' | 'hash' | ((text: string) => string);
+    targetLang?: string;
+    namespaces?: Record<string, string>;
+}
+export declare function loadConfig(cwd?: string): I18nTurboConfig;

package/dist/src/config.js

@@ -1,20 +1,14 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadConfig = loadConfig;
-const path_1 = __importDefault(require("path"));
-const fs_1 = __importDefault(require("fs"));
+import path from 'path';
+import fs from 'fs';
 const DEFAULT_CONFIG = {
     translationFunction: 't',
     minStringLength: 2,
     excludePatterns: [],
     keyGenerationStrategy: 'snake_case',
 };
-function loadConfig(cwd = process.cwd()) {
-    const configPath = path_1.default.join(cwd, 'i18n-turbo.config.js');
-    if (fs_1.default.existsSync(configPath)) {
+export function loadConfig(cwd = process.cwd()) {
+    const configPath = path.join(cwd, 'i18n-turbo.config.js');
+    if (fs.existsSync(configPath)) {
         try {
             // Dynamic require is acceptable for a CLI tool reading local config
             const userConfig = require(configPath);

package/dist/src/extractor.d.ts

@@ -0,0 +1,11 @@
+import { I18nTurboConfig } from "./config.js";
+interface ExtractOptions {
+    fnName: string;
+    dryRun: boolean;
+    merge: boolean;
+    lang?: string;
+    force?: boolean;
+    config?: I18nTurboConfig;
+}
+export declare function extractStringsFromDirectory(inputDir: string, outputFile: string, options: ExtractOptions): Promise<void>;
+export {};

package/dist/src/extractor.js

@@ -1,56 +1,19 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractStringsFromDirectory = extractStringsFromDirectory;
 // src/extractor.ts
-const fs_1 = __importDefault(require("fs"));
-const fs_2 = require("fs"); // Async FS
-const path_1 = __importDefault(require("path"));
-const babel = __importStar(require("@babel/core"));
-const traverse_1 = __importDefault(require("@babel/traverse"));
-const generator_1 = __importDefault(require("@babel/generator"));
-const t = __importStar(require("@babel/types"));
-const scanner_1 = require("./scanner");
-const utils_1 = require("./utils");
-const google_translate_api_1 = require("@vitalets/google-translate-api");
-const p_limit_1 = __importDefault(require("p-limit"));
-const minimatch_1 = require("minimatch");
-async function extractStringsFromDirectory(inputDir, outputFile, options) {
+import fs from "fs";
+import { promises as fsPromises } from "fs"; // Async FS
+import path from "path";
+import * as babel from "@babel/core";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const traverse = require("@babel/traverse").default;
+const generate = require("@babel/generator").default;
+import * as t from "@babel/types";
+import { getSourceFiles } from "./scanner.js";
+import { generateTranslationKey } from "./utils.js";
+import { translate } from '@vitalets/google-translate-api';
+import pLimit from "p-limit";
+import { minimatch } from "minimatch";
+export async function extractStringsFromDirectory(inputDir, outputFile, options) {
     // console.log('DEBUG: extractor options.config:', options.config);
     // Map of namespace name -> translation map
     const namespaceMaps = {};
@@ -74,15 +37,15 @@ async function extractStringsFromDirectory(inputDir, outputFile, options) {
     // Logic update: If namespaces are used, we need to load MULTIPLE files.
     // For simplicity: If config.namespaces exists, we assume outputFile is a DIRECTORY or prefix base.
     // But strictly, if user passes `locales/en.json`, we might treat `locales` as the dir.
-    const outputDir = path_1.default.extname(outputFile) ? path_1.default.dirname(outputFile) : outputFile;
+    const outputDir = path.extname(outputFile) ? path.dirname(outputFile) : outputFile;
     if (options.merge) {
         for (const ns of Object.keys(namespaceMaps)) {
             const nsFile = options.config?.namespaces
-                ? path_1.default.join(outputDir, `${ns}.json`)
+                ? path.join(outputDir, `${ns}.json`)
                 : outputFile; // If no namespaces, use the single output file
-            if (fs_1.default.existsSync(nsFile)) {
+            if (fs.existsSync(nsFile)) {
                 try {
-                    namespaceMaps[ns] = JSON.parse(fs_1.default.readFileSync(nsFile, "utf-8"));
+                    namespaceMaps[ns] = JSON.parse(fs.readFileSync(nsFile, "utf-8"));
                 }
                 catch {
                     console.warn(`[WARN] Could not parse ${nsFile}, starting fresh.`);
@@ -90,12 +53,12 @@ async function extractStringsFromDirectory(inputDir, outputFile, options) {
             }
         }
     }
-    const files = await (0, scanner_1.getSourceFiles)(inputDir, options.config?.excludePatterns);
-    const limit = (0, p_limit_1.default)(50); // Concurrency limit
+    const files = await getSourceFiles(inputDir, options.config?.excludePatterns);
+    const limit = pLimit(50); // Concurrency limit
     await Promise.all(files.map((file) => limit(async () => {
         try {
             // Read file async
-            const code = await fs_2.promises.readFile(file, "utf-8");
+            const code = await fsPromises.readFile(file, "utf-8");
             // Parse AST (still sync for now as babel.parseAsync just wraps it usually)
             const ast = babel.parseSync(code, {
                 filename: file,
@@ -106,10 +69,10 @@ async function extractStringsFromDirectory(inputDir, outputFile, options) {
             // Determine namespace for this file
             let currentNs = defaultNamespace;
             if (options.config?.namespaces) {
-                const relativePath = path_1.default.relative(process.cwd(), file); // or relative to inputDir? relative to CWD usually for globs
+                const relativePath = path.relative(process.cwd(), file); // or relative to inputDir? relative to CWD usually for globs
                 // Check against globs
                 for (const [pattern, nsName] of Object.entries(options.config.namespaces)) {
-                    if ((0, minimatch_1.minimatch)(relativePath, pattern)) {
+                    if (minimatch(relativePath, pattern)) {
                         currentNs = nsName;
                         break;
                     }
@@ -152,7 +115,7 @@ async function extractStringsFromDirectory(inputDir, outputFile, options) {
                 }
                 return undefined;
             };
-            (0, traverse_1.default)(ast, {
+            traverse(ast, {
                 JSXText(path) {
                     const rawText = path.node.value.trim();
                     if (!rawText || /^\{.*\}$/.test(rawText))
@@ -165,7 +128,7 @@ async function extractStringsFromDirectory(inputDir, outputFile, options) {
                     // Sibling comments (JSX expression container before parent Element)
                     const siblingComment = path.parentPath ? getContextFromSibling(path.parentPath) : undefined;
                     contextComment = comment || siblingComment;
-                    const key = (0, utils_1.generateTranslationKey)(rawText, options.config?.keyGenerationStrategy);
+                    const key = generateTranslationKey(rawText, options.config?.keyGenerationStrategy);
                     namespaceMaps[currentNs][key] = rawText;
                     if (contextComment) {
                         namespaceMaps[currentNs][`${key}_comment`] = contextComment;
@@ -219,13 +182,36 @@ async function extractStringsFromDirectory(inputDir, outputFile, options) {
                         path.parentPath.node.callee.type === "Identifier" &&
                         path.parentPath.node.callee.name === options.fnName)
                         return;
+                    // ✅ Skip common DOM identifiers
+                    if (path.parentPath.isCallExpression()) {
+                        const callee = path.parentPath.node.callee;
+                        let fnName = '';
+                        if (t.isIdentifier(callee)) {
+                            fnName = callee.name;
+                        }
+                        else if (t.isMemberExpression(callee) && t.isIdentifier(callee.property)) {
+                            fnName = callee.property.name;
+                        }
+                        if ([
+                            'getElementById',
+                            'querySelector',
+                            'querySelectorAll',
+                            'addEventListener',
+                            'removeEventListener',
+                            'postMessage',
+                            'setAttribute',
+                            'getAttribute'
+                        ].includes(fnName)) {
+                            return;
+                        }
+                    }
                     if (!value ||
                         value.length < (options.config?.minStringLength || 2) ||
                         value.length > 80)
                         return;
                     if (!/[a-zA-Z]/.test(value))
                         return;
-                    const key = (0, utils_1.generateTranslationKey)(value, options.config?.keyGenerationStrategy);
+                    const key = generateTranslationKey(value, options.config?.keyGenerationStrategy);
                     // console.log(`DEBUG: key for "${value}" -> "${key}"`);
                     namespaceMaps[currentNs][key] = value;
                     if (contextComment) {
@@ -251,8 +237,16 @@ async function extractStringsFromDirectory(inputDir, outputFile, options) {
                                 "type",
                                 "rel",
                                 "target",
-                                "alt",
-                                "placeholder",
+                                // "alt",          // Likely want to translate alt
+                                // "placeholder",  // Likely want to translate placeholder
+                                "path", // React Router
+                                "to", // Link
+                                "element", // Route
+                                "defaultLocale", // I18nProvider
+                                "value", // Inputs
+                                "name", // Inputs
+                                "htmlFor", // Labels
+                                "as" // Polymorphic
                             ].includes(attrName.name))
                             return;
                     }
@@ -276,9 +270,9 @@ async function extractStringsFromDirectory(inputDir, outputFile, options) {
                 },
             });
             if (!options.dryRun && modified) {
-                const output = (0, generator_1.default)(ast).code;
+                const output = generate(ast).code;
                 // Write file async
-                await fs_2.promises.writeFile(file, output);
+                await fsPromises.writeFile(file, output);
             }
         }
         catch (err) {
@@ -287,7 +281,7 @@ async function extractStringsFromDirectory(inputDir, outputFile, options) {
     })));
     if (!options.dryRun) {
         if (outputDir !== ".") {
-            await fs_2.promises.mkdir(outputDir, { recursive: true });
+            await fsPromises.mkdir(outputDir, { recursive: true });
         }
         // Write all namespace files
         for (const [ns, map] of Object.entries(namespaceMaps)) {
@@ -312,15 +306,37 @@ async function extractStringsFromDirectory(inputDir, outputFile, options) {
                 // Let's assume `outputFile` denotes the folder structure for the default file.
                 // e.g. `locales/en.json` -> outputDir = `locales`
                 // If namespaces active: `locales/common.json`, `locales/auth.json`.
-                targetFile = path_1.default.join(outputDir, `${ns}.json`);
+                targetFile = path.join(outputDir, `${ns}.json`);
             }
             const mapToWrite = map;
             // Translation logic
             if (options.lang && options.lang !== "en") {
                 const translated = {};
+                let langPath;
+                if (options.config?.namespaces) {
+                    langPath = path.join(outputDir, `${ns}_${options.lang}.json`);
+                }
+                else {
+                    langPath = path.join(path.dirname(outputFile), `${options.lang}.json`);
+                }
+                // Load existing translations for this language if available
+                let existingTranslations = {};
+                if (fs.existsSync(langPath)) {
+                    try {
+                        existingTranslations = JSON.parse(await fsPromises.readFile(langPath, 'utf-8'));
+                    }
+                    catch (e) {
+                        console.warn(`[WARN] Could not parse existing translation file ${langPath}`);
+                    }
+                }
                 for (const [key, text] of Object.entries(map)) {
+                    // Check if exists
+                    if (!options.force && existingTranslations[key]) {
+                        translated[key] = existingTranslations[key];
+                        continue;
+                    }
                     try {
-                        const res = await (0, google_translate_api_1.translate)(text, { to: options.lang });
+                        const res = await translate(text, { to: options.lang });
                         console.log(`Translated [${ns}] "${text}" => "${res.text}"`);
                         translated[key] = res.text;
                     }
@@ -329,27 +345,11 @@ async function extractStringsFromDirectory(inputDir, outputFile, options) {
                         translated[key] = text;
                     }
                 }
-                // If namespaces active: `locales/lang/ns.json` or `locales/ns.lang.json`?
-                // Let's do `locales/lang.json` if single file, 
-                // BUT if namespaces: `locales/ns.json` (en), `locales/ns_fr.json`?
-                // OR `locales/fr/ns.json`.
-                // Let's stick to `locales/fr.json` if NO namespaces (legacy).
-                // If namespaces: `locales/fr/ns.json`? Or `locales/ns.fr.json`?
-                // Complexity increase!
-                // Simplified for this task:
-                // If namespaces: write `outputDir/ns.json`. If lang available, write `outputDir/ns_lang.json` (flat).
-                let langPath;
-                if (options.config?.namespaces) {
-                    langPath = path_1.default.join(outputDir, `${ns}_${options.lang}.json`);
-                }
-                else {
-                    langPath = path_1.default.join(path_1.default.dirname(outputFile), `${options.lang}.json`);
-                }
-                await fs_2.promises.writeFile(langPath, JSON.stringify(translated, null, 2), "utf-8");
+                await fsPromises.writeFile(langPath, JSON.stringify(translated, null, 2), "utf-8");
             }
             else {
                 // Default language (usually EN)
-                await fs_2.promises.writeFile(targetFile, JSON.stringify(mapToWrite, null, 2), "utf-8");
+                await fsPromises.writeFile(targetFile, JSON.stringify(mapToWrite, null, 2), "utf-8");
             }
         }
     }

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * i18n-turbo - Internationalization toolkit for React
+ *
+ * This package provides:
+ * - React components (I18nProvider, useTranslation) for runtime i18n
+ * - CLI tool for extracting hardcoded strings from JSX/TSX files (run via CLI only)
+ */
+export { I18nProvider, useTranslation, createI18n, type I18nProviderProps, type I18nConfig, type I18nContextValue, type Translations, type TranslationDictionary, type InterpolationValues, } from './react';

package/dist/src/index.js

@@ -0,0 +1,12 @@
+/**
+ * i18n-turbo - Internationalization toolkit for React
+ *
+ * This package provides:
+ * - React components (I18nProvider, useTranslation) for runtime i18n
+ * - CLI tool for extracting hardcoded strings from JSX/TSX files (run via CLI only)
+ */
+// React components and hooks
+export { I18nProvider, useTranslation, createI18n, } from './react';
+// Note: CLI functionality (extractStringsFromDirectory) is only available
+// via the command line tool, not as a module export, since it uses Node.js APIs
+// that are not compatible with browser environments.

package/dist/src/react.d.ts

@@ -0,0 +1,106 @@
+import React, { type ReactNode } from 'react';
+/**
+ * Translation dictionary type - maps keys to translated strings
+ */
+export type TranslationDictionary = Record<string, string>;
+/**
+ * Translations configuration - maps locale codes to translation dictionaries
+ */
+export type Translations = Record<string, TranslationDictionary>;
+/**
+ * Interpolation values for translation strings
+ */
+export type InterpolationValues = Record<string, string | number>;
+/**
+ * Configuration options for I18nProvider
+ */
+export interface I18nConfig {
+    /** Map of locale codes to translation dictionaries */
+    translations: Translations;
+    /** Default/initial locale */
+    defaultLocale?: string;
+    /** Fallback locale when translation is missing */
+    fallbackLocale?: string;
+}
+/**
+ * Context value returned by useTranslation hook
+ */
+export interface I18nContextValue {
+    /** Translation function */
+    t: (key: string, values?: InterpolationValues) => string;
+    /** Current locale */
+    lang: string;
+    /** Set the current locale */
+    setLang: (lang: string) => void;
+    /** Available locales */
+    locales: string[];
+}
+/**
+ * Hook to access translation functions and locale state
+ *
+ * @example
+ * ```tsx
+ * const { t, lang, setLang } = useTranslation();
+ *
+ * return (
+ *   <div>
+ *     <h1>{t('hello')}</h1>
+ *     <p>{t('welcome_message', { name: 'John' })}</p>
+ *     <button onClick={() => setLang('es')}>Español</button>
+ *   </div>
+ * );
+ * ```
+ */
+export declare function useTranslation(): I18nContextValue;
+/**
+ * Props for I18nProvider component
+ */
+export interface I18nProviderProps {
+    /** Child components */
+    children: ReactNode;
+    /** Translation dictionaries keyed by locale */
+    translations: Translations;
+    /** Default/initial locale (defaults to 'en') */
+    defaultLocale?: string;
+    /** Fallback locale when translation is missing (defaults to defaultLocale) */
+    fallbackLocale?: string;
+}
+/**
+ * Provider component for internationalization context
+ *
+ * @example
+ * ```tsx
+ * import { I18nProvider } from 'i18n-turbo';
+ * import en from './locales/en.json';
+ * import es from './locales/es.json';
+ *
+ * const translations = { en, es };
+ *
+ * function App() {
+ *   return (
+ *     <I18nProvider translations={translations} defaultLocale="en">
+ *       <MyApp />
+ *     </I18nProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function I18nProvider({ children, translations, defaultLocale, fallbackLocale, }: I18nProviderProps): React.ReactElement;
+/**
+ * Factory function to create a configured I18n instance
+ * Useful for creating reusable configurations
+ *
+ * @example
+ * ```tsx
+ * const { Provider, useTranslation } = createI18n({
+ *   translations: { en, es, fr },
+ *   defaultLocale: 'en',
+ * });
+ * ```
+ */
+export declare function createI18n(config: I18nConfig): {
+    Provider: ({ children }: {
+        children: ReactNode;
+    }) => import("react/jsx-runtime").JSX.Element;
+    useTranslation: typeof useTranslation;
+};

package/dist/src/react.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useState, useCallback, useMemo } from 'react';
+const I18nContext = createContext({
+    t: (key) => key,
+    lang: 'en',
+    setLang: () => { },
+    locales: [],
+});
+/**
+ * Hook to access translation functions and locale state
+ *
+ * @example
+ * ```tsx
+ * const { t, lang, setLang } = useTranslation();
+ *
+ * return (
+ *   <div>
+ *     <h1>{t('hello')}</h1>
+ *     <p>{t('welcome_message', { name: 'John' })}</p>
+ *     <button onClick={() => setLang('es')}>Español</button>
+ *   </div>
+ * );
+ * ```
+ */
+export function useTranslation() {
+    return useContext(I18nContext);
+}
+/**
+ * Interpolate values into a translation string
+ * Replaces {{key}} patterns with corresponding values
+ */
+function interpolate(template, values) {
+    if (!values)
+        return template;
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+        const value = values[key];
+        return value !== undefined ? String(value) : `{{${key}}}`;
+    });
+}
+/**
+ * Provider component for internationalization context
+ *
+ * @example
+ * ```tsx
+ * import { I18nProvider } from 'i18n-turbo';
+ * import en from './locales/en.json';
+ * import es from './locales/es.json';
+ *
+ * const translations = { en, es };
+ *
+ * function App() {
+ *   return (
+ *     <I18nProvider translations={translations} defaultLocale="en">
+ *       <MyApp />
+ *     </I18nProvider>
+ *   );
+ * }
+ * ```
+ */
+export function I18nProvider({ children, translations, defaultLocale = 'en', fallbackLocale, }) {
+    const [lang, setLang] = useState(defaultLocale);
+    const effectiveFallback = fallbackLocale ?? defaultLocale;
+    const locales = useMemo(() => Object.keys(translations), [translations]);
+    const t = useCallback((key, values) => {
+        // Try current locale first
+        const currentDict = translations[lang];
+        if (currentDict?.[key]) {
+            return interpolate(currentDict[key], values);
+        }
+        // Try fallback locale
+        if (lang !== effectiveFallback) {
+            const fallbackDict = translations[effectiveFallback];
+            if (fallbackDict?.[key]) {
+                return interpolate(fallbackDict[key], values);
+            }
+        }
+        // Return key as last resort
+        return interpolate(key, values);
+    }, [lang, translations, effectiveFallback]);
+    const contextValue = useMemo(() => ({
+        t,
+        lang,
+        setLang,
+        locales,
+    }), [t, lang, locales]);
+    return (_jsx(I18nContext.Provider, { value: contextValue, children: children }));
+}
+/**
+ * Factory function to create a configured I18n instance
+ * Useful for creating reusable configurations
+ *
+ * @example
+ * ```tsx
+ * const { Provider, useTranslation } = createI18n({
+ *   translations: { en, es, fr },
+ *   defaultLocale: 'en',
+ * });
+ * ```
+ */
+export function createI18n(config) {
+    const ConfiguredProvider = ({ children }) => (_jsx(I18nProvider, { translations: config.translations, defaultLocale: config.defaultLocale, fallbackLocale: config.fallbackLocale, children: children }));
+    return {
+        Provider: ConfiguredProvider,
+        useTranslation,
+    };
+}

package/dist/src/reverser.d.ts

@@ -0,0 +1 @@
+export declare function reverseStringsFromDirectory(inputDir: string, i18nFile: string, fnName?: string): Promise<void>;

package/dist/src/reverser.js

@@ -1,96 +1,67 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.reverseStringsFromDirectory = reverseStringsFromDirectory;
-const fs_1 = __importDefault(require("fs"));
-const babel = __importStar(require("@babel/core"));
-const traverse_1 = __importDefault(require("@babel/traverse"));
-const t = __importStar(require("@babel/types"));
-const generator_1 = __importDefault(require("@babel/generator"));
-const scanner_1 = require("./scanner");
-async function reverseStringsFromDirectory(inputDir, i18nFile, fnName = "t") {
-    const translationMap = JSON.parse(fs_1.default.readFileSync(i18nFile, "utf-8"));
-    const files = await (0, scanner_1.getSourceFiles)(inputDir);
-    for (const file of files) {
-        const code = fs_1.default.readFileSync(file, "utf-8");
-        const ast = babel.parseSync(code, {
-            filename: file,
-            presets: ["@babel/preset-typescript", "@babel/preset-react"],
-        });
-        if (!ast)
-            continue;
-        let modified = false;
-        (0, traverse_1.default)(ast, {
-            CallExpression(path) {
-                const callee = path.node.callee;
-                const args = path.node.arguments;
-                if (t.isIdentifier(callee, { name: fnName }) &&
-                    args.length === 1 &&
-                    t.isStringLiteral(args[0])) {
-                    const key = args[0].value;
-                    const originalText = translationMap[key];
-                    if (typeof originalText === "string") {
-                        const parent = path.parentPath;
-                        if (parent?.isJSXExpressionContainer()) {
-                            const containerParent = parent.parentPath;
-                            if (containerParent?.isJSXAttribute() &&
-                                containerParent.node.value === parent.node) {
-                                // If the expression is inside an attribute, set attribute value to string literal
-                                containerParent.node.value = t.stringLiteral(originalText);
-                                parent.remove(); // Remove the expression container if still present
+import fs from "fs";
+import * as babel from "@babel/core";
+import _traverse from "@babel/traverse";
+// @ts-ignore
+const traverse = _traverse.default || _traverse;
+import * as t from "@babel/types";
+import _generate from "@babel/generator";
+// @ts-ignore
+const generate = _generate.default || _generate;
+import { getSourceFiles } from "./scanner.js";
+export async function reverseStringsFromDirectory(inputDir, i18nFile, fnName = "t") {
+    try {
+        const translationMap = JSON.parse(fs.readFileSync(i18nFile, "utf-8"));
+        const files = await getSourceFiles(inputDir);
+        for (const file of files) {
+            const code = fs.readFileSync(file, "utf-8");
+            const ast = babel.parseSync(code, {
+                filename: file,
+                presets: ["@babel/preset-typescript", "@babel/preset-react"],
+            });
+            if (!ast)
+                continue;
+            let modified = false;
+            traverse(ast, {
+                CallExpression(path) {
+                    const callee = path.node.callee;
+                    const args = path.node.arguments;
+                    if (t.isIdentifier(callee, { name: fnName }) &&
+                        args.length === 1 &&
+                        t.isStringLiteral(args[0])) {
+                        const key = args[0].value;
+                        const originalText = translationMap[key];
+                        if (typeof originalText === "string") {
+                            const parent = path.parentPath;
+                            if (parent?.isJSXExpressionContainer()) {
+                                const containerParent = parent.parentPath;
+                                if (containerParent?.isJSXAttribute() &&
+                                    containerParent.node.value === parent.node) {
+                                    // If the expression is inside an attribute, set attribute value to string literal
+                                    containerParent.node.value = t.stringLiteral(originalText);
+                                    parent.remove(); // Remove the expression container if still present
+                                }
+                                else {
+                                    // Otherwise, it's a JSX child
+                                    parent.replaceWith(t.jsxText(originalText));
+                                }
                             }
                             else {
-                                // Otherwise, it's a JSX child
-                                parent.replaceWith(t.jsxText(originalText));
+                                // Not in JSX, just replace with a string literal
+                                path.replaceWith(t.stringLiteral(originalText));
                             }
+                            modified = true;
                         }
-                        else {
-                            // Not in JSX, just replace with a string literal
-                            path.replaceWith(t.stringLiteral(originalText));
-                        }
-                        modified = true;
                     }
-                }
-            },
-        });
-        if (modified) {
-            const output = (0, generator_1.default)(ast).code;
-            fs_1.default.writeFileSync(file, output, "utf-8");
+                },
+            });
+            if (modified) {
+                const output = generate(ast).code;
+                fs.writeFileSync(file, output, "utf-8");
+            }
         }
     }
+    catch (err) {
+        console.error("[Reverser Error]", err);
+        throw err;
+    }
 }

package/dist/src/scanner.d.ts

@@ -0,0 +1 @@
+export declare function getSourceFiles(dir: string, excludes?: string[]): Promise<string[]>;

package/dist/src/scanner.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSourceFiles = getSourceFiles;
-const glob_1 = require("glob");
-async function getSourceFiles(dir, excludes = []) {
+import { glob } from 'glob';
+export async function getSourceFiles(dir, excludes = []) {
     console.log(`Scanning dir: ${dir}, excludes: ${excludes}`);
-    const files = await (0, glob_1.glob)(`${dir}/**/*.{js,jsx,ts,tsx}`, {
+    const files = await glob(`${dir}/**/*.{js,jsx,ts,tsx}`, {
         nodir: true,
         ignore: ['**/node_modules/**', '**/dist/**', ...excludes]
     });

package/dist/src/utils.d.ts

@@ -0,0 +1,2 @@
+export type KeyStrategy = 'snake_case' | 'camelCase' | 'hash';
+export declare function generateTranslationKey(text: string, strategy?: KeyStrategy | ((text: string) => string)): string;

package/dist/src/utils.js

@@ -1,11 +1,5 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateTranslationKey = generateTranslationKey;
-const crypto_1 = __importDefault(require("crypto"));
-function generateTranslationKey(text, strategy = 'snake_case') {
+import crypto from 'crypto';
+export function generateTranslationKey(text, strategy = 'snake_case') {
     if (typeof strategy === 'function') {
         return strategy(text);
     }
@@ -13,7 +7,7 @@ function generateTranslationKey(text, strategy = 'snake_case') {
         case 'camelCase':
             return toCamelCase(text);
         case 'hash':
-            return crypto_1.default.createHash('md5').update(text).digest('hex').substring(0, 8);
+            return crypto.createHash('md5').update(text).digest('hex').substring(0, 8);
         case 'snake_case':
         default:
             return toSnakeCase(text);

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "i18n-turbo",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Extract hardcoded text from JSX/TSX files and convert to i18n format.",
-  "main": "dist/index.js",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
   "files": [
     "dist",
     "README.md",
@@ -47,7 +49,20 @@
     "minimatch": "^10.1.1",
     "p-limit": "^3.1.0"
   },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@types/react": "^19.0.0",
     "@types/babel__core": "^7.20.5",
     "@types/babel__generator": "^7.27.0",
     "@types/babel__traverse": "^7.20.7",