vibe-surveyDocs

Overlay Runtime

Overlay translations are authored outside the Workbench at /overlay/[surveyId] and applied by Survey Link when a respondent opens /s/[surveyId]?lang=....

Authoring entrypoint

/overlay/[surveyId] loads the current survey HTML source, extracts translatable origin rows, and lets authors maintain per-language overlays without changing the canonical survey source.

Overlay origin rows include supported question text, option labels, attribute labels, group labels, section titles, loop item labels, redirect group titles, safe custom HTML text blocks, and internal Survey Link copy. Code-bearing DSL blocks such as <script>, <run-code>, <condition>, <validation>, <jump>, <screen-out>, <quota>, and <survey-config> are not translated as free text.

Per-language source format

The selected language editor stores a rootless fragment made only of <entry> tags:

<entry key="question:Q1:description">안녕하세요.</entry>
<entry key="question:Q1:option:1:label">예</entry>
<entry key="internal:action:next">다음</entry>

Rules:

  • Every <entry> needs a key matching the extracted origin rows.
  • The selected-language fragment must not wrap entries in <overlay> or <language>.
  • Full legacy <overlay><language>...</language></overlay> documents remain a compatibility read/split path, not the canonical selected-language source.
  • Inactive languages are preserved in the overlay document but are not valid runtime targets until reactivated.

XLSX import/export

Overlay XLSX export includes key, variable, origin, and one overlay:{language} column for each active requested language. Import updates the selected active language by matching key; unknown keys are skipped, missing overlay columns are rejected, and blank overlay cells are not written.

Survey Link resolves language in this order:

  1. No lang query, or lang equal to <survey-config origin-lang="..." />, renders the origin survey with overlayStatus="origin".
  2. A valid non-origin lang loads the active overlay language, parses its selected-language <entry> fragment, applies translations to the HTML source and internal runtime copy, and renders with overlayStatus="applied".
  3. Invalid, missing, inactive, incomplete, blank, or stale overlays render the language-unavailable page with overlayStatus="unavailable" and a reason such as invalid, missing, inactive, incomplete, blank, or stale.

The resolved Survey Link receives effective lang, text direction (dir), overlayStatus, and translated internal copy. RTL languages use RTL direction at the Survey Link root.

Origin language behavior

The origin language belongs to <survey-config origin-lang="en" />. Overlay authoring can promote or preserve the origin language, but the origin source remains the canonical HTML DSL. Overlay fragments are language-specific deltas for runtime rendering and XLSX maintenance, not replacement survey sources.