Skip to content

Polyglot.js + Locize

Lightweight, framework-agnostic JavaScript i18n with built-in plural handling — paired with Locize for cloud translation management, AI translation, and CDN delivery.

Polyglot.js (developed and open-sourced by Airbnb) is a small, framework-agnostic JavaScript internationalization library. It supports interpolation (%{name} syntax), pluralization via its own pipe-separated forms (1 cat ||| %{smart_count} cats), and per-language plural rules — all without depending on ICU MessageFormat or any specific frontend framework.

Locize natively supports the polyglot.js format at the platform level — translators see Polyglot's plural-form syntax in the editor, plural rules are enforced per language, and you do not need to convert formats. The integration uses the locizer client to load translations from your Locize project and CDN, then pass them to a Polyglot instance.

Key facts
  • Format: polyglot.js (handled by Locize's format-polyglot package — native platform support)
  • Runtime: Very small (~3–4 KB minified) — Polyglot's main appeal
  • Plurals: Pipe-separated forms in a single key value, with Polyglot's own per-language plural rules
  • Framework support: Framework-agnostic — works with React, Vue, Angular, vanilla JavaScript, Node.js
  • Example repo: locize-polyglot-example
  • Best for: Small-to-medium apps that want minimal i18n runtime and do not need ICU MessageFormat

How Polyglot works in your code

Basic interpolation and plural usage. Polyglot's smart_count automatically picks the right plural form based on the active locale.

import Polyglot from 'node-polyglot'

const polyglot = new Polyglot({
  phrases: {
    greeting: 'Hello, %{name}!'
  },
  locale: 'en'
})

polyglot.t('greeting', { name: 'World' })
// => "Hello, World!"
polyglot.extend({
  num_cats: '1 cat |||| %{smart_count} cats'
})

polyglot.t('num_cats', { smart_count: 1 })
// => "1 cat"

polyglot.t('num_cats', { smart_count: 5 })
// => "5 cats"

Connecting Polyglot to Locize

The standard pattern: initialize locizer with your Locize project, load translations from the CDN, then pass them into a new Polyglot instance.

// Load translations from Locize CDN into Polyglot
// <script src="https://unpkg.com/locizer/locizer.min.js"></script>
locizer
  .init({
    fallbackLng: 'en',
    projectId: '[your project id]',
    cdnType: 'standard'
  })
  .load('translation', function (err, translations, lng) {
    const polyglot = new Polyglot({ phrases: translations, locale: lng })
    console.log(polyglot.t('some key'))
  })

Translation updates ship from Locize to your running app via the CDN — no rebuild required for translation changes. This is the same continuous localization model used by i18next + Locize, just plugged into Polyglot's API instead.

Full working example. For more on Polyglot's freedom-vs-features tradeoff against i18next and FormatJS, see The freedom of choice: i18next, polyglot, or FormatJS.

Frequently asked questions

What is Polyglot.js?

Polyglot.js (developed and open-sourced by Airbnb) is a small, framework-agnostic JavaScript internationalization library. It supports interpolation, pluralization (with its own pluralization rules per language), and key-based lookups — without depending on the heavier ICU MessageFormat or any specific frontend framework. Polyglot is a good fit for projects that need lightweight i18n with minimal runtime overhead, especially when ICU MessageFormat is overkill.

Does Locize support Polyglot.js?

Yes. Locize natively supports the polyglot.js format at the platform level — pluralization is handled within the format (single key with pipe-separated forms), and translators see the format-specific syntax in the editor. The integration uses the locizer client: a small JavaScript module that loads translations from your Locize project and CDN, then passes them to a Polyglot instance.

How do I connect Polyglot to Locize?

Include the locizer script (or install the npm package), call `locizer.init({ projectId, cdnType })`, then `locizer.load('namespace', callback)` to fetch translations. Inside the callback, create a `new Polyglot({ phrases: translations, locale: lng })` and use it like any other Polyglot instance. Translation updates ship from Locize to your running app via the CDN — no rebuild required for translation changes. Full working example: github.com/locize/locize-polyglot-example.

How does Polyglot handle plurals with Locize?

Polyglot uses its own pluralization syntax — multiple forms in a single string value, separated by `||||`, e.g. `"1 cat" + "||||" + "%{smart_count} cats"`. Locize's polyglot.js format support handles this natively: translators see the plural forms as separate input fields, but the stored value follows Polyglot's pipe-separated convention so your runtime code does not need to change. The right number of forms per language is enforced based on Polyglot's plural rules.

When should I pick Polyglot over i18next, react-intl, or LinguiJS?

Pick Polyglot when you want the smallest runtime, the simplest API, and do not need ICU MessageFormat. It is a good fit for: small-to-medium apps that do not need React-specific i18n hooks, projects where bundle size matters more than feature richness, and codebases that prefer one minimal library over a framework. Pick i18next when you want the richest feature set + deepest Locize integration. Pick react-intl or LinguiJS when you want ICU MessageFormat and React-specific tooling.