localize-ai

localize-ai

AI-powered React localization with AST-based extraction, namespace-based loading, and smart caching ⚡

👉 No regex. No manual cleanup. Just accurate and scalable translations.

Context-aware AI localization with multi-provider support ⚡

Automatically extract, translate, and serve multilingual UI — powered by AI ⚡

Designed for performance: no unnecessary data, no re-fetching, minimal bundle impact.

✨ Features

🔧 Core

• 🔍 AST-based extraction (no regex)
• 🧩 Supports template literals with variables
• 🧹 Removes unused (dead) translations automatically
• 🌍 AI-powered translations (OpenAI, Gemini)
• ⚡ Incremental translation (only new strings/languages)

⚡ Performance

• Namespace-based splitting
  → Each language is split into namespaces (common.json, dashboard.json, etc.)

• Lazy loading
  → Only loads required namespace instead of entire language

• Caching
  → Prevents repeated fetches per language + namespace

⚛️ Developer Experience

• 🧠 Zero-config runtime
• ⚛️ React hooks + context
• 🧠 Context-aware translations
• 💸 Cost optimized (no re-translation)

⚡ Performance Optimizations

localize-ai is optimized for production:

• Per-locale splitting → Each language is stored separately (translations_en.json, translations_hi.json)
• Lazy loading → Only loads the active language instead of all translations
• Caching → Prevents repeated fetches and improves performance

👉 This ensures fast load times and minimal bundle size.

🧠 Smart Extraction (AST-based)

Localize-ai uses AST parsing instead of regex, ensuring accurate extraction:

• Handles complex code patterns
• Supports template literals with variables
• Avoids false positives

Example:

t(`hello {{userName}}, your order {{id}} is ready`, {
  userName,
  id: orderId
});

👉 Variables are preserved and translated correctly.

🧩 Namespace-based Loading

Localize-ai supports namespace-based translation splitting for large applications:

public/
  └── locales/
      ├── en/
      │   ├── common.json
      │   ├── dashboard.json
      │   ├── checkout.json
      │   └── ...
      ├── fr/
      │   ├── common.json
      │   ├── dashboard.json
      │   └── ...

Why this matters:

• Loads only required translations
• Improves performance for large apps
• Reduces initial bundle size

👉 No more loading the entire language file at once.

🚀 Smart Caching

Localize-ai caches translations per:

• language
• namespace

This ensures:

• no duplicate network requests
• faster UI rendering
• better runtime performance

📦 Installation

npm install localize-ai

⚙️ Setup (2 steps)

1️⃣ Create config

// localize.config.js
export default {
  sourceLanguage: "en",
  translationLanguages: ["hi", "fr"],
  provider: "gemini", // or "openai"
  apikey: "VITE_GEMINI_API_KEY",
  context: "E-commerce checkout UI for buying products",
};

👉 Providing context improves translation accuracy by helping AI understand intent (e.g., "Charge" in payments vs battery).

2️⃣ Add your API key

VITE_GEMINI_API_KEY=your_api_key_here

🚀 Usage

Step 1: Initialize

npx localize-ai init

Step 2: Extract & translate

npx localize-ai translate

This will:

• scan your codebase
• extract t("text")
• generate translations
• create per-language translation files:

public/
  └── locales/
      ├── en/
      │   ├── common.json
      │   ├── [namespace].json
      │   └── ...
      ├── fr/
      │   └── ...

localize.runtime.json

Step 3: Wrap your app

import { LanguageContextProvider } from "localize-ai";

<LanguageContextProvider>
  <App />
</LanguageContextProvider>;

Step 4: Use translations

Using namespaces

const { t } = useTranslation("dashboard");

👉 Loads only dashboard.json for the active language.

If no namespace is provided:

const { t } = useTranslation();

👉 Uses common.json by default.

🌍 Change language

const { setLang } = useTranslation();

setLang("fr"); // switch language

🧹 Dead Translation Cleanup

npx localize-ai delete-sync

Localize-ai automatically removes unused translations:

• Detects strings no longer present in code
• Cleans up translation files
• Keeps JSON lean and optimized

👉 Prevents bloated translation files over time.

🧠 How it works

Code → AST Extract → Namespace Split → AI Translate → JSON → Lazy Load → Cache → UI

• Only new strings are translated
• Only missing languages are generated
• Existing translations are reused

📁 Output

public/
  └── locales/
      ├── en/
      │   ├── common.json
      │   ├── [namespace].json
      │   └── ...
      ├── fr/
      │   └── ...

⚡ Example

<h1>{t("Get started")}</h1>

➡️ Automatically becomes:

{
  "common": {
    "Get started": "शुरू करें"
  }
}

🛠 CLI Commands

npx localize-ai init        # generate runtime config
npx localize-ai translate   # extract + translate
npx localize-ai delete-sync   # delete dead translations

🎯 Why localize-ai?

Feature	localize-ai	traditional i18n
Auto extraction	✅	❌
AST-based parsing (no regex)	✅	❌
AI translation	✅	❌
Incremental updates	✅	❌
Namespace-based loading	✅	⚠️ manual
Lazy loading	✅	⚠️ manual
Built-in caching	✅	❌
Dead translation cleanup	✅	❌
Context-aware translations	✅	❌
Setup time	⚡ minutes	⏳ hours

⚠️ Notes

• Only static strings inside t("...") are extracted
• Ensure public/ folder exists
• API key is required only for translation step

🗺 Roadmap

Core Improvements

• AST-based extraction (no regex)
• Template literal support with variables
• Better error handling & retry logic for failed translations
• CLI UX improvements (spinners, better logs)

Performance & Scalability

• Lazy loading translations
• Namespace-based splitting
• Per-locale structure
• Smart caching (per language + namespace)
• CDN support for translation files

Features

• Multi-provider support (OpenAI, Gemini)
• Fallback providers (auto-switch if one fails)
• Custom translation rules (skip/override specific keys)
• Namespace configuration (custom naming & grouping)

Developer Experience

• VS Code extension (highlight untranslated strings)
• Debug mode (show missing translations in UI)
• CLI dry-run mode
• Type-safe translations (TS support for keys)

Maintenance & Optimization

• Dead translation cleanup
• Translation validation (detect missing/interpolated variables)
• Sync check (detect outdated translations)

Future Ideas

• Framework support beyond React (Next.js, Vue)
• Web dashboard for managing translations
• Analytics (missing keys, usage tracking)
• Collaboration support (teams & workflows)

🤝 Contributing

PRs welcome! Feel free to open issues or suggest improvements.

📄 License

MIT

💬 Author

Parth Gupta

⭐ Support

If you like this project:

👉 Star the repo 👉 Share with developers 👉 Give feedback