DF-827: translation engine evaluation and recommendation

[spjtls9]

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

Blocked by: #206 (DF-826) — this PR is branched off it, so review only the diff shown here.
Blocks: #208 (DF-824) 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 ← this PR
4	#208	DF-824	Korean navigation tree
5	#209	DF-828	Pilot Korean translations
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.

---

Adds one file: i18n/03-tooling-evaluation.md

Recommendation

Start with Mintlify's built-in AI translations. Keep General Translation as the documented fallback. Do not adopt Lingo.dev.

The disqualifying criterion

The 710 internal links carrying a #fragment (see the DF-826 PR earlier in this stack). An engine that cannot pin English heading anchors breaks them silently.

• General Translation solves it in configuration — experimentalAddHeaderAnchorIds: "mintlify"
• Lingo.dev has no published equivalent
• Mintlify-native is silent on it — which is exactly what the bake-off measures

Strongest evidence for the fallback

mintlify/docs — Mintlify's own documentation repo — runs on General Translation. At HEAD it has gt.config.json, gt-lock.json, es/ fr/ zh/ content trees, and per-locale nav files $ref'd from docs.json. The people who wrote the MDX renderer chose this tool to localize their own docs.

How to settle it in an afternoon

A 12-page bake-off covering every structural pattern in the corpus, scored by validate-mdx-parity.mjs so the answer is a number rather than a preference:

node i18n/scripts/validate-mdx-parity.mjs --source docs --target <engine-out>/docs \
  --locale ko --link-prefix --require-anchors --json

Then four human checks on those twelve only: glossary adherence, the 리텐션/데이터 보관 split, particles after Latin words, and register.

Twelve pages to find out beats guessing across 295.

This decision has downstream consequences in this stack

If Mintlify-native wins, the DF-830 and DF-831 PRs later in this stack should be closed rather than merged — Mintlify opens the translation PR itself, so there is no config to write and no workflow to install. Only the three validation steps survive. That is flagged in both of those PRs.

[linear-code]

DF-827

[greptile-apps]

Confidence Score: 4/5

The documented bake-off command should be corrected before merging because it cannot produce the stated 12-page evaluation.

The validator recursively processes all MDX beneath docs and excludes listed root-level guides and reference fixtures, so its output does not measure the proposed sample.

Files Needing Attention: i18n/03-tooling-evaluation.md

Important Files Changed

Filename	Overview
i18n/03-tooling-evaluation.md	Adds the tooling recommendation and bake-off procedure, but the validator command does not select the stated cross-directory sample.

_{Reviews (1): Last reviewed commit: "DF-827: translation engine evaluation an..." | Re-trigger Greptile}

[greptile-apps]

Bake-off selects wrong files

When an evaluator runs this command, --source docs recursively validates the entire docs/ tree while excluding the listed root-level guides/ and reference/ fixtures, so it cannot produce the promised representative 12-page score.