Skip to content

Core / locale: HostLocaleConfig

Functions, types, and exports for Core / locale: HostLocaleConfig.

Page outline

Host-based locale configuration.

  • mode: "map" (default): each locale maps to a full, canonical host, matched exactly against the request host. Used by the route examples as a validation signal on top of /:locale/....
  • mode: "domain": a complete locale-to-host map is authoritative, without adding locale path prefixes. Hosts may use unrelated domain names.
  • mode: "subdomain": the leftmost DNS label of the request host is the locale (de.example.com -> de). Base-domain-independent, so it needs no per-locale host map and works unchanged across lvh.me and production.
  • mode: "tld": the top-level domain (the rightmost DNS label) determines the locale. Resolution is three-tiered: a TLD label that already is a supported locale is authoritative automatically (example.de -> de); a TLD whose label differs from the language code is authoritative only when listed in tld ({ at: "de" }); anything else (.com, the multilingual .ch, …) is deliberately not authoritative and falls back to Accept-Language/default. defaultTld names the outbound TLD used when switching to the default locale, which has no authoritative TLD of its own (en -> .com).
import type { HostLocaleConfig } from "@palamedes/core/locale"

type HostLocaleConfig<TLocale extends string> = {
    mode?: "map" | "domain" | "subdomain" | "tld";
    locales?: Partial<Record<TLocale, string>>;
    defaultHost?: string | null;
    /**
     * `mode: "tld"` only. Explicit TLD-label -> locale overrides for country codes
     * whose label is not itself a supported locale code (e.g. `{ at: "de", uk: "en" }`).
     */
    tld?: Record<string, TLocale>;
    /**
     * `mode: "tld"` only. Outbound TLD label for the default locale, which has no
     * authoritative TLD of its own (e.g. `"com"` so `en` switches to `.com`).
     */
    defaultTld?: string;
};

Properties

NameTypeRequiredDescription
mode"map" | "domain" | "subdomain" | "tld"No
localesPartial<Record<TLocale, string>>No
defaultHoststring | nullNo
tldRecord<string, TLocale>Nomode: "tld" only. Explicit TLD-label -> locale overrides for country codes
whose label is not itself a supported locale code (e.g. { at: "de", uk: "en" }).
defaultTldstringNomode: "tld" only. Outbound TLD label for the default locale, which has no
authoritative TLD of its own (e.g. "com" so en switches to .com).

Source entry on GitHub

Last updated: November 10, 2026