stele

Stele

What is stele?

Stele is a suite of tools for building international applications in modern single page apps. The name comes from the Rosetta Stone, which was a Stele, meaning a giant stone (or wooden) monument, often with some sort of decree. Really, it was the coolest name we could think of that was not taken on NPM.

The Problems

The ecosystem in javascript for internationalization is quite daunting to first look into. At Patreon we had a few main goals for starting our internationalization journey.

1. We have thousands of untranslated strings.
2. We have dozens of developers working as the same time
3. We have tens of thousands of strings and do not want to bloat our application by sending down strings we do not need

Our goal is not to create a new standard to replace all standards in the JS ecosystem. We wanted to solve the problems we were facing at Patreon and share our solution. If you are facing a different set of problems this may not be the right solution for you or your product.

What we needed in an internationalizable library

1. Transitioning strings should be as easy as possible.
2. Writing translatable strings should be as easy as possible.
3. Use the power of our compiler to alleviate run time checks of strings.
4. Easily enforce conversion of our site with an existing lint rule.

The Components

1. Webpack plugin for compiling individual languages, and extracting a json file
2. Webpack loader for rewriting individual files
3. An abstraction of ICU strings to aid in writing more complex international strings

How it works

This library is heavily inspired by elm-i18n and i18n-webpack-plugin

What we do for simple strings

Given:

__('Hello World!')

Replace with (English):

__(generateInternationalizableString('Hello World'))

As this is static and has no formatters, we can simplify further to:

'Hello World'

Replace with (Spanish):

'Hola Mundo'

Given:

__('Hello, {name}', { name: 'Ben' })

Replace with (English)

__(generateInternationalizableString('Hello, {name}', { name: 'Ben' }))

Replace with (Spanish)

__(generateInternationalizableString('Hola, {name}', { name: 'Ben' }))

Plurals

In the world of JavaScript internationalization plurals are where we have noticed the most division. Often, the most simple of libraries ignore this and leave it up to the user to handle. We wanted to create a simple type-safe interface for generating plural ICU compatible strings. It ends up looking something like this:

import { Translatable, Argument, Count, plural } from 'stele'

@Translatable()
class MyMessages {
    apples(@Argument() name, @Count() appleCount) {
        const appleSuffix = plural(appleCount, {
            one: 'an apple',
            other: count => `${count} apples`,
        })
        return `${name} has ${appleSuffix}`
    }
}

document.findElementById('root').textContent = new MyMessages().apples('Ben', 5)