Skip to content
fabricators docs
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.

csharp
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:

csharp
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.

Use the first API as the minimal host and BFF integration for the trusted preference transport.

↑ ↓ to move↵ to openSearching fabricators .NET foundation v0.19.0