Dynamic Language Switcher

A Weglot-like automatic translation package for JavaScript/TypeScript applications that automatically detects and translates content without requiring manual JSON configuration. Perfect for dynamic websites, SPAs, and applications where content changes frequently.

📦 Available on npm: dynamic-language-switcher

🚀 Quick Installation

npm install dynamic-language-switcher

✨ Features

• 🌍 Automatic Content Detection: Automatically scans the DOM for translatable content
• 🔄 No Manual Configuration: Works like Weglot - no JSON files or manual setup required
• 🚀 Real-time Translation: Translates content on-demand when switching languages
• 📱 Dynamic Content Monitoring: Automatically detects new content added to the page
• 🌐 Translation API Integration: Supports DeepL, Google Cloud Translation (coming soon), and custom APIs
• 🇨🇳 Multi-language Support: 20+ languages including English, Spanish, French, German, Italian, Portuguese, Russian, Japanese, Korean, Arabic, Hebrew, Persian, Urdu, Hindi, Bengali, Thai, Vietnamese, Turkish, Dutch, and more
• 🇳🇵 Nepali Language Support: Full Nepali language support with Devanagari script
• 🔄 RTL Support: Full Right-to-Left language support for Arabic, Hebrew, Persian, Urdu, and more
• ⚛️ React Integration: Hooks, components, and context providers for seamless React integration
• 🚀 Next.js Support: Server-side rendering, static generation, and middleware integration
• 🎯 TypeScript: Full TypeScript support with comprehensive type definitions
• 💾 Persistence: Language preference persistence with localStorage
• 🔧 Flexible: Easy to integrate with any JavaScript/TypeScript project
• 📱 Responsive: Mobile-friendly components and utilities
• 🧪 Tested: Comprehensive test coverage with Jest

🚀 Quick Start

Installation

npm install dynamic-language-switcher

Basic Usage (Weglot-like)

import { LanguageSwitcher } from "dynamic-language-switcher";

// Initialize with automatic translation
const languageSwitcher = new LanguageSwitcher({
  defaultLanguage: "en",
  autoTranslate: true,
  translationApi: {
    provider: "deepl",
    apiKey: "your-deepl-api-key",
  },
});

// Start automatic content detection and translation
languageSwitcher.startAutoTranslation();

// Switch language - content is automatically translated!
await languageSwitcher.setLanguage("es");

Advanced Configuration

const languageSwitcher = new LanguageSwitcher({
  defaultLanguage: "en",
  autoTranslate: true,
  preserveOriginalText: true, // Keep original text for restoration
  contentSelectors: ["h1", "h2", "h3", "p", "span", "div", "a", "button"],
  excludeSelectors: [
    "script",
    "style",
    "code",
    "pre",
    "[data-no-translate]",
    ".no-translate",
  ],
  translationApi: {
    provider: "deepl",
    apiKey: "your-deepl-api-key",
    batchSize: 50,
    rateLimit: 100,
  },
});

🔧 How It Works

1. Automatic Content Detection

The system automatically scans your page for translatable content using intelligent selectors:

// Automatically detects content in:
// - Headings (h1, h2, h3, etc.)
// - Paragraphs and text elements
// - Buttons and links
// - Form placeholders
// - Meta descriptions
// - And more...

2. Dynamic Content Monitoring

Watches for new content being added to the page:

// Content added dynamically is automatically detected
document.body.innerHTML += "<p>New content that will be translated!</p>";

// Content updates are also detected
element.textContent = "Updated content";

3. Automatic Translation

Translates content when switching languages:

// Switch to Spanish - all detected content is automatically translated
await languageSwitcher.setLanguage("es");

// Switch to Chinese - content is translated again
await languageSwitcher.setLanguage("zh-CN");

4. No Manual Setup Required

Unlike traditional i18n libraries, you don't need to:

• ❌ Define translation JSON files
• ❌ Manually mark translatable text
• ❌ Configure translation keys
• ❌ Update translation files when content changes

🌐 Translation API Support

DeepL (Recommended)

translationApi: {
  provider: "deepl",
  apiKey: "your-deepl-api-key"
}

Google Cloud Translation API (Coming Soon)

