Edge Translation (Workers AI) & Offline CLI Translation
Real-time prompt translation via Cloudflare Workers AI (AI binding) with slot protection and multi-model fallback, plus offline Ark CLI translation tools.
Slloy uses two separate translation pipelines:
- Runtime Edge Translation (
server/src/translate.ts&POST /api/translate): Powered by Cloudflare Workers AI (env.AIbinding) for interactive prompt and slot translation on/prompts/<slug>. - Offline Content Translation (
tools/translate-*.ts): Powered by Volcengine Ark LLM APIs during build/authoring time for UI dictionaries, blog posts, and long-form article series.
1. Runtime Edge Translation via Cloudflare Workers AI
Why Cloudflare Workers AI (env.AI)
Running interactive translation on Cloudflare Workers AI keeps inference inside the Cloudflare edge network under the same account—requiring zero additional third-party vendor keys or cross-border data processors, and operating within Workers AI's free daily tier (~10,000 neurons/day) with sub-cent overage costs.
Placeholder Slot Protection (protectSlots & restoreSlots)
Prompt templates contain variable placeholders like `{product}` or `{brand_name}`. LLMs frequently translate curly-brace words into the target language (e.g., {产品}) or drop them entirely in RTL/CJK scripts, which breaks variable substitution.
server/src/translate.ts prevents placeholder corruption via a two-pass sentinel guard:
- Pre-Translation (
protectSlots):- Matches
/\{[^{}\n]{1,40}\}/gand replaces each placeholder sequentially with an ASCII bracket sentinel:[[1]],[[2]], etc. - The system prompt explicitly instructs the model:
"Keep every marker of the form [[1]], [[2]] exactly as it is, in the same place."
- Matches
- Post-Translation (
restoreSlots):- Replaces
/\[\[\s*(\d+)\s*\]\]/gback with the original`{...}`token. - Hallucinated Sentinel Stripping: If the model invents an out-of-range sentinel (e.g., appending
[[1]]when translating a short slot value that had0tokens, observed in live testing on"磨砂玻璃香水瓶 30ml"),restoreSlotsstrips the unmatched sentinel and collapses double spaces. - Strict Completeness Verification: Checks that every original token is present in the restored string. If any placeholder was lost, throws
TranslateError("PLACEHOLDER_LOST")(HTTP 502) rather than returning a broken prompt template.
- Replaces
Multi-Model Fallback Chain & Isolate Sticky Cache
On 2026-11-14, Cloudflare deprecated @cf/meta/llama-3.1-8b-instruct (error code 5028), proving that relying on a single hardcoded Workers AI model ID risks sudden silent outages. createTranslator() maintains an ordered model chain and remembers the first working model (let working: string | null = null) within the isolate:
| Order | Workers AI Model ID | Neuron Cost (per ~257-char prompt) | Characteristics |
|---|---|---|---|
1 (Default config.ai.translateModel) | @cf/meta/llama-4-scout-17b-16e-instruct | ~10 neurons | Fast, accurate photography terminology (frosted glass -> 磨砂玻璃). |
2 (FALLBACK_MODELS[0]) | @cf/meta/llama-3.3-70b-instruct-fp8-fast | ~23 neurons | Strongest minor-locale stability (ar, he, nl, ru). |
3 (FALLBACK_MODELS[1]) | @cf/qwen/qwen3-30b-a3b-fp8 | ~16 neurons | Highest CJK terminology precision. |
4 (FALLBACK_MODELS[2]) | @cf/meta/llama-3.1-8b-instruct-fp8 | ~5 neurons | Lowest-cost emergency fallback. |
- Output Length Sanity Check (
EMPTY_RESULT): If the translated output is empty or shorter thansource.length * 0.3(catching refusal replies like"Sorry"while accommodating English -> CJK compression of0.4–0.6x),translate()rejects the output and falls back to the next model in the chain. - Fast-Fail on Account Errors:
classifyModelError()classifies upstream errors intoMODEL_MISSING(1001/5004/5028/deprecated -> tries next model),MODEL_FORBIDDEN(Workers AI not enabled -> aborts immediately),MODEL_QUOTA(429-> aborts immediately), andMODEL_ERROR. - Sanitized Error Reporting (
sanitizeDetail): Strips hex strings (>= 16chars) and long numbers (>= 6digits) before logging so account IDs or internal quotas never leak.
Public Endpoint Guards (POST /api/translate)
Defined in server/src/http/routes/translate.ts:
- Anonymous Access: Publicly callable without login (since
/prompts/<slug>pages are public). - 3 Abuse Guards:
- Length Cap:
text.length <= TRANSLATE_MAX_TEXT(3,000chars; slot values useTRANSLATE_MAX_VALUE = 200chars on the client). - Target Locale Whitelist (
TRANSLATE_TARGETS): Strictly restricted to Slloy's14locale tags (en,zh-CN,zh-TW,ja,ko,de,fr,es,pt,it,nl,ru,ar,he). - DB-Backed IP Rate Limit:
scope: "translate", max20requests per minute per IP.
- Length Cap:
- Headers: Always responds with
Cache-Control: no-store.
2. Offline CLI Translation Tools (tools/translate-*.ts)
Static site copy, blog articles, and SEO comparison series are translated offline at authoring time and committed to Git so pre-rendered HTML and /_worker/content/ bundles have zero runtime LLM dependency:
| CLI Script | Scope & Target Files | Key Rules & Guards |
|---|---|---|
tools/translate-ark.ts | Translates UI dictionary namespaces (locales/en/*.json -> locales/<locale>/*.json), including errors.json (fail.<CODE>), works.json, and common.json. | Preserves interpolation variables (`{count}`, `{cap}`) and brand/model names (Slloy, Seedream, Seedance, Wan, Kling); verified by tests/tools/i18n-catalog.test.ts. |
tools/translate-blog-ark.ts | Translates Markdown/JSON blog posts across the 14 supported locales. | Preserves internal link paths, code blocks, frontmatter slugs, and image URLs. |
tools/translate-article-series.ts | Batch-translates structured SEO article series and model comparison guides. | Enforces localized Title (<= 60 chars target / 75 max) and H1 rules verified by tools/check-meta.ts. |
Compliance Redlines & Platform AI Disclosures
The 6 code-enforced compliance redlines in server/src/compliance/redlines.ts, derived Amazon main-image warnings, and copyable platform disclosure templates.
14-Locale Architecture & Edge Negotiation
Supported 14 languages (including RTL Arabic and Hebrew), URL prefix mapping, and Worker-level createLocaleRedirect priority rules.