International SEO and Structured Data

APay renders SEO metadata on the server for the built storefront languages: English (en), Simplified Chinese (zh), Hong Kong Traditional Chinese (zh-HK), and Russian (ru). The active deployment can build a subset with APAY_LOCALES.

Trusted site URL

Single-domain deployments must set Settings → Site URL (site_url) to an absolute HTTP or HTTPS origin such as https://store.example.com. Paths, query strings, fragments, credentials, and non-HTTP schemes are invalid. APay never guesses a public origin from an arbitrary request Host.

When APAY_DOMAIN_LOCALES is enabled, the current Host must match that build-time allowlist. APAY_PUBLIC_PROTOCOL=https is recommended behind a reverse proxy. See Domain Locale Binding for the proxy and cache requirements.

If no trusted origin is available, storefront HTML degrades to noindex,follow, omits canonical and JSON-LD, and /sitemap.xml returns HTTP 503. robots.txt remains available but omits its Sitemap line.

Language URLs

The default language uses an unprefixed path; other built languages use a locale prefix. For an English-default site, one product is represented as:

  • English: /products/example
  • Simplified Chinese: /zh/products/example
  • Hong Kong Traditional Chinese: /zh-HK/products/example
  • Russian: /ru/products/example

Each indexable page emits one canonical URL, hreflang links for reachable built languages, an x-default link to the unprefixed default-language URL, og:url, and the correct HTML language. Query strings and fragments do not create alternate canonical pages.

When APAY_LOCALE_DOMAINS is enabled, language ownership defines the canonical URLs: Simplified Chinese can use https://myshopark.com/products/example, English https://myshopark.com/products/example, and Russian https://myshopark.com/ru/products/example. Canonical, og:url, JSON-LD page addresses, and reciprocal hreflang use those owner URLs. Both domains use the build default for x-default. Each domain's sitemap contains only its own <loc> URLs with cross-domain alternates. See Domain Locale Binding for configuration, redirect exclusions, and rollback.

Structured data

All structured data is emitted as one SSR <script type="application/ld+json"> with a Schema.org @graph:

PageNodes
Public storefrontOrganization, WebSite
Active product detailProduct, Offer, BreadcrumbList
Active blog detailBlogPosting, BreadcrumbList
Qingpu downloadsSoftwareApplication, BreadcrumbList
Shoply app detailSoftwareApplication, BreadcrumbList
Shoply theme detailProduct, Offer when backed by a product, BreadcrumbList

Entity pages submit the localized data they already fetched during SSR. Product offers use the same useLocaleCurrency() amount and ISO currency as the visible page and checkout. APay does not fabricate ratings, reviews, inventory, authors, SKU/GTIN values, search actions, or social profiles. Missing optional facts are omitted.

Inactive products and posts return or remain 404 and are excluded. NFT mock product, creator, drop, stock, and live-status facts are intentionally noindex and never emitted as Product schema.

Route policy and sitemap

app/core/seo.routes.json and each theme's seo.routes.json are the index policy source. Every real page entry must be classified as public, private, or redirect. The SEO guard fails when a page is unclassified, classified twice, or a manifest path does not exist.

Shoply's /about is a redirect to the public /page/about page. Legacy solution URLs are also redirects; they must not appear as sitemap destinations. Deleted /page/case is excluded, while /cases/:slug is classified as a public detail route.

Theme-specific dynamic sources are declared in theme.host.json as seoSources: { "source-name": "server/seo.ts" }. The module exports getSitemapEntries(source) and returns { path, lastmod? } entries. The build registry includes only selected storefront providers; core Sitemap code does not import individual themes. A missing or failing provider produces HTTP 503 instead of silently omitting its routes.

The sitemap contains only:

  • the current active theme plus non-suppressed core public routes;
  • the current trusted origin;
  • built languages and their alternates;
  • active products and active blog posts;
  • real Shoply marketplace seed routes.

Documentation landing pages are included. Individual Nuxt Content document paths remain discoverable through SSR links and canonical metadata but are not proactively enumerated by the current sitemap generator.

