vibe-survey문서

Overlay Runtime

Overlay translation은 Workbench 밖의 /overlay/[surveyId]에서 작성하고, 응답자가 /s/[surveyId]?lang=...로 Survey Link를 열 때 적용됩니다.

Authoring entrypoint

/overlay/[surveyId]는 현재 survey HTML source를 로드하고 번역 가능한 origin row를 추출한 뒤, canonical survey source를 바꾸지 않고 language별 overlay를 관리하게 합니다.

Overlay origin row에는 지원되는 question text, option label, attribute label, group label, section title, loop item label, redirect group title, 안전한 custom HTML text block, 내부 Survey Link copy가 포함됩니다. <script>, <run-code>, <condition>, <validation>, <jump>, <screen-out>, <quota>, <survey-config> 같은 code-bearing DSL block은 자유 텍스트 번역 대상으로 다루지 않습니다.

Per-language source format

선택된 language editor는 <entry> tag만 포함하는 rootless fragment를 저장합니다.

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

규칙:

  • 모든 <entry>는 추출된 origin row와 일치하는 key가 필요합니다.
  • 선택 language fragment는 <overlay> 또는 <language> wrapper를 포함하지 않습니다.
  • 전체 legacy <overlay><language>...</language></overlay> document는 호환용 read/split path일 뿐 canonical selected-language source가 아닙니다.
  • 비활성 language는 overlay document에 보존되지만 다시 활성화되기 전에는 runtime target으로 사용할 수 없습니다.

XLSX import/export

Overlay XLSX export는 key, variable, origin, 그리고 요청된 active language별 overlay:{language} column을 포함합니다. Import는 key를 기준으로 선택된 active language를 업데이트합니다. 알 수 없는 key는 skip하고, overlay column이 없으면 reject하며, 빈 overlay cell은 쓰지 않습니다.

Survey Link는 language를 다음 순서로 해석합니다.

  1. lang query가 없거나 <survey-config origin-lang="..." />와 같은 lang이면 origin survey를 overlayStatus="origin"으로 렌더링합니다.
  2. 유효한 non-origin lang이면 active overlay language를 로드하고 selected-language <entry> fragment를 파싱해 HTML source와 internal runtime copy에 적용한 뒤 overlayStatus="applied"로 렌더링합니다.
  3. invalid, missing, inactive, incomplete, blank, stale overlay는 language-unavailable page를 overlayStatus="unavailable"와 invalid, missing, inactive, incomplete, blank, stale 같은 reason으로 렌더링합니다.

Resolved Survey Link는 effective lang, text direction(dir), overlayStatus, translated internal copy를 받습니다. RTL language는 Survey Link root에 RTL direction을 적용합니다.

Origin language behavior

Origin language는 <survey-config origin-lang="en" />가 소유합니다. Overlay authoring은 origin language를 promote 또는 preserve할 수 있지만, origin source는 계속 canonical HTML DSL입니다. Overlay fragment는 runtime rendering과 XLSX maintenance를 위한 language-specific delta이며 replacement survey source가 아닙니다.