Skip to Content
Slloy Docs
SEO, i18n & Redirect Governance

14-Locale Architecture & Edge Negotiation

Supported 14 languages (including RTL Arabic and Hebrew), URL prefix mapping, and Worker-level createLocaleRedirect priority rules.

Slloy serves 14 languages with localized static pre-rendering (dist/) and edge SSR (/prompts). Locale negotiation is executed at the Cloudflare Worker entry point (server/src/http/middleware/localeRedirect.ts and server/src/i18n.ts).

1. The 14 Supported Locales & URL Prefix Table

English (en) is the default unprefixed locale at the root (/). All other 13 locales use a two-letter URL path prefix (/<prefix>/...), with Simplified and Traditional Chinese mapped to /zh and /tw for historical URL continuity:

BCP 47 Tag (ServerLocale)URL Prefix (localePath)og:localeDirection (dir)Language NameAccept-Language Aliases (ALIAS)
en"" (root /)en_USltrEnglishen, en-*
zh-CNzh (/zh)zh_CNltrSimplified Chinese (简体中文)zh-hans, zh-cn, zh-sg, zh
zh-TWtw (/tw)zh_TWltrTraditional Chinese (繁體中文)zh-hant, zh-tw, zh-hk, zh-mo, tw
jaja (/ja)ja_JPltrJapanese (日本語)ja, ja-*
koko (/ko)ko_KRltrKorean (한국어)ko, ko-*
dede (/de)de_DEltrGerman (Deutsch)de, de-*
frfr (/fr)fr_FRltrFrench (Français)fr, fr-*
eses (/es)es_ESltrSpanish (Español)es, es-*
ptpt (/pt)pt_BRltrPortuguese (Português)pt, pt-*
itit (/it)it_ITltrItalian (Italiano)it, it-*
nlnl (/nl)nl_NLltrDutch (Nederlands)nl, nl-*
ruru (/ru)ru_RUltrRussian (Русский)ru, ru-*
arar (/ar)ar_SArtlArabic (العربية)ar, ar-*
hehe (/he)he_ILrtlHebrew (עברית)he, he-*

Exact-Before-Prefix Matching (negotiateLocale)

When parsing Accept-Language (e.g., zh-TW,zh;q=0.9,en;q=0.8), negotiateLocale() sorts tags by descending q weight and matches exact tag -> ALIAS map -> base subtag:

  • If a tag has base zh, it checks tag.includes("hant") ? "zh-TW" : "zh-CN" before falling back to zh-CN. This prevents Traditional Chinese users (zh-TW, zh-HK, zh-MO, zh-Hant) from being greedily matched by the zh prefix into Simplified Chinese.
  • RTL locales (ar, he) set dir = "rtl" on <html> and wrap Base UI components in <DirectionProvider direction="rtl">.

2. Worker-Level Locale Negotiation (createLocaleRedirect)

Prior to 2026-11-17 (T18), only the root homepage / performed client-side language redirection via inline JavaScript, leaving deep links (/pricing, /generator, /showcase) stuck in English unless the user manually switched languages.

createLocaleRedirect({ assets }) (server/src/http/middleware/localeRedirect.ts) moves negotiation to the Cloudflare Worker middleware layer across all public pages, following a strict 6-step priority pipeline:

flowchart TD
    A["Incoming Request (GET / HEAD)"] --> B{"1. Page Path & No Existing Prefix?"}
    B -- "No (/api/*, /admin, /zh/*, .html/.js, etc.)" --> Z["Pass through: next()"]
    B -- "Yes (Unprefixed English Page)" --> C{"2. Crawler / Bot User-Agent?"}
    C -- "Yes (Googlebot, Lighthouse, curl, etc.)" --> Z
    C -- "No (Human Browser)" --> D["3. Read slloy_lang Cookie -> Fallback to Accept-Language"]
    D --> E{"4. Resolved Locale === 'en'?"}
    E -- "Yes" --> Z
    E -- "No (e.g. zh-CN -> /zh)" --> F{"5. Does Target Asset Exist in dist/?"}
    F -- "No (English-only page)" --> Z
    F -- "Yes (200 OK in ASSETS)" --> G["6. HTTP 302 Redirect to /<prefix><pathname>"]

Detailed Priority & Safety Rules

  1. Method, Prefix & Non-Page Bypass (isPagePath & hasLocalePrefix):
    • Only intercepts GET and HEAD requests.
    • Bypasses any path with a file extension (/\.[a-z0-9]+$/i), trailing slashes other than / (left to the 301 canonical trailing-slash normalizer), /404, /index, and all operational/app prefixes (SKIP_PREFIXES: /api/, /admin, /account, /my, /auth/, /assets/, /uploads/, /_worker/, /s/, /.well-known/, /cdn-cgi/).
    • Bypasses any URL that already starts with a non-English locale prefix (/zh, /ja/pricing, etc.)—if a user explicitly clicks a /ja link, they always see Japanese.
  2. Crawler & Audit Tool Bypass (CRAWLER Regex):
    • Search engines and audit bots (bot, crawler, spider, slurp, archiver, facebookexternalhit, embedly, pinterest, google-inspectiontool, chrome-lighthouse, headlesschrome, python-requests, curl/, wget/) never get redirected.
    • Google explicitly warns against Accept-Language redirects for crawlers: if Googlebot crawls /pricing with a regional Accept-Language and gets 302 redirected to /zh/pricing, the English canonical URL drops out of the index and contradicts the page's hreflang annotations.
  3. Explicit Cookie Priority Over Accept-Language (slloy_lang):
    • Reads the slloy_lang cookie first (cookieLocale(c.req.header("cookie"))). The frontend language switcher writes both localStorage and the slloy_lang cookie.
    • If a Chinese user manually selects English in the UI (slloy_lang=en), chosen resolves to "en" and overrides their browser's Accept-Language: zh-CN, keeping them on English across future visits.
    • Only when slloy_lang is absent or invalid does it fall back to negotiateLocale(c.req.header("accept-language")).
  4. Target Asset Existence Check (targetExists):
    • Before redirecting /some-page to /<prefix>/some-page, the middleware probes assets.fetch("http://localhost/<prefix>/some-page.html") (or /<prefix>.html for /) and cancels the response body stream immediately.
    • If the localized page does not return HTTP 200 (for example, an English-only article), the middleware stays on the English page instead of 302 redirecting the user into a 404.
  5. Single-Hop Redirect & Uncacheable Headers:
    • Root / redirects directly to /<prefix> (e.g., /zh, never /zh/, which would trigger a second trailing-slash 301 redirect), preserving url.search query parameters (?utm_source=...).
    • Always emits HTTP 302 with:
      Cache-Control: private, no-store
      Vary: Accept-Language, Cookie
      This guarantees that an edge cache never stores a language redirect and serves it to subsequent visitors with different cookies or languages.

On this page