multilanguagejs

🌍 MultilanguageJS

Simple, zero-dependency i18n for static websites.

Add multi-language support with just a few lines of code, no complex configurations or heavy frameworks needed.

✨ Features

• 🚫 Zero dependencies - nothing to install besides the lib itself
• 🔀 Two translation modes - HTML templates and string dictionaries
• 🌐 Browser language detection - auto-detect with navigator.language
• 🔄 Fallback support - missing translations gracefully fall back to your default language
• 🔷 TypeScript - full type definitions included out of the box
• 🪶 Tiny - ~2KB minified, because your users shouldn’t pay for i18n
• 📦 CDN + npm - use it however you want

📥 Installation

npm

npm install multilanguagejs

CDN

<script src="https://unpkg.com/multilanguagejs/dist/multilanguagejs.umd.cjs"></script>

🚀 Quick Start

Option 1: String Dictionaries

The simplest approach: provide translations as a JavaScript object and mark elements with data-i18n.

<h1 data-i18n="greeting"></h1>
<p data-i18n="description"></p>

<script src="https://unpkg.com/multilanguagejs/dist/multilanguagejs.umd.cjs"></script>
<script>
  const ml = new MultilanguageJS({
    languages: ["en-US", "pt-BR"],
    defaultLanguage: "en-US",
    translations: {
      "en-US": {
        greeting: "Hello!",
        description: "Welcome to my website.",
      },
      "pt-BR": {
        greeting: "Olá!",
        description: "Bem-vindo ao meu site.",
      },
    },
  });

  ml.setLanguageFromBrowser();
</script>

Option 2: HTML Templates

Use native <template> tags to define content variants directly in your HTML.

<template type="language-group">
  <h1 language="en-US">Hello!</h1>
  <h1 language="pt-BR">Olá!</h1>
</template>

<template type="language-group">
  <p language="en-US">Welcome to my website.</p>
  <p language="pt-BR">Bem-vindo ao meu site.</p>
</template>

<script type="module">
  import MultilanguageJS from "multilanguagejs";

  const ml = new MultilanguageJS({
    languages: ["en-US", "pt-BR"],
    defaultLanguage: "en-US",
  });

  ml.setLanguageFromBrowser();
</script>

🤝 Combining Both Modes

You can use templates and string dictionaries together in the same page. Templates are great for complex HTML blocks, while string dictionaries work well for simple text content.

📖 API

new MultilanguageJS(options)

Creates a new instance.

Option	Type	Required	Description
languages	string[]	✅	Array of accepted language codes
defaultLanguage	string	➖	Fallback language (defaults to first in languages)
translations	object	➖	Translation dictionaries keyed by language

Methods

Method	Description
setLanguage(lang)	Set the active language. Falls back to default if the language is not accepted.
setLanguageFromBrowser()	Set the language based on navigator.language.
getActiveLanguage()	Returns the current active language or null.
getAcceptedLanguages()	Returns the array of accepted languages.
getDefaultLanguage()	Returns the default/fallback language.
setTranslations(translations)	Update the translation dictionaries at runtime. Immediately re-applies if a language is active.
getLanguageTemplates()	Returns all <template type="language-group"> elements found in the document.

🔀 Language Switcher Example

<select id="lang-switcher">
  <option value="en-US">English</option>
  <option value="pt-BR">Português</option>
</select>

<script>
  document.getElementById("lang-switcher").addEventListener("change", (e) => {
    ml.setLanguage(e.target.value);
  });
</script>

🔷 TypeScript

Full type definitions are included. Import types directly:

import MultilanguageJS from "multilanguagejs";
import type { MultilanguageJSOptions, Translations } from "multilanguagejs";

🛠️ Development

npm install        # Install dependencies
npm test           # Run tests
npm run test:watch # Run tests in watch mode
npm run build      # Build for production
npm run lint       # Lint source code

📄 License

MIT - Ian Welerson

This site is open source. Improve this page.