Nano Stores I18n

Tiny and flexible JS library to make your web application translatable. Uses Nano Stores state manager and JS Internationalization API.

Small. Around 1 KB (minified and gzipped). Zero dependencies.
Works with React, Preact, Vue, Svelte, and plain JS.
Supports tree-shaking and translation on-demand download.
Plain flat JSON translations compatible with online translation services like Weblate.
Out of the box TypeScript support for translations.
Flexible variable translations. You can change translation, for instance, depends on screen size.

// components/post.jsx
import { params, count } from '@nanostores/i18n' // You can use own functions
import { useStore } from '@nanostores/react'
import { i18n, format } from '../stores/i18n.js'

export const messages = i18n('post', {
  title: 'Post details',
  published: params('Was published at {at}'), // TypeScript will get `at` type
  comments: count({
    one: '{count} comment',
    many: '{count} comments'
  })
})

export const Post = ({ author, comments, publishedAt }) => {
  const t = useStore(messages)
  const { time } = useStore(format)
  return <article>
    <h1>{t.title}</h1>
    <p>{t.published({ at: time(publishedAt) })}</p>
    <p>{t.comments(comments.length)}</p>
  </article>
}

// stores/i18n.js
import { createI18n, localeFrom, browser, formatter } from '@nanostores/i18n'
import { persistentAtom } from '@nanostores/persistent'

export const setting = persistentAtom<string | undefined>('locale', undefined)

export const locale = localeFrom(
  setting,  // User’s locale from localStorage
  browser({ // or browser’s locale auto-detect
    available: ['en', 'fr', 'ru'],
    fallback: 'en'
  })
)

export const format = formatter(locale)

export const i18n = createI18n(locale, {
  get (code) {
    return fetchJSON(`/translations/${code}.json`)
  }
})

// public/translations/ru.json
{
  "post": {
    "title": "Данные о публикации",
    "published": "Опубликован {at}",
    "comments": {
      "one": "{count} комментарий",
      "few": "{count} комментария",
      "many": "{count} комментариев",
    }
  },
  // Translations for all other components
}

Install

npm install nanostores @nanostores/i18n

Usage

We store locale, time/number formatting functions and translations in Nano Stores’ atoms. See Nano Stores docs to learn how to use atoms in your framework.

Locale

Locale is a code of user’s language and dialect like hi (Hindi), de-AT (German as used in Austria). We use Intl locale format.

Current locale should be stored in store. We have localeFrom() store builder to find user’s locale in first available source:

import { localeFrom } from '@nanostores/i18n'

export const locale = localeFrom(store1, store2, store3)

We have store with a locale from browser settings. You need to pass list of available translations of your application. If store will not find common locale, it will use fallback locale (en, but can be changed by fallback option).

import { localeFrom, browser } from '@nanostores/i18n'

export const locale = localeFrom(
  …,
  browser({ available: ['en', 'fr', 'ru'] })
)

Before browser store, you can put a store, which will allow user to override locale manually. For instance, you can keep an locale’s override in localStorage.

import { persistentAtom } from '@nanostores/persistent'

export const localeSettings = persistentAtom<string>('locale')

export const locale = localeFrom(
  localeSettings,
  browser({ available: ['en', 'fr', 'ru'] })
)

Or you can take user’s locale from URL router:

import { computed } from 'nanostores'
import { router } from './router.js'

const urlLocale = computed(router, page => page?.params.locale)

export const locale = localeFrom(
  urlLocale,
  browser({ available: ['en', 'fr', 'ru'] })
)

You can use locale as any Nano Store:

import { useStore } from '@nanostores/react'
import { locale } from '../stores/i18n.js'

// Pure JS example
locale.listen(code => {
  console.log(`Locale was changed to ${code}`)
})

// React example
export const CurrentLocale = () => {
  let code = useStore(locale)
  return `Your current locale: ${code}`
}

For tests you can use simple atom:

import { atom } from 'nanostores'

const locale = atom('en')
locale.set('fr')

Date & Number Format

formatter() creates a store with a functions to format number and time.

import { formatter } from '@nanostores/i18n'

export const format = formatter(locale)

This store will have time() and number() functions.

import { useStore } from '@nanostores/react'
import { format } from '../stores/i18n.js'

export const Date = (date) => {
  let { time } = useStore(format)
  return time(date)
}

These functions accepts options of Intl.DateTimeFormat and Intl.NumberFormat.

time(date, {
  hour12: false,
  month: 'long',
  day: 'numeric',
  hour: 'numeric',
  minute: 'numeric'
}) //=> "November 1, 01:56:33"

I18n Object

I18n objects is used to define new component and download translations on locale changes.

import { createI18n } from '@nanostores/i18n'

export const i18n = createI18n(locale, {
  async get (code) {
    return await fetchJSON(`/translations/${code}.json`)
  }
})

In every component you will have base translation with functions and types. This translation will not be download from the server. By default, you should use English. You can change base locale in components with baseLocale option.

Translations

We have 2 types of translations:

Base translation. Developers write it in component sources. It is used for TypeScript types and translation functions (count(), params(), etc).

export const messages = i18n('post', {
  title: 'Post details',
  published: params('Was published at {at}'),
  comments: count({
    one: '{count} comment',
    many: '{count} comments'
  })
})

Other translations They use JSON format and will be created by translators.

{
  "post": {
    "title": "Данные о публикации",
    "published": "Опубликован {at}",
    "comments": {
      "one": "{count} комментарий",
      "few": "{count} комментария",
      "many": "{count} комментариев"
    }
  }
}

Translations should be a flat structure (key → translation), without a nested keys. pluralization (count()) and other helpers doesn’t introduce additional nesting, since they are count as an translation.

Parameters

