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: 生产环境词典
+description: 理解词典合并、紧凑消息键、资源生成和 SSR 行为。
+order: 20
+toc:
+  - id: merge-order
+    title: 合并顺序
+  - id: build-output
+    title: 构建产物
+  - id: server-rendering
+    title: 服务端渲染
+---
+
+## 合并顺序 {#merge-order}
+
+包词典按配置顺序合并，应用词典最后合并。因此应用默认只需翻译自身消息，除非它有意自定义包内文案。
+
+> 只导入应用实际使用的词典来源。特定 Block 的入口不会导入无关功能的词典。
+
+## 构建产物 {#build-output}
+
+生产构建期间，插件会：
+
+1. 为每种语言合并配置的词典；
+2. 根据语义消息 ID 创建共享 Schema；
+3. 将这些 ID 替换为确定的紧凑键；
+4. 为每种语言输出一个带内容哈希的 JSON 资源。
+
+私有 Schema 仅用于构建诊断，不会发送到浏览器。
+
+## 服务端渲染 {#server-rendering}
+
+SSR Bundle 会嵌入匹配的紧凑词典。浏览器导航只加载选中语言的资源，因此增加语言不会让主应用 Bundle 重复包含所有翻译。
@@ -0,0 +1,44 @@
+---
+title: CLI 与 Message Studio
+description: 添加语言、提取消息、编译词典并运行翻译界面。
+order: 21
+toc:
+  - id: scripts
+    title: Scripts
+  - id: commands
+    title: 命令
+  - id: daily-workflow
+    title: 日常工作流
+---
+
+## Scripts {#scripts}
+
+```json
+{
+  "scripts": {
+    "i18n": "workspace-i18n",
+    "i18n:extract": "workspace-i18n extract",
+    "i18n:compile": "workspace-i18n compile",
+    "i18n:ui": "workspace-i18n ui"
+  }
+}
+```
+
+## 命令 {#commands}
+
+- `new <locale>` 校验 BCP 47 标签、更新配置并创建词典。
+- `extract` 查找应用消息并更新词典。
+- `compile` 生成 TypeScript 词典模块。
+- `ui` 启动带有 Extract 和 Compile 操作的 Message Studio。
+
+在应用目录外执行时，每个命令都接受 `--project <path>`。
+
+## 日常工作流 {#daily-workflow}
+
+```sh
+bun run i18n extract
+bun run i18n ui
+bun run i18n compile
+```
+
+提交应用配置以及 `en-US`、`zh-Hans` 词典。生成的私有 Schema 数据仍属于构建产物。
@@ -0,0 +1,36 @@
+---
+title: Devtool
+description: 通过浮动开发界面检查和编辑词典。
+order: 30
+toc:
+  - id: mount-the-devtool
+    title: 挂载 Devtool
+  - id: theme-and-language
+    title: 主题与语言
+  - id: custom-surfaces
+    title: 自定义界面
+---
+
+## 挂载 Devtool {#mount-the-devtool}
+
+将 Devtool 挂载在 `I18nProvider` 内，并且只在开发环境启用：
+
+```tsx
+import { I18nDevtool } from "@workspace/i18n/devtool"
+
+{
+  import.meta.env.DEV && (
+    <I18nDevtool locale="zh-Hans" dark={'[data-theme="dark"]'} />
+  )
+}
+```
+
+组件通过 Portal 渲染，因此不会被应用的 overflow 或层叠上下文裁剪。
+
+## 主题与语言 {#theme-and-language}
+
+`dark` 选项接受类名或 CSS 选择器。控制面板语言独立于被翻译的应用语言，支持 `en-US` 和 `zh-Hans`，并会从 `navigator.languages` 回退到 `en-US`。
+
+## 自定义界面 {#custom-surfaces}
+
+当应用需要替换默认浮动面板时，可使用 `MessagePanel`、`MessageRepositoryProvider` 和 `createHttpMessageRepository` 构建自定义开发界面。
@@ -0,0 +1,44 @@
+---
+title: 运行时
+description: 加载语言词典，并通过 React 组件和 Hooks 使用消息。
+order: 11
+toc:
+  - id: load-the-catalog
+    title: 加载词典
+  - id: provide-the-locale
+    title: 提供语言
+  - id: translate-content
+    title: 翻译内容
+---
+
+## 加载词典 {#load-the-catalog}
+
+生成的词典加载器同时支持开发、生产和 SSR 构建：
+
+```tsx
+import { use } from "react"
+import { loadMessageCatalog } from "@workspace/i18n/catalogs"
+
+const messages = use(loadMessageCatalog(locale))
+```
+
+## 提供语言 {#provide-the-locale}
+
+```tsx
+<I18nProvider
+  locale={locale}
+  locales={[
+    { locale: "en-US", label: "English" },
+    { locale: "zh-Hans", label: "简体中文" },
+  ]}
+  catalogs={{ [locale]: messages }}
+>
+  {children}
+</I18nProvider>
+```
+
+## 翻译内容 {#translate-content}
+
+JSX 内容使用 `Translate`，命令式翻译函数使用 `useTranslate`，单个描述符使用 `useMessage`。`useLocale`、`useLocales` 和 `useFormatters` 提供语言状态与 `Intl` 格式化器。
+
+`Translate` 会直接委托给 Lingui，不会增加额外的 DOM 包装元素。
@@ -0,0 +1,48 @@
+---
+title: 项目配置
+description: 创建应用配置并接入 Vite 插件。
+order: 10
+toc:
+  - id: configuration
+    title: 配置文件
+  - id: catalog-sources
+    title: 词典来源
+  - id: vite-plugin
+    title: Vite 插件
+---
+
+## 配置文件 {#configuration}
+
+在使用方应用中创建 `i18n.config.json`：
+
+```json
+{
+  "sourceLocale": "en-US",
+  "locales": ["en-US", "zh-Hans"],
+  "catalogPath": "src/locales/{locale}/messages",
+  "catalogSources": ["@workspace/ui/locales/{locale}"],
+  "include": ["src", "../../packages/ui/src"],
+  "exclude": ["**/*.test.{ts,tsx}"]
+}
+```
+
+该文件是应用唯一的持久国际化配置。CLI 命令只为子进程创建临时 Lingui 配置。
+
+工作区只提供简体中文（`zh-Hans`）和美式英语（`en-US`）。应用词典和包词典来源应使用相同的语言键。
+
+## 词典来源 {#catalog-sources}
+
+词典来源按从左到右的顺序合并，应用词典始终位于最后。将可复用包词典放在前面，使产品特有翻译可以覆盖它们。
+
+## Vite 插件 {#vite-plugin}
+
+```ts
+import { i18n } from "@workspace/i18n/vite"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+  plugins: [i18n()],
+})
+```
+
+插件会提供开发词典 API，并通过 `@workspace/i18n/catalogs` 暴露生成的加载器。
@@ -0,0 +1,35 @@
+---
+title: 概览
+description: 了解从应用配置到生产环境翻译词典的完整流程。
+order: 1
+toc:
+  - id: ownership-model
+    title: 所有权模型
+  - id: workflow
+    title: 工作流
+  - id: package-entries
+    title: 包入口
+---
+
+## 所有权模型 {#ownership-model}
+
+每个应用都拥有自己的 `i18n.config.json` 和应用词典。可复用包可以附带内置词典，但由应用决定合并哪些词典，也可以覆盖其中的消息。
+
+这样既能让产品文案始终由应用控制，也不会重复维护共享包的翻译。
+
+## 工作流 {#workflow}
+
+1. 配置语言和词典来源。
+2. 安装 Vite 插件。
+3. 将一个语言词典加载到 `I18nProvider`。
+4. 提取并翻译应用消息。
+5. 开发时使用 Devtool 或 Message Studio。
+6. 编译紧凑且可缓存的生产资源。
+
+## 包入口 {#package-entries}
+
+- `@workspace/i18n` 提供 React 运行时。
+- `@workspace/i18n/catalogs` 加载生成的词典。
+- `@workspace/i18n/devtool` 提供开发界面。
+- `@workspace/i18n/vite` 配置 Vite。
+- `workspace-i18n` 提供命令行工具。