translationApi: {
  provider: "google-cloud",
  apiKey: "your-google-cloud-api-key"
}

Note: This will be implemented in a future update

Custom API

translationApi: {
  provider: "custom",
  endpoint: "https://your-translation-api.com/translate"
}

📚 API Reference

Core Methods

startAutoTranslation()

Start automatic content detection and translation.

stopAutoTranslation()

Stop automatic translation.

translatePage(targetLanguage?)

Translate the entire page to the specified language.

translateElement(element, targetLanguage?)

Translate a specific element.

restoreOriginalText()

Restore all translated content to the original text.

getDetectedContent()

Get all detected translatable content.

Content Detection Options

{
  contentSelectors: [
    "h1", "h2", "h3", "h4", "h5", "h6",
    "p", "span", "div", "a", "button", "label",
    "input[placeholder]", "textarea[placeholder]"
  ],
  excludeSelectors: [
    "script", "style", "code", "pre",
    "[data-no-translate]", ".no-translate",
  ]
}

Excluding Content from Translation

<!-- Exclude specific elements -->
<div data-no-translate>This won't be translated</div>
<div class="no-translate">This also won't be translated</div>

<!-- Exclude entire sections -->
<section data-no-translate>
  <h2>Technical Documentation</h2>
  <p>This entire section is excluded</p>
</section>

⚛️ React Integration

Hooks

import { useLanguage } from "dynamic-language-switcher";

function MyComponent() {
  const { currentLanguage, switchLanguage, isTranslating } = useLanguage();

  return (
    <div>
      <h1>Welcome to our app</h1>
      <button onClick={() => switchLanguage("es")}>Switch to Spanish</button>
      {isTranslating && <p>Translating...</p>}
    </div>
  );
}

Components

import { LanguageSwitcher, RTLDirection } from "dynamic-language-switcher";

function App() {
  return (
    <RTLDirection>
      <header>
        <h1>My App</h1>
        <LanguageSwitcher variant="dropdown" />
      </header>
      <main>
        <p>This content will be automatically translated</p>
      </main>
    </RTLDirection>
  );
}

🚀 Next.js Integration

Server-side Rendering

import { GetServerSideProps } from "next";
import { detectLanguageFromRequest } from "dynamic-language-switcher";

export const getServerSideProps: GetServerSideProps = async (context) => {
  const language = detectLanguageFromRequest(context);

  return {
    props: {
      language,
      // ... other props
    },
  };
};

Static Generation

import { GetStaticProps } from "next";
import { createLocalizedPage } from "dynamic-language-switcher";

export const getStaticProps = createLocalizedPage(
  async (context) => {
    return {
      props: {
        /* ... */
      },
    };
  },
  ["en", "es", "zh-CN", "np", "ar"]
);

🌍 Supported Languages

Western Languages

• English (en), Spanish (es), French (fr), German (de)
• Italian (it), Portuguese (pt), Russian (ru), Dutch (nl)

Asian Languages

• Japanese (ja), Korean (ko), Chinese (zh-CN/zh-TW)
• Nepali (np), Hindi (hi), Bengali (bn), Thai (th)
• Vietnamese (vi), Turkish (tr)

RTL Languages

• Arabic (ar), Hebrew (he), Persian (fa), Urdu (ur)
• And many more...

🏗️ Project Structure

src/
├── core/                 # Core language switcher logic
│   └── language-switcher.ts
├── types/               # TypeScript type definitions
│   └── types.ts
├── utils/               # Utility functions
│   ├── utils.ts
│   ├── content-detector.ts    # Automatic content detection
│   ├── translation-service.ts # Translation API integration
│   └── env-loader.ts          # Environment configuration
├── hooks/               # React hooks
│   └── useLanguage.ts
├── components/          # React components
│   └── components.tsx
├── adapters/            # Framework adapters (Next.js, etc.)
│   └── index.ts
└── index.ts             # Main entry point

🧪 Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

🔧 Development

# Install dependencies
npm install

# Build the package
npm run build

# Run linting
npm run lint

# Run type checking
npm run type-check

# Clean build artifacts
npm run clean

📦 Publishing

# Login to npm
npm login

# Publish the package
npm publish

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Sushant R. Dangal - GitHub

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.