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,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` 暴露生成的加载器。