EOTranslator.js

What is this?

EOTranslator.js is a lightweight, zero-dependency JavaScript library that makes it easy to translate web page content. Define a dictionary, create a translator instance, and call a single method to translate a string or an entire DOM tree.

---

Installation

npm / pnpm / yarn

npm install eo-translatorjs
# or
pnpm add eo-translatorjs
# or
yarn add eo-translatorjs

Browser (script tag)

<script src="eo-translatorjs.min.js"></script>

---

Quick start

// CommonJS (Node.js)
const EOTranslator = require("eo-translatorjs");

// ES module bundler
import EOTranslator from "eo-translatorjs";

const dict = {
  en: { greeting: "Hello" },
  fr: { greeting: "Bonjour" },
  es: { greeting: "Hola" },
};

const translator = new EOTranslator(dict, "en");

translator.translate("greeting");           // → "Hello"
translator.translate("greeting", { lang: "fr" }); // → "Bonjour"

---

Constructor

new EOTranslator(dictionary, language?)

Parameter	Type	Required	Description
dictionary	object	✅	Plain object with language keys at the top level
language	string	✗	Default language. Falls back to the document lang attribute, then "en"

const translator = new EOTranslator(dict);          // language defaults to "en"
const translator = new EOTranslator(dict, "fr");    // explicitly set to French

Throws:

• Error — when the dictionary is not a plain object
• TypeError — when the language argument is not a string
• Error — when the language key does not exist in the dictionary

---

Properties

dictionary

Get or replace the entire translation dictionary at runtime.

translator.dictionary = {
  en: { home: "House" },
  fr: { home: "Maison" },
};

Throws if the assigned value is not a plain object.

language

Get or set the active language at runtime.

translator.language = "fr";
console.log(translator.language); // "fr"

Throws if the value is not a string or does not exist in the dictionary.

languages (read-only)

Returns an array of all language keys currently present in the dictionary.

const dict = { en: {}, fr: {}, es: {} };
const translator = new EOTranslator(dict, "en");

console.log(translator.languages); // ["en", "fr", "es"]

---

Methods

translate(key, options?)

Translates a key in the active (or specified) language.

Parameter	Type	Description
key	string	Translation key. Supports dot notation for nested keys
options.lang	string	Override the active language for this call only
options.fallback	string	Value to return when the key is not found. Defaults to the key itself
options.params	object	Interpolation parameters replacing {placeholder} tokens

const dict = {
  en: {
    greeting: "Hello, {name}!",
    ui: {
      title: "Welcome",
    },
  },
  fr: {
    greeting: "Bonjour, {name}!",
  },
};

const translator = new EOTranslator(dict, "en");

// Basic translation
translator.translate("ui.title");                             // → "Welcome"

// With parameters
translator.translate("greeting", { params: { name: "Luffy" } }); // → "Hello, Luffy!"

// With a language override (does not change the default)
translator.translate("greeting", { lang: "fr", params: { name: "Luffy" } }); // → "Bonjour, Luffy!"

// Missing key — returns the key itself by default
translator.translate("missing.key");                         // → "missing.key"

// Missing key — custom fallback
translator.translate("missing.key", { fallback: "N/A" });   // → "N/A"

---

translateElement(element, lang?)

Translates the content of a single DOM element. The element must carry the eo-translator attribute.

Supported attributes:

Attribute	Required	Description
eo-translator	✅	The translation key
eo-translator-fallback	✗	Fallback text when the key is not found
eo-translator-params	✗	JSON object of interpolation parameters
eo-translator-html	✗	Set to "true" to write innerHTML instead of textContent

<span
  id="hello"
  eo-translator="greeting"
  eo-translator-params='{ "name": "Luffy" }'
></span>

const dict = { en: { greeting: "Hello, {name}!" } };
const translator = new EOTranslator(dict, "en");

translator.translateElement(document.getElementById("hello"));
// <span ...>Hello, Luffy!</span>

HTML rendering:

<span
  id="hello"
  eo-translator="greeting"
  eo-translator-html="true"
></span>

const dict = { en: { greeting: "Hello, <b>World</b>!" } };
const translator = new EOTranslator(dict, "en");

translator.translateElement(document.getElementById("hello"));
// <span ...>Hello, <b>World</b>!</span>

Passing null or an element without the eo-translator attribute is a safe no-op.

---

translateDOM(container?, lang?)

Translates all [eo-translator] elements within a container in one call.

When called without arguments it scans the entire document (browser only).

// Translate everything in the document using the active language
translator.translateDOM();

// Translate everything inside a specific container
translator.translateDOM(document.getElementById("app"));

// Translate a container using a language override
translator.translateDOM(document.getElementById("app"), "fr");

---

add(lang, key, translation)

Adds a new translation entry or updates an existing one. Supports dot notation for nested keys. Creates the language group automatically if it does not yet exist.

const dict = {
  en: { tr1: "Translation 1" },
  fr: { tr1: "Traduction 1" },
};
const translator = new EOTranslator(dict, "en");

// Add a new key
translator.add("en", "tr2", "Translation 2");

// Update an existing key
translator.add("en", "tr1", "Updated translation 1");

// Add a nested key — creates intermediate objects automatically
translator.add("fr", "menu.home", "Accueil");
translator.add("fr", "menu.about", "À propos");

---

remove(lang, key)

Removes a translation entry from the dictionary. Supports dot notation. Does nothing if the language or key does not exist.

// Remove a top-level key
translator.remove("fr", "tr1");

// Remove a nested key
translator.remove("fr", "menu.about");

---

isValidLanguage(lang)

Returns true when the given string is a top-level key in the dictionary.

const dict = { en: {}, fr: {} };
const translator = new EOTranslator(dict, "en");

translator.isValidLanguage("fr");  // → true
translator.isValidLanguage("ar");  // → false

---

Nested keys

Dot-separated keys let you organise translations into namespaces without any extra configuration.

const dict = {
  en: {
    nav: {
      home: "Home",
      about: "About us",
    },
    footer: {
      copyright: "© 2024 Example Inc.",
    },
  },
};

const translator = new EOTranslator(dict, "en");

translator.translate("nav.home");         // → "Home"
translator.translate("nav.about");        // → "About us"
translator.translate("footer.copyright"); // → "© 2024 Example Inc."
translator.translate("nav.missing");      // → "nav.missing" (fallback to key)

---

Parameter interpolation

Use {placeholder} tokens inside translations and supply values via options.params (or the eo-translator-params attribute in HTML).

const dict = {
  en: {
    greeting: "Hello, {first} {last}!",
    score: "You scored {points} points.",
  },
};

const translator = new EOTranslator(dict, "en");

translator.translate("greeting", { params: { first: "Monkey", last: "D. Luffy" } });
// → "Hello, Monkey D. Luffy!"

translator.translate("score", { params: { points: 42 } });
// → "You scored 42 points."

---

Credits

Icon made by Freepik from Flaticon and is licensed by Creative Commons BY 3.0.