Locales
You will be able to define the locales an app supports in one place, with defineLocales. Each locale states a timeZone and a dir, and one of them is the default.
On this page
Locale list
src/i18n.tsimport { defineLocales } from '@k8ordo/i18n';
import type { LocaleOf } from '@k8ordo/i18n';
export const locales = defineLocales(
{
ja: { timeZone: 'Asia/Tokyo', dir: 'ltr' },
'en-US': { timeZone: 'America/New_York', dir: 'ltr' },
ar: { timeZone: 'Africa/Cairo', dir: 'rtl' },
},
{ default: 'en-US' },
The default locale
);
export type Locale = LocaleOf<typeof locales>;
declare module '@k8ordo/i18n' {
interface Register {
locale: Locale;
Registers the tag union
}
}Pass defineLocales an object keyed by locale tag. Tags are BCP 47, and the spelling you write is the URL segment: en-US gives /en-US/….
Keys are inferred as literal types, so no as const is needed. LocaleOf<typeof locales> is the union of the tags.
An @k8ordo/framework app leaves the declaration out: the framework generates Register from this locales export. See @k8ordo/framework’s Routing.
Pitfall
Call defineLocales once per app. A second call replaces the list defined before it. Define it in one module, export it, and import it everywhere else.
Default locale
locales.default; // 'en-US'The default locale is chosen with default in the second argument. Without it, the locale written first is the default, and locales.default is typed as the whole union.
The default is used when:
- in the browser, the first segment of the URL is not a locale
- negotiation matches no locale
- on the server, neither
runnorparamsSchemahas set a locale
Time zone
timeZone is the IANA time zone the locale’s dates are shown in. How dates are written is covered in Formatting.
The runtime’s zone is the server’s on the server and the visitor’s in the browser. Using it, the server’s HTML and the hydrating render can show different times. With a zone per locale, the server and the browser write dates in the same zone.
Pick the zone that fits what the site is about. A site about events in Tokyo may show its English pages in Asia/Tokyo too.
Text direction
locales.definitions.ar;
// { timeZone: 'Africa/Cairo', dir: 'rtl' }dir is the direction the locale’s text runs in: ltr or rtl. Intl.Locale’s getTextInfo() has not reached every browser, so the direction is not derived from the tag.
Write the current locale’s dir onto <html>. See Current locale.
Rejected definitions
defineLocales({ ja: { timeZone: 'Asia/Tokio', dir: 'ltr' } });
// TypeError: defineLocales: the timeZone of "ja", "Asia/Tokio", is not a time zoneA wrong definition throws a TypeError as soon as defineLocales is called. Every message starts with defineLocales:.
- No locale at all:
no locale is defined - A
defaultoutside the list:the default "fr" is not in ["ja","en"] - A tag that is not BCP 47:
"en_US" is not a BCP 47 language tag - A time zone the runtime does not know:
the timeZone of "ja", "Asia/Tokio", is not a time zone - A
dirother thanltrandrtl:the dir of "ja", "auto", is neither "ltr" nor "rtl"
A default outside the list, a missing timeZone and a dir other than ltr and rtl are type errors as well. A tag that is not BCP 47 and a time zone the runtime does not know pass the types; only this check catches them.
What the definition returns
The value defineLocales returns holds the list and the functions made from it. Wherever one is needed, import locales.
all: the tags, in the order writtendefinitions: each locale’s{ timeZone, dir }, the object as givendefault: the default localeis(value): membership as a type guard; case-sensitivenegotiateandnegotiateRequest: functions that pick a locale from the visitor’s preferences. See Negotiation.localizeanddelocalize: functions that put the locale segment on a pathname and take it off. See Switching.paramsSchema,runandgetLocale: set the current locale and read it. See Current locale.- Under static mode of
@k8ordo/framework,src/routes/[locale]/paths.tsreturnsall. Writing it is covered in Parameters. dateTimeFormatand four more:Intlformatters for the current locale. See Formatting.
The argument and return types are listed under API.