Instant Translate Storefront Texts (v1)

Method & Path

POST /api/v1/public/storefront/stores/:slug/translate

Actual backend path: /v1/public/storefront/stores/:slug/translate

Description

Machine-translate catalog / CMS strings for the public storefront (product names, category names, marquee, etc.). Translations are not entered manually — they are generated via Google Cloud Translation (preferred) or OpenAI, and cached.

Personas:

• Customer: uses this endpoint from the storefront when the Workspace Owner has enabled instant translation.
• Workspace Owner / Staff (store.manage): enable the feature with appearance.instantTranslationEnabled on Update Store.

Authentication

None (public). Requires appearance.instantTranslationEnabled === true on the store; otherwise returns 403.

Headers

Header	Type	Required	Description
Content-Type	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
slug	string	Yes	Public store slug

Request Body

{
  "texts": ["كريم مرطب", "سيروم فيتامين سي"],
  "targetLanguage": "he",
  "sourceLanguage": "ar"
}

Field	Type	Required	Description
texts	string[]	Yes	1–80 strings, each ≤ 4000 chars; total ≤ 24000 chars
targetLanguage	"ar" | "en" | "he"	Yes	Customer display language
sourceLanguage	"ar" | "en" | "he" | "auto"	No	Content language (defaults to auto)

Response 200 OK

{
  "translations": [
    { "source": "كريم مرطب", "translated": "קרם לחות" },
    { "source": "سيروم فيتامين سي", "translated": "סרום ויטמין C" }
  ],
  "provider": "google",
  "cachedCount": 0,
  "translatedCount": 2
}

Field	Description
provider	google | openai | identity | cache
cachedCount	Strings served from cache
translatedCount	Strings freshly translated in this request

Common Errors

• 400 Bad Request: Invalid body, or neither Google credentials nor OPENAI_API_KEY configured
• 403 Forbidden: Instant translation disabled for this store
• 404 Not Found: Store slug not found / unpublished
• 500 Internal Server Error: Unexpected provider failure