It never unions routes from every bundled theme. Generation fails instead of returning partial XML when the database query fails or the result exceeds 50,000 URLs. Responses cache for five minutes with stale revalidation; CDN keys must include Host.

Private /admin, /api, /auth, /user, /payment, /callback, and /app paths receive X-Robots-Tag: noindex, nofollow. Unknown or unclassified storefront paths use noindex,follow so crawlers can observe the directive. robots.txt blocks API routes but deliberately allows private HTML to be fetched so crawlers can read its noindex response header.

Generative Engine Optimization (GEO)

APay includes a host-level GEO layer alongside traditional SEO so AI search engines and retrieval agents (OAI-SearchBot, ChatGPT-User, PerplexityBot, Claude-SearchBot, ClaudeBot, Google-Extended, Applebot-Extended, etc.) can index and cite public facts without scraping hydration payloads:

  1. /llms.txt, /llms-full.txt, and /rss.xml:
    • /llms.txt renders a structured Markdown directory for the active theme and trusted origin: site overview, public core pages, active products with base currency pricing, active blog posts matching domain locale ownership, documentation pages, and theme-provided dynamic entries (ThemeSitemapEntry optionally supplies title, description, section, and markdown).
    • /llms-full.txt appends the cleaned full-text Markdown corpus for active products, documentation (converted from Nuxt Content Minimark AST via minimarkToMarkdown with Shiki styles stripped), blog articles, and theme catalog entries.
    • /rss.xml outputs an RSS 2.0 XML feed for active blog articles. On single-domain multi-locale sites, /llms.txt, /llms-full.txt, and /rss.xml accept ?locale=<code> (e.g. ?locale=zh) to return the localized corpus.
    • All endpoints enforce classifySeoRoute(...) === 'public' and return HTTP 503 if no trusted origin is configured.
  2. Markdown Mirrors and Content Negotiation:
    • Public blog, product, documentation, and theme-declared dynamic detail routes support explicit .md suffixes (/blog/:slug.md, /products/:slug.md, /docs/**.md, and any /:group/:slug.md backed by a theme seoSources declaration, plus localized prefixes) as well as Accept: text/markdown content negotiation.
    • Responses emit Content-Type: text/markdown; charset=utf-8, Vary: Accept, canonical and llms-txt Link headers, and YAML frontmatter (title, canonical_url, type, locale, price/currency, published_at, updated_at) followed by sanitized Markdown.
    • Indexable SSR pages emit <link rel="llms-txt">, <link rel="alternate" type="application/rss+xml"> (when blog routes are public), and <link rel="alternate" type="text/markdown"> on Markdown-mirror-capable detail pages.
    • If a theme suppresses or marks a route as private (for example, nft suppressing /products/**), the Markdown mirror is refused and returns 404.
  3. AI Crawler Directives, Admin Controls & JSON-LD:
    • /robots.txt declares explicit rules for AI_SEARCH_BOTS (controlled by geo_ai_bots_policy under Admin → Settings → SEO: allow by default, or disallow) and advertises LLMs-Txt: <origin>/llms.txt.
    • Admin → Settings → SEO also manages search engine webmaster verification tokens (google_site_verification, bing_site_verification, baidu_site_verification, yandex_site_verification) which are automatically injected into public indexable <head> tags.
    • useJsonLd.ts provides useFaqPageJsonLd (FAQPage) and useSoftwareApplicationJsonLd (SoftwareApplication) in addition to useProductJsonLd and useBlogPostingJsonLd, strictly omitting any fabricated ratings or review counts.
    • GEO & SEO Growth Cockpit & IndexNow:
      • AI Bot Telemetry (GET /api/admin/settings/seo-telemetry): Filters access_logs at the SQL query layer for AI_SEARCH_BOTS (OAI-SearchBot, GPTBot, PerplexityBot, ClaudeBot, Google-Extended, etc.) and requests to /llms.txt, /llms-full.txt, and *.md mirrors without pre-truncating general traffic, displaying 30-day crawl leaderboards and top AI-crawled pages in Admin → Settings → SEO.
      • IndexNow Real-Time Push (POST /api/admin/settings/seo-indexnow): Configure indexnow_key and indexnow_auto_push in Admin → Settings → SEO. APay automatically hosts /<indexnow_key>.txt at the root and asynchronously pushes updated canonical HTML and .md mirror URLs when products or blog posts are published or updated.
      • Single-Page GEO/SEO Inspector: Product (/admin/products/[id]) and Post (/admin/posts/[id]) editors include a sidebar readiness score (0–100, Grade A–D), .md mirror & JSON-LD live preview modal, and one-click IndexNow push.
      • Proactive Audit Radar & One-Click Auto-Optimizer (GET /api/admin/settings/seo-audit, POST /api/admin/settings/seo-autofill): Automatically scans all active products and blog posts, surfaces actionable diagnostics (missing citations, AI-crawled posts without product links, uncrawled orphan pages), and supports one-click smart extraction of tldr, keySpecs, faqs, and bidirectional product ↔ blog relatedLinks (both inside individual editors and in full-site batch mode).
    • Citation-Ready Structured Content (metaData):
      • Products and posts support tldr (concise takeaway), keySpecs (label-value pairs rendered as Markdown tables in .md mirrors / /llms-full.txt and additionalProperty PropertyValue nodes in Product JSON-LD), faqs (question-answer pairs automatically injected as FAQPage JSON-LD and appended to .md mirrors), and relatedLinks (bidirectional internal links between products, tutorials, and docs), with per-locale overrides under metaData.translations[locale].
    • GeoIP Smart Checkout Routing & Cross-Conversion:
      • /api/payments/info uses offline GeoIP (resolveRequestGeo) to prioritize regionally preferred payment gateways (sortPaymentMethodsByGeo) and surfaces a recommendedByGeo indicator in PaymentWorkspace.vue without altering canonical URLs or currencySnapshot accounting.
      • The Growth Cockpit reuses the shared visitor report service (loadVisitorReport + buildVisitorGeoConversions) to cross-analyze visitor GeoIP country with ai and search acquisition channels (geoConversions), computing deduplicated visitor conversion rates (paidVisitors / totalVisitors, aiPaidVisitors / aiVisitors, searchPaidVisitors / searchVisitors) and per-currency revenue/AOV buckets (revenueByCurrency, aovByCurrency) without summing across different accounting currencies.
    • MCP Server Discovery in /llms.txt:
      • /llms.txt includes an ## AI Agent & MCP Protocol section advertising /api/mcp (JSON-RPC 2.0 Streamable HTTP), /.well-known/oauth-protected-resource, and /.well-known/oauth-authorization-server.

Site icon

Upload the site icon under Admin → Settings → General, then click Save changes. Uploading only fills in the favicon URL; it does not save the setting. The shared head plugin reads site_favicon for all themes and admin pages, including SSR, and updates the current browser tab after settings are saved. Refresh other open tabs to load the new setting. An empty value uses /favicon.svg.

Uploaded files receive a unique URL on each upload. Local /uploads/*.ico responses use Content-Type: image/vnd.microsoft.icon and retain X-Content-Type-Options: nosniff.

Verification

Run the focused guards before building:

npm run check:seo
node --experimental-strip-types scripts/check-domain-locales.mjs
node --experimental-strip-types scripts/check-locale-domains.mjs

After deployment, inspect SSR source—not only the hydrated DOM—for the canonical, alternates, robots meta, and single JSON-LD graph. Probe /robots.txt, /sitemap.xml, every configured Host, one URL per language, an active and inactive product, an active blog post, a 404, and a private page. Validate sample entity pages with a structured-data validator without treating rich-result eligibility as a ranking guarantee.

Rollback requires deploying the previous artifact or reverting the SEO route manifests and code. No database migration, payment rollback, or production data rewrite is involved.