JStrings Localization

A javascript singleton Localization for both Node.js and Web browsers. The localised files are based on JStrings format.

Table of Contents

• Install
• About JStrings
• Usage
  • With Node.js
  • In a browser
• Localization class
  • Fields
  • Methods
• String prototype
• License

Install

$ npm i -D jstrings-localization

Or:

$ npm install --save-dev jstrings-localization

About JStrings

JStrings are an extension of the String Resources format used inside Apple developments. This format is usefull during localisation process, human readable, and easy to shared. The Apple Strings Resources is in text format and contains pairs of key-value that are strings. Comments can be sets inside the text file.

/* A one line comment */
"My first key"="My first value";

/*
 *  A multi-lines comment
 *
 */
"My second key"="My second value";
 

The file format is very simple !

Composed with the filename itself, followed by optinals underscore and ISO code, terminated by the extension.

filename[_iso].extension

// Default file
common.jstrings.txt
// English localised file
common_en.jstrings.txt
// French localised file
common_fr.jstrings.txt
...etc

ISO code's format and extensions are whatever you'd like (See : ISO 639).

The default file is used when no localised file according to a code were found.

The JStrings introduces multi-lines values. It used a specifics values format, surrounded by brackets. The output result will be joined by a newline.

/* A multi-lines values */
"My 1st line..."=["My 1st line","followed by a 2nd line","","Ended by a 4th line"];

It's up to you to define the key you'd like to use. It must be unique along the files you're using. Best practive is to be verbose in your code.

You'd like to add some variables in your string, for example, like this :

    "Welcome %1 ! Rock\'n\'Roll !".localize().replace('%1',user.name);

There's no specific format for the variables. You can use any caracters you'd like at your own risk. By the way, you can combine strings together.

Usage

With Node.js

"use strict";

const Localization    = require("Localization");

const languages       = ["de","en","es","he","fr"];
let   lang            = "en";

Localization.language( languages, lang );

Localization.load("strings/common.jstrings.txt");
Localization.load("strings/myapp.jstrings.txt");

console.log( "Hello world !".localize() );

In a browser

    <script type="text/javascript" src="js/jq/jquery.min.js"></script>
    <script type="text/javascript" src="js/lib/Localization.cls.js"></script>
    <script type="text/javascript">
        var languages       = ["de","en","es","he","fr"];
        var lang            = "en";

        var page            = "welcome.html";

        Localization.language( languages, lang );

        lang = /fr/.test(navigator.language) ? 'fr' : 'en'; //Force 'fr' if ok 
        Localization.localize( lang );

        if( ! Localization.load("strings/common.jstrings.txt") )
            console.log("Localization common FAILED !");
            
        if( ! Localization.load("strings/myapp.jstrings.txt")  )
            console.log("Localization myapp  FAILED !");

        splash( "Hello world !".localize() );
        
        $("#content").load("inc/" + page.localize());
    </script>

Localization class

The implementation of the Localization Class is based on the Singleton. You don't need to instanciate it.

Fields

| Name | Type | Description | |:----------------|:------------:|:------------------------------------------------------| | version | string | The class version. | | preferedLanguage | array| The languages your application can handel. | | defaultLanguage | string| Default language used when unmatched user language. | | currentLanguage | string| The language in use. | | userLanguage | string| The user language preferences or system language |

You must not sets this values. Use the methods insteed. Keep in mind they are read only.

Methods

• language( preferedLang ,defaultLang )

  Global settings of the Localization class. You would call it first.

  • preferedLang

    Type: array

    List of the languages your application handle.

  • defaultLang

    Type : string

    The default language used when user language's can't match any in the list.

• localize( lang )

  Specified the language for the localisation. Updates also all the files previouly loaded to the specified language.

  • lang

    Type : string

    The language used for the comming localisations. When you changed the code at run time, keep in mind to refresh your application.

    Important ! There is no ordered list of the files. Don't think overwriting !

• load( file )

  Load a file in path format, according to the localised settings.

  • file

    Type : string

    The path of the file to load. The format must not contains any iso code.

String prototype

• localize()

  Localise the string value or the variable value. When no corresponding translation is available, the string remains the same.

    "localize me".localize()

License

MIT © guitarneck