feat(docs): add bilingual package documentation site

2026-09-20 15:53:28 +08:00
parent 60f6f1fb1a
commit dc80bd8ae0
111 changed files with 6531 additions and 0 deletions
@@ -0,0 +1,33 @@
+---
+title: Production catalogs
+description: Understand merging, compact message keys, asset generation, and SSR behavior.
+order: 20
+toc:
+  - id: merge-order
+    title: Merge order
+  - id: build-output
+    title: Build output
+  - id: server-rendering
+    title: Server rendering
+---
+
+## Merge order {#merge-order}
+
+Package sources are merged in configured order, followed by the application catalog. An application therefore translates only its own messages unless it intentionally customizes package copy.
+
+> Import only the locale sources used by the application. Block-specific entries do not import catalogs from unrelated features.
+
+## Build output {#build-output}
+
+During production builds, the plugin:
+
+1. merges configured catalogs for every locale;
+2. creates one shared schema from semantic message IDs;
+3. replaces those IDs with deterministic compact keys;
+4. emits one content-hashed JSON asset per locale.
+
+The private schema is diagnostic build state and is not shipped to the browser.
+
+## Server rendering {#server-rendering}
+
+The SSR bundle embeds the matching compact catalog. Browser navigation loads only the selected locale asset, so adding languages does not duplicate every translation in the main application bundle.
@@ -0,0 +1,44 @@
+---
+title: CLI and Message Studio
+description: Add locales, extract messages, compile catalogs, and run the translation interface.
+order: 21
+toc:
+  - id: scripts
+    title: Scripts
+  - id: commands
+    title: Commands
+  - id: daily-workflow
+    title: Daily workflow
+---
+
+## Scripts {#scripts}
+
+```json
+{
+  "scripts": {
+    "i18n": "workspace-i18n",
+    "i18n:extract": "workspace-i18n extract",
+    "i18n:compile": "workspace-i18n compile",
+    "i18n:ui": "workspace-i18n ui"
+  }
+}
+```
+
+## Commands {#commands}
+
+- `new <locale>` validates a BCP 47 tag, updates configuration, and creates the catalog.
+- `extract` finds application messages and updates catalogs.
+- `compile` produces TypeScript catalog modules.
+- `ui` starts Message Studio with Extract and Compile actions.
+
+Every command accepts `--project <path>` when it is invoked outside the application directory.
+
+## Daily workflow {#daily-workflow}
+
+```sh
+bun run i18n extract
+bun run i18n ui
+bun run i18n compile
+```
+
+Commit the application configuration and the `en-US` and `zh-Hans` catalogs. Generated private schema data remains build output.