Skip to Content
Slloy Docs
Prompt Library, Compliance & Translation

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:

  1. Runtime Edge Translation (server/src/translate.ts & POST /api/translate): Powered by Cloudflare Workers AI (env.AI binding) for interactive prompt and slot translation on /prompts/<slug>.
  2. 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:

  1. Pre-Translation (protectSlots):
    • Matches /\{[^{}\n]{1,40}\}/g and 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."
  2. Post-Translation (restoreSlots):
    • Replaces /\[\[\s*(\d+)\s*\]\]/g back 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 had 0 tokens, observed in live testing on "磨砂玻璃香水瓶 30ml"), restoreSlots strips 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.

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:

OrderWorkers AI Model IDNeuron Cost (per ~257-char prompt)Characteristics
1 (Default config.ai.translateModel)@cf/meta/llama-4-scout-17b-16e-instruct~10 neuronsFast, accurate photography terminology (frosted glass -> 磨砂玻璃).
2 (FALLBACK_MODELS[0])@cf/meta/llama-3.3-70b-instruct-fp8-fast~23 neuronsStrongest minor-locale stability (ar, he, nl, ru).
3 (FALLBACK_MODELS[1])@cf/qwen/qwen3-30b-a3b-fp8~16 neuronsHighest CJK terminology precision.
4 (FALLBACK_MODELS[2])@cf/meta/llama-3.1-8b-instruct-fp8~5 neuronsLowest-cost emergency fallback.
  • Output Length Sanity Check (EMPTY_RESULT): If the translated output is empty or shorter than source.length * 0.3 (catching refusal replies like "Sorry" while accommodating English -> CJK compression of 0.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 into MODEL_MISSING (1001/5004/5028/deprecated -> tries next model), MODEL_FORBIDDEN (Workers AI not enabled -> aborts immediately), MODEL_QUOTA (429 -> aborts immediately), and MODEL_ERROR.
  • Sanitized Error Reporting (sanitizeDetail): Strips hex strings (>= 16 chars) and long numbers (>= 6 digits) 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:
    1. Length Cap: text.length <= TRANSLATE_MAX_TEXT (3,000 chars; slot values use TRANSLATE_MAX_VALUE = 200 chars on the client).
    2. Target Locale Whitelist (TRANSLATE_TARGETS): Strictly restricted to Slloy's 14 locale tags (en, zh-CN, zh-TW, ja, ko, de, fr, es, pt, it, nl, ru, ar, he).
    3. DB-Backed IP Rate Limit: scope: "translate", max 20 requests per minute per IP.
  • 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 ScriptScope & Target FilesKey Rules & Guards
tools/translate-ark.tsTranslates 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.tsTranslates Markdown/JSON blog posts across the 14 supported locales.Preserves internal link paths, code blocks, frontmatter slugs, and image URLs.
tools/translate-article-series.tsBatch-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.

On this page