DF-833: language prioritization, rollout playbook + i18n/ index - #212
Conversation
Prioritization uses a signal Mixpanel already has: mixpanel.com publishes hreflang alternates for exactly en-US, ko-KR, ja-JP and id-ID. Marketing has already decided which non-English markets are worth translating for and paid for it, so docs should follow that list rather than invent one. Korean is in flight; Japanese is next; Indonesian third but verify against docs traffic first. Do not extend past Japanese on inference. docs.json already reports into a Mixpanel project, so pageviews by locale — and the measured lift after /ko ships — are a report away. That same report settles whether the API reference ever gets translated, for every language at once. Playbook makes a new language a checklist rather than a project: ~1 week, most of it native review. Configure (~1h), extend the glossary (~half a day, and before bulk translation — fixing terminology across 295 translated pages costs far more than deciding it once), translate (hours, unattended), validate (minutes, must exit 0), native review (~3-5 days, the only step that does not compress), then ship and watch. Also adds the reviewer checklist that the DF-831 workflow's PR body points at, and README.md as the entry point for the whole directory — landing last, once everything it indexes exists. Side finding for whoever owns the marketing site: mixpanel.com/ko/ returns 200 but currently serves English. The alternate is declared, the content is not there. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Confidence Score: 2/5The rollout playbook should be corrected before merging because following it can fail translation and navigation validation while leaving guides unchecked. The documented root-level config does not exist at this stage, the copied navigation labels cannot satisfy the required check, and validation covers only one of the two translated content trees. Files Needing Attention: i18n/04-rollout-playbook.md
|
| Filename | Overview |
|---|---|
| i18n/04-rollout-playbook.md | Adds the rollout procedure, but its config path, navigation check, and validation coverage make the documented workflow fail or miss content. |
| i18n/README.md | Adds a coherent i18n project index whose referenced files, anchors, and principal state claims match the repository. |
Reviews (1): Last reviewed commit: "DF-833: language prioritization, rollout..." | Re-trigger Greptile
![greptile-apps[bot]](https://cdn.statically.io/img/avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| ### 3 · Translate — hours, unattended | ||
|
|
||
| ```bash | ||
| npx gtx-cli translate --config gt.config.json # or: Mintlify dashboard → add locale |
There was a problem hiding this comment.
When an engineer follows this command from the repository root before the staged configuration is relocated, gtx-cli looks for nonexistent root-level gt.config.json instead of i18n/config/gt.config.json, causing translation to fail before it starts.
| # ...translate the values... | ||
|
|
||
| node i18n/scripts/build-locale-nav.mjs <locale> # → i18n/nav/<locale>.json | ||
| node i18n/scripts/build-locale-nav.mjs <locale> --check # must exit 0 |
There was a problem hiding this comment.
When an engineer copies labels.ko.json as instructed, the retained Community key is not consumed because the builder traverses only navigation.tabs; --check therefore reports it as unused and exits nonzero, blocking the rollout.
| node i18n/scripts/validate-mdx-parity.mjs \ | ||
| --source docs --target <locale>/docs \ | ||
| --locale <locale> --link-prefix --require-anchors --allow-code-comments |
There was a problem hiding this comment.
When a rollout contains both docs and guides, this step validates only <locale>/docs, leaving structural defects in translated guides undetected before review and publishing.
| node i18n/scripts/validate-mdx-parity.mjs \ | |
| --source docs --target <locale>/docs \ | |
| --locale <locale> --link-prefix --require-anchors --allow-code-comments | |
| node i18n/scripts/validate-mdx-parity.mjs \ | |
| --source docs --target <locale>/docs \ | |
| --locale <locale> --link-prefix --require-anchors --allow-code-comments | |
| node i18n/scripts/validate-mdx-parity.mjs \ | |
| --source guides --target <locale>/guides \ | |
| --locale <locale> --link-prefix --require-anchors --allow-code-comments |
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.
Adds:
04-rollout-playbook.md,README.mdREADME.mdis the entry point for the wholei18n/directory, and lands last in this stack so it never indexes files that don't exist yet.Prioritization uses a signal Mixpanel already has
mixpanel.compublisheshreflangalternates for exactly four locales:en-US,ko-KR,ja-JP,id-ID. Marketing has already decided which non-English markets are worth translating for and paid for it. Docs should follow that list rather than invent a new one — same markets, same sales motion, same customers.kojaides/pt-BR, thende/frDo not extend past Japanese on inference.
docs.jsonalready reports into a Mixpanel project, so pageviews by locale — and the measured lift after/koships — are a report away. That same report settles whether the API reference ever gets translated, for every language at once. We sell this product; we should use it.The playbook
A new language becomes a checklist, ~1 week, most of it review: configure (~1h) → extend the glossary (~½ day, before bulk translation) → translate (hours, unattended) → validate (minutes, must exit 0) → native review (~3–5 days, the only step that does not compress) → ship and watch.
Also adds the reviewer checklist that the DF-831 workflow's PR body points at.
Side finding worth routing onward
mixpanel.com/ko/returns 200 but currently serves English. The alternate is declared, the content is not there. Worth flagging to whoever owns the marketing site — a Korean docs launch may land before a Korean marketing site.