Locale and currency

Goal

Set how the workspace stores and displays money, languages, calendars, and date/number formats — correctly split across Tenant settings and Localization setup.

Who it is for

Tenant admins. Viewing settings needs tenant.view / localization.view; saving needs tenant.manage / localization.admin. Individual users only change their UI language in the top-bar locale switcher (must be in enabled_locales).

Preconditions

• You know the business base currency, operating timezone, and which languages documents and field translations must support.
• Sensitive changes (including Base currency and Fiscal year starts) may require an audited reason dialog.

Split of ownership (do not mix these up)

Concern	Screen	Route	Permission
Base currency, enabled currencies, Timezone	Tenant settings → tab Localization (Currency and timezone)	/settings	tenant.view / tenant.manage
Enabled languages, Default language, calendars, date/number format presets	Localization setup	/localization/setup	localization.view / localization.admin
Personal UI language	Top-bar locale switcher	—	authenticated

Tenant settings shows the hint: Languages, date/number formats, calendars and format presets are managed in Localization setup. Use Open localization setup when you need languages/formats.

Steps — currency and timezone

1. Open Tenant settings (/settings).
2. Open the Localization tab.
3. Set Base currency, Enabled currencies (base is always included), and Timezone.
4. Save — toast Settings saved. Posted historical amounts keep the currency they were recorded in; new documents default to the tenant base currency.

Steps — languages and formats

1. Open Localization setup (/localization/setup).
2. On Options, set Enabled languages and Default language (default must be one of the enabled locales).
3. Configure calendars and format presets as needed (display-only — stored dates stay ISO/UTC).
4. Save — toast Localization settings saved.

Steps — your UI language

1. Use the top-bar locale control.
2. The client calls PATCH /auth/locale. If the locale is not enabled for the tenant → validation error (locale_not_enabled).

Result

• Forms that use TranslatableInput offer chips for each enabled locale.
• Lists and documents format dates, numbers, and money via tenant preferences (useTenantFormat()).
• Field-translation maps only accept keys in enabled_locales.

Hard stops

• default_locale not in enabled_locales → localization error default_not_enabled.
• User locale outside enabled set → locale_not_enabled.
• Currency codes outside the supported registry → validation 422.
• Changing base currency / fiscal year start may require confirmation with an audit reason.

Related

• New workspace (onboarding)
• Tenant settings
• Enable modules