params() translation transform replaces parameters in translation string.

import { useStore } from '@nanostores/react'
import { params } from '@nanostores/i18n'
import { i18n } from '../stores/i18n.js'

export const messages = i18n('hi', {
  hello: params('Hello, {name}')
})

export const Robots = ({ name }) => {
  const t = useStore(messages)
  return t.hello({ name })
}

You can use time() and number() formatting functions.

And you can also use the count() function:

import { count, params } from '@nanostores/i18n'
import { i18n } from '../stores/i18n'

export const messages = i18n('pagination', {
  page: params<{ category: string }>(
    count({
      one: 'One page in {category}',
      many: '{count} pages in {category}'
    })
  )
})

export const RobotsListInfo = ({ count }) => {
  const t = useStore(messages)
  return t.page({ category: 'robots' })(count)
}

Pluralization

In many languages, text could be different depends on items count. Compare 1 robot/2 robots in English with 1 робот/2 робота/3 робота/21 робот in Russian.

We hide this complexity with count() translation transform:

import { useStore } from '@nanostores/react'
import { count } from '@nanostores/i18n'
import { i18n } from '../stores/i18n.js'

export const messages = i18n('robots', {
  howMany: count({
    one: '{count} robot',
    many: '{count} robots'
  })
})

export const Robots = ({ robots }) => {
  const t = useStore(messages)
  return t.howMany(robots.length)
}

{
  "robots": {
    "howMany": {
      "one": "{count} робот",
      "few": "{count} робота",
      "many": "{count} роботов"
    }
  }
}

count() uses Intl.PluralRules to get pluralization rules for each locale.

Custom Variable Translations

In additional to params() and count() you can define your own translation transforms. Or you can change pluralization or parameters syntax by replacing count() and params().

import { transform, strings } from '@nanostores/i18n'

// Add parameters syntax like hello: "Hi, %1"
export const paramsList = transform((locale, translation, ...args) => {
  return strings(translation, str => {
    return str.replace(/%\d/g, pattern => args[pattern.slice(1)])
  })
})

import { paramsList } from '../lib/paramsList.ts'

export const messages = i18n('hi', {
  hello: paramsList('Hello, %1')
})

Translation Process

The good I18n support is not about the I18n library, but about translation process.

Developer creates base translation in component’s source.

CI runs script to extract base translation to JSON.

import { messagesToJSON } from '@nanostores/i18n'

const files = await glob('src/*.tsx')
const components = await Promise.all(files.map(async (file) => {
  return (await import(file).messages)
}))
const json = messagesToJSON(...components)

CI uploads JSON with base translation to online translation service.
Translators translate application on this service.
CI or translation service download translation JSONs to the project.

Lazy loading

In general case developer pass get function like this to fetch all translations on locale change.

export const i18n = createI18n(locale, {
  async get (code) {
    return fetchJSON(`/translations/${code}.json`)
  }
})

Then define post component with i18n.

export const messages = i18n('post', {
  post: 'Post details'
})

Many application parts are rarely used, so there is a way to get translations for them partial.

We can use component names like main/post or settings/user.

export const messages = i18n('main/post', {
  post: 'Post details'
})

We can define that components are more commonly used and give them same prefixes like main/heading , main/post and main/comment.

Translations should be named:

// public/translations/ru/main.json
{
  "main/post": {
    "post": "Данные о публикации"
  },
  "main/heading": {
    "heading": "Заголовок"
  },
  "main/comment": {
    "comment": "Комментарий"
  }
}
// public/translations/ru/settings.json

During rendering i18n saves all component names that are used. When locale changed i18n send names to get function.

We can pass get function that split the prefixes, filter unique of them and make fetch for needed translations.

export const i18n = createI18n(locale, {
  async get(code, components) {
    let prefixes = components.map(name => name.split('/')[0])
    let unique = Array.from(new Set(prefixes))
    return Promise.all(
      unique.map(chunk =>
        fetchJSON(`/translations/${code}/${chunk}.json`)
      )
    )
  }
})

After each of new renderings i18n checks translations in cache. If not in cache:
- Splits component unique prefix or get name without prefix.
- Checks if translations for it were fetched, but response not received yet.
- Calls get function for component name if needed - main or settings.
Fetch will be called for all new rendered component with unique name. To prevent this we might want to give them same prefixes.

Server-Side Rendering

For SSR you may want to use own locale store and set cache options in custom i18n to avoid translations loading:

import { createI18n } from '@nanostores/i18n'
import { atom } from 'nanostores'

let locale, i18n

if (isServer) {
  locale = atom(db.getUser(userId).locale || parseHttpLocaleHeader())
  i18n = createI18n(locale, {
    async get () {
      return {}
    },
    cache: {
      fr: frMessages
    }
  })
} else {
  …
}

export { locale, i18n }

Processors

Global translation processor applied to all messages. For instance, we can create screen size transform:

// stores/i18n.js
import { atom, onMount } from 'nanostores'
import { createI18n, createProcessor } from '@nanostores/i18n'

const screenSize = atom('big')
onMount(screenSize, () => {
  let media = window.matchMedia('(min-width: 600px)')
  const check = () => {
    screenSize.set(media.matches ? 'big' : 'small')
  }
  media.addEventListener('change', check)
  return () => {
    media.removeEventListener('change', check)
  }
})

export const size = createProcessor(screenSize)

export const i18n = createI18n(locale, {
  get: …,
  processors: [
    size
  ]
})

// components/send-to-user.jsx
import { i18n, size } from '../stores/i18n.js'

export const messages = i18n({
  send: size({
    big: 'Send message',
    small: 'send'
  }),
  name: 'User name'
})

export const SendLabel = () => {
  const t = useStore(messages)
  return t.send()
}

parabolabam/i18n