DF-831: staged CI workflow — delta-translate on merge, open a PR

[spjtls9]

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

Blocked by: #210 (DF-830) — this PR is branched off it, so review only the diff shown here.
Blocks: #212 (DF-833) 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
6	#210	DF-830	Staged translation config
▸ 7	#211	DF-831	Staged CI workflow ← this PR
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: config/translate.yml; expands config/README.md to cover both files

Staged at i18n/config/translate.yml, not .github/workflows/. Installed early it runs on every merge to main and fails — no secrets, and gt.config.json targets a navigation path that does not exist yet.

⚠️ This PR may need to be closed rather than merged

If Mintlify-native translations win the DF-827 decision, delete translate.yml — Mintlify opens the translation PR itself, on a continuous schedule, with a human merge gate. This workflow would be a duplicate pipeline for a feature we already pay for.

The flow

push to main touching docs/, guides/, docs.json or the glossary → gtx-cli delta translation via gt-lock.json → validation gate → create-pull-request against main with an i18n label and a reviewer checklist. concurrency: cancel-in-progress so a later push supersedes an in-flight run.

The part worth keeping regardless of engine

validate-mdx-parity.mjs --link-prefix --require-anchors --allow-code-comments
build-locale-nav.mjs ko --check
build-glossary.mjs ko --check

A translation that renames a <Frame>, translates a code identifier, drops an import, unprefixes a link, or drifts a heading anchor looks exactly like a normal diff to a reviewer. Something has to prove it did not break 914 <Frame> tags, 2,721 links, and 3,723 heading anchors — and Mintlify's own translation PR needs that gate just as much as ours would.

So if we go native: delete translate.yml, keep those three steps as a small verify-i18n.yml. The recipe is in config/README.md.

Reviewer burden, deliberately narrowed

Because structure is machine-verified, the PR body this workflow generates asks reviewers only for what a machine cannot judge: glossary adherence, the 리텐션/데이터 보관 split, particles after Latin words, register, and a rendered layout check.

Secrets needed before this can move

GT_API_KEY and GT_PROJECT_ID as repo secrets — only if General Translation wins.

[linear-code]

DF-831

[greptile-apps]

Confidence Score: 4/5

The workflow should not be activated until glossary artifacts are generated before validation; dependency pinning is also advisable.

A source-glossary change reaches a check-only validation step without any preceding artifact generation, preventing the promised translation PR from being opened.

Files Needing Attention: i18n/config/translate.yml

Security Review

The staged workflow uses mutable action tags and an unpinned CLI despite granting write permissions and exposing translation-provider credentials when activated.

Important Files Changed

Filename	Overview
i18n/config/translate.yml	Adds the staged translation workflow, but glossary-only source changes fail its check-only artifact gate and executable dependencies are not immutable.
i18n/config/README.md	Clearly documents staging, activation prerequisites, and the Mintlify-native fallback.

Sequence Diagram

sequenceDiagram
    participant Main as Push to main
    participant CI as Translation workflow
    participant GTX as gtx-cli
    participant Gate as Validation gate
    participant PR as Translation PR
    Main->>CI: Matching documentation change
    CI->>GTX: Delta translation
    GTX-->>CI: Localized changes
    CI->>Gate: MDX, navigation, glossary checks
    alt All checks pass
        Gate-->>CI: Valid
        CI->>PR: Open review PR
    else Any check fails
        Gate-->>CI: Failure
        CI--xPR: No PR opened
    end

Loading

_{Reviews (1): Last reviewed commit: "DF-831: staged CI workflow — delta-trans..." | Re-trigger Greptile}

[greptile-apps]

Glossary artifacts are never generated

When the source glossary changes without separately regenerated artifacts, this workflow invokes only build-glossary.mjs --check, causing validation to fail before the translation PR is opened.

Suggested change

	- name: Check the glossary artifacts are in sync
	run: node i18n/scripts/build-glossary.mjs ko --check
	- name: Generate and check glossary artifacts
	run: |
	node i18n/scripts/build-glossary.mjs ko
	node i18n/scripts/build-glossary.mjs ko --check

Source Used: Linear — [M3] Build CI: delta-translate on merge to main → open PR

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!

[greptile-apps]

Workflow dependencies remain mutable

Once activated, the workflow resolves mutable action tags and an unpinned gtx-cli while granting repository write permissions and exposing provider credentials, increasing supply-chain risk and allowing incompatible releases to break translation runs. How this was verified: The workflow contains no immutable references or package lock, and its executable steps receive write permissions or provider secrets.