Nano Stores I18n

Server-Side Rendering (SSR)

When using SSR with hydration, you should use your own locale store and provide a cache in createI18n to prevent the server from attempting to fetch translations over the network.

Server-Only Rendering

If you are rendering content entirely on the server without client hydration, use loadTranslations(messages) to ensure all required translations are loaded before the component renders.

import { loadTranslations } from '@nanostores/i18n'
import { i18n } from '../stores/i18n.js'

// The messages store created via i18n()
export const messages = i18n('post', { post: 'Post details' })

async function Post() {
  // Wait for translations to be ready
  const t = await loadTranslations(messages)
  return <span>{t.post}</span>
}

To use Nano Stores I18n, install both nanostores and @nanostores/i18n using npm.

If you are using Astro, you must also install astro-nanostores-i18n.

npm install nanostores @nanostores/i18n

The createI18n(locale, options) function is the core of the library. It manages the loading and caching of translations.

Key Options:

• get(code, components?): An async function used to fetch translations for a specific locale code. If components are provided, you can implement lazy loading based on component prefixes.
• cache: An object to provide pre-loaded translations (useful for SSR).
• preprocessors: An array of functions to transform all messages (e.g., applying typography rules).
• processors: An array of custom processors that allow translations to change based on other application state (e.g., screen size).

import { createI18n } from '@nanostores/i18n'

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

Base translations are defined directly in your component source code. They serve two purposes: providing TypeScript types and acting as the default fallback.

Use the i18n(namespace, definition) function to create a translation store for a specific component or section.

Translation Helpers:

• params(template): Replaces placeholders in a string (e.g., params('Hello, {name}')).
• count(options): Handles pluralization using Intl.PluralRules (e.g., count({ one: '...', other: '...' })).
• transform(fn): Allows creating custom translation transforms.

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

// Define base translations for a component
export const messages = i18n('post', {
  title: 'Post details',
  published: params('Was published at {at}'),
  comments: count({
    one: '{count} comment',
    other: '{count} comments'
  })
})

The localeFrom() function is a store builder used to find the user's current locale by checking a list of provided stores in order.

Common patterns include:

• Browser settings: Use browser({ available: [...] }) to detect the locale from the user's browser settings. You must provide a list of available locales.
• Manual override: Combine a persistent store (like localStorage) with the browser store so users can manually switch languages.
• URL Router: Use a computed store to extract the locale from URL parameters.

The locale store can then be used with any Nano Stores framework integration (e.g., @nanostores/react).

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

// Example: Priority given to manual settings, then browser settings
export const locale = localeFrom(
  localeSettings, 
  browser({ available: ['en', 'fr', 'ru'] as const })
)

Processors allow you to create custom translation types that react to external application state. This is useful for changing text based on things like screen size, user roles, or theme.

1. Create a processor using createProcessor(someStore).
2. Inside the processor, return a function that maps state values to specific translation strings.
3. Add the processor to the processors array in createI18n.
4. Use the processor inside your i18n() definition.

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

const screenSize = atom('big')
export const size = createProcessor(screenSize)

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

// In your component definition
export const messages = i18n({
  send: size({
    big: 'Send message',
    small: 'send'
  })
})

Translations should be provided as plain flat JSON files. This format is compatible with online translation services like Weblate. The structure should match the keys used in your i18n() calls.

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