
Research
npm Malware Targets Telegram Bot Developers with Persistent SSH Backdoors
Malicious npm packages posing as Telegram bot libraries install SSH backdoors and exfiltrate data from Linux developer machines.
Stone.js is a client-side gettext-like JavaScript internationalization library that provides many useful functionalities like:
immediate translation (gettext)
differed translation using lazy strings (lazyGettext)
JavaScript and HTML internationalization
replacement support inside translated strings
plural forms support (ngettext/lazyNgettext)
tools to extract/update/build translatable strings (see stonejs-tools)
First download Stone.js zip or clone the repository.
Then include the stonejs.js
or stonejs.min.js
(from the dist
folder) in you HTML page, and create an alias for the Stone.gettext
function:
<script src="dist/stonejs.js"></script>
<script>
window._ = Stone.gettext;
</script>
First install the stonejs
package:
npm install --save stonejs
Then include it where you need it, and create an alias for the Stone.gettext
function:
// using CommonJS modules
var Stone = require("stonejs");
var _ = Stone.gettext;
// using ES6 modules
import Stone, { gettext as _ } from "stonejs";
To internationalize your JavaScript files, you just have to "mark" all translatable strings of your application by passing them to the gettext
function.
Example:
// ---- Replace ----
var text = "Hello World";
// --- by ----
var text = _("Hello World");
// NOTE: you can also write Stone.gettext("Hello World")
// if you do not want to create the "_" alias for the gettext function
To internationalize your HTML files, you just have to add the stonejs
attribute to all translatable tags.
Example:
<!-- replace -->
<div>Hello World</div>
<!-- by -->
<div stonejs>Hello World</div>
NOTE: To allow Stone.js to translate your DOM, you have to enable DOM scan:
Stone.enableDomScan(true);
Once you have internationalized your application, you will have to:
Extract the translatable strings from your js and html files,
Translate the extracted strings,
Build your translation inside string catalogs.
For all those steps, you can use the Stone.js tools available here:
The last step to display your application into plenty of languages is to load the catalogs you built with stonejs-tools and set the current locale.
NOTE: Stone.js Tools can build the catalogs in two formats: js
and json
. Be careful if you use the javascript one. You should include the catalog file after the stonejs lib is loaded (you should include it after in your HTML file if you are using the standalone version of the lib, and if you use the npm/browserify version, you should include the file after the first time you require
the library).
Example:
<script src="dist/stonejs.js"></script>
<script>
var catalogs = {
"fr": {
"plural-forms": "nplurals=2; plural=(n > 1);",
"messages": {
"Hello World": ["Bonjour le monde"],
"Hello {name}": ["Bonjour {name}"]
}
},
"it": {
"plural-forms": "nplurals=2; plural=(n != 1);",
"messages": {
"Hello World": ["Buongiorno il mondo"],
"Hello {name}": ["Buongiorno {name}"]
}
}
};
window._ = Stone.gettext; // Alias the Stone.gettext function
Stone.addCatalogs(catalogs); // Add catalogs (here it is hard coded for the need of the example
Stone.enableDomScan(true); // Allow Stone.js to scan the DOM to find translatable nodes
Stone.setLocale("fr"); // Sets the locale to french
console.log(_("Hello World"));
// Bonjour le monde
console.log(_("Hello World", "it"));
// Buongiorno il mondo
console.log(_("Hello {name}", {name: "John"}));
// Bonjour John
console.log(_("Hello {name}", {name: "John"}, "it"));
// Buongiorno John
var text = Stone.lazyGettext("Hello World");
console.log(text.toString());
// Bonjour le monde
Stone.setLocale("it");
console.log(text.toString());
// Buongiorno il mondo
Stone.setLocale("c");
console.log(text.toString());
// Hello World
Stone.setLocale("foo");
console.log(text.toString());
// Hello World
</script>
Translates the given string to the current language.
String: Stone.gettext( <string> [, locale] );
String: Stone.gettext( <string> [, replacements] [, locale] );
params:
string
: The string to translate.locale
: The locale string to use for translation (optional, default: current locale).replacements
: an object containing replacements for the string (optional, see example below).returns:
The translated string.
Examples:
var text1 = Stone.gettext("Hello World");
var text1 = Stone.gettext("Hello World", "it");
var text2 = Stone.gettext("Hello {name}", {name: "John"});
var text3 = Stone.gettext("Hello {name}", {name: "John"}, "it");
Same as Stone.gettext
but returns a Stone.LazyString
instead of a String
.
String: Stone.lazyGettext( <string> [, locale] );
String: Stone.lazyGettext( <string> [, replacements] [, locale] );
Translates the given strings to the current language with plural support.
String: Stone.ngettext( <string>, <stringPlural>, <number> [, locale] );
String: Stone.ngettext( <string>, <stringPlural>, <number> [, replacements] [, locale] );
params:
string
: The string to translate, in English singular form.stringPlural
: The string to translate, in English plural form.number
: The number that determines plural formslocale
: The locale string to use for translation (optional, default: current locale).replacements
: an object containing replacements for the string (optional, see example below).Note: 'n' is an implicit replacement for given number.
returns:
The translated string, in some plural form.
Examples:
var text1 = Stone.ngettext("one apple", "{nbApples} apples", 3, {nbApples: 3});
var text2 = Stone.ngettext("{n} apple", "{n} apples", 3, {n: 3});
var text3 = Stone.ngettext("{n} apple", "{n} apples", 3); // 'n' is an implicit replacement of given number
Same as Stone.ngettext
but returns a Stone.LazyNString
instead of a String
.
Translates the given string to the current language using a context argument to solve ambiguities (read more).
String: Stone.pgettext( <context>, <string> [, locale] );
String: Stone.pgettext( <context>, <string> [, replacements] [, locale] );
params:
context
: The context of the string.string
: The string to translate.locale
: The locale string to use for translation (optional, default: current locale).replacements
: an object containing replacements for the string (optional).returns:
The translated string.
Examples:
var text1 = Stone.pgettext("going back", "Back");
var text1 = Stone.pgettext("back of an object", "Back", "it");
Same as Stone.pgettext
but returns a Stone.LazyPString
instead of a String
.
Translates the given strings to the current language with plural support and using a context argument to solve ambiguities (read more).
String: Stone.npgettext( <context>, <string>, <stringPlural>, <number> [, locale] );
String: Stone.npgettext( <context>, <string>, <stringPlural>, <number> [, replacements] [, locale] );
params:
context
: The context of the string.string
: The string to translate, in English singular form.stringPlural
: The string to translate, in English plural form.number
: The number that determines plural formslocale
: The locale string to use for translation (optional, default: current locale).replacements
: an object containing replacements for the string (optional, see example below).Note: 'n' is an implicit replacement for given number.
returns:
The translated string, in some plural form.
Examples:
var text1 = Stone.npgettext("fruit", "one apple", "{nbApples} apples", 3, {nbApples: 3});
var text2 = Stone.npgettext("fruit", "{n} apple", "{n} apples", 3, {n: 3});
var text3 = Stone.npgettext("fruit", "{n} apple", "{n} apples", 3); // 'n' is an implicit replacement of given number
Same as Stone.npgettext
but returns a Stone.LazyNPString
instead of a String
.
Adds one (or more if you merged multiple languages into one file) string catalog.
Stone.addCatalogs( <catalogs> );
params:
catalogs
: An object containing translated strings (catalogs can be built using [stronejs-tools][]).Examples:
Stone.addCatalogs(catalogs);
Register a string to be translatable.
Do not operate translation.
Translation can be operated later with Stone.gettext
.
This can be useful in special cases where you want to register a string for translation,
but want to keep a reference of the original string, in order to translate it later.
String: Stone.gettext_noop( <string> );
params:
string
: The string to register for translationreturns:
The exact same given string
Examples:
var translatable1 = Stone.gettext_noop("Some string to translate");
var translatable2 = Stone.gettext_noop("Hello {name}");
var text1 = Stone.gettext(translatable1);
var text2 = Stone.gettext(translatable2, { name: "John" });
Returns the current locale (aka target language for the gettext
and lazyGettext
functions). The default locale is "c" (it means no translation: simply returns the string as it is in the source).
String: Stone.getLocale();
Examples:
var locale = Stone.getLocale();
// "c", "en", "fr", ...
Returns all availables catalogs.
String: Stone.listCatalogs();
Examples:
var catalogsList = Stone.listCatalogs();
// ["c", "en", "fr", ... ]
Defines the current locale (aka the target language for the gettext
and lazyGettext
functions).
NOTE: You can use the setBestMatchingLocale
function to set the best language for the user.
Stone.setLocale( <locale> );
params:
locale
: The locale code (e.g. en
, fr
, ...)Examples:
Stone.setLocale("fr");
Find and set the best language for the user (depending on available catalogs and given language list).
Stone.setBestMatchingLocale( [locales] );
params:
locales
: (optional) string or array of string (e.g. "fr"
, ["fr", "fr_FR", "en_US"]
).Examples:
Stone.setBestMatchingLocale(); // Automaticaly set the best language (from informations given by the browser)
setBestMatchingLocale("fr"); // Finds the catalog that best match "fr" ("fr", "fr_FR", fr_*,...)
setBestMatchingLocale(["fr", "en_US", "en_UK"]); // Finds the best available catalog from the given list
Find and return the given locale that best matches the given catalogs.
Stone.findBestMatchingLocale( [locales], [catalogs] );
params:
locales
: string or array of string (e.g. "fr"
, ["fr", "fr_FR", "en_US"]
).catalogs
: array of string (e.g. ["fr_FR", "en"]
).Example:
Stone.findBestMatchingLocale(["fr"], ["pt_BR", "fr_CA", "fr_FR"]); // -> "fr_FR"
Tries to guess the user language (based on the browser's preferred languages).
String: Stone.guessUserLanguage();
returns:
The user's language.
example:
var locale = Stone.guessUserLanguage();
Allows Stone.js to scan all the DOM to find translatable strings (and to translate them).
Stone.enableDomScan( <enable> );
params:
enable
: Enable the scan of the DOM if true
, disable it otherwise.example:
Stone.enableDomScan(true);
Updates the DOM translation if DOM scan was enabled with Stone.enableDomScan
(re-scan and re-translate all strings).
Stone.updateDomTranslation();
Stone.LazyString
is an object returned by the Stone.lazyGettext
function. It behaves like a standard String
object (same API) but its value changes if you change the locale with Stone.setLocale
function.
This is useful when you have to define translatable strings before the string catalog was loaded, or to automatically re-translate strings each time the locale is changed.
You can find an example of its use in the PhotonUI documentation:
Same as Stone.LazyString
, using Stone.ngettext
for plural support.
Same as Stone.LazyString
, using Stone.pgettext
for context support.
Same as Stone.LazyString
, using Stone.npgettext
for plural and context support.
This event is fired each time the locale changes (using the Stone.setLocale
function).
{
"fr": {
"plural-forms": "nplurals=2; plural=(n > 1);",
"messages": {
"Hello World": {
"*": ["Bonjour le monde"]
},
"Hello {name}": {
"*": ["Bonjour {name}"]
}
}
},
"it": {
"plural-forms": "nplurals=2; plural=(n != 1);",
"messages": {
"Hello World": {
"*": ["Buongiorno il mondo"]
},
"Hello {name}": {
"*": ["Buongiorno {name}"]
}
}
}
}
Want to support this project?
[NEXT] (changes on master
but not released yet):
v2.7.0:
pgettext
, npgettext
,...) (@Krenodeno, #33, #40)v2.6.0:
ngettext()
for the JS API (thanks @jbghoul, #17)gettext_noop()
for the JS API (thanks @jbghoul, #19)v2.5.0:
gettext()
call (thanks @JochLAin, #13)v2.4.0:
listCatalogs
methods to list available catalogs (thanks @BobRazowsky, #12)v2.3.0:
addCatalog
function now merge catalogs.v2.2.0:
findBestMatchingLocale
)v2.1.0:
fr_FR
, fr_CA
,...)setBestMatchingLocale
)v2.0.0:
FAQs
gettext-like client-side Javascript Internationalization Library
The npm package stonejs receives a total of 0 weekly downloads. As such, stonejs popularity was classified as not popular.
We found that stonejs demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Malicious npm packages posing as Telegram bot libraries install SSH backdoors and exfiltrate data from Linux developer machines.
Security News
pip, PDM, pip-audit, and the packaging library are already adding support for Python’s new lock file format.
Product
Socket's Go support is now generally available, bringing automatic scanning and deep code analysis to all users with Go projects.