Localization
Facet shows datetimes and interface text per account. Every account sets its own timezone and language on the in-app Settings page. The instance default fills the gap for accounts that follow the server. You set that default in the config file or on the platform settings page.
When to use this
Section titled “When to use this”Set localization when:
- You set the default timezone or language for the whole install.
- You answer why two accounts see different times for one document.
- You point users to their own preferences.
Before you start
Section titled “Before you start”- The allowed languages are
enandfr. - The default timezone must be a loadable IANA name, for example
Europe/Paris. - Both keys are hot: a runtime pin applies without a restart, while a config file change needs one.
1. Set the defaults in the config file
Section titled “1. Set the defaults in the config file”localization: default_timezone: UTC default_language: enThe section is optional. The defaults are UTC and en. The load
validates both: a timezone the runtime cannot load, or a language
outside the allowlist, fails the boot.
2. Pin the defaults at runtime
Section titled “2. Pin the defaults at runtime”Open Configure → Platform → Settings and set
localization.default_timezone or localization.default_language. The
save reaches every running process, so no restart is needed. Clear the
pin to follow the file again.
The same save works through the API. The body nests one object level per path segment:
curl -k -X PATCH -H "Authorization: Bearer $FACET_API_KEY" \ -H "Content-Type: application/json" \ -d '{"localization": {"default_timezone": "Europe/Paris"}}' \ "https://facet.localhost:3443/Api/core/SystemSettings/settings"3. Know the chain
Section titled “3. Know the chain”Each account key resolves in this order:
- The account’s own row, set on the in-app Settings page.
- The server default: the settings pin, then the config file, then the built-in default.
- The static default:
UTCfor the timezone,enfor the language.
The mapping is core.timezone → localization.default_timezone, and
core.language → localization.default_language. An account row always
wins. A cleared account row follows the server.
4. Point users to their own settings
Section titled “4. Point users to their own settings”Users open the in-app Settings page:
-
Timezone offers
Auto (system timezone), which follows the browser, andServer default, which clears the account row and follows your instance default. -
Language offers
enandfr, with the sameServer defaultoption.Saves are instant, one field at a time. See Settings, sessions, and API keys for the user’s view.
5. Know what follows the settings
Section titled “5. Know what follows the settings”- Datetimes render in the account’s display timezone, across tables, audit views, datetime pickers, and CSV exports.
dateanddateperiodvalues are calendar dates. They render as written and never pass through a timezone conversion.- The interface language cookie mirrors the account language, so the choice holds across reloads and signs-in.
Example
Section titled “Example”Set the instance defaults for an office in Paris, and check the effective values:
localization: default_timezone: Europe/Paris default_language: enOr pin the same values at runtime without a restart:
curl -k -X PATCH -H "Authorization: Bearer $FACET_API_KEY" \ -H "Content-Type: application/json" \ -d '{"localization": {"default_timezone": "Europe/Paris", "default_language": "fr"}}' \ "https://facet.localhost:3443/Api/core/SystemSettings/settings"Accounts that picked their own values keep them. Accounts on
Server default switch at once.
Troubleshooting
Section titled “Troubleshooting”The boot fails and names localization.default_timezone.
The value is not a loadable IANA name. Use a name the runtime can load,
for example Europe/Paris.
A save answers 422 on the language.
The value is outside the allowlist. Use en or fr.
A user sees times in the wrong zone.
The account row wins over the server default. The user picks the right
zone on the Settings page, or selects Server default to follow you.
Auto follows the browser, not the server.
A pin change did not reach one user.
That user holds an account row for the key. The server default only fills an empty row.
Related
Section titled “Related”- Settings, sessions, and API keys — the account-level preferences users change.
- System settings — the runtime tier and how pins work.
- Configuration files — the file the defaults live in.
- Internals on GitHub: settings.md, system-settings.md.