Polyglot.js
[![Build Status][travis-image]][travis-url]
Polyglot.js is a tiny I18n helper library written in JavaScript, made to work both in the browser and in CommonJS environments (Node). It provides a simple solution for interpolation and pluralization, based off of Airbnb’s experience adding I18n functionality to its Backbone.js and Node apps.
I18n is incredibly important for us at Airbnb, as we have listings in 192 countries, and we translate our site into 30-odd different languages.
We’re also hiring talented engineers to help us scale up to meet the challenges of buliding a global marketplace.
View the documentation on Github.
View the annotated source.
Polylglot is agnostic to your translation backend. It doesn’t perform any translation; it simply gives you a way to manage translated phrases from your client- or server-side JavaScript application.
Installation
install with npm:
$ npm install node-polyglot
Running the tests
Clone the repo, run npm install, and npm test.
Usage
Instantiation
First, create an instance of the Polyglot class, which you will use for translation.
var polyglot = new Polyglot();
Polyglot is class-based so you can maintain different sets of phrases at the same time, possibly in different locales. This is very useful for example when serving requests with Express, because each request may have a different locale, and you don’t want concurrent requests to clobber each other’s phrases.
See Options Overview for information about the options object you can choose to pass to new Polyglot.
Translation
Tell Polyglot what to say by simply giving it a phrases object,
where the key is the canonical name of the phrase and the value is
the already-translated string.
polyglot.extend({
"hello": "Hello"
});
polyglot.t("hello");
=> "Hello"
You can also pass a mapping at instantiation, using the key phrases:
var polyglot = new Polyglot({phrases: {"hello": "Hello"}});
Polyglot doesn’t do the translation for you. It’s up to you to give it
the proper phrases for the user’s locale.
A common pattern is to gather a hash of phrases in your backend, and output
them in a <script> tag at the bottom of the document. For example, in Rails:
app/controllers/home_controller.rb
def index
@phrases = {
"home.login" => I18n.t("home.login"),
"home.signup" => I18n.t("home.signup"),
...
}
end
app/views/home/index.html.erb
<script>
var polyglot = new Polyglot({phrases: <%= raw @phrases.to_json %>});
</script>
And now you can utilize i.e. polyglot.t("home.login") in your JavaScript application
or Handlebars templates.
Interpolation
Polyglot.t() also provides interpolation. Pass an object with key-value pairs of
interpolation arguments as the second parameter.
polyglot.extend({
"hello_name": "Hola, %{name}."
});
polyglot.t("hello_name", {name: "DeNiro"});
=> "Hola, DeNiro."
Polyglot also supports nested phrase objects.
polyglot.extend({
"nav": {
"hello": "Hello",
"hello_name": "Hello, %{name}",
"sidebar": {
"welcome": "Welcome"
}
}
});
polyglot.t("nav.sidebar.welcome");
=> "Welcome"
The substitution variable syntax is customizable.
var polyglot = new Polyglot({
phrases: {
"hello_name": "Hola {{name}}"
},
interpolation: {prefix: '{{', suffix: '}}'}
});
polyglot.t("hello_name", {name: "DeNiro"});
=> "Hola, DeNiro."
Pluralization
For pluralization to work properly, you need to tell Polyglot what the current locale is. You can use polyglot.locale("fr") to set the locale to, for example, French. This method is also a getter:
polyglot.locale()
=> "fr"
You can also pass this in during instantiation.
var polyglot = new Polyglot({locale: "fr"});
Currently, the only thing that Polyglot uses this locale setting for is pluralization.
Polyglot provides a very basic pattern for providing pluralization based on a single string that contains all plural forms for a given phrase. Because various languages have different nominal forms for zero, one, and multiple, and because the noun can be before or after the count, we have to be overly explicit about the possible phrases.
To get a pluralized phrase, still use polyglot.t() but use a specially-formatted phrase string that separates the plural forms by the delimiter `