Internationalization Engine

Status: Draft for review
Depends on: Platform Engine, Site Engine contracts, Integration Engine adapters, Operations Engine audit/async infrastructure

Purpose

Own the platform-wide locale model, translation lifecycle, localized-content resolution, regional formatting contracts and translation operations used by every other engine.

Internationalization is a cross-cutting engine: domain engines continue to own their business entities, while the Internationalization Engine defines and provides the contracts used to attach, resolve, validate and operate localized representations.

Owns

• platform locale catalog and BCP 47 locale normalization;
• tenant locale configuration and defaults;
• site locale configuration and defaults;
• locale resolution/fallback policy;
• translation records/lifecycle primitives where centrally modeled;
• translation completeness and stale-translation status;
• translation permissions/assignment metadata;
• locale-aware formatting services/contracts;
• localization key catalog for application/system strings;
• translation import/export orchestration;
• machine/human translation provider orchestration through Integration Engine;
• localized-template resolution for notifications/communications;
• audit-friendly translation publication state.

Does not own

• the canonical business entity being translated;
• currency exchange rates or financial calculation;
• booking/availability business rules;
• site page structure or component definitions;
• marketing/ad campaign business state;
• provider-specific machine-translation credentials;
• customer identity itself.

Those remain with their owning engines.

Core domain concepts

Concept	Definition
Locale	Normalized BCP 47 language/region identifier supported by the platform.
Locale Set	Ordered set of locales enabled for a tenant or site.
Default Locale	Locale used when no more-specific supported locale can be resolved.
Resolved Locale	Locale selected for a specific request/communication/operation.
Fallback Locale	Locale used when requested localized content is unavailable.
Translation	Locale-specific representation of translatable fields attached to a canonical entity/key.
Translation State	Lifecycle such as DRAFT, READY, PUBLISHED, STALE where publication control is required.
Source Locale	Locale considered authoritative/source for a particular translation workflow.
Translation Completeness	Computed state describing whether required localizable fields exist for a locale.
Localized System Key	Stable machine key such as booking.confirmed.title resolved to locale-specific text.

Locale-resolution precedence

Public-site request resolution should generally consider:

1. explicit route/query locale where allowed;
2. persisted customer/site preference;
3. authenticated user's preferred locale;
4. Accept-Language negotiation;
5. site default locale;
6. tenant default locale;
7. platform fallback locale.

The exact precedence for a given API surface must be documented and deterministic.

Operational workflows such as outgoing communications should prioritize the recipient's explicit/preferred locale before site/browser signals.

API contract — locale configuration

Method	Route	Primary actor	Contract intent
GET	/api/public/v1/locales	Visitor/Custom Site	Return enabled locales for the resolved public site.
GET	/api/tenant/v1/locales	Tenant Admin/Content Editor	Return platform-available and tenant-enabled locale configuration.
PUT	/api/tenant/v1/locales	Tenant Owner/Admin	Configure tenant locale set/default subject to entitlements.
PUT	/api/tenant/v1/sites/{siteId}/locales	Tenant Admin/Content Editor	Configure site locale set/default from tenant-enabled locales.
GET	/api/platform/v1/locales	Platform Admin	Inspect platform locale catalog and status.
POST	/api/platform/v1/locales	Platform Admin	Add/enable a supported platform locale definition.

API contract — localized content/translation operations

The final persistence style may vary by entity; these endpoints express behavior, not a requirement for one universal translation table.

Method	Route	Primary actor	Contract intent
GET	/api/tenant/v1/translations/status	Tenant Admin/Content Editor	Translation completeness/staleness summary by locale/domain/site.
GET	/api/tenant/v1/translations/{domain}/{entityId}	Content Editor/Translator	Return localized representations/status for one entity.
PUT	/api/tenant/v1/translations/{domain}/{entityId}/{locale}	Content Editor/Translator	Create/update locale-specific representation under owning-domain schema.
POST	/api/tenant/v1/translations/{domain}/{entityId}/{locale}/publish	Authorized Editor/Admin	Publish/approve translation where domain requires translation publication state.
POST	/api/tenant/v1/translations/export	Tenant Admin/Translator	Export selected translation scope.
POST	/api/tenant/v1/translations/import	Tenant Admin/Translator	Validate/import translation package.
POST	/api/tenant/v1/translations/assist	Authorized Editor/Translator	Request machine-assisted translation when entitled/provider configured.

All translation writes must validate against the owning engine's translatable-field schema; this engine must not accept arbitrary unknown business fields.

Public/headless API locale contract

Localized public resources should support a normalized locale request mechanism and communicate resolution metadata when needed.

Illustrative response envelope fragment:

{
  "locale": {
    "requested": "fr-CA",
    "resolved": "fr",
    "fallbackUsed": true
  },
  "data": {}
}

Domain APIs may inline locale metadata differently, but semantics must remain consistent.

Events

• tenant.locales.changed
• site.locales.changed
• translation.created
• translation.updated
• translation.published
• translation.stale
• translation.imported
• translation.assistance.requested
• translation.assistance.completed

Events must carry tenant identity and canonical entity/key identifiers. They should carry locale identifiers but must not duplicate large translated payloads unless an integration contract explicitly requires it.

Regional formatting contract

The engine provides/reference-defines formatting services for:

• date and time;
• number/decimal;
• currency display (not FX calculation);
• percentages;
• measurement display;
• relative time where appropriate;
• timezone-aware presentation.

Canonical persistence remains engine-owned and locale-neutral.

Timezone rules

• store timestamps in canonical UTC form unless a specialized domain model requires otherwise;
• retain the authoritative IANA timezone on locations/resources/schedules where local wall-clock semantics matter;
• evaluate opening hours, appointment slots, tee times, departures and similar operational schedules in the authoritative location/resource timezone;
• convert only for presentation when desired;
• never derive operational timezone from browser locale.

SEO/localized-route contract

In cooperation with Site Engine, support:

• localized slugs;
• locale-prefixed routes where configured;
• canonical URL per locale;
• reciprocal hreflang relationships;
• locale-specific OpenGraph/Twitter/SEO text;
• localized sitemap entries;
• redirect behavior when slugs/locales change.

Communications contract

CRM/Integration/Marketing communications should resolve locale using recipient preference and context. Templates use stable machine keys plus locale variants.

Example:

booking.confirmed
├── es-DO
├── en-US
└── fr-FR

The business event remains booking.confirmed; locale changes only its presentation.

Roles & responsibility matrix

Legend: A accountable, R responsible, C consulted, I informed, — none.

Capability	Platform Admin	Tenant Owner	Tenant Admin	Content Editor / Translator	Marketing	Customer
Platform locale catalog	A/R	I	I	I	I	I
Tenant locale enablement/default	C	A	R	C	I	I
Site locale configuration	I	A	R	R	C	I
Translate site/content/offering copy	I	A	C	R	C	I
Publish/approve translations	I	A	R	R when permitted	C	I
Translation completeness review	I	A	R	R	C	—
Customer preferred locale	—	I	C	—	I	A/R
Machine-assisted translation configuration	C	A	R	C	C	—

A dedicated Translator permission bundle may be created without making Translator a hard-coded platform role.

Entitlement controls

Plans may control:

• maximum active locales;
• locale-specific page/section overrides;
• translation workflow/approval sophistication;
• machine-assisted translation availability/quotas;
• translation import/export;
• advanced localization analytics.

The locale-aware architecture itself cannot be disabled.

Security and isolation

• Every translation/configuration record is tenant-scoped where tenant-owned.
• Site locale configuration must belong to the same tenant as the site.
• Translation writes require authorization against both tenant and owning domain entity.
• Machine-translation provider credentials remain in Integration Engine/secret storage.
• Translation import is schema validated and cannot write across tenant boundaries.
• Locale input is normalized/validated against enabled/supported locale sets.

Cross-engine contracts

Engine	Internationalization relationship
Platform	Tenant/site locale entitlements, identity preferences, tenant defaults.
Capability	Localizable vertical/schema labels, custom-field labels and option labels.
Commerce	Offering/policy/package/add-on text and timezone-sensitive operational semantics.
Site	Localized pages, sections, navigation, routes and SEO.
CRM	Customer preferred locale and localized conversation/customer touchpoints.
Marketing	Localized campaigns, landing copy and audience/market variants.
Channel & Advertising	Locale/channel-specific catalogs and creative payloads.
Finance	Locale-aware display/invoice text; canonical money/currency remains Finance-owned.
Integration	Translation providers, localized communication providers/templates.
Operations	Async translation jobs, audit, metrics and failure handling.

Acceptance criteria

• No platform domain requires language-suffixed columns as its standard extensibility model.
• Tenant and site locale sets/defaults are independently configurable within entitlements.
• Public APIs deterministically resolve locale and can expose fallback metadata.
• Managed Sites support localized navigation/content/SEO without duplicating whole site structures by default.
• Customer communication can resolve the recipient's preferred locale.
• Operational schedules preserve authoritative IANA timezone semantics.
• Translation completeness/staleness can be inspected by tenant administrators.
• Translation writes are tenant-isolated and schema-validated against owning domains.
• Custom/headless sites use the same locale/content contracts as Managed Sites.