chore: specs

2026-04-24 14:55:19 +00:00 · 2026-02-06 09:28:04 -06:00
parent 93a11ddedf
commit 861aed0c6a
8 changed files with 468 additions and 0 deletions
--- a/specs/09-docs-starlight-i18n-master.md
+++ b/specs/09-docs-starlight-i18n-master.md
@@ -0,0 +1,85 @@
+# Docs Starlight i18n Master Plan
+
+## Context and decision
+
+- Requested path was `packages/docs`, but Astro + Starlight docs are in `packages/web`.
+- `packages/docs` currently contains a Mintlify starter and is out of scope for this rollout.
+- This plan implements i18n in `packages/web` and keeps current `/docs/*` URLs working.
+
+## Goals
+
+1. No hardcoded English UI strings in the docs site shell/components.
+2. Every supported locale has every required i18n key.
+3. Astro + Starlight i18n is implemented using first-party best practices.
+
+## Non-goals
+
+- Migrating Mintlify content in `packages/docs`.
+- Changing product names, command literals, code samples, or provider/model identifiers.
+
+## Locale mapping (from README files)
+
+| README file     | Language              | Starlight key | `lang` tag | Dir   | Notes                                               |
+| --------------- | --------------------- | ------------- | ---------- | ----- | --------------------------------------------------- |
+| `README.md`     | English               | `root`        | `en`       | `ltr` | Root locale keeps existing non-prefixed docs routes |
+| `README.ar.md`  | Arabic                | `ar`          | `ar`       | `rtl` | Validate RTL layout and punctuation                 |
+| `README.br.md`  | Portuguese (Brazil)   | `pt-br`       | `pt-BR`    | `ltr` | README uses `br`; docs use canonical `pt-br`        |
+| `README.bs.md`  | Bosnian               | `bs`          | `bs-BA`    | `ltr` | Requires custom UI translations                     |
+| `README.da.md`  | Danish                | `da`          | `da-DK`    | `ltr` |                                                     |
+| `README.de.md`  | German                | `de`          | `de-DE`    | `ltr` |                                                     |
+| `README.es.md`  | Spanish               | `es`          | `es-ES`    | `ltr` |                                                     |
+| `README.fr.md`  | French                | `fr`          | `fr-FR`    | `ltr` |                                                     |
+| `README.it.md`  | Italian               | `it`          | `it-IT`    | `ltr` |                                                     |
+| `README.ja.md`  | Japanese              | `ja`          | `ja-JP`    | `ltr` |                                                     |
+| `README.ko.md`  | Korean                | `ko`          | `ko-KR`    | `ltr` |                                                     |
+| `README.no.md`  | Norwegian             | `nb`          | `nb-NO`    | `ltr` | README uses `no`; docs use canonical `nb`           |
+| `README.pl.md`  | Polish                | `pl`          | `pl-PL`    | `ltr` |                                                     |
+| `README.ru.md`  | Russian               | `ru`          | `ru-RU`    | `ltr` |                                                     |
+| `README.th.md`  | Thai                  | `th`          | `th-TH`    | `ltr` |                                                     |
+| `README.tr.md`  | Turkish               | `tr`          | `tr-TR`    | `ltr` |                                                     |
+| `README.zh.md`  | Chinese (Simplified)  | `zh-cn`       | `zh-CN`    | `ltr` | README uses `zh`; docs use canonical `zh-cn`        |
+| `README.zht.md` | Chinese (Traditional) | `zh-tw`       | `zh-TW`    | `ltr` | README uses `zht`; docs use canonical `zh-tw`       |
+
+Compatibility note:
+
+- If short-code URL compatibility is required, add redirects from `br -> pt-br`, `no -> nb`, `zh -> zh-cn`, and `zht -> zh-tw`.
+
+## Spec breakdown
+
+- `specs/10-docs-starlight-i18n-foundation.md`
+- `specs/11-docs-i18n-shell-astro.md`
+- `specs/12-docs-i18n-share-surfaces.md`
+- `specs/13-docs-i18n-content-structure.md`
+- `specs/14-docs-i18n-locale-pack-west.md`
+- `specs/15-docs-i18n-locale-pack-east.md`
+- `specs/16-docs-i18n-guardrails-ci.md`
+
+## Parallel execution plan
+
+| Phase | Specs      | Parallelism                   |
+| ----- | ---------- | ----------------------------- |
+| A     | 10         | Sequential (foundation first) |
+| B     | 11, 12, 13 | Fully parallel after 10       |
+| C     | 14, 15     | Fully parallel after 11/12/13 |
+| D     | 16         | Final gate after 14/15        |
+
+Parallel agent capacity:
+
+- Phase B: 3 agents.
+- Phase C: up to 17 agents (1 per locale) using locale checklists in specs 14 and 15.
+
+## Definition of done
+
+- `packages/web` Starlight config has all locales configured and routable.
+- All user-visible shell/component strings are translation-key based.
+- Locale docs trees exist for every required language and slug.
+- Key parity checks pass for all locales.
+- Build and type checks pass for docs app.
+
+## Validation commands
+
+```bash
+bun --cwd packages/web astro check
+bun --cwd packages/web build
+bun --cwd packages/web run i18n:check
+```
--- a/specs/10-docs-starlight-i18n-foundation.md
+++ b/specs/10-docs-starlight-i18n-foundation.md
@@ -0,0 +1,52 @@
+# Docs i18n Foundation (Astro + Starlight)
+
+## Objective
+
+Wire Starlight-native i18n in `packages/web` so all downstream work can localize against one source of truth.
+
+## Primary targets
+
+- `packages/web/astro.config.mjs`
+- `packages/web/src/content.config.ts`
+- `packages/web/src/content/i18n/en.json` (new)
+- `packages/web/src/content/i18n/*.json` (new for each locale)
+
+## Implementation plan
+
+1. Configure Starlight locales in `astro.config.mjs`.
+   - Use root English locale (`root`) to preserve existing route shape.
+   - Add all mapped locales from spec 09 with correct `lang` and `dir`.
+2. Keep Starlight as the i18n router.
+   - Do not build a custom parallel i18n routing layer.
+3. Add the `i18n` collection in `src/content.config.ts`.
+   - Use `i18nLoader()` and `i18nSchema()`.
+   - Extend schema with custom project keys used by `Lander`, `Header`, `Head`, `Share`, and `share/*` components.
+4. Add locale JSON dictionaries in `src/content/i18n/`.
+   - Include one baseline dictionary for English.
+   - Include one dictionary per locale key.
+   - For region-specific locales, use BCP-47 filenames (for example `pt-BR.json`, `zh-CN.json`, `zh-TW.json`).
+   - Keep placeholders/interpolations stable across locales.
+5. Decide fallback policy.
+   - During migration: allow fallback to root locale content.
+   - Final state: all required keys and docs slugs exist in all locales.
+
+## Dependencies
+
+- No upstream dependency.
+- Blocks specs 11, 12, 13, 14, and 15.
+
+## Acceptance criteria
+
+- Locale picker includes all required locales.
+- `Astro.locals.t` resolves Starlight + custom keys.
+- `src/content.config.ts` validates i18n key schema.
+- Build succeeds with locale routing enabled.
+
+## Validation commands
+
+```bash
+bun --cwd packages/web astro check
+bun --cwd packages/web build
+rg -n 'locales|defaultLocale|root' packages/web/astro.config.mjs
+rg -n 'i18nLoader|i18nSchema|docsLoader|docsSchema' packages/web/src/content.config.ts
+```
--- a/specs/11-docs-i18n-shell-astro.md
+++ b/specs/11-docs-i18n-shell-astro.md
@@ -0,0 +1,52 @@
+# Docs Shell i18n (Astro surfaces)
+
+## Objective
+
+Remove hardcoded English strings from Astro-rendered docs shell surfaces and use locale-aware labels and links.
+
+## Primary targets
+
+- `packages/web/astro.config.mjs`
+- `packages/web/config.mjs`
+- `packages/web/src/components/Header.astro`
+- `packages/web/src/components/Head.astro`
+- `packages/web/src/components/Lander.astro`
+- `packages/web/src/components/SiteTitle.astro` (only if fallback text needs localization)
+- `packages/web/src/content/i18n/*.json`
+
+## Implementation plan
+
+1. Sidebar translations
+   - Localize grouped labels (`Usage`, `Configure`, `Develop`) using Starlight `sidebar[].translations`.
+   - Keep slug lists unchanged.
+2. Header link localization
+   - Replace static `Home` / `Docs` labels in config with translation keys.
+   - In `Header.astro`, render labels through `Astro.locals.t(...)`.
+3. Locale-aware internal links
+   - Replace hardcoded `"/"` and `"/docs"` shell links with locale-safe URLs (`astro:i18n` helpers).
+4. Metadata and hero copy localization
+   - Localize static tagline/title fragments in `Head.astro` and `Lander.astro`.
+   - Localize all visible CTA text, captions, and section labels in `Lander.astro`.
+5. Keep literals stable where required
+   - Do not translate product names, code snippets, command lines, or provider identifiers.
+
+## Dependencies
+
+- Depends on spec 10.
+- Runs in parallel with specs 12 and 13.
+
+## Acceptance criteria
+
+- No hardcoded English UI labels remain in the target Astro files.
+- Sidebar group labels are localized for all supported locales.
+- Header and hero links remain valid in every locale.
+- Docs build succeeds with all locales enabled.
+
+## Validation commands
+
+```bash
+bun --cwd packages/web astro check
+bun --cwd packages/web build
+rg -n 'label:\s*"Usage"|label:\s*"Configure"|label:\s*"Develop"' packages/web/astro.config.mjs
+rg -n 'Get Started|The AI coding agent built for the terminal|Home|Docs' packages/web/src/components/*.astro
+```
--- a/specs/12-docs-i18n-share-surfaces.md
+++ b/specs/12-docs-i18n-share-surfaces.md
@@ -0,0 +1,54 @@
+# Docs Share Surface i18n (Solid + route handlers)
+
+## Objective
+
+Localize all user-visible strings in share routes and Solid share components used by the docs site.
+
+## Primary targets
+
+- `packages/web/src/pages/s/[id].astro`
+- `packages/web/src/pages/[...slug].md.ts`
+- `packages/web/src/components/Share.tsx`
+- `packages/web/src/components/share/part.tsx`
+- `packages/web/src/components/share/content-bash.tsx`
+- `packages/web/src/components/share/content-error.tsx`
+- `packages/web/src/components/share/content-markdown.tsx`
+- `packages/web/src/components/share/content-text.tsx`
+- `packages/web/src/components/share/copy-button.tsx`
+- `packages/web/src/components/share/common.tsx`
+- `packages/web/src/content/i18n/*.json`
+
+## Implementation plan
+
+1. Create a single translation bridge for Solid components.
+   - Resolve strings in `.astro` (`Astro.locals.t`) and pass a `messages` object into `Share.tsx`.
+   - Avoid duplicating separate client dictionaries.
+2. Replace hardcoded UI text in share components.
+   - Status text (`Connected`, `Connecting`, `Waiting for messages`, etc.).
+   - Expand/collapse controls (`Show more`, `Show less`, etc.).
+   - Labels/tooltips (`Cost`, `Input Tokens`, `Scroll to bottom`, copy tooltips).
+3. Localize route-layer fallback text.
+   - `Not found` and share metadata description should come from translation keys.
+4. Locale-aware formatting.
+   - Use locale-sensitive date/number formatting where `luxon`/`Intl` output is displayed.
+5. Keep technical tokens unchanged.
+   - Tool IDs, protocol literals, and command identifiers remain literal.
+
+## Dependencies
+
+- Depends on spec 10.
+- Runs in parallel with specs 11 and 13.
+
+## Acceptance criteria
+
+- No hardcoded English UI copy remains in targeted share files.
+- Share page metadata, status labels, and controls localize by locale.
+- Locale-aware formatting is applied where values are formatted for display.
+
+## Validation commands
+
+```bash
+bun --cwd packages/web astro check
+bun --cwd packages/web build
+rg -n 'Show more|Show less|Waiting for messages|Connected|Disconnected|Not found|Scroll to bottom' packages/web/src/components/Share.tsx packages/web/src/components/share packages/web/src/pages/s/[id].astro packages/web/src/pages/[...slug].md.ts
+```
--- a/specs/13-docs-i18n-content-structure.md
+++ b/specs/13-docs-i18n-content-structure.md
@@ -0,0 +1,47 @@
+# Docs Content Structure and Link i18n
+
+## Objective
+
+Restructure docs content for Starlight locale directories and eliminate locale-breaking absolute links.
+
+## Primary targets
+
+- `packages/web/src/content/docs/*.mdx` (root English source of truth)
+- `packages/web/src/content/docs/<locale>/**/*.mdx` (new locale trees)
+- `packages/web/src/content/docs/**/*.mdx` (link updates)
+- `packages/web/scripts/i18n-scaffold-pages.ts` (new)
+- `packages/web/scripts/i18n-link-check.ts` (new)
+
+## Implementation plan
+
+1. Keep root locale docs where they are.
+   - Root English remains in `src/content/docs/*.mdx` for non-prefixed URLs.
+2. Scaffold locale trees for all non-root locales.
+   - Mirror all 35 English slugs into each locale directory.
+   - Preserve frontmatter shape and page IDs.
+3. Convert locale-breaking links.
+   - Replace internal absolute `/docs/...` links with locale-safe links (relative slug links preferred).
+   - Preserve anchors and query strings.
+4. Add repeatable scaffolding + checks.
+   - Scaffolding script to create/mirror missing pages.
+   - Link check to fail on new absolute internal `/docs/` links in docs content.
+
+## Dependencies
+
+- Depends on spec 10.
+- Runs in parallel with specs 11 and 12.
+
+## Acceptance criteria
+
+- Every non-root locale directory exists under `src/content/docs/`.
+- Every locale contains the full English slug set.
+- No internal markdown links force the default locale via hardcoded `/docs/...` paths.
+
+## Validation commands
+
+```bash
+bun --cwd packages/web astro check
+bun --cwd packages/web build
+rg -n '\]\(/docs/' packages/web/src/content/docs --glob '*.mdx'
+rg -n 'href="/docs/' packages/web/src/content/docs --glob '*.mdx'
+```
--- a/specs/14-docs-i18n-locale-pack-west.md
+++ b/specs/14-docs-i18n-locale-pack-west.md
@@ -0,0 +1,67 @@
+# Docs Locale Pack West
+
+## Objective
+
+Complete translation keys and docs content for west/latin/rtl locales.
+
+Locales in this pack:
+
+- `ar`, `bs`, `da`, `de`, `es`, `fr`, `it`, `nb`, `pl`, `pt-br`, `tr`
+
+## Parallelization model
+
+- Run one subagent per locale (11 subagents total) with the same checklist.
+- All locale subagents can run concurrently.
+
+## Primary targets
+
+- `packages/web/src/content/i18n/ar.json`
+- `packages/web/src/content/i18n/bs.json`
+- `packages/web/src/content/i18n/da.json`
+- `packages/web/src/content/i18n/de.json`
+- `packages/web/src/content/i18n/es.json`
+- `packages/web/src/content/i18n/fr.json`
+- `packages/web/src/content/i18n/it.json`
+- `packages/web/src/content/i18n/nb.json`
+- `packages/web/src/content/i18n/pl.json`
+- `packages/web/src/content/i18n/pt-BR.json`
+- `packages/web/src/content/i18n/tr.json`
+- `packages/web/src/content/docs/ar/**/*.mdx`
+- `packages/web/src/content/docs/bs/**/*.mdx`
+- `packages/web/src/content/docs/da/**/*.mdx`
+- `packages/web/src/content/docs/de/**/*.mdx`
+- `packages/web/src/content/docs/es/**/*.mdx`
+- `packages/web/src/content/docs/fr/**/*.mdx`
+- `packages/web/src/content/docs/it/**/*.mdx`
+- `packages/web/src/content/docs/nb/**/*.mdx`
+- `packages/web/src/content/docs/pl/**/*.mdx`
+- `packages/web/src/content/docs/pt-br/**/*.mdx`
+- `packages/web/src/content/docs/tr/**/*.mdx`
+
+## Per-locale checklist
+
+1. Translate all required keys in the locale i18n JSON.
+2. Keep placeholders, interpolation tokens, and key names exactly aligned with English.
+3. Translate all 35 locale docs pages slug-for-slug.
+4. Keep code blocks, shell commands, config keys, and product names literal.
+5. Validate markdown formatting and frontmatter schema.
+6. Run locale-specific verification command before handoff.
+
+## Dependencies
+
+- Depends on specs 11, 12, and 13.
+- Runs in parallel with spec 15.
+
+## Acceptance criteria
+
+- All listed locale dictionaries are complete and schema-valid.
+- All listed locale docs trees contain all required slugs.
+- i18n parity and build checks pass for this locale set.
+
+## Validation commands
+
+```bash
+bun --cwd packages/web astro check
+bun --cwd packages/web build
+bun --cwd packages/web run i18n:check -- --locales ar,bs,da,de,es,fr,it,nb,pl,pt-br,tr
+```
--- a/specs/15-docs-i18n-locale-pack-east.md
+++ b/specs/15-docs-i18n-locale-pack-east.md
@@ -0,0 +1,57 @@
+# Docs Locale Pack East
+
+## Objective
+
+Complete translation keys and docs content for east/cjk/cyrillic locales.
+
+Locales in this pack:
+
+- `ja`, `ko`, `ru`, `th`, `zh-cn`, `zh-tw`
+
+## Parallelization model
+
+- Run one subagent per locale (6 subagents total).
+- All locale subagents can run concurrently.
+
+## Primary targets
+
+- `packages/web/src/content/i18n/ja.json`
+- `packages/web/src/content/i18n/ko.json`
+- `packages/web/src/content/i18n/ru.json`
+- `packages/web/src/content/i18n/th.json`
+- `packages/web/src/content/i18n/zh-CN.json`
+- `packages/web/src/content/i18n/zh-TW.json`
+- `packages/web/src/content/docs/ja/**/*.mdx`
+- `packages/web/src/content/docs/ko/**/*.mdx`
+- `packages/web/src/content/docs/ru/**/*.mdx`
+- `packages/web/src/content/docs/th/**/*.mdx`
+- `packages/web/src/content/docs/zh-cn/**/*.mdx`
+- `packages/web/src/content/docs/zh-tw/**/*.mdx`
+
+## Per-locale checklist
+
+1. Translate all required keys in locale i18n JSON.
+2. Keep placeholders/interpolation tokens unchanged.
+3. Translate all 35 locale docs pages slug-for-slug.
+4. Keep commands, code blocks, and technical identifiers literal.
+5. Validate script consistency and typography for each language.
+6. Run locale-specific verification command before handoff.
+
+## Dependencies
+
+- Depends on specs 11, 12, and 13.
+- Runs in parallel with spec 14.
+
+## Acceptance criteria
+
+- All listed locale dictionaries are complete and schema-valid.
+- All listed locale docs trees contain all required slugs.
+- i18n parity and build checks pass for this locale set.
+
+## Validation commands
+
+```bash
+bun --cwd packages/web astro check
+bun --cwd packages/web build
+bun --cwd packages/web run i18n:check -- --locales ja,ko,ru,th,zh-cn,zh-tw
+```
--- a/specs/16-docs-i18n-guardrails-ci.md
+++ b/specs/16-docs-i18n-guardrails-ci.md
@@ -0,0 +1,54 @@
+# Docs i18n Guardrails and CI
+
+## Objective
+
+Prevent regressions by enforcing key parity, docs slug parity, locale-safe links, and no hardcoded English UI strings in docs shell components.
+
+## Primary targets
+
+- `packages/web/scripts/i18n-verify.ts` (new)
+- `packages/web/scripts/i18n-check-keys.ts` (new)
+- `packages/web/scripts/i18n-check-pages.ts` (new)
+- `packages/web/scripts/i18n-check-links.ts` (new)
+- `packages/web/scripts/i18n-check-ui-strings.ts` (new)
+- `packages/web/package.json`
+- `.github/workflows/typecheck.yml` (or a dedicated workflow)
+
+## Implementation plan
+
+1. Key parity check
+   - Compare locale JSON keysets against English baseline.
+   - Fail on missing keys or unexpected extra keys (unless explicitly allowlisted).
+2. Page parity check
+   - Compare locale docs slug sets against root English slug set.
+   - Fail on missing locale pages.
+3. Link safety check
+   - Fail on internal absolute markdown links that start with `/docs/`.
+4. UI string check
+   - Scan targeted UI shell files for hardcoded English literals.
+   - Keep an explicit allowlist for technical literals and command snippets.
+5. Aggregate command
+   - Add `i18n:check` script that runs all checks and is CI-ready.
+6. CI integration
+   - Add `packages/web` i18n checks to existing CI gate.
+
+## Dependencies
+
+- Depends on specs 14 and 15 completion.
+
+## Acceptance criteria
+
+- `bun --cwd packages/web run i18n:check` exists and fails on regression.
+- CI runs i18n checks on pull requests to `dev`.
+- Missing keys/pages and locale-breaking links are blocked automatically.
+
+## Validation commands
+
+```bash
+bun --cwd packages/web run i18n:check
+bun --cwd packages/web run i18n:check:keys
+bun --cwd packages/web run i18n:check:pages
+bun --cwd packages/web run i18n:check:links
+bun --cwd packages/web run i18n:check:ui
+bun --cwd packages/web build
+```