@instructure/i18nliner

v3.1.1

Published

4 days ago

i18n made simple

Downloads

5,348

I18nliner.js

I18nliner is I18n made simple.

No .js/yml translation files. Easy inline defaults. Optional keys. Easy pluralization. Wrappers for HTML-free translations.

I18nliner extends i18n-js, so you can add it to an already-internationalized app that uses it.

TL;DR

I18nliner lets you do stuff like this:

I18n.t("Ohai %{user}, my default translation is right here in the code. \
  Inferred keys, oh my!", {user: user.name});

and this:

I18n.t("*Translators* won't see any markup!",
  {wrappers: ['<a href="/translators">$1</em>']});

Best of all, you don't need to maintain translation files anymore; I18nliner will do it for you.

Installation

To install the command-line tools (for extracting/managing translations), use npm (see below).

Depending on how you manage JavaScript dependencies in your app, you have several options for installing/including the runtime extensions:

npm

npm install i18nliner --save

You'll need to shoehorn i18n.js into your app, which (as of this writing) is not CJS-compatible :-/, e.g.

// assuming you shoehorn this in
var I18n = require("./path/to/cjs'd/i18n");
// add the runtime extensions
require("i18nliner/dist/lib/extensions/i18n_js").default(I18n);

Features

No more .js/.yml translation files

Instead of maintaining .js/.yml files and doing stuff like this:

I18n.t('account_page_title');

Forget the translation file and just do:

I18n.t('account_page_title', "My Account");

Regular I18n options follow the (optional) default translation, so you can do the usual stuff (placeholders, etc.).

Okay, but don't the translators need them?

Sure, but you don't need to write them. Just run:

i18nliner export

This extracts all default translations from your codebase and outputs them to config/locales/generated/en.json

It's okay to lose your keys

Why waste time coming up with keys that are less descriptive than the default translation? I18nliner makes keys optional, so you can just do this:

I18n.t("My Account")

I18nliner will create a unique key based on the translation (e.g. 'my_account'), so you don't have to. See I18nliner.inferred_key_format for more information.

This can actually be a good thing, because when the en changes, the key changes, which means you know you need to get it retranslated (instead of letting a now-inaccurate translation hang out indefinitely). Whether you want to show "[ missing translation ]" or the en value in the meantime is up to you.

Wrappers

Suppose you have something like this in your JavaScript:

var string = 'You can <a href="/new">lead</a> a new discussion or \
  <a href="/search">join</a> an existing one.';

You might say "No, I'd use handlebars". Bear with me here, we're trying to make this easy for you and the translators :). For I18n, you might try something like this:

var string = I18n.t('You can %{lead} a new discussion or %{join} an \
  existing one.', {
    lead: '<a href="/new">' + I18n.t('lead') + '</a>',
    join: '<a href="/search"> + 'I18n.t('join') + '</a>')
  });

This is not great, because:

There are three strings to translate.
When translating the verbs, the translator has no context for where it's being used... Is "lead" a verb or a noun?
Translators have their hands somewhat tied as far as what is inside the links and what is not.

So you might try this instead:

var string = I18n.t('You can <a href="%{leadUrl}">lead</a> a new \
  discussion or <a href="%{joinUrl}">join</a> an existing one.', {
    leadUrl: "/new",
    joinUrl: "/search"
  });

This isn't much better, because now you have HTML in your translations. If you want to add a class to the link, you have to go update all the translations. A translator could accidentally break your page (or worse, cross-site script it).

So what do you do?

I18nliner lets you specify wrappers, so you can keep HTML out the translations, while still just having a single string needing translation:

var string = I18n.t('You can *lead* a new discussion or **join** an \
  existing one.', {
    wrappers: [
      '<a href="/new">$1</a>',
      '<a href="/search>$1</a>'
    ]
  });

Default delimiters are increasing numbers of asterisks, but you can specify any string as a delimiter by using a object rather than an array.

HTML Safety

I18nliner ensures translations, interpolated values, and wrappers all play nicely (and safely) when it comes to HTML escaping. Wrappers are assumed to be HTML-safe, so everything else that is unsafe will get automatically escaped. If you are using i18n.js, you can hint that an interpolation value is already HTML-safe via %h{...}, e.g.

I18n.t("If you type %{input} you get %h{raw_input}", {input: "<input>", raw_input: "<input>"});
=> "If you type &lt;input&gt; you get <input>"

If any interpolated value or wrapper is HTML-safe, everything else will be HTML- escaped.

Inline Pluralization Support

Pluralization can be tricky, but i18n.js gives you some flexibility. I18nliner brings this inline with a default translation object, e.g.

I18n.t({one: "There is one light!", other: "There are %{count} lights!"},
  {count: picard.visibleLights.length});

Note that the count interpolation value needs to be explicitly set when doing pluralization.

If you just want to pluralize a single word, there's a shortcut:

I18n.t("person", {count: users.length});

This is equivalent to:

I18n.t({one: "1 person", other: "%{count} people"},
  {count: users.length});

Configuration

.i18nignore

I18nliner supports a .gitignore-style file, so you can exclude certain files and directories from processing. Just create a .i18nignore file, and add patterns as necessary.

.i18nrc

If you have an .i18nrc containing valid JSON, I18nliner will use it to override default settings. This can be useful for overriding anything in the default config or for activating plugins. For example:

{
  "directories": ["app"],
  "plugins": [
    "react-i18nliner",
    "i18nliner-handlebars",
  ]
}

Command Line Utility

i18nliner check

Ensures that there are no problems with your translate calls (e.g. missing interpolation values, reusing a key for a different translation, etc.). Go add this to your Jenkins/Travis tasks.

i18nliner export

Does an i18nliner check, and then extracts all default translations from your codebase, merges them with any other translation files, and outputs them to locales/generated/translations.json (or .js).

i18nliner diff

Does an i18nliner export and creates a diff from a previous one (path or git commit hash). This is useful if you only want to see what has changed since a previous release of your app.

i18nliner import

Imports a translated .json/.js file. Ensures that all placeholders and wrappers are present.

.i18nignore and more

By default, the check and export tasks will look for inline translations in any .js files. You can tell it to always skip certain files/directories/patterns by creating a .i18nignore file. The syntax is the same as .gitignore, though it supports a few extra things.

If you only want to check a particular file/directory/pattern, you can set the --only option when you run the command, e.g.

i18nliner check --only=/app/**/user*

Compatibility

I18nliner is backwards compatible with i18n.js, so you can add it to an established (and already internationalized) app. Your existing translation calls, keys and translation files will still just work without modification.