On this page
Localize presentation and app catalogs
Resolve scoped locale/timezone preferences and compose tenant-specific app translation catalogs.
Status: supplied in 0.15.0. These APIs are not in 0.14.0.
AddFoundationPresentation and UseFoundationPresentation provide a scoped
RequestPresentation without changing CurrentCulture/CurrentUICulture. Explicit
supported locales and timezones are resolved at startup, independently of the
machine's defaults. Default preferences are en-US and UTC. A consumer can enable
it-IT and Europe/Rome, for example. Neither preference establishes tenant access.
HTTP/BFF contract
The default configurable request headers match sfeedo: x-locale and
x-timezone. An explicit supported locale wins over Accept-Language, then
the configured default applies. Accept-Language honors positive quality weights
and deterministic language fallback; unsupported languages use the default.
Invalid, duplicate or unsupported explicit overrides return a no-store 400
Presentation.InvalidPreferences; bounded negotiation prevents unbounded input.
Version 0.16.0 also applies parent-language fallback to explicit
overrides: x-locale: it resolves to supported it-IT, just as Accept-Language
does. RejectUnsupportedOverrides defaults to true; setting it to false makes
unsupported, well-formed overrides use the configured default. The scoped
LocaleOverrideFallback and TimeZoneOverrideFallback flags record that choice.
Malformed, duplicate, comma-joined, empty or overlong values remain 400.
AcceptAnyResolvableTimeZone defaults to false. Opting in permits any zone the
host's TimeZoneInfo resolves, rather than requiring an exhaustive allowlist.
Known system IDs resolve case-insensitively to their canonical ID. Hosts still
need current timezone data; an unresolved ID follows the strict/fallback policy.
For sfeedo, configure it-IT with supported [it-IT, en-US], Europe/Rome,
RejectUnsupportedOverrides = false and AcceptAnyResolvableTimeZone = true.
This does not mutate ambient culture or pre-shift canonical UTC timestamps.
Responses declare Content-Language, x-resolved-locale and
x-resolved-timezone, merging existing Vary with both preference headers and
Accept-Language. Use this opt-in middleware on localized response paths; do not
unnecessarily vary every technical endpoint. Do not publicly cache authenticated
or tenant-specific responses merely because Vary is present.
In a BFF product, the browser talks only to its BFF. That BFF forwards validated presentation preferences, preserving its CSRF/session and private backend transport. It returns or consumes the resolved preference metadata consistently. No browser header becomes an authority, tenant/company grant or credential binding.
FormatNumber, FormatDate and FormatInstant receive explicit culture/zone through RequestPresentation. Include formatted labels next to canonical numbers/UTC instants; never replace a decimal amount or ISO instant with a display string. Business DateOnly values do not undergo timezone conversion. Error codes and translation keys remain stable machine identifiers alongside translated text.
Response controls
Status: supplied in 0.18.0, not included in 0.17.0. Resolution, strictness, invariant serialization and UTC defaults are unchanged. New options:
| Option | Default | Behavior |
|---|---|---|
EmitContentLanguageHeader |
true |
Writes Content-Language |
EmitResolvedLocaleHeader |
true |
Writes x-resolved-locale |
EmitResolvedTimeZoneHeader |
true |
Writes x-resolved-timezone |
AddVaryHeader |
true |
Merges preference headers and Accept-Language into Vary |
OnInvalidPreferences |
Unset | Uses the existing HTTP 400 JSON error |
Options are snapshotted at registration. Disabled emission leaves existing application-owned headers untouched; it does not remove them. Vary merging preserves existing names and a wildcard. Valid responses retain their existing Cache-Control. Disable preference Vary only on invariant response paths or when the consumer provides correct cache partitioning; a localized response must not be reused across incompatible preferences. Header emission does not format data.
The optional trusted callback receives HttpContext and a
PresentationPreferenceError with Kind (Malformed/Unsupported) and HeaderName,
never the rejected value. The middleware first applies HTTP 400 and no-store;
the callback chooses the response representation and can resolve scoped services
through HttpContext. Keep it thread-safe and honor RequestAborted. With no callback,
the existing application/json body { "code": "Presentation.InvalidPreferences" }
is preserved. Malformed/duplicate/oversized headers remain errors even with
RejectUnsupportedOverrides = false; unsupported values alone may fall back.
services.AddFoundationPresentation(options =>
{
options.RejectUnsupportedOverrides = false;
options.AcceptAnyResolvableTimeZone = true;
options.EmitContentLanguageHeader = false;
options.EmitResolvedLocaleHeader = false;
options.EmitResolvedTimeZoneHeader = false;
options.AddVaryHeader = false; // Only for an appropriate cache contract.
options.OnInvalidPreferences = (http, error) =>
{
http.Response.ContentType = "text/plain";
return http.Response.WriteAsync(
"Invalid " + error.HeaderName + " value.", http.RequestAborted);
};
});IC can retain its existing timestamp response converter and HTTP compatibility adapter. This increment adds no automatic JSON timestamp re-offsetting, culture- dependent number binding or changed pagination defaults/status codes. Its full IUserContext/ITenantContext and staff/team semantics remain product-owned.
Runtime catalog contract
ITranslationCatalogSource in Fabricators.Application.Localization reads an
exact authorized authority/app/tenant/locale scope at runtime. A null tenant
identifies the app-owned base catalog. TranslationCatalogComposer copies a
bounded exact-locale base catalog plus optional matching-tenant overrides into
an immutable resolved snapshot with a scope/locale/revision-bound cache key.
Another app, tenant or locale cannot be substituted during composition.
Products own durable publication, authorization and audit. Only an admitted publisher can update its app's catalog; an authorized tenant administrator can override that app's own keys for that tenant. No override changes other tenants or the original catalog. Disabled/uninstalled apps must not contribute catalogs merely because their assemblies exist on the server. The API supplies no allow-all source, public editing endpoint or global mutable dictionary.
Select fallback explicitly: requested locale, declared parent language, then the app's declared default, with tenant override before the base at each chosen locale. Record the locale actually used. The exact-scope source/composer does not silently select a different locale. Pluralization, parameter interpolation and rich text require a separately reviewed formatter; messages are plain data, never executable templates or trusted HTML. Escape for the actual output context.
Publish a new durable revision whenever content changes. Cache and invalidation must include authority, tenant, app, locale, catalog revisions and any other visibility scope. Cache formatted values additionally by timezone, format and currency/minor-unit rules. Missing source/capability is an explicit product integration boundary, not permission to fetch another tenant's catalog.
The initial increment proves request isolation, culture-independent technical values, deterministic negotiation, timezone display and namespace/revision isolation. Actual ERP app catalog storage/editing, publisher verification, cross-process invalidation, BFF adoption and frontend text integration remain consumer work; no frontend is supplied here.
Request-zone JSON and host/background controls (0.19.0)
Status: supplied in 0.19.0, not in 0.18.0. The existing defaults preserve explicit DateTimeOffset offsets and do not convert UTC output automatically. For products whose BFF always forwards the effective preference headers, opt in:
services.AddFoundationPresentation(options =>
{
options.DefaultLocale = "it-IT";
options.SupportedLocales = ["it-IT", "en-US"];
options.DefaultTimeZone = "UTC";
options.AcceptAnyResolvableTimeZone = true;
options.RequireAuthenticationMiddleware = true;
options.RequireHttpContext = true;
});
// Register after other Foundation JSON defaults. Numbers retain existing parsing.
services.AddFoundationRequestZoneJson();
app.UseAuthentication();
app.UseFoundationPresentation();G-01: AddFoundationRequestZoneJson converts every outgoing DateTimeOffset using
that request's resolved RequestPresentation.TimeZone, including UTC values from
the database. DST is evaluated at each instant; the instant never changes.
Nullable timestamps, collections and nested DTOs use the same converter. Strict
input remains offset-qualified and normalized to UTC. There is no process-global
zone or ambient-culture change. Plain ConfigureJson retains its previous output
policy; adoption is explicit. DateTime is deliberately unchanged (G-06).
OffsetTimestampConverter can also be configured directly, or through
JsonTimeOptions.OutputZone, retaining strict input validation. Fixed output-zone
resolvers are suitable for explicitly scoped jobs; request-zone HTTP options are
not durable/event serializers and fail outside the presentation middleware.
G-03: register presentation after UseAuthentication whenever the host has
authentication or user-derived preference resolution. Presentation resolves at
middleware entry. The optional RequireAuthenticationMiddleware guard detects
the reversed order at runtime; it defaults to false so anonymous hosts continue
to work. Do not resolve the scoped presentation earlier in the pipeline.
G-04 (nonblocking improvement): JsonTimeOptions.ConfigureTimestamps and
ConfigureNumbers independently control installation of date converters and
NumberHandling (Strict by default). Both switches default to true on existing
runtime configuration APIs. Set ConfigureNumbers = false for date-only adoption
without changing current numeric parsing; IC can also restore its own numeric
options. The new request-zone registration preserves number handling by default.
No locale-dependent decimal parsing is introduced.
G-05: a standalone worker that does not register presentation fails DI resolution;
there is no automatic Foundation service in that host. The subtle case is a job
running in an API host which registered presentation: without an HTTP request,
its scoped resolution historically used the configured defaults (for IC: UTC/it,
not necessarily UTC/en). HasHttpRequest now exposes that absence and
RequireHttpRequest() rejects it explicitly. RequireHttpContext = true makes
DI resolution reject it too; the default remains false for compatibility. A job
must load user/team preferences explicitly and construct its own immutable
RequestPresentation. PresentationTimeZoneContext in Application adapts that
same snapshot to existing ITimeZoneContext handlers without a second resolver.
Neither context grants user/team/tenant authority.
G-07: Vary partitions by request headers, not by authenticated identity.
If resolution also uses a saved user/team preference, mark personalized responses
Cache-Control: private (or no-store where required); do not share them through
a CDN on Vary alone. Internal/object cache keys must include the effective
locale/timezone plus all visibility scopes, or cache neutral UTC data and convert
after retrieval. The BFF owns precedence (saved user preference, detected browser
zone, fallback) and should overwrite untrusted incoming preference headers.
G-08: when RejectUnsupportedOverrides = false, malformed explicit locale/zone
values now fall back to their respective configured defaults too, with fallback
flags and a debug event containing only the header name. Invalid raw values are
never logged/echoed. This includes duplicates, comma-joined, empty and overlong
values reaching the middleware. HTTP server/proxy protocol parsing can still
reject invalid wire headers before Foundation runs. Strict mode remains the
unchanged default; malformed Accept-Language negotiation remains bounded and
strict. Earlier sections describing non-strict malformed rejection apply through
0.18.0 only. This opt-in compatibility change is intentional, not a global change
to request validation.
Related integration guides
Use the first API as the minimal host and BFF integration for the trusted preference transport.