internationalisation

Project status

Use case

A jQuery plugin to replace alternate version of text for client side internationalisation.

Content

Installation

Classical dom injection

You can simply download the compiled version as zip file here and inject it after needed dependencies:

<script
    src="https://code.jquery.com/jquery-3.6.0.min.js"
    integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4="
    crossorigin="anonymous"
></script>
<script
    src="https://torben.website/clientnode/data/distributionBundle/index.js"
></script>
<!--Inject downloaded file:
<script src="index.js"></script>
-->
<!--Or integrate via cdn:-->
<script
    src="https://torben.website/internationalisation/data/distributionBundle/index.js"
></script>

The compiled bundle supports AMD, commonjs, commonjs2 and variable injection into given context (UMD) as export format: You can use a module bundler if you want.

Package managed and module bundled

If you are using npm as package manager you can simply add this tool to your package.json as dependency:

...
"dependencies": {
    ...
    "internationalisation": "latest",
    ...
},
...

After updating your packages you can simply depend on this script and let a module bundler do the hard stuff or access it via an exported variable name in given context.

...
import Language from 'internationalisation'
class SpecialLanguage extends Language...
Language({options..})
// or
import {$} from 'internationalisation'
$.Language()
class SpecialLanguage extends $.Language.class ...
// or
Language = require('internationalisation').default
value instanceof Language
// or
$ = require('internationalisation').$
$.Language()
...

Usage

To add two versions of a text string you can simply add your translation directly in markup. See how easy it is:

<p>
    Your englisch version.
    <!--deDE:Ihre deutsche Variante.-->
    <!--frFR:
        Sa version française.
    -->
</p>

Sometime you need to explicit mark a text node as text to replace with next translation node. In this case you can simple wrap a self defined dom node.

<lang-replace>
    Your englisch version with <strong>dom nodes</strong> inside.
</lang-replace>
<!--deDE:
    Ihre deutsche Variante mit eingebetteten <strong>dom Knoten</strong>.
-->
<!--frFR:
    Votre version français <strong>dom nodes</strong> à l'intérieur.
-->

It is also possible to use an alternative replacement node.

<lang-replace>
    Your englisch version with <strong>dom nodes</strong> inside.
</lang-replace>
<lang-replacement>deDE:
    Ihre deutsche Variante mit eingebetteten <strong>dom Knoten</strong>.
</lang-replacement>
<lang-replacement>frFR:
    Votre version français <strong>dom nodes</strong> à l'intérieur.
</lang-replacement>

Usually the language dom node precedes the text node to translate. It is possible to write a special syntax to use a replacement for the next dom node containing text.

<!--|deDE:Ihre deutsche Variante.--><!--|frFR:Votre version français.-->
<p>Your englisch version.</p>

Its possible to save one translation once if you specify the area with known translations.

<!--The "div.toc" selector defines the default known language area.-->
<div class="toc">
  <ul>
    <li><a href="title-1">title 1</a></li>
      <ul>
        <li><a href="title-2">title 2</a></li>
      </ul>
  </ul>
</div>
<h1 id="title-1">title 1<!--deDE:Titel 1--><!--frFR:titre 1--></h1>
<h2 id="title-2">title 2<!--deDE:Titel 2--><!--frFR:titre 2--></h2>

With the below initialisation you can simple add this links everywhere in your page to switch language. On click you will switch the current language interactively. Try it by yourself:

<a href="#language-deDE">de</a>
<a href="#language-enUS">en</a>
<a href="#language-frFR">fr</a>

Here you can see a complete initialisation example with all available options to initialize the plugin with different configuration.

<script
    src="https://code.jquery.com/jquery-3.6.0.min.js"
    integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4="
    crossorigin="anonymous"
></script>
<script
    src="https://torben.website/clientnode/data/distributionBundle/index.js"
></script>
<script
    src="https://torben.website/internationalisation/data/distributionBundle/index.js"
></script>

<script>
    $(($) => $.Language({
        domNodeSelectorPrefix: 'body',
        default: 'enUS',
        selection: [],
        initial: null,
        templateDelimiter: {pre: '{{', post: '}}'},
        fadeEffect: true,
        textNodeParent: {
            showAnimation: [{opacity: 1}, {duration: 'fast'}],
            hideAnimation: [{opacity: 0}, {duration: 'fast'}]
        },
        preReplacementLanguagePattern: '^\\|({1})$',
        replacementLanguagePattern: '^([a-z]{2}[A-Z]{2}):((.|\\s)*)$',
        currentLanguagePattern: '^[a-z]{2}[A-Z]{2}$',
        replacementDomNodeName: ['#comment', 'lang-replacement'],
        replaceDomNodeNames: ['#text', 'lang-replace'],
        toolsLockDescription: '{1}Switch',
        languageHashPrefix: 'language-',
        currentLanguageIndicatorClassName: 'current',
        sessionDescription: '{1}',
        languageMapping: {
            deDE: ['de', 'de_de', 'de-de', 'german', 'deutsch'],
            enUS: ['en', 'en_us', 'en-us'],
            enEN: ['en_en', 'en-en', 'english'],
            frFR: ['fr', 'fr_fr', 'fr-fr', 'french']
        },
        onSwitched: $.noop(),
        onEnsured: $.noop(),
        onSwitch: $.noop(),
        onEnsure: $.noop(),
        domNode: {knownTranslation: 'div.toc'}
    }))
</script>