Skip to content

Commit 866fb26

Browse files
authored
perf(site): ship each page only its own strings, in its own language (#62278)
1 parent a74e2d3 commit 866fb26

63 files changed

Lines changed: 1322 additions & 504 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.opencode/agent/translator.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,14 +24,14 @@ If no locale-specific glossary exists, use the global glossary only.
2424

2525
# Website Copy (opencode.ai)
2626

27-
When translating the marketing site (`services/site/src/i18n/<locale>.ts` and `src/i18n/content/<locale>.ts`):
27+
When translating the marketing site (`services/site/src/i18n/<locale>.ts` and `services/site/src/i18n/content/<locale>.ts`):
2828

2929
- Keep every `{{param}}`, every link id in `[text](id)` (translate the text, keep the id) and every `` `code` `` span exactly.
3030
- Keep these names as written: OpenCode, OpenCode Models, OpenCode Go, OpenCode Go Plus, Claude Opus 5.5, Anomaly, Console, and every company, model and app name.
3131
- Never describe OpenCode as an AI coding agent: it is an "open source coding agent". Do not add "AI" to that phrase in any language. "AI models" and "AI providers" are fine.
3232
- Prefer natural phrasing over literal translation. Use statements, not questions. Avoid colons where the language allows another construction.
3333
- Keep strings about as long as the English. Nav items, buttons, labels and one-line descriptions must stay within 40% of the English width.
34-
- Validate with `bun i18n/check.ts <locale>` from the worktree parent folder before you finish.
34+
- From `services/site`, run `bun src/i18n/check.ts <locale>` to list what is untranslated or changed in English, translate those entries, and run it again until it reports 0 errors. Then run `bun src/i18n/check.ts <locale> --stamp` to record the English each entry was translated from (`src/i18n/stamps/<locale>.json`).
3535

3636
---
3737

‎services/site/DESIGN.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -128,9 +128,10 @@ Motion decisions follow Emil Kowalski's skills ([emilkowalski/skills](https://gi
128128
## i18n and RTL
129129

130130
- Put new copy in `src/i18n/en.ts` (or `src/i18n/content`), never hard-coded in a component.
131-
- Follow the translators' rules in `i18n/packets.md` (keep names, params, code and prices; stay within 140% in tight places).
131+
- Name a key in full where the page shows it (`i18n.t("home.hero.title")`, or a template that starts it, such as `` `site.theme.${name}` ``): each page's browser bundle gets only the keys its code names (`script/i18n-slices.ts`).
132+
- Follow the translators' rules in `.opencode/agent/translator.md` (keep names, params, code and prices; stay within 140% in tight places), and check a locale with `bun src/i18n/check.ts <locale>`.
132133
- Lay out with logical properties (`padding-inline-start`, `inset-inline-end`), never left and right; the site ships 17 locales with right to left.
133-
- Keep the locale prefix on internal links with `language.route()`.
134+
- Keep the locale prefix on internal links with `language.route()`; it leaves the docs, the Console and the English-only pages unprefixed (`localized` in `src/lib/language.ts`).
134135

135136
## Options and flags
136137

‎services/site/script/check-locale-switch.ts‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,10 @@ import { tmpdir } from "os"
1212
import { join } from "path"
1313

1414
const base = process.argv[2] ?? "http://localhost:3011"
15-
const steps = ["es", "fr", "ar"]
15+
// Ends in English, whose address has no prefix, so Back and Forward cross between a prefixed and an
16+
// unprefixed address.
17+
const steps = ["es", "fr", "ar", "en"]
18+
const address = (locale: string) => (locale === "en" ? "/" : `/${locale}`)
1619

1720
const tmp = await mkdtemp(join(tmpdir(), "locale-switch-"))
1821
await Bun.$`bun add playwright@1.57.0 && bunx playwright install chromium`.cwd(tmp).quiet()
@@ -71,7 +74,7 @@ const expected = Object.fromEntries(
7174
await Promise.all(
7275
["ja", ...steps].map(async (locale) => {
7376
const page = await reference.newPage()
74-
await page.goto(`${base}/${locale}`, { waitUntil: "networkidle" })
77+
await page.goto(`${base}${address(locale)}`, { waitUntil: "networkidle" })
7578
return [locale, await snapshot(page)] as const
7679
}),
7780
),
@@ -83,13 +86,13 @@ const devices = [
8386
name: "desktop",
8487
options: { viewport: { width: 1440, height: 900 } },
8588
open: '[data-component="language-picker"] [data-slot="trigger"]',
86-
item: (locale: string) => `[data-component="language-picker"] [data-slot="dropdown"] a[href="/${locale}"]`,
89+
item: (locale: string) => `[data-component="language-picker"] [data-slot="dropdown"] a[href="${address(locale)}"]`,
8790
},
8891
{
8992
name: "phone",
9093
options: { viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true },
9194
open: '[data-component="language-picker"] [data-slot="trigger"]',
92-
item: (locale: string) => `a[data-slot="row"][href="/${locale}"]`,
95+
item: (locale: string) => `a[data-slot="row"][href="${address(locale)}"]`,
9396
},
9497
]
9598
for (const device of devices) {
@@ -102,18 +105,18 @@ for (const device of devices) {
102105
trigger?.click()
103106
}, device.open)
104107
await page.evaluate((selector) => document.querySelector<HTMLElement>(selector)?.click(), device.item(locale))
105-
await page.waitForURL(`${base}/${locale}`)
108+
await page.waitForURL(`${base}${address(locale)}`)
106109
await page.waitForFunction((lang) => document.documentElement.dataset.locale === lang, locale, { timeout: 5000 })
107110
compare(`${device.name} picker → ${locale}`, await snapshot(page), expected[locale])
108111
}
109112
await page.goBack()
110-
await page.waitForURL(`${base}/fr`)
111-
await page.waitForFunction(() => document.documentElement.dataset.locale === "fr", undefined, { timeout: 5000 })
112-
compare(`${device.name} back → fr`, await snapshot(page), expected.fr)
113-
await page.goForward()
114113
await page.waitForURL(`${base}/ar`)
115114
await page.waitForFunction(() => document.documentElement.dataset.locale === "ar", undefined, { timeout: 5000 })
116-
compare(`${device.name} forward → ar`, await snapshot(page), expected.ar)
115+
compare(`${device.name} back → ar`, await snapshot(page), expected.ar)
116+
await page.goForward()
117+
await page.waitForURL(`${base}/`)
118+
await page.waitForFunction(() => document.documentElement.dataset.locale === "en", undefined, { timeout: 5000 })
119+
compare(`${device.name} forward → en`, await snapshot(page), expected.en)
117120
await context.close()
118121
}
119122

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
// The translation slices in the client build (script/i18n-slices.ts works out what goes in each):
2+
//
3+
// - each locale gets a table module (virtual:i18n/<locale>) holding the shell's strings and where each
4+
// other slice is, each slice a module of its own (virtual:i18n/<locale>/<slice>), and
5+
// src/i18n/tables.ts becomes the 18 tables;
6+
// - src/i18n/english.ts keeps only the English the browser reads in every language;
7+
// - every import() of a lazy boundary (a page route, a module only ever loaded with import())
8+
// loads the boundary's slice alongside it and resolves once both have arrived, so the boundary's
9+
// code never runs before its strings (a top-level await in the boundary would do the same, but
10+
// makes Rolldown split the shared chunks differently);
11+
// - the server reads where the files went (virtual:i18n-preload) to preload a page's own
12+
// (src/i18n/preload.ts), so no string costs a round trip before hydration.
13+
//
14+
// The development server and the Worker keep the source files whole.
15+
import path from "node:path"
16+
import { fileURLToPath } from "node:url"
17+
import { spawnSync } from "node:child_process"
18+
import type { Plugin } from "vite"
19+
import type { result as Result } from "./i18n-slices"
20+
21+
type Slices = typeof Result
22+
23+
// Vite ids use forward slashes on every platform.
24+
const slashes = (file: string) => file.replaceAll("\\", "/")
25+
const root = slashes(fileURLToPath(new URL("..", import.meta.url)))
26+
const runtime = path.posix.join(root, "src/i18n/index.ts")
27+
const tablesFile = path.posix.join(root, "src/i18n/tables.ts")
28+
const englishFile = path.posix.join(root, "src/i18n/english.ts")
29+
// An import() of a module, with any spaces or comments (such as /* @vite-ignore */) inside.
30+
const dynamicImport = /\bimport\(\s*(?:\/\*[\s\S]*?\*\/\s*)*(["'])([^"'`]+)\1\s*\)/g
31+
32+
export function i18nSlices(): Plugin {
33+
let build = false
34+
let slices: Slices | undefined
35+
// Output file of each virtual module in the client build, by its id.
36+
const files = new Map<string, string>()
37+
const client = (environment: { name: string }) => build && environment.name === "client"
38+
const analyze = () => {
39+
if (slices) return slices
40+
const run = spawnSync("bun", ["script/i18n-slices.ts", "--json"], { cwd: root, maxBuffer: 256 * 1024 * 1024 })
41+
if (run.status !== 0) throw new Error(`i18n-slices failed:\n${run.stderr}`)
42+
slices = JSON.parse(run.stdout.toString()) as Slices
43+
return slices
44+
}
45+
const boundary = (id: string) => analyze().boundaries[slashes(id).split("?")[0]]
46+
const routes = () => Object.keys(analyze().boundaries).filter((file) => file.startsWith(`${root}src/routes/`))
47+
// The page routes whose import() in SolidStart's route list loads their slice (checked in generateBundle).
48+
const routed = new Set<string>()
49+
50+
return {
51+
name: "i18n-slices",
52+
enforce: "post",
53+
configResolved(config) {
54+
build = config.command === "build"
55+
},
56+
resolveId(id) {
57+
if (id.startsWith("virtual:i18n")) return `\0${id}`
58+
},
59+
load(id) {
60+
// Read by the server only; the browser's copy is empty.
61+
if (id === "\0virtual:i18n-preload")
62+
return `export default ${JSON.stringify(build && this.environment.name !== "client" ? preloads() : null)}`
63+
if (!client(this.environment)) return
64+
const data = analyze()
65+
if (id === englishFile) return `export const english = ${json(data.english)}`
66+
if (id === tablesFile)
67+
return `export const tables = {\n${Object.keys(data.locales)
68+
.map((locale) => ` ${JSON.stringify(locale)}: () => import("virtual:i18n/${locale}").then((module) => module.default),`)
69+
.join("\n")}\n}`
70+
const match = id.match(/^\0virtual:i18n\/(\w+)(?:\/([\w-]+))?$/)
71+
if (!match) return
72+
const locale = data.locales[match[1] as keyof Slices["locales"]]
73+
if (match[2] === "all") return `export default ${json(locale.full)}`
74+
if (match[2]) return `export default ${json(locale.slices[match[2]])}`
75+
// The shell's strings are in the table itself, which every page loads anyway; an empty slice
76+
// has no entry.
77+
const entries = Object.keys(data.shared).flatMap((slice) => {
78+
const payload = locale.slices[data.shared[slice]]
79+
if (slice === "shell") return [` shell: ${json(payload)},`]
80+
if (!Object.keys(payload.dict).length && !Object.keys(payload.content).length) return []
81+
return [` ${JSON.stringify(slice)}: () => import("virtual:i18n/${match[1]}/${data.shared[slice]}"),`]
82+
})
83+
return `export default {\n slices: {\n${entries.join("\n")}\n },\n all: () => import("virtual:i18n/${match[1]}/all"),\n}`
84+
},
85+
async transform(code, id) {
86+
if (!client(this.environment) || id.startsWith("\0") || slashes(id).includes("/src/i18n/")) return
87+
const slices = new Map<string, string>()
88+
for (const match of code.matchAll(dynamicImport)) {
89+
const target = await this.resolve(match[2], id)
90+
const slice = target && boundary(target.id)
91+
if (!target || !slice) continue
92+
slices.set(match[0], slice)
93+
if (id === "solid-start:routes") routed.add(slashes(target.id).split("?")[0])
94+
}
95+
if (!slices.size) return
96+
return {
97+
code: [
98+
`import { loadSlice as __i18nSlice } from ${JSON.stringify(runtime)};`,
99+
"const __i18nWith = (module, slice) => Promise.all([module, __i18nSlice(slice).catch(() => {})]).then((loaded) => loaded[0]);",
100+
code.replace(dynamicImport, (text) => (slices.has(text) ? `__i18nWith(${text}, ${JSON.stringify(slices.get(text))})` : text)),
101+
].join("\n"),
102+
map: null,
103+
}
104+
},
105+
generateBundle(_, bundle) {
106+
if (!client(this.environment)) return
107+
// A page route whose import() wasn't rewritten would run before its strings arrive: fail the
108+
// build instead (a change in how SolidStart writes its route list, for example).
109+
const missed = routes().filter((file) => !routed.has(file))
110+
if (missed.length)
111+
throw new Error(`i18n-slices: SolidStart's route list doesn't load the strings of ${missed.join(", ")}`)
112+
for (const chunk of Object.values(bundle))
113+
if (chunk.type === "chunk" && chunk.facadeModuleId?.startsWith("\0virtual:i18n/"))
114+
files.set(chunk.facadeModuleId.slice(1), `/${chunk.fileName}`)
115+
},
116+
}
117+
118+
/** For each locale, the files a page in it loads before hydration: its table (with the shell's strings) and its route's slice. */
119+
function preloads() {
120+
const data = analyze()
121+
const src = `${root}src/`
122+
return Object.fromEntries(
123+
Object.keys(data.locales).map((locale) => [
124+
locale,
125+
{
126+
table: files.get(`virtual:i18n/${locale}`),
127+
routes: Object.fromEntries(
128+
Object.entries(data.boundaries)
129+
.filter(([file]) => file.startsWith(`${src}routes/`))
130+
.map(([file, slice]) => [
131+
file.slice(src.length),
132+
files.get(`virtual:i18n/${locale}/${data.shared[slice]}`) ?? null,
133+
]),
134+
),
135+
},
136+
]),
137+
)
138+
}
139+
}
140+
141+
/** Strings as one JSON.parse call: compact whether or not the build minifies, and quick to parse. */
142+
function json(value: unknown) {
143+
return `JSON.parse('${JSON.stringify(value).replace(/\\/g, "\\\\").replace(/'/g, "\\'")}')`
144+
}

0 commit comments

Comments
 (0)