@divine/localization
v1.0.0
Published
The Divine Localization Library
Downloads
19
Readme
The Divine Localization Library
The Doctrine
Localization and translations should be code, not data.
The Motivation
As developers, we want our languages to be expressive, elegant and concise, so that we may express complex thoughts effortlessly and clearly to both the machine and readers of our code. We want first-class editor support for syntax highlighting, code completions and validation.
Yet, when it comes to building something as complex as natural language sentences, we are supposed to make do with just plain strings, a switch/case construct and some fixed plural function like it's still the 80's. No typed arguments, no syntax validation or highlighting, no lookup-tables, custom functions or dictionaries, no tooling for finding out where a particular translation is used by the program, or if it's even used at all.
Additionally, in web applications in particular, you may sometimes want to translate rich-text/markup and not just plain text. No can do. So now the application has to know if a particular sentence should be HTML-encoded or not, with no way to enforce that all translations match — and prepare to get p0wned if you forget to encode a parameter.
The Conviction
This TypeScript library is really more dogma than code. In fact, it currently only exposes a single function! However:
- Your translations are easily available for consumption as a single property, either as a constant or a function.
- Translation keys can be plain strings, JSX/TSX markup (React/Stencil/etc) or any other custom type or object you wish.
- Your IDE will provide code completion and will show what arguments are required and syntax highlight the actual translations.
- TypeScript will validate that all translations conform to the base language specification for every key, both regarding input parameters and the return type.
- You can define and use any kind of utility functions or lookup tables/dictionaries in your translations, including the standard Intl namespace for formatting dates, numbers and lists.
- It's also possible to look up other translated keys from within a translation.
export const EN = {
intro: {
title: 'Introduction',
descr: () => `The "${C.title}" chapter`,
about: (who: Person) => `About ${who.name}`,
loves: (who: Person, what: Item, count: number) =>
<>The gentle {who.name} <i>loves</i> {EN_PRONOUNS[who.gender]} little {EN_PLURAL(what, count)}.</>
},
}
export const C = translated.current(EN);
...
export const ES: Translation<typeof EN> = {
intro: {
title: `Introducción`,
loves: ({ name, gender }, what, count) =>
<>
{gender !== 'f' ? 'El buen' : 'La buena'} {name} <i>ama</i> {count === 1 ? 'su' : 'sus'} {
ES_ADJ(ES_ITEMS[what].g, count, 'pequeño', 'pequeña', 'pequeños', 'pequeñas')} {
ES_ITEMS[what][count === 1 ? 's' : 'p']}
</>
}
}
...
const { intro } = translated(EN, ES) as typeof EN;
const html = <body>
<h1>{ intro.title }</h1>
<h2>{ intro.descr() }</h2>
<h3>{ intro.about(params.who) }</h3>
<p>{ intro.loves(params.who, params.what, params.count) }</p>
</body>Check out the fully interactive Playground example to better understand how it works. Make some mistakes and see what happens!
Prior Art
These ideas are not new. I found the 20 year old Maketext article, shared by m0llusk on Hacker News, particularly intriguing. A must read!