language-observer

^{LanguageObserver is a lightweight and flexible class designed to simplify internationalization in your web application. It automatically applies translations to elements on your page and supports dynamic content updates. By observing language changes via class modifications, it ensures seamless integration of nested translation structures and attribute-based localization.}

^{1kB gzipped}

Demo

➤ Install

$ yarn add language-observer

➤ Import

import LanguageObserver from 'language-observer';

➤ Usage

const languageObserver = new LanguageObserver();

languageObserver.init({ lang: 'ru' });

_{translations.js}

window.translations = window.translations || {};

window.translations['ru'] = {
  app: {
    title: {
      main: "Приложение",
      settings: "Настройки",
    },
    menu: {
      profile: "Профиль",
    },
  },
  buttons: {
    save: "Сохранить",
  },
};

window.translations['en'] = {
  app: {
    title: {
      main: "Application",
      settings: "Settings",
    },
    menu: {
      profile: "Profile",
    },
  },
  buttons: {
    save: "Save",
  },
};

window.translations['es'] = {
  app: {
    title: {
      main: "Aplicación",
      settings: "Configuraciones",
    },
    menu: {
      profile: "Perfil",
    },
  },
  buttons: {
    save: "Guardar",
  },
};

_Switching

document.querySelector('#change-lang-to-es')?.addEventListener('click', () => {
  languageObserver.loadLanguage('es');
});

_{HTML example}

<p data-i18n="title.welcome"></p>

<img data-i18n-attr='{"alt": "image.altText"}' src="image.jpg" alt="Default Alt Text">

➤ Options

Option	Type	Default	Description
`lang`	`string`	`'ru'`	(Optional) The language code to initialize with. If not provided, the language is detected from the `<body>` element's class.

➤ Methods

Method	Parameters	Returns	Description
`init(options?)`	`options`: `{ lang?: string }`	`void`	Initializes the observer. If a `lang` is provided in options, it loads and applies that language's translations.
`loadLanguage(lang)`	`lang`: `string`	`Promise`	Loads and applies translations for the specified language. If translations are not found, falls back to the default language and logs a warning.
`applyTranslations()`	`none`	`Promise`	Applies the current translations to all elements with `data-i18n` and `data-i18n-attr` attributes on the page. Useful for updating translations after dynamic content changes.
`updateTranslations()`	`none`	`void`	Manually updates translations on the page. Call this method after adding new translations to `window.translations` to apply them without changing the language or reloading the page.
`loadTranslations(lang, loader)`	`lang`: `string` `loader`: `(lang) => Promise`	`Promise`	Asynchronously loads translations for the specified language using the provided `loader` function, then applies them if the language matches the current language.
`getNestedTranslation(obj, path)` (static method)	`obj`: `object` `path`: `string`	`any`	Retrieves a nested translation value from an object using a dot-separated key path. Returns `undefined` if the key does not exist.

➤ Example of using methods

_{Using the loadTranslations method}

async function fetchTranslations(lang) {
  const response = await fetch(`/locales/${lang}.json`);

  return response.json();
}

languageObserver.loadTranslations('fr', fetchTranslations);

_{Using the getNestedTranslation method}

const nestedValue = LanguageObserver.getNestedTranslation(
  window.translations['en'], 
  'app.menu.profile'
);

console.log(nestedValue);

➤ License

language-observer is released under MIT license