Internationalization Principles¶

Status: FROZEN — Foundation v1.0
Applies to: Every engine, API, Managed Site, Custom/headless site, Tenant Admin experience, Platform Admin experience, communication channel and public/customer-facing workflow

Architectural invariant¶

Internationalization is mandatory platform infrastructure, not an optional Site Engine feature.

Every tenant runs on locale-aware contracts even when the tenant enables only one language. Multi-language use may be plan/entitlement controlled, but the underlying domain, APIs and persistence models must never assume a single language.

The Tenant Admin experience is localized/i18n-aware. The Platform Admin experience is built i18n-ready even if its initial operating language is English.

Important

Language/locale, currency, timezone and market/country are independent dimensions. No engine may infer one from another unless a documented business rule explicitly does so.

Core principles¶

Locale-aware by default. Every customer-facing or tenant-admin-facing localizable string has an explicit locale context.
Canonical data stays locale-neutral. IDs, quantities, money minor units, timestamps, workflow states and machine-readable codes are not translated.
No language-suffixed schemas. Do not introduce fields such as title_en, title_es, description_fr as the platform pattern.
Structure and translation are separate. Page/section/component structure can be shared while translatable content varies by locale.
Fallback is deterministic and observable. APIs and renderers must know when fallback content was used.
Formatting is not translation. Dates, times, numbers, money and measurements use locale-aware formatting while preserving canonical values.
Location time is authoritative for operational rules. Availability and scheduling are interpreted in the resource/location timezone unless a domain contract says otherwise.
Localized SEO is first-class. Slugs, titles, descriptions, canonical/hreflang and structured content must support locale variants.
Communications honor recipient preference. Email, notifications and future messaging channels resolve the customer/user preferred locale using a documented fallback chain.
Translation state is manageable. Tenant administrators can inspect completeness, stale translations and publication readiness.
Vertical schemas are localizable. Platform-defined labels/help text/options and tenant-defined custom-field labels can be translated without redefining the underlying machine key.
Custom/headless contracts behave identically. The Custom delivery model must not implement a separate translation model from Managed Sites.
Administrative applications are not exempt. Tenant Admin is localized; Platform Admin remains i18n-ready from the beginning.

Locale hierarchy¶

Platform-supported locales
        ↓
Tenant-enabled locales
        ↓
Site-enabled locales
        ↓
Requested/customer/user locale
        ↓
Deterministic fallback chain

A tenant may run several sites with different locale sets and different defaults.

Example:

Platform: en, es, fr, it, pt, de, ...

Tenant:
  es, en, fr

Site A:
  default: es
  enabled: es, en

Site B:
  default: en
  enabled: en, fr

Locale identifiers¶

Use BCP 47 language tags where locale specificity is relevant, for example:

es-DO
es-ES
en-US
en-GB
fr-FR

The platform may support a base-language fallback such as fr-CA -> fr when the requested locale is not available.

Fallback contract¶

The initial fallback model is:

requested locale
    ↓
base language (when configured/applicable)
    ↓
site/experience default locale
    ↓
tenant default locale
    ↓
platform fallback locale

Fallback behavior must be returned/observable where API consumers need to distinguish translated content from fallback content.

An intentionally empty localized field is not the same as a missing translation. The persistence/translation model must be able to represent that distinction where it affects rendering.

Translatable vs locale-neutral data¶

Common translatable data¶

offering names and descriptions;
categories/taxonomies/display labels;
custom-field labels/help text/option labels;
pages and page-section content;
navigation labels;
SEO/OpenGraph/social metadata;
FAQs, policies and cancellation explanations;
package/add-on names and descriptions;
notification/email/message templates;
marketing campaign copy and creative metadata;
catalog/channel-facing titles/descriptions;
Tenant Admin application/system strings;
Platform Admin application/system strings where localized variants are provided.

Common locale-neutral data¶

tenant/business-unit/site IDs;
workflow/status codes;
inventory quantities;
timestamps stored in canonical form;
money amounts in minor units plus ISO currency;
coordinates;
resource IDs;
machine keys such as YACHT_CHARTER, QUOTE_REQUIRED, booking.confirmed.

Currency, timezone, market and units¶

Internationalization must not collapse these dimensions:

Locale      = es-DO
Currency    = USD or DOP
Timezone    = America/Santo_Domingo
Market      = DO
Unit system = tenant/site/user presentation preference

A Spanish-language user may choose USD. An English-language user may book a resource whose authoritative timezone is America/Santo_Domingo.

Managed Site requirements¶

Managed Sites must support:

locale-aware routing;
localized slugs where enabled;
shared page structure with localized content by default;
controlled locale-specific section/page overrides where entitled;
localized navigation and functional-component labels;
localized SEO and hreflang generation;
locale-aware sitemap/canonical generation;
preview and publication readiness per locale.

Custom/headless requirements¶

Custom-plan APIs must accept an explicit/requested locale and return deterministic locale metadata.

Example:

GET /api/public/v1/offerings/01HX...?locale=es-DO

or through a standardized language header when supported:

Accept-Language: es-DO,es;q=0.9,en;q=0.8

Responses that return localized material should be able to communicate the resolved locale and fallback status.

Translation operations¶

The platform should support, progressively:

translation completeness reporting;
draft/published translation state where required;
stale translation detection when source content changes;
translator/editor permissions;
import/export workflows;
human translation workflow;
optional machine-assisted translation through Integration Engine providers;
audit history for translation changes.

Machine translation must never silently overwrite an approved human translation.

Plan relationship¶

Internationalization itself is not removable. Plans may limit active locale count, translation workflow sophistication, locale-specific overrides or automated translation capabilities.

A one-locale Starter tenant and a many-locale Custom tenant use the same locale-aware domain contracts.

Cross-engine requirement¶

Every engine specification must contain an Internationalization Contract identifying:

which owned data is translatable;
which owned data is locale-neutral;
locale-sensitive operations;
formatting/timezone requirements;
API/event locale behavior where relevant;
translation ownership and fallback expectations.