@scopeact/autoi18n 1.1.2 → 1.2.1

package/README.md

@@ -1,256 +1,117 @@
-# @scopeact/autoi18n
-
-[![npm version](https://img.shields.io/npm/v/@scopeact/autoi18n.svg)](https://www.npmjs.com/package/@scopeact/autoi18n)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-> CLI to automatically migrate React / TypeScript projects to i18n using AST and LLMs.
-
-**auto-i18n** scans TS/TSX files, extracts hardcoded strings, replaces them with `t("key")`, generates translation files, and optionally injects the correct i18n imports — all with explicit, opinionated trade-offs.
-
-This is a **migration tool**, not a runtime framework.
-
----
-
-## Why this exists
-
-Internationalizing a React codebase usually means:
-
-* Manually hunting hardcoded strings
-* Guessing translation keys
-* Rewriting components by hand
-* Copy-pasting JSON across languages
-
-It’s repetitive, boring, and easy to screw up.
-
-**auto-i18n automates the mechanical work and delegates semantic decisions to an LLM.**
-
----
-
-## What this tool does
-
-* Parses **TypeScript and TSX using AST** (no regex hacks)
-* Detects static hardcoded strings
-* Rewrites code to use `t("key")`
-* Generates translation files
-* Uses an **LLM to generate semantic translation keys**
-* Optionally injects i18n imports automatically
-* Supports different i18n libraries
-
----
-
-## Installation
-
-No global install required:
-
-```bash
-npx @scopeact/autoi18n init
-```
-
----
-
-## Usage
-
-### 1. Initialize configuration
-
-```bash
-npx @scopeact/autoi18n init
-```
-
-This creates:
-
-* `auto-i18n.config.json`
-
----
-
-### 2. Run the migration
-
-```bash
-npx @scopeact/autoi18n run
-```
-
-The tool will:
-
-1. Parse files into AST
-2. Detect static string literals
-3. Ask the LLM to infer **semantic translation keys**
-4. Rewrite source code
-5. Inject i18n imports if missing
-6. Generate translation files
-
----
-
-## Example
-
-### Before
-
-```tsx
-export function Home() {
-  return (
-    <div>
-      <h1>Hello world</h1>
-      <p>Welcome to our platform</p>
-    </div>
-  );
-}
-```
-
-### After
-
-```tsx
-import { useTranslation } from "react-i18next";
-
-export function Home() {
-  return (
-    <div>
-      <h1>{t("greeting")}</h1>
-      <p>{t("description")}</p>
-    </div>
-  );
-}
-```
-
-Generated translation file:
-
-```json
-{
-  "greeting": "Hello world",
-  "description": "Welcome to our platform"
-}
-```
-
----
-
-## Configuration
-
-Example `auto-i18n.config.json`:
-
-```json
-{
-  "sourceLang": "pt",
-  "targetLangs": [ "en", "es", "de" ],
-  "autoInject": true,
-  "i18nLibrary": "react-i18next",
-  "provider": "ollama",
-  "localesDir": "./locales",
-  "model": "gemma3-translator",
-  "files": [ "**/*.tsx" ]
-}
-```
-
-### Options
-
-#### `autoInject`
-
-```json
-{
-  "autoInject": true
-}
-```
-
-Automatically injects the required i18n import at the top of the file **if it does not already exist**.
-
-This avoids manual setup and keeps the migration fully automated.
-
----
-
-#### `i18nLibrary`
-
-```json
-{
-  "i18nLibrary": "react-i18next"
-}
-```
-
-Defines which i18n library should be used when injecting imports and hooks.
-
-Supported values:
-
-* `react-i18next`
-* `next-i18n`
-
-This affects:
-
-* import statements
-* generated code structure
-
----
-
-## Why keys are AI-generated (no dry-run)
-
-Translation key naming is a **semantic problem**, not a mechanical one.
-
-For example:
-
-* Is `"Hello world"` a title, a CTA, or a heading?
-* Does it belong to `home`, `layout`, or `marketing`?
-
-These decisions cannot be inferred deterministically.
-
-**auto-i18n intentionally requires an LLM to:**
-
-* infer intent
-* generate meaningful keys
-* avoid arbitrary conventions
-
-Because of this, a traditional dry-run would produce **misleading results** and is intentionally not supported.
-
-This trade-off is explicit.
-
----
-
-## Why AST instead of regex
-
-Regex does not understand JSX or TypeScript.
-
-AST parsing:
-
-* Preserves syntax structure
-* Avoids accidental replacements
-* Handles real-world React code
-* Produces predictable transformations
-
-This tool is designed for **production codebases**, not demos.
-
----
-
-## Limitations
-
-This tool does **not** handle:
-
-* Dynamic strings (`"Hello " + name`)
-* Template literals with expressions
-* Runtime-generated text
-* Context-dependent translations
-
-It is meant to **bootstrap i18n**, not replace human review.
-
----
-
-## When you should NOT use this
-
-* Your project already has a mature i18n setup
-* Translations depend heavily on runtime logic
-* You expect zero review after migration
-
----
-
-## Design philosophy
-
-* Explicit over clever
-* Predictable over magical
-* Narrow scope over feature bloat
-
-This tool solves **one specific problem**, deliberately.
-
----
-
-## License
-
-Distributed under MIT license. See [LICENSE](LICENSE) for more details.
-
----
-
-## 🇧🇷 Nota
-
-README principal em inglês por usabilidade global.
-Português aqui só pra lembrar que esse projeto nasceu no Brasil.
+
+# @scopeact/autoi18n
+
+[![npm version](https://img.shields.io/npm/v/@scopeact/autoi18n.svg?style=flat-square)](https://www.npmjs.com/package/@scopeact/autoi18n)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/felipevetter/auto-i18n/publish.yml?style=flat-square)](https://github.com/felipevetter/auto-i18n/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-blue.svg?style=flat-square)](https://github.com/felipevetter/auto-i18n/pulls)
+
+> The only i18n tool that handles both **Extraction** (via AST + AI) and **Runtime** (Zero-Config).
+
+**autoi18n** is a dual-purpose tool designed to take a hardcoded React/Next.js project to full internationalization in minutes, not hours.
+
+---
+
+## ⚡ The Core: CLI Migration
+
+The CLI scans your `TSX` files, extracts hardcoded strings using **Abstract Syntax Tree (AST)**, and uses **AI to generate semantic keys**.
+
+- **No Regex:** Safe code transformations that won't break your syntax.
+- **AI-Powered:** Keys like `welcome_title` instead of `text_1`.
+- **Auto-Inject:** Automatically adds imports to your files.
+
+### Quick Start
+```bash
+npx @scopeact/autoi18n init
+npx @scopeact/autoi18n run
+```
+
+---
+
+## 🚀 The Feature: Zero-Config Runtime
+
+We noticed that even after extracting strings, configuring i18n in **Next.js (App Router)** is a nightmare (Middleware, `[locale]` folders, etc). 
+
+So we built a **minimalist, high-performance runtime** specifically for the CLI output.
+
+### 1. Setup the Provider (Root Layout)
+No need to move files into `[locale]` folders. Just wrap your layout.
+
+```tsx
+// app/layout.tsx
+import { I18nProvider } from "@scopeact/autoi18n/client";
+import { getI18nConfig } from "@scopeact/autoi18n/server";
+
+export default async function RootLayout({ children }) {
+  const i18n = await getI18nConfig('en'); // Default language
+
+  return (
+    <html lang={i18n.locale}>
+      <body>
+        <I18nProvider locale={i18n.locale} messages={i18n.messages}>
+          {children}
+        </I18nProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### 2. Usage in Server Components
+```tsx
+// app/page.tsx (Server)
+import { getI18n } from '@scopeact/autoi18n/server';
+
+export default async function Page() {
+  const { t } = await getI18n();
+  return <h1>{t("hero_title")}</h1>;
+}
+```
+
+### 3. Usage in Client Components
+```tsx
+// components/Button.tsx (Client)
+'use client';
+import { useI18n } from '@scopeact/autoi18n/client';
+
+export function HeroButton() {
+  const { t } = useI18n();
+  return <button>{t("get_started")}</button>;
+}
+```
+
+---
+
+## 🛠 Configuration
+
+Created via `init`, the `auto-i18n.config.json` controls the magic:
+
+```json
+{
+  "sourceLang": "pt",
+  "targetLangs": ["en", "es"],
+  "i18nLibrary": "@scopeact/autoi18n",
+  "provider": "openai",
+  "localesDir": "./locales",
+  "files": ["src/**/*.tsx"]
+}
+```
+
+---
+
+## 💎 Why autoi18n?
+
+| Feature | Tradicional (next-intl/i18next) | **autoi18n** |
+| :--- | :--- | :--- |
+| **Key Creation** | Manual (Hours of copy-paste) | **AI-Automated** (Seconds) |
+| **Code Rewrite** | Manual | **AST-Automated** |
+| **Folder Structure** | Forced `[locale]` nesting | **Stay as you are** |
+| **Next.js Setup** | Complex (Middleware/Config) | **Zero-Config** |
+
+---
+
+## 🇧🇷 Born in Brazil
+Projeto desenvolvido com foco em resolver a dor real de desenvolvedores que precisam entregar projetos globais rápido. 
+
+## License
+MIT © [Felipe Vetter](https://github.com/felipevetter)

package/dist/chunk-36HQJSGI.cjs

@@ -0,0 +1,40 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }// src/runtime/client.tsx
+var _react = require('react'); var _react2 = _interopRequireDefault(_react);
+var _navigation = require('next/navigation');
+var _jsxruntime = require('react/jsx-runtime');
+var I18nContext = _react.createContext.call(void 0, void 0);
+function I18nProvider({
+  children,
+  locale: initialLocale,
+  messages: initialMessages
+}) {
+  const [locale, setLocaleState] = _react.useState.call(void 0, initialLocale);
+  const [messages, setMessages] = _react.useState.call(void 0, initialMessages);
+  const router = _navigation.useRouter.call(void 0, );
+  _react2.default.useEffect(() => {
+    setLocaleState(initialLocale);
+    setMessages(initialMessages);
+  }, [initialLocale, initialMessages]);
+  const t = (key) => {
+    return messages[key] || key;
+  };
+  const setLocale = (newLocale) => {
+    document.cookie = `NEXT_LOCALE=${newLocale}; path=/; max-age=31536000`;
+    setLocaleState(newLocale);
+    router.refresh();
+  };
+  return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, I18nContext.Provider, { value: { locale, messages, t, setLocale }, children });
+}
+function useI18n() {
+  const context = _react.useContext.call(void 0, I18nContext);
+  if (!context) {
+    throw new Error("useI18n deve ser usado dentro de um I18nProvider");
+  }
+  return context;
+}
+
+
+
+
+exports.I18nProvider = I18nProvider; exports.useI18n = useI18n;
+//# sourceMappingURL=chunk-36HQJSGI.cjs.map

package/dist/chunk-36HQJSGI.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/auto-i18n/auto-i18n/packages/autoi18n/dist/chunk-36HQJSGI.cjs","../src/runtime/client.tsx"],"names":[],"mappings":"AAAA;ACGA,4EAAsE;AAEtE,6CAA0B;AAwClB,+CAAA;AA/BR,IAAM,YAAA,EAAc,kCAAA,KAA2C,CAAS,CAAA;AAEjE,SAAS,YAAA,CAAa;AAAA,EACzB,QAAA;AAAA,EACA,MAAA,EAAQ,aAAA;AAAA,EACR,QAAA,EAAU;AACd,CAAA,EAIG;AACC,EAAA,MAAM,CAAC,MAAA,EAAQ,cAAc,EAAA,EAAI,6BAAA,aAAsB,CAAA;AACvD,EAAA,MAAM,CAAC,QAAA,EAAU,WAAW,EAAA,EAAI,6BAAA,eAAwB,CAAA;AACxD,EAAA,MAAM,OAAA,EAAS,mCAAA,CAAU;AAEzB,EAAA,eAAA,CAAM,SAAA,CAAU,CAAA,EAAA,GAAM;AAClB,IAAA,cAAA,CAAe,aAAa,CAAA;AAC5B,IAAA,WAAA,CAAY,eAAe,CAAA;AAAA,EAC/B,CAAA,EAAG,CAAC,aAAA,EAAe,eAAe,CAAC,CAAA;AAEnC,EAAA,MAAM,EAAA,EAAI,CAAC,GAAA,EAAA,GAAgB;AACvB,IAAA,OAAO,QAAA,CAAS,GAAG,EAAA,GAAK,GAAA;AAAA,EAC5B,CAAA;AAEA,EAAA,MAAM,UAAA,EAAY,CAAC,SAAA,EAAA,GAAsB;AACrC,IAAA,QAAA,CAAS,OAAA,EAAS,CAAA,YAAA,EAAe,SAAS,CAAA,0BAAA,CAAA;AAC1C,IAAA,cAAA,CAAe,SAAS,CAAA;AACxB,IAAA,MAAA,CAAO,OAAA,CAAQ,CAAA;AAAA,EACnB,CAAA;AAEA,EAAA,uBACI,6BAAA,WAAC,CAAY,QAAA,EAAZ,EAAqB,KAAA,EAAO,EAAE,MAAA,EAAQ,QAAA,EAAU,CAAA,EAAG,UAAU,CAAA,EACzD,SAAA,CACL,CAAA;AAER;AAEO,SAAS,OAAA,CAAA,EAAU;AACtB,EAAA,MAAM,QAAA,EAAU,+BAAA,WAAsB,CAAA;AACtC,EAAA,GAAA,CAAI,CAAC,OAAA,EAAS;AACV,IAAA,MAAM,IAAI,KAAA,CAAM,kDAAkD,CAAA;AAAA,EACtE;AACA,EAAA,OAAO,OAAA;AACX;ADvBA;AACA;AACE;AACA;AACF,+DAAC","file":"/home/runner/work/auto-i18n/auto-i18n/packages/autoi18n/dist/chunk-36HQJSGI.cjs","sourcesContent":[null,"'use client';\n\n// @ts-ignore\nimport React, { createContext, useContext, useState, ReactNode } from 'react';\n// @ts-ignore\nimport { useRouter } from 'next/navigation';\n\ntype I18nContextType = {\n    locale: string;\n    messages: Record<string, string>;\n    t: (key: string) => string;\n    setLocale: (newLocale: string) => void;\n};\n\nconst I18nContext = createContext<I18nContextType | undefined>(undefined);\n\nexport function I18nProvider({\n    children,\n    locale: initialLocale,\n    messages: initialMessages\n}: {\n    children: ReactNode;\n    locale: string;\n    messages: Record<string, string>;\n}) {\n    const [locale, setLocaleState] = useState(initialLocale);\n    const [messages, setMessages] = useState(initialMessages);\n    const router = useRouter();\n\n    React.useEffect(() => {\n        setLocaleState(initialLocale);\n        setMessages(initialMessages);\n    }, [initialLocale, initialMessages]);\n\n    const t = (key: string) => {\n        return messages[key] || key;\n    };\n\n    const setLocale = (newLocale: string) => {\n        document.cookie = `NEXT_LOCALE=${newLocale}; path=/; max-age=31536000`;\n        setLocaleState(newLocale);\n        router.refresh();\n    };\n\n    return (\n        <I18nContext.Provider value={{ locale, messages, t, setLocale }}>\n            {children}\n        </I18nContext.Provider>\n    );\n}\n\nexport function useI18n() {\n    const context = useContext(I18nContext);\n    if (!context) {\n        throw new Error('useI18n deve ser usado dentro de um I18nProvider');\n    }\n    return context;\n}"]}

package/dist/chunk-NYRK5OWZ.js

@@ -0,0 +1,40 @@
+// src/runtime/client.tsx
+import React, { createContext, useContext, useState } from "react";
+import { useRouter } from "next/navigation";
+import { jsx } from "react/jsx-runtime";
+var I18nContext = createContext(void 0);
+function I18nProvider({
+  children,
+  locale: initialLocale,
+  messages: initialMessages
+}) {
+  const [locale, setLocaleState] = useState(initialLocale);
+  const [messages, setMessages] = useState(initialMessages);
+  const router = useRouter();
+  React.useEffect(() => {
+    setLocaleState(initialLocale);
+    setMessages(initialMessages);
+  }, [initialLocale, initialMessages]);
+  const t = (key) => {
+    return messages[key] || key;
+  };
+  const setLocale = (newLocale) => {
+    document.cookie = `NEXT_LOCALE=${newLocale}; path=/; max-age=31536000`;
+    setLocaleState(newLocale);
+    router.refresh();
+  };
+  return /* @__PURE__ */ jsx(I18nContext.Provider, { value: { locale, messages, t, setLocale }, children });
+}
+function useI18n() {
+  const context = useContext(I18nContext);
+  if (!context) {
+    throw new Error("useI18n deve ser usado dentro de um I18nProvider");
+  }
+  return context;
+}
+
+export {
+  I18nProvider,
+  useI18n
+};
+//# sourceMappingURL=chunk-NYRK5OWZ.js.map

package/dist/chunk-NYRK5OWZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime/client.tsx"],"sourcesContent":["'use client';\n\n// @ts-ignore\nimport React, { createContext, useContext, useState, ReactNode } from 'react';\n// @ts-ignore\nimport { useRouter } from 'next/navigation';\n\ntype I18nContextType = {\n    locale: string;\n    messages: Record<string, string>;\n    t: (key: string) => string;\n    setLocale: (newLocale: string) => void;\n};\n\nconst I18nContext = createContext<I18nContextType | undefined>(undefined);\n\nexport function I18nProvider({\n    children,\n    locale: initialLocale,\n    messages: initialMessages\n}: {\n    children: ReactNode;\n    locale: string;\n    messages: Record<string, string>;\n}) {\n    const [locale, setLocaleState] = useState(initialLocale);\n    const [messages, setMessages] = useState(initialMessages);\n    const router = useRouter();\n\n    React.useEffect(() => {\n        setLocaleState(initialLocale);\n        setMessages(initialMessages);\n    }, [initialLocale, initialMessages]);\n\n    const t = (key: string) => {\n        return messages[key] || key;\n    };\n\n    const setLocale = (newLocale: string) => {\n        document.cookie = `NEXT_LOCALE=${newLocale}; path=/; max-age=31536000`;\n        setLocaleState(newLocale);\n        router.refresh();\n    };\n\n    return (\n        <I18nContext.Provider value={{ locale, messages, t, setLocale }}>\n            {children}\n        </I18nContext.Provider>\n    );\n}\n\nexport function useI18n() {\n    const context = useContext(I18nContext);\n    if (!context) {\n        throw new Error('useI18n deve ser usado dentro de um I18nProvider');\n    }\n    return context;\n}"],"mappings":";AAGA,OAAO,SAAS,eAAe,YAAY,gBAA2B;AAEtE,SAAS,iBAAiB;AAwClB;AA/BR,IAAM,cAAc,cAA2C,MAAS;AAEjE,SAAS,aAAa;AAAA,EACzB;AAAA,EACA,QAAQ;AAAA,EACR,UAAU;AACd,GAIG;AACC,QAAM,CAAC,QAAQ,cAAc,IAAI,SAAS,aAAa;AACvD,QAAM,CAAC,UAAU,WAAW,IAAI,SAAS,eAAe;AACxD,QAAM,SAAS,UAAU;AAEzB,QAAM,UAAU,MAAM;AAClB,mBAAe,aAAa;AAC5B,gBAAY,eAAe;AAAA,EAC/B,GAAG,CAAC,eAAe,eAAe,CAAC;AAEnC,QAAM,IAAI,CAAC,QAAgB;AACvB,WAAO,SAAS,GAAG,KAAK;AAAA,EAC5B;AAEA,QAAM,YAAY,CAAC,cAAsB;AACrC,aAAS,SAAS,eAAe,SAAS;AAC1C,mBAAe,SAAS;AACxB,WAAO,QAAQ;AAAA,EACnB;AAEA,SACI,oBAAC,YAAY,UAAZ,EAAqB,OAAO,EAAE,QAAQ,UAAU,GAAG,UAAU,GACzD,UACL;AAER;AAEO,SAAS,UAAU;AACtB,QAAM,UAAU,WAAW,WAAW;AACtC,MAAI,CAAC,SAAS;AACV,UAAM,IAAI,MAAM,kDAAkD;AAAA,EACtE;AACA,SAAO;AACX;","names":[]}