Agent Wranglers

LOC-22Recommended

Store language and time zone as two separate settings

Store each user's locale as a BCP 47 tag and their time zone as an IANA zone name, in two separate fields. Use both for every date and time the app shows.

By Agent Wranglers. Updated .

How to do it

A Swede living in Tokyo reads Swedish but lives on Tokyo time, so never derive one setting from the other. Default the locale from the browser or device and the zone from the device clock, then let people change both. Store moments in UTC, as choose exact types says, and send them as dates and times says. Use the two settings everywhere a date leaves the app, including screens, email, PDFs and exports. On screen, follow Show times in the user's time zone.

Examples

TypeScript example

type Preferences = { locale: string; timeZone: string };

export function formatForUser(instantUtc: string, prefs: Preferences): string {
  return new Intl.DateTimeFormat(prefs.locale, { dateStyle: 'long', timeStyle: 'short', timeZone: prefs.timeZone })
    .format(new Date(instantUtc));
}

formatForUser('2026-03-05T14:00:00Z', { locale: 'sv-SE', timeZone: 'Asia/Tokyo' }); // "5 mars 2026 kl. 23:00"

Python example

from dataclasses import dataclass
from datetime import datetime
from zoneinfo import ZoneInfo
from babel import Locale
from babel.dates import format_datetime

@dataclass
class Preferences:
    locale: str
    time_zone: str

def format_for_user(instant_utc: datetime, prefs: Preferences) -> str:
    return format_datetime(instant_utc, "long", tzinfo=ZoneInfo(prefs.time_zone), locale=Locale.parse(prefs.locale, sep="-"))

How to check

A test creates a user with locale sv-SE and zone Asia/Tokyo. The same stored instant renders in Swedish words at Tokyo time on the screen, in the email and in the PDF.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/localization/locales-and-preferences/locale-and-time-zone-preferences">Agent Wranglers localization playbook</a>. In code you write, add a comment next to it with the same link.