i18n Module

LocalesService

The abstract class LocalesService (packages/i18n/src/services/locales.service.ts) is the base of every locale source. It owns the language state — source language, active language, detection, persistence, fallback — and delegates the key lookup to the Translator. A subclass only says how the messages of one language are loaded.

Methods

path is a dot separated key path or an array of segments; vars fills the {{ placeholders }} of the message. Both translate() and lookup() use the active language unless you pass a langcode yourself.

Keys and fallback

The fallback is per key, not per language: de-AT is looked up as de-AT, then de, then every entry of the fallbackLangcodes option. The first language that has the key wins, the others are not consulted for that key.

await localesService.setLangcode("de-AT");
// de-AT -> de -> en -> it (the variants of fallbackLangcodes)
localesService.translate("form.newsletter.title");

A message is either a string or a set of plural forms selected by the count variable:

const locales = {
  de: {
    cart: {
      items: { one: "{{ count }} Artikel", other: "{{ count }} Artikel" },
    },
  },
};

zero, one and two win when count is exactly that number, the rest follows Intl.PluralRules for the active language, and other is the last resort. An empty string is a valid message, so you can blank a text without a fallback.

Options

LocalesOptions is the second constructor argument of both services:

Your own service

Extend LocalesService and implement load(), which resolves the messages of one language or undefined if it has none:

import {
  LocalesService,
  type LocalesOptions,
  type MessageTree,
} from "@ribajs/i18n";

class MyLocalesService extends LocalesService {
  constructor(protected readonly endpoint: string, options: LocalesOptions) {
    super(options);
  }

  protected async load(langcode: string): Promise<MessageTree | undefined> {
    const response = await fetch(`${this.endpoint}/${langcode}.json`);
    return response.ok ? await response.json() : undefined;
  }
}

load() is called once per language, concurrent callers share the same promise, and the resolved messages are cached; a load that rejected is retried by the next switch.

Override resolveLangcodes(): Promise<string[]> when the selectable languages are not known upfront; it is called once by init(), before the first load():

protected async resolveLangcodes(): Promise<string[]> {
  const response = await fetch(`${this.endpoint}/index.json`);
  return response.ok ? await response.json() : [];
}

Inside both you may use this.langcodes and this.sourceLangcode, and in a subclass of LocalesRestService also this.urlFor(langcode) and this.fetchJSON(url). Without an override of resolveLangcodes(), init() rejects when the langcodes option is missing.

LocalesStaticService

The LocalesStaticService holds the messages of all languages in memory, which suits a bundled app, a demo or a small set of UI strings. Any language can be read without loading anything, so the service never emits a request and works without a DOM.

import { LocalesStaticService } from "@ribajs/i18n";

const locales = {
  de: {
    examples: {
      newsletter: {
        description_html:
          "Abonnieren Sie unseren Newsletter und erhalten Sie <strong>10% Rabatt</strong> auf Ihren nächsten Einkauf.",
        input_value: "Unbekannt",
        placeholder_last_name: "Nachname",
        title: "Melde dich für den Newsletter an",
      },
    },
  },
  en: {
    examples: {
      newsletter: {
        description_html:
          "Subscribe to our newsletter and get <strong>10% off</strong> your next purchase.",
        input_value: "Unknown",
        placeholder_last_name: "Surname",
        title: "Sign up for the newsletter",
      },
    },
  },
};

const localesService = new LocalesStaticService(locales);

The root keys of locales are the language codes (de, en, …). Do not wrap the messages in an extra property such as locales: a lookup of examples.newsletter.title would resolve against en.locales.examples… and find nothing. The nested keys are the key paths the binders and the t formatter use.

new LocalesStaticService(catalog: Catalog, options?: LocalesOptions)

Without the langcodes option the catalog keys are the selectable languages. Set the option to offer a subset of them, or to add a language whose messages are not in the catalog:

const localesService = new LocalesStaticService(locales, {
  sourceLangcode: "en",
  langcodes: ["en", "de", "fr"],
  detect: ["query", "storage", "html"],
  persist: true,
});

Since the source language is the language of your markup, you can leave its entry out of the catalog: its messages are not needed, and a key without a message keeps the markup the element had. Keep in mind that a catalog entry of the source language does win over the markup for the keys it contains.

The service only implements load(), which reads the catalog; detection, persistence and the fallback chain come from LocalesService. See LocalesService for the options and the fallback rules, LocalesRestService for messages that are not bundled.

LocalesRestService

The LocalesRestService fetches the messages over HTTP with HttpService.getJSON(). It requests one file per language the first time that language is needed, caches the response and requests nothing else, which keeps the initial payload small.

import { LocalesRestService } from "@ribajs/i18n";

const localesService = new LocalesRestService((langcode) => `/locales/${langcode}.json`, {
  langcodes: ["en", "de", "fr"],
  sourceLangcode: "en",
});

new LocalesRestService(url: string | ((langcode: string) => string), options?: LocalesRestOptions)

Each file contains the message tree of that one language, without the langcode as a wrapper:

{
  "form": {
    "newsletter": {
      "title": "Newsletter abonnieren"
    }
  }
}

A missing url throws in the constructor. langcodes is required in the options, because the service cannot know which languages the server offers: without it, and without an override of resolveLangcodes(), init() rejects.

Lazy per language

init() loads the detected language and the languages of its fallback chain, nothing else. setLangcode() loads the language it is asked for before it applies it. Every response is cached, so switching back and forth requests a file once; a request that failed is not cached and is retried by the next switch.

The catalog of the source language is never requested, because the markup is the source. Set loadSourceCatalog: true to fetch it as well.

await localesService.setLangcode("de");
// one request for /locales/de.json, then `translate()` reads synchronously
localesService.translate("form.newsletter.title");

A failed request rejects the setLangcode() promise, emits error and leaves the active language in place.

One file for all languages

Pass a fixed url and pick the messages of the requested language out of the response with parse(). Requests to the same url are shared, so one file serves every switch:

import { LocalesRestService, type LocalesRestOptions, type MessageTree } from "@ribajs/i18n";

class ThemeLocalesService extends LocalesRestService {
  constructor(baseUrl: string, options: LocalesRestOptions = {}) {
    super(`${baseUrl}/locales`, options);
  }

  protected parse(body: unknown, langcode: string): MessageTree | undefined {
    return (body as Record<string, MessageTree>)[langcode];
  }

  protected async resolveLangcodes(): Promise<string[]> {
    const body = (await this.fetchJSON(this.urlFor(this.sourceLangcode))) as object;
    return Object.keys(body);
  }
}

/locales then returns { "de": { … }, "fr": { … } } and init() reads the languages from its keys.

Hooks

packages/shopify-tda/src/services/locales.service.ts is a real implementation of these hooks: the ?shop=… query of the Shopify backend lives in its buildUrl(), the messages of all languages arrive in one file, which resolveLangcodes() and parse() read.

See LocalesService for the shared options, the fallback rules and the events.

i18n-[type]

<h1 rv-i18n-text="'examples.newsletter.title'">Sign up for the newsletter</h1>
<!-- source language active: "Sign up for the newsletter"
     de active:        "Melde dich für den Newsletter an"
     fr active:        no message in fr or its fallbacks, the markup again -->

<p rv-i18n-html="'form.greeting'" data-name="Pascal">
  Hello
  <template lang="de">Hallo {{ name }}</template>
  <template lang="default">Welcome</template>
</p>

<p rv-i18n-html="'form.greeting'">
  Hello
  <template lang="de">Hallo {{ name }}</template>
  <template name="name">Pascal</template>
</p>

const locales = {
  de: { form: { greeting: "Hallo {{ name }}" } },
};

<p rv-i18n-html="">Hello<template lang="de">Hallo</template></p>

t

This formatter resolves a translation key path in a mustache text node and re-renders when the language changes. For element content and attributes, the i18n-* binders (rv-i18n-text, rv-i18n-html, …) are more explicit and support the source markup and inline templates, see rv-i18n-[type].

In mustache text nodes, Riba’s default delimiters are a single { and } (see configuration: templateDelimiters). That differs from Liquid/Shopify, which use {{ and }} — do not copy that syntax here. Double braces are the placeholders inside a translation, not Riba’s syntax.

{ 'examples.newsletter.title' | t }

Arguments

{ 'form.newsletter.title' | t }
{ 'form.newsletter.title' | t 'de' }
{ 'cart.items' | t vars }
{ 'cart.items' | t 'de' vars }

Both are optional and may be given in any order: a string argument is a langcode, an object is the variables. A langcode can be a literal in the markup, the variables are a keypath read from the view model, so a text node with variables has to be bound:

const model = {
  vars: { count: 3, name: "Pascal" },
};

<p>{ 'cart.items' | t vars }</p>
<!-- with de: { cart: { items: { one: "{{ count }} Artikel", other: "{{ count }} Artikel" } } } -->
<!-- renders "3 Artikel" in the active language -->

A langcode argument reads a language that may not be loaded yet: with a LocalesRestService and en active, a t 'de' renders the key until de has been loaded once, for example by setLangcode("de") or preload("de"). Translate the active language instead when the text must always be complete.

Missing keys

The formatter renders the key itself when neither the active language nor a fallback chain has the message:

{ 'form.unknown' | t } <!-- renders: form.unknown -->

The missing option of the service still applies: with missing: "marker" the text becomes translation missing: "form.unknown", and with missing: "throw" the error is thrown while the text node is rendered. Before the service is ready the text is empty and re-renders with the message in the ready event.

The formatter subscribes to changed (and to ready while the service is not ready yet) through the view model, and the subscriptions are removed when the view is unbound.

i18n-switcher

Use this component to switch to another available language. It does not ship with a template: add your own markup as children, for example buttons bound to langcodes.

The languages come from the configuration of the LocalesService, never from the component: the scope langcodes is localesService.getAvailableLangcodes(), which reads the langcodes option (or the keys of the catalog of a LocalesStaticService). Add a language there and it shows up in the switcher, remove it and it disappears. The component re-reads the list on ready and changed, which only updates the active flag of an entry.

Types

export interface Langcode {
  code: string;
  active: boolean;
}

Template methods

Both methods catch a failed switch and log it to the console; setLangcode() is asynchronous because it loads the messages first.

Template properties

With persist: true on the service the language a visitor picks is remembered in localStorage, with detect: ["storage", …] the switcher opens in that language on the next visit.