DF-824: Korean navigation tree (staged — docs.json untouched) - #208
Conversation
…ched Everything DF-824 needs, built and verified, without making the config change. docs.json is not modified by this PR. - labels.ko.json — all 128 navigation labels translated per the DF-826 terminology policy - ko.json — generated Korean nav tree: 5 tabs, 390 page paths prefixed `ko/` - build-locale-nav.mjs — regenerates it deterministically. `--check` fails when docs.json gains a label with no Korean or the map keeps a stale one, so the nav cannot silently rot; `--drop-tab` supports the DF-826 scope decision to defer the API reference. - preview-docsjson-patch.mjs — prints, and optionally stages, the exact docs.json change without making it. The change itself is one shape: navigation.tabs becomes navigation.languages[], the existing tree becomes the `en` entry, and Korean is $ref'd out to ./ko.json — the layout Mintlify uses for their own docs. English stays at the repo root, so no English URL changes and enabling it is a no-op for English readers. Two decisions for whoever applies it, both written up in nav/README.md: global anchors cannot be localized per-locale (recommend leaving them shared), and whether the API Docs tab belongs in the Korean nav at all. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Confidence Score: 4/5The PR appears safe to merge, with two non-blocking gaps in navigation drift validation and its documentation. The generated assets and preview transformation are coherent, but Files Needing Attention: i18n/scripts/build-locale-nav.mjs, i18n/nav/README.md
|
| Filename | Overview |
|---|---|
| i18n/scripts/build-locale-nav.mjs | Generates translated locale navigation, but check mode does not verify that committed generated output is current. |
| i18n/scripts/preview-docsjson-patch.mjs | Safely previews the current tabs/global navigation conversion without modifying docs.json. |
| i18n/nav/README.md | Documents rollout decisions but references a nonexistent CI configuration. |
| i18n/nav/ko.json | Adds the generated five-tab Korean navigation tree. |
| i18n/nav/labels.ko.json | Adds the Korean translation map consumed by the generator. |
Reviews (1): Last reviewed commit: "DF-824: Korean navigation tree, staged —..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| if (checkOnly) { | ||
| console.log(missing.size || unused.size ? "check: FAIL" : "check: OK"); | ||
| process.exit(missing.size || unused.size ? 1 : 0); |
There was a problem hiding this comment.
--check validates only missing and unused labels without comparing the generated tree against committed ko.json. Page-path, ordering, nesting, or icon changes therefore still report check: OK while leaving the generated navigation stale.
| # 1. see exactly what changes | ||
| node i18n/scripts/preview-docsjson-patch.mjs ko --write |
There was a problem hiding this comment.
The README says --check runs in config/translate.yml, but that configuration and any equivalent workflow invocation are absent. Maintainers are therefore told CI prevents navigation drift when the check is not automated.
1 participant
Documents in
i18n/cross-reference each other, so relative links to files added later in the stackresolve 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.jsonis untouched, no workflow is installed, andno
ko/tree exists at the repo root. Turning Korean on is a separate, deliberate sequence:docs.jsonlanguagesarray;cp i18n/nav/ko.json ./ko.jsondocs/+guides/intoko/gt.config.jsonto root,translate.ymlto.github/workflows/, setGT_API_KEY+GT_PROJECT_ID/koSteps 3 and 6 are the only ones that change live behaviour. Both are reversible by reverting one file.
Everything DF-824 needs, built and verified — without making the config change.
Adds:
nav/{README.md,ko.json,labels.ko.json},scripts/{build-locale-nav.mjs,preview-docsjson-patch.mjs}What's here
labels.ko.json— all 128 navigation labels translated per the DF-826 terminology policyko.json— generated Korean nav tree: 5 tabs, 390 page paths prefixedko/build-locale-nav.mjs— regenerates it deterministically.--checkfails whendocs.jsongains a label with no Korean or the map keeps a stale one, so the nav cannot silently rot.--drop-tabsupports the DF-826 scope decision to defer the API reference.preview-docsjson-patch.mjs— prints, and optionally stages, the exactdocs.jsonchange without making itThe change itself, when someone applies it
One shape:
navigation.tabsbecomesnavigation.languages[], the existing tree becomes theenentry, and Korean is$ref'd out to./ko.json— the layout Mintlify uses for their own docs. English stays at the repo root, so no English URL changes and enabling it is a no-op for English readers. Reversible by reverting one file.Two decisions for whoever applies it
Both written up in
nav/README.md:navigation.global.anchors(About Us / Community / Blog) is shared across every language by design. Korean strings are staged under_global_anchorsif you'd rather move them into each language entry. Recommend leaving them shared — three English words in the top bar beats a nav that drifts per locale.ko.jsoncurrently mirrors English exactly. If the API reference is deferred per DF-826, regenerate with--drop-tab="API Docs".