Locales

defineLocales(all, options?)

It takes an array of locale tags and an optional default. The tags are inferred as literal types, so no as const is needed.

// src/i18n.ts
import { defineLocales } from '@k8ordo/i18n';
import type { LocaleOf } from '@k8ordo/i18n';

export const locales = defineLocales(['en-US', 'en-GB', 'ja'], {
  default: 'ja',
});

export type Locale = LocaleOf<typeof locales>;

declare module '@k8ordo/i18n' {
  interface Register {
    locale: Locale;
  }
}

Without default, the first tag is the default. The type of default is the union of the list, so a tag outside it fails to compile.

A wrong list throws a TypeError where it is defined, not later where it is used. A repeated tag and a tag that is not BCP 47 pass the type checker, so this check is the only thing that catches them. A default outside the list already fails to compile, and is checked again at run time for callers in JavaScript and values forced through as.

One set per application

defineLocales does more than return a value: it registers the default and the membership check that message() reads. message() does not take the set as an argument because that would make each declaration look like a side effect to the bundler, which could then no longer drop unused messages.

The last set defined wins, so that when a dev server re-evaluates the module after a locale is added, the next message called reads the new set. The flip side: defining another set with defineLocales inside a test, a demo or a helper makes every message read that set from then on. Define the set in one module, export it, and import it everywhere else.

What the set returns

The value is a Locales<L, D>, where L is the union of the tags and D is the default tag.

How the members that deal with the URL — localize, delocalize, paths, paramsSchema, getLocale and run — are used is covered on a page of its own.

Read URLs & locale

Types

BCP 47 tags

A tag is checked by whether Intl.Locale accepts it. A wrong separator such as en_US, or ***, is not BCP 47.

The tag as you spell it in the set is the URL segment: en-US gives /en-US/…. Spell tags the way you want them in URLs.

Negotiation

negotiate(requested) returns the one supported locale that best fits a preference list — navigator.languages, or a parsed Accept-Language header.

1. Take the requested tags one at a time, in order.
2. If a supported locale matches the tag exactly (ignoring case), return it.
3. Otherwise, return the first supported locale that speaks the same language.
4. Skip a tag that is not BCP 47 instead of throwing on it: the list is user input.
5. If nothing matched by the end of the list, return the default.

• Negotiation's exact match ignores case (en-gb matches en-GB and comes back spelled as the set spells it). is and delocalize do not ignore case.
• Matching by language compares only the language subtag (language of Intl.Locale). Script and region are not weighed, so with ['zh-Hans', 'zh-Hant'] a request for zh-Hant-TW gets zh-Hans, the one written first. When several locales share a language, the order you write them in is the order a language match picks them in.

Each tag is tried down to its language before the next one is looked at, rather than searching the whole list for exact matches first, so that the visitor's first choice wins. Someone who sends ['en-US', 'ja'] wants English most; if the set has en, they get en, even though ja further down is an exact match.

The argument is an Iterable<string>, so navigator.languages, an array and a Set all pass as they are.

// src/preferred-locale.ts
import { parseAcceptLanguage } from '@k8ordo/i18n';

import { locales } from './i18n';
import type { Locale } from './i18n';

export const fromBrowser = (): Locale => locales.negotiate(navigator.languages);

export const fromHeaders = (headers: Headers): Locale =>
  locales.negotiate(parseAcceptLanguage(headers.get('accept-language')));

Worked examples

Results against defineLocales(['ja', 'en', 'en-GB']).

parseAcceptLanguage(header)

Turns an Accept-Language header into a preference list negotiate accepts. It is how a server negotiates from a request header.

• Tags are ordered by their q weight, highest first; a tag without one weighs 1.
• Tags of equal weight keep the order the header gives them.
• Tags weighted 0 or less (an empty q= reads as 0), and the * wildcard, are dropped. The wildcard means "anything", which is what the default already means.
• A missing header (null) or a blank one is an empty list.
• Spacing, an upper-case parameter name such as Q=, and unknown parameters are tolerated. A q that is not a number, such as q=abc, is ignored, and the tag keeps a weight of 1.
• Tags themselves are not validated; negotiate skips the ones that are not BCP 47.

Try negotiation

Edit the header and watch the list parseAcceptLanguage makes, which locale of the set each tag matched, and the answer negotiate gives. The set is this site's own locales (ja and en, default ja). There is no separate sample set because, as described above, a second defineLocales would replace the set every message on this page reads.