DF-828: pilot Korean translations (3 pages, hand-translated)

[spjtls9]

📚 Part 5 of an 8-PR stack — merge in order

Blocked by: #208 (DF-824) — this PR is branched off it, so review only the diff shown here.
Blocks: #210 (DF-830) and everything after it in the stack.

Do not merge out of order. Each PR is branched off the one above it; merging ahead of its base pulls
in unreviewed commits. As each lands, GitHub retargets the next onto main automatically.

	PR	Issue	Scope
1	#205	DF-823	Plan & entitlement findings
2	#206	DF-826	Scope, spec, glossary, validator
3	#207	DF-827	Engine evaluation
4	#208	DF-824	Korean navigation tree
▸ 5	#209	DF-828	Pilot Korean translations ← this PR
6	#210	DF-830	Staged translation config
7	#211	DF-831	Staged CI workflow
8	#212	DF-833	Prioritization, playbook, index

Documents in i18n/ cross-reference each other, so relative links to files added later in the stack
resolve once the stack has landed. The final state is link-checked; every relative link resolves.

Operational sequencing — none of this happens on merge

Merging this stack changes nothing a reader sees. docs.json is untouched, no workflow is installed, and
no ko/ tree exists at the repo root. Turning Korean on is a separate, deliberate sequence:

Step	Action	Gated on
1	Mintlify dashboard → Settings → Translations — confirm the feature, and whether it exposes glossary control	DF-823
2	Run the 12-page bake-off; pick the engine	step 1
3	Apply the docs.json languages array; cp i18n/nav/ko.json ./ko.json	steps 1–2
4	Bulk-translate docs/ + guides/ into ko/	steps 2–3
5	Native Korean review (~3–5 days) — the step that does not compress	step 4
6	Only if General Translation won: move gt.config.json to root, translate.yml to .github/workflows/, set GT_API_KEY + GT_PROJECT_ID	steps 2–4
7	Backfill/reconcile, then publish /ko	steps 5–6

Steps 3 and 6 are the only ones that change live behaviour. Both are reversible by reverting one file.

---

Three pages, hand-translated. Not a sample of bulk output.

Adds: pilot/README.md, pilot/ko/docs/** (3 .mdx)

Why only three

These are the quality bar engines get scored against in the DF-827 bake-off, and the proof the DF-826 spec is achievable before we ask an engine to hit it.

Bulk translation of the remaining 292 pages is intentionally held until the engine decision lands. Running 295 pages through the wrong engine — or through any engine before confirming whether Mintlify's built-in translations are already on (DF-823) — is the expensive mistake this issue can make.

Chosen to exercise what breaks machine translation

Page	Exercises
what-is-mixpanel.mdx	Unused /snippets/*.jsx import, <Frame> wrapping a raw <iframe> with 5 boolean JSX attrs, same-page #fragment links, escaped \$2.50
data-structure/concepts.mdx	44-line JSON fence that is 27 lines of English commentary, 4- and 2-column tables with <br /> and inline code in cells, 8 internal links
quickstart/capture-events/autocapture.mdx	Snippet import, code fences with trailing whitespace preserved

All three pass the validator on strictest settings, zero warnings:

node i18n/scripts/validate-mdx-parity.mjs \
  --source docs/data-structure/concepts.mdx \
  --target i18n/pilot/ko/docs/data-structure/concepts.mdx \
  --locale ko --link-prefix --require-anchors --allow-code-comments

What they settled

Heading anchors are solvable by convention — ## 이벤트의 구조 [#anatomy-of-an-event] keeps /ko/docs/...#anatomy-of-an-event resolving, so cross-locale deep links stay portable.

Code comments needed an explicit rule — concepts.mdx would otherwise leave the most important explanation on the page in English.

Inert

Staged under i18n/pilot/ — no route, no build impact. Promote once docs.json carries the languages array (DF-824): mkdir -p ko && cp -r i18n/pilot/ko/docs ko/

Reviewing

This one genuinely needs a Korean reader. The structure is machine-verified; what needs human eyes is whether the Korean is any good — terminology against i18n/glossary/ko.csv, register (-합니다 / -하세요), and particles after Latin words.

[linear-code]

DF-828

[greptile-apps]

Confidence Score: 4/5

The PR appears safe to merge, with a non-blocking glossary-consistency issue in two Korean reference pages.

The translated pages remain inert and preserve their source structure and technical meaning; only the glossary’s first-use bilingual terminology convention needs correction.

Files Needing Attention: i18n/pilot/ko/docs/what-is-mixpanel.mdx and i18n/pilot/ko/docs/data-structure/concepts.mdx

Important Files Changed

Filename	Overview
i18n/pilot/README.md	Documents the pilot’s purpose, validation commands, preservation decisions, and intentionally inert deployment state.
i18n/pilot/ko/docs/data-structure/concepts.mdx	Preserves MDX and executable JSON structure, but first-use report names do not follow the glossary’s bilingual convention.
i18n/pilot/ko/docs/quickstart/capture-events/autocapture.mdx	Faithfully translates the prose while preserving the import and JavaScript examples.
i18n/pilot/ko/docs/what-is-mixpanel.mdx	Preserves JSX, assets, links, and anchors, but the first 코호트 occurrence omits its English gloss.

_{Reviews (1): Last reviewed commit: "DF-828: pilot Korean translations — thre..." | Re-trigger Greptile}

[greptile-apps]

Missing first-use English terms

The first occurrences of 코호트 here and 퍼널, 리텐션, and 브레이크다운 in concepts.mdx omit the glossary-required English terms in parentheses. This makes the reference translations inconsistent with the terminology convention required by the automatically discovered DF-826.

Source Used: Linear — [M2] Define Korean translation scope, preservation spec, and glossary

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!