mthh/loc-i18next

Smart selectors to be used with i18next (same API as jquery-i18next but with html5 selectors)

loc-i18next

Introduction

A replicate of jquery-i18next module (which is great by the way!), intended for use without jquery.

Comparaison with jquery-i18next

jquery-i18next plugin :

jqueryI18next.init(i18nextInstance, $);
$(".nav").localize();

loc-i18next :

localize = locI18next.init(i18next);
localize(".nav");

Initialize the plugin

With options :

import i18next from 'i18next';
import locI18next from "loc-i18next";

const localize = locI18next.init(i18next, {
  selectorAttr: 'data-i18n', // selector for translating elements
  targetAttr: 'i18n-target',
  optionsAttr: 'i18n-options',
  useOptionsAttr: false,
  parseDefaultValueFromContent: true
  document: window.document,
});

Using default values :

import i18next from 'i18next';
import locI18next from "loc-i18next";

const localize = locI18next.init(i18next);

Using options in translation function

<a id="btn1" href="#" data-i18n="myKey"></a>
localize("#btn1", options);

or

<a id="btn1" href="#" data-i18n="myKey" i18n-options="{ 'a': 'b' }"></a>
localize("#btn1");

Usage of selector function

translate an element

<a id="btn1" href="#" data-i18n="myKey"></a>
localize("#btn1", options);

myKey: same key as used in i18next (optionally with namespaces) options: same options as supported in i18next.t

translate children of an element

<ul class="nav">
  <li><a href="#" data-i18n="nav.home"></a></li>
  <li><a href="#" data-i18n="nav.page1"></a></li>
  <li><a href="#" data-i18n="nav.page2"></a></li>
</ul>
localize(".nav");

translate some inner element

<div class="outer" data-i18n="ns:key" data-i18n-target=".inner">
  <input class="inner" type="text"></input>
</div>
localize(".outer");

set different attribute

<a id="btn1" href="#" data-i18n="[title]key.for.title"></a>
localize("#btn1");

set multiple attributes

<a id="btn1" href="#" data-i18n="[title]key.for.title;myNamespace:key.for.text"></a>
localize("#btn1");

set innerHtml attributes

<a id="btn1" href="#" data-i18n="[html]key.for.title"></a>
localize("#btn1");

prepend content

<a id="btn1" href="#" data-i18n="[prepend]key.for.title">insert before me, please!</a>
localize("#btn1");

append content

<a id="btn1" href="#" data-i18n="[append]key.for.title">append after me, please!</a>
localize("#btn1");

set as an attribute

<a id="btn1" href="#" data-i18n="[data-someNameAttribute]key.for.content"></a>
localize("#btn1");

use a custom document object

<template id="template">
  <a id="btn1" href="#" data-i18n="myKey"></a>
</template>
const shadowRoot = document.body.attachShadow();
const template = document.getElementById("template");
shadowRoot.appendChild(template.content.cloneNode(true));
localize("#btn1", {document: shadowRoot});

Motivation

• Having an occasion to try some packages like rollup, babel or uglify.
• Obtaining the same kind of functionnalities than with jquery-i18next in a project not using jquery.

Project actively using loc-i18next

• Magrit : http://magrit.cnrs.fr/

Blog posts about using loc-i18next

• https://code.tutsplus.com/tutorials/translating-stimulus-apps-with-i18next--cms-30770
• https://phraseapp.com/blog/posts/localizing-stimulusjs-i18next/

loc-i18next's Issues

Does this support Internet Explorer?

I think it does b/c it looks to me like you are using preset-env w/o any target (i.e. no .browserlistrc, no target specified in .babelrc), which looks like it defaults to ES5.

Is the intent of this project to support Internet Explorer?

We have this requirement b/c we are thinking about using it for the page we will show to IE users when they try to visit our app (which does not support IE).

Issue with prepend

Hello,

First of all, awesome that you made this library :)! It works very well.
However, I found a little bug that was present a couple months ago in another library as well.
i18next/jquery-i18next#19
Is there a possible fix for this issue?

Pass a custom document object to the options of handle

Passing a custom document object can be useful. My use case is shadow DOMs: the contents of the shadow DOMs are not available to document.querySelectorAll, but are available to shadowRoot.querySelectorAll.

Although not documented, this plugin accepts a document option in init, which defaults to document (i.e. window.document). This was added by commit 6d6569d.
However, this change does not support passing a custom document to the handle function. This would allow using a different document object within the same project.

I am preparing a pull request to solve this.

Disable interpolation

I want to disable interpolation for an element, but the interpolated string is displayed. My code:
localize("#myElement", {interpolation: {escapeValue: false}});

Tagged Version

We're using your code in an Firefox Extension and their guidelines ask to link to specific tagged version of third party libraries, if you could add a tag for the latest version we'd appreciate it very much, thank you.

Example

Why even ur example is not working??? Documentation is for old version or what??

i18next.t is not a function

Hi,

I am trying to use i18next and loc-i18next to translate a very simple web page that I am working on.

I configured i18next and loc-i18next in the following manner:

import i18next from 'i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import locI18next from "loc-i18next";

import en from '../locales/en.json';

const i18n = i18next.use(LanguageDetector).init({
  debug: false,
  fallbackLng: 'en',
  ns: ['dg'],
  defaultNS: 'dg',
  namespaceSeparator: '.',
  resources: {
    'en' : {
      dg: en
    },
  },
});

const localize = locI18next.init(i18n, {
  selectorAttr: "data-i18n",
  optionsAttr: "i18n-options",
  useOptionsAttr: true
});

export { localize };

In my main index.js file, I tried to use it in the following form:

document.addEventListener("DOMContentLoaded", () => {
  // Localize
  localize('#title');;
});

The relevant HTML is

<div>
      <p id="title" data-i18n="app.welcome.title"></p>
      <p id="subtitle">You will receive a one-time SMS to download the app</p>
</div>

However, I get the following error

TypeError: i18next.t is not a function

If I try to use the translate function directly, it works

document.addEventListener("DOMContentLoaded", () => {
  // Localize
  i18n.then(translate => {
    console.log(translate('app.welcome.title'));
  });
});

Package Versions

"i18next": "15.0.6",
"i18next-browser-languagedetector": "3.0.1",
"loc-i18next": "0.1.4"

Could someone please tell me what I am doing wrong?

Not usable with npm

Hi, actually this plugin can not be used correctly with require('loc-i18next').

The dist folder doesn't exists.

What if I need the translation on the whole page?

Hi there,

I have to switch languages on whole page. How do I do it?
What I saw from the document indicates that I have to use a selector to locate where the attribute is,
so if I want to have the translation on the whole page, does it mean that I need to do it like this:

localize("body");

Please help.

Thanks

Won't work with node

Hello.
When I add loc-i18next.min.js to document, it works. But if I try to use loc-i18next with require() method, it doesn't work.
Here is my code:

"use strict";
const i18next = require("i18next");
const locI18next = require("loc-i18next");

 i18next.init({
lng: 'en',
resources: { 
  en: {
    translation: {
      nav: {
        home: 'Home'
      }
    }
  }
}
}, function(err, t) {

const localize = locI18next.init(i18next);

localize('#hi');
});