---
title: "Domain Locale Binding"
canonical_url: "https://ainode.run/docs/domain-locales"
type: "doc"
locale: "en"
description: "Bind multiple verified domains to different default storefront languages in one APay deployment."
---

# Domain Locale Binding
> Bind multiple verified domains to different default storefront languages in one APay deployment.

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:

```bash
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
```

```bash
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:

1. an explicit route or API `locale` value;
2. the `i18n_redirected` cookie saved by an explicit user choice;
3. a supported locale prefix in the referring storefront URL;
4. the current domain's default locale;
5. `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](/docs/seo).

## 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`:

```bash
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:

```bash
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 `` 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/.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

1. Verify domain ownership, DNS, TLS, proxy headers, and Host-aware cache keys.
2. Build with all required `APAY_LOCALES`, `APAY_DOMAIN_LOCALES`, and `APAY_PUBLIC_PROTOCOL=https`.
3. Probe `/`, each alternate locale prefix, registration links, a pending checkout email, and a sandbox payment callback on every domain.
4. Confirm canonical and `hreflang` output 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.
