i18next-to-fluent

i18next-to-fluent is a solution simplifying the migration from I18next to Fluent.

Common use cases:

• convertion from i18next's full-featured .json resources to .ftl
• getting rid of i18next dependency without rewriting a bunch of code

Warning: the package is unstable right now. Although it can fit your needs, its production usage is discouraged. See Notice and Development roadmap sections for details.

---

• Installation
• Usage
• Project structure
• Motivation behind the project
• Notice
• Development roadmap
• License

Installation

npm install --save i18next-to-fluent

Usage

Simple as heck usage example has not been implemented yet. However, a basic end-to-end test already exists and passes.

Project structure

• converter from .json to .ftl.

It transforms full-featured (nested data structures, plurals, references and more) i18next localization resources to the Fluent compatible ones.

• client-side adapter to provide compatibility layer between your i18next-oriented code and Fluent API. It's the right time to remove i18next related packages from the list of dependencies.

It basically resolves your old paths to the new ones and allows you to use good old t('mainPage.header.title').

This way it saves you from making lots of code changes since paths to messages will be different. It'll most likely happen if you have previously used nested objects and arrays heavily (Fluent does not actually support deeply nested data structures at the moment).

• React bindings to provide resolving adapter to your components.

• instructions about how to set up localization pipeline effectively from scratch: from the workspace for translators to the performant loading of resources at the client side.

Motivation behind the project

In today's world of high customization, massive A/B testing, and quickly changing requirements, it is preferable to speed up release cycle all the time.

When it comes about conversion optimization of text content, it turns out to be crucial to test as many variants as possible setting up experiments really quickly. All are based on multiple user related parameters. All are in different places on the same web pages, in parallel.

Without granting full control over text content to the direct editors (marketing team, localizers), it immediately becomes unmaintainable and slows the company down.

Being a developer, if you've ever created these phrases first, then those ones for some special ocassion and so on switching between all of them in the source code, you and your colleagues definitely know this feeling.

When I personally started figuring out how to optimize localization management in order to untie the hands of marketing team, I decided:

• to move localization resources out of source code repository
• to find a specification supporting parameterized, multivariant phrases
• to find and provide colleagues a UI developed exactly for localization purposes

What I've ended up is the combination of Fluent and Pontoon, both being open source and developed by Mozilla.

Fluent brings a number of notable improvements to the process of localization and, generally speaking, to the way we manage the text content on web applications.

Sharing separation of concerns principle with ICU MessageFormat, Fluent goes further by providing more readable syntax and usability and by giving localizers even more control over formatting.

Read the comparison articles about feature set and syntax between Fluent and ICU MessageFormat.

At the time I started a migration of one of my projects, it turned out that it would not be easy to say the least. One of the issues was the fact that i18next's nested trees of phrases were simply incompatible with Fluent which supported no more than 1 level of object nesting (attributes of messages).

Since it seemed like there was no tool providing complete compatibility layer on the wild, I decided to develop and to publish one by myself.

Notice

The project is under development right now. There's a number of unsolved issues as well as the lack of documentation. API also may change at any time.

Wait a little bit until the full compatibility is provided. I'm personally interested to stabilize the solution as quickly as possible to set up the migration of commercial projects e.g. fish.travel. Stay tuned!

If you'd like to show your support and point the development to specific edge cases or feature requests, consider reacting on issues with comments or just emoji. This way I will see what's the most expected for the community and focus on solving those issues first.

See Development roadmap section for status of what's implemented.

Development roadmap

i18next features

• Interpolation

  • Basic ("Hello, {{name}}!")
  • Member expressions ("I am {{author.name}}")

• Objects and Arrays

  {
    "tree": {
      "res": "added {{something}}"
    },
    "array": ["a", "b", "c"]
  }

  • Resolution of paths to the phrases inside objects ('tree.res')
  • Resolution of paths to non-strings ('tree', 'array')
  • Resolution of arrays ('array.0')

• Plurals

  • Singular / Plural

    • supported for en, es (i.e. locales with "one", "other" CLDR rules), and ru (i.e. locales with "one", "few", "other" CLDR rules) locales at the moment

  • Interval

• Nesting

  {
    "nesting1": "1 $t(nesting2)",
    "nesting2": "2 $t(nesting3)",
    "nesting3": "3",
  }

  i18next.t('nesting1'); // -> "1 2 3"

• Context

• Namespaces

Compatibility with Fluent

• Flatten deeply nested objects
• Transfrom arrays
• Transform "-" in the beginning of message/attribute key
• Transform digits in the beginning of message/attribute key
• Escape Fluent special characters inside message values (e.g. "{")

Adapter between i18next oriented code and Fluent

• Resolvers API
• Caching

React bindings

• Legacy Context Provider
• Official Context API Provider
• Consumer
• Hooks

Converters

• transformer of resources from .json to .ftl
• transformer of imports from react-i18next to the adapter

Packaging

• ES Modules

Instructions

• Runnable demo that's available online (only end-to-end test is available now)
• Converter API (tests are partially available now)
• Adapters API (tests are available now)
• React bindings API
• Tutorial about how to load .ftl resource bundle on the server
• Performance oriented tutorials and examples

License

i18next-to-fluent is MIT licensed.