Repository navigation
feat(www): add multi-language docs - #55448
MrMushrooooom wants to merge 6 commits into
Conversation
![opencode-agent[bot]](https://avatars.githubusercontent.com/in/1549082?s=60&v=4){kind=small}
There was a problem hiding this comment.
Locale detection, redirects and rendering work as described, but I don't think this can deploy as it stands.
How I checked: bun typecheck and bun run build in services/www pass, including link validation. I also ran the built Worker locally with wrangler dev:
Accept-Language: degives a 308 to/v2/docs/de/....oc_locale=enkeeps English./v2/docs/zh/config/returnslang="zh-Hans", translated headings that keep the English IDs,Set-Cookie: oc_locale=zhand a cache MISS header.
Public API: unchanged. The SDK, server API, config, CLI and plugins are untouched. The only additions are the new docs URLs under /v2/docs/<code>/ and the docs now also setting the existing shared oc_locale cookie.
Blocking: the Worker bundle grows from about 6.6 MiB on the base to about 110.8 MiB. I measured both with wrangler deploy --dry-run ("Total Upload: 113422 KiB" vs "6727 KiB"). Cloudflare's limit is 64 MiB uncompressed, so the deploy will probably be rejected. Even if it went through, parsing that much code at startup risks the 1 s startup limit. The size comes from the server-rendered docs route (prerender = false), which bundles every compiled page for all 18 locales into the Worker. Details are in the inline comment.
Related: #43646
| import DocsPage from "../../docs/components/DocsPage.astro" | ||
| import { parseDocsPath } from "../../docs/lib/language" | ||
| import { getDocsPage } from "../../docs/lib/pages" | ||
|
|
||
| export const prerender = false |
There was a problem hiding this comment.
Because this route renders on the server, every compiled MDX page for all 18 locales (about 2,250 chunks plus a 13 MB data-layer module) goes into the Worker. wrangler deploy --dry-run reports Total Upload: 113422 KiB, up from 6727 KiB on the base, and Cloudflare's Worker limit is 64 MiB uncompressed. Could the pages be prerendered as static assets instead (the docs-index route already builds every locale), with the Worker or middleware handling only the locale redirect for unprefixed URLs and the Markdown responses? Those could read from the built assets, for example with run_worker_first on /v2/docs*. That would also remove the need for the hand-rolled caches.default layer that replaces Workers Cache.
|
Thanks for building the multi-language layer for the V2 docs — that is exactly the piece that was missing. Two things from my side that may be useful here:
What I would need from you:
I will not open a translation PR until this lands, to avoid a large conflict. |
All 61 pages under services/www/src/docs/content, placed at the locale path that anomalyco#55448 establishes (`content/vi/<path>`), so a Vietnamese reader gets Vietnamese documentation instead of English. Per page this keeps the English structure exactly: frontmatter key order, heading count and level sequence, fenced code blocks byte-identical, the inline-code spans, link targets with their anchors, table column counts, and component prop names. Code, commands, config keys, API paths, model and provider names, and the Mismatched-case product names (Model Context Protocol, Agent Client Protocol, Theme Tool) are left as written. Terminology follows the Vietnamese glossary: tác nhân, phiên, tệp, tiện ích mở rộng, nhà cung cấp, mô hình, lời nhắc, kỹ năng, không gian làm việc. Stacked on anomalyco#55448, which adds the multi-language routing and locale dictionaries this content needs.
|
Are you still planning to port this to If you are not continuing, I would like to take it over: port the locale layer to the new docs tree, reuse the translations from this PR with credit, and land Turkish first. I will open a feature request for the Would you rather port it yourself, or hand it off? |
|
@akiciemir For the Vietnamese side: I am not porting it, so take it over — and the translations are there to reuse.
I had a per-page comparison against the English source (heading levels and counts, code fences, inline code, link targets, table shapes). I can re-run it on the new tree once there is a structure to compare against, if that helps. |
|
Thanks, that's generous. I'll take the Vietnamese content too, alongside Turkish, once the locale layer has an approved home in Yes please to the per-page comparison script when there is a structure to compare against. And thanks for the glossary; I'll use its shape for Turkish. I'm holding implementation PRs until the structure is agreed. #56316 was closed and #55448 still targets the removed tree, so I'll ask in Discord about the current plan. |
|
Update on my previous comment. Discord is blocked in Turkey, so I can't use the community channel to ask about the V2 docs plan. With #56316 closed and #55448 still targeting the removed tree, I don't have a route to design approval. I'm cancelling the Turkish and Vietnamese translation work. Thanks @dat-rd for offering the Vietnamese pages and glossary; they stay available on your branch. If the locale layer lands or a maintainer picks this up, I can revisit. |
Issue for this PR
N/A
Type of change
What does this PR do?
Adds multi-language support to the V2 docs (
services/www) using the same 18 locales and codes as opencode.ai, and translates all 62 pages into the 17 non-English locales./v2/docs/...; other locales live at/v2/docs/<code>/...(e.g./v2/docs/zh/). Translations mirror the English path undercontent/<code>/. Internal links, the header, the sidebar, and cards keep the reader's locale./dataproxy): URL prefix, then the sharedoc_localecookie, thenAccept-Language. Unprefixed pages 308-redirect to the preferred locale. The footer language picker sets the cookie. Because Workers Cache would serve cached pages before this redirect runs, it's replaced by acaches.defaultcache keyed by the locale-specific URL (x-opencode-docs-cacheheader shows HIT/MISS).#anchorlinks work in every locale..tsdictionaries followingpackages/console/app/src/i18n.compaction.keep.tokens(wascompaction.tokens), the credit card fee (4.6% + $0.31), auto-recharge on the Console models page, and a "Rename a workspace" section.No changes outside
services/www, except onebun.lockline forgithub-slugger.How did you verify your code works?
bun run checkat the repo root;bun typecheck,bun run check:generated, andbun run buildinservices/www. The build includes link and anchor validation for every locale, and Pagefind indexes 18 languages / 1134 pages.Accept-Language, an explicit English choice sticking, cache HIT/MISS, and unchangedllms.txt, API reference, inference redirect, and Markdown responses.Screenshots / recordings
Verified locally in the browser (footer language picker, translated sidebar and content, Arabic RTL layout).
Checklist
Added by the opencode bot (AI-generated).
Related: #43646