Domain Locale Binding
APay can serve multiple exact domains from one deployment and give each domain its own default storefront language. A binding changes the language used by an unprefixed URL; it does not lock the domain to one language. Other built languages remain available through URL prefixes.
For example, with English, Chinese, and Russian built into the site:
| Domain | Default URL | Other language examples |
|---|---|---|
apay.example | / is English | /zh, /ru |
cn.apay.example | / is Chinese | /en, /ru |
ru.apay.example | / is Russian | /en, /zh |
Build configuration
Set APAY_LOCALES and APAY_DOMAIN_LOCALES before building. APAY_DOMAIN_LOCALES accepts either a comma-separated host=locale list or a JSON object:
APAY_LOCALES=en,zh,ru \
APAY_DOMAIN_LOCALES=apay.example=en,cn.apay.example=zh,ru.apay.example=ru \
APAY_PUBLIC_PROTOCOL=https \
npm run build
APAY_DOMAIN_LOCALES='{"apay.example":"en","cn.apay.example":"zh"}' npm run build
Hosts are exact, lowercase-normalized names. Wildcards, schemes, paths, user info, invalid ports, conflicting duplicate bindings, and locales omitted from APAY_LOCALES stop the build. A development host may include a port, such as localhost:3000=zh.
APAY_PUBLIC_PROTOCOL is optional and accepts only http or https. Production deployments behind a proxy should set it to https, so payment callbacks and email links never depend on an ambiguous internal connection protocol.
Without APAY_DOMAIN_LOCALES, APay keeps its single-domain APAY_DEFAULT_LOCALE behavior. Configure an absolute HTTP(S) site_url in Settings so canonical URLs, JSON-LD, and /sitemap.xml have a trusted public origin. APay does not fall back to an arbitrary Host header.
Request behavior
The storefront and business APIs use the following language priority:
- an explicit route or API
localevalue; - the
i18n_redirectedcookie saved by an explicit user choice; - a supported locale prefix in the referring storefront URL;
- the current domain's default locale;
Accept-Language, then the site default.
On a user's first unprefixed visit, APay stores the mapped domain default in the i18n cookie before browser or GeoIP detection. A later explicit language choice remains effective on that domain. Checkout currency snapshots and payment-method locale filters follow the same resolved locale.
Canonical and hreflang links stay on the current domain because the binding defines a default language rather than language ownership. The unprefixed URL is the domain's x-default; other built languages use their normal prefixes. The same trusted origin and language paths are used by JSON-LD and the sitemap; see International SEO and Structured Data.
Fixed language ownership
Enable APAY_LOCALE_DOMAINS in addition to domain defaults when Simplified Chinese must use shopark.net and English plus all other languages must use shopark.ai. It accepts a locale=host list or JSON object; * supplies the owner for remaining built locales. Every owner must be allowed by APAY_DOMAIN_LOCALES, every built locale needs an owner, and an owner's unprefixed default language must belong to that owner. Invalid configurations fail the build.
The repository includes the public build preset config/shopark-domains.env:
APAY_BUILD_THEMES=shopark
APAY_LOCALES=en,zh,zh-HK,ru
APAY_DEFAULT_LOCALE=en
APAY_DOMAIN_LOCALES=shopark.net=zh,shopark.ai=en
APAY_LOCALE_DOMAINS=zh=shopark.net,*=shopark.ai
APAY_PUBLIC_PROTOCOL=https
Build with the preset; supply database and session secrets through the existing private deployment environment:
node scripts/build-shopark-domains.mjs
Also enable en,zh,zh-HK,ru in the admin localization setting supported_locales. Building a locale creates its routes, but a non-empty backend whitelist can still reject that locale with HTTP 404. For example, supported_locales=en,zh,ru rejects /zh-HK even though the package contains Traditional Chinese. Local themes using one database share this setting.
| Locale | Canonical storefront URL |
|---|---|
| Simplified Chinese | https://shopark.net/ |
| English | https://shopark.ai/ |
| Traditional Chinese | https://shopark.ai/zh-HK |
| Russian | https://shopark.ai/ru |
Language switches retain the page, query, and fragment and navigate to the owning domain. Storefront GET/HEAD requests on the wrong domain, redundant default-language prefixes, and www aliases receive HTTP 301, for example shopark.ai/zh-HK/page/pricing?ref=x → shopark.ai/page/pricing?ref=x. Client navigation follows the same policy. The URL determines language; old cookies, localStorage, backend defaults, and browser detection cannot override it.
APIs, admin, authentication, account pages, payment pages, callbacks, and assets are excluded from automatic cross-domain redirects. POST requests are unchanged. An explicit language-menu switch can still cross domains; cookies and login sessions remain independent, with no cross-domain sign-in.
Canonical, og:url, and structured-data page URLs use the owner. Reciprocal hreflang links point to canonical URLs across domains. Both domains use the build's APAY_DEFAULT_LOCALE for x-default (English in this preset). Each domain's sitemap includes only its own <loc> URLs with cross-domain alternates. Omitting APAY_LOCALE_DOMAINS preserves the default-only behavior above.
Before deployment, configure DNS, TLS, and reverse proxy routing for both domains and declared www aliases. Check fresh visits, stale language preferences, menu switches, non-looping redirects, SSR SEO, and both sitemaps. Run node --experimental-strip-types scripts/check-locale-domains.mjs; the ownership guard is also enforced by prebuild. Roll back to the previous artifact or remove APAY_LOCALE_DOMAINS and rebuild to restore default-only binding. No database or payment-state rollback is needed. Browsers may retain cached 301 responses; validate in a test environment before deployment.
With a local artifact running on port 5489 against a temporary database configured with active_theme=shopark, run node scripts/check-locale-domains-http.mjs. Override the local address with APAY_DOMAIN_CHECK_BASE_URL; this probe rejects non-local targets and uses Host headers without contacting the public domains. It checks GET/HEAD redirects, stale cookies, forwarded hosts, SSR metadata, per-domain sitemaps, unknown-host rejection, and session/payment exclusions.
DNS, TLS, proxy, and cache
Every configured domain must already be verified and routed to the same APay deployment. Provision DNS and a valid TLS certificate before enabling the mapping. The reverse proxy must replace, not append user-controlled, X-Forwarded-Host and X-Forwarded-Proto values.
When domain mappings are enabled, APay accepts a forwarded or direct host only when it exactly matches the build allowlist. An unknown host is rejected with HTTP 400 by the core server middleware. Nitro SSR may internally read /api/settings and /api/_nuxt_icon/<collection>.json with GET/HEAD, including icon query strings. Only Nitro's internal request marker enables this exception; HTTP headers cannot enable it. Private APIs and write methods remain subject to Host validation. These public reads do not generate absolute URLs or alter domain locale selection. Registration verification links, pending-order email links, payment callbacks, and default payment return URLs also verify the trusted origin before business writes or payment plugin execution. APay does not silently generate links from an unrecognized Host header.
node --experimental-strip-types scripts/check-domain-host-guard.mjs executes the real Host middleware with isolated IO. It verifies internal settings/icon reads and rejection of unknown hosts, forged internal headers, private paths, and write methods. The language ownership prebuild guard also runs this check.
Admin SSR session reads use useRequestFetch() to forward the incoming cookies and domain headers. Forwarding only cookies makes the internal /api/admin/session request fail Host validation, so a page reload (including an admin language switch) appears to log the admin out. scripts/check-admin-session-domains.mjs, included in the ownership prebuild guard, checks sealed sessions across both domains and all four languages while preserving unauthenticated and unknown-host rejection. Admin language changes stay on the current domain; cross-domain login sharing remains disabled.
The Nuxt build subprocess may use an internal host while prerendering content indexes. APay's build wrapper marks that subprocess with APAY_NUXT_BUILD=1, which bypasses only the global storefront Host rejection. Trusted-origin generation remains strict, and this marker must not be configured in a deployed runtime.
CDN and reverse-proxy caches must include the Host in their cache key. Never share rendered HTML for / across configured domains.
Rollout and rollback
- Verify domain ownership, DNS, TLS, proxy headers, and Host-aware cache keys.
- Build with all required
APAY_LOCALES,APAY_DOMAIN_LOCALES, andAPAY_PUBLIC_PROTOCOL=https. - Probe
/, each alternate locale prefix, registration links, a pending checkout email, and a sandbox payment callback on every domain. - Confirm canonical and
hreflangoutput and reject a request with an unknown Host.
To roll back, deploy the previous artifact or remove APAY_DOMAIN_LOCALES and APAY_PUBLIC_PROTOCOL, rebuild, and return traffic to the primary domain. No database migration, order snapshot rewrite, payment-status change, or production data rollback is required.