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.
@@ -0,0 +1,36 @@
+---
+title: Devtool
+description: Inspect and edit catalogs from a floating development interface.
+order: 30
+toc:
+  - id: mount-the-devtool
+    title: Mount the Devtool
+  - id: theme-and-language
+    title: Theme and language
+  - id: custom-surfaces
+    title: Custom surfaces
+---
+
+## Mount the Devtool {#mount-the-devtool}
+
+Mount the Devtool inside `I18nProvider` and only during development:
+
+```tsx
+import { I18nDevtool } from "@workspace/i18n/devtool"
+
+{
+  import.meta.env.DEV && (
+    <I18nDevtool locale="zh-Hans" dark={'[data-theme="dark"]'} />
+  )
+}
+```
+
+The component renders through a portal, so application overflow and stacking contexts do not clip it.
+
+## Theme and language {#theme-and-language}
+
+The `dark` option accepts a class name or a CSS selector. Control-panel language is independent from the translated application locale, supports `en-US` and `zh-Hans`, and falls back from `navigator.languages` to `en-US`.
+
+## Custom surfaces {#custom-surfaces}
+
+Use `MessagePanel`, `MessageRepositoryProvider`, and `createHttpMessageRepository` when the application needs a custom development interface instead of the default floating panel.
@@ -0,0 +1,44 @@
+---
+title: Runtime
+description: Load a locale catalog and consume messages through React components and hooks.
+order: 11
+toc:
+  - id: load-the-catalog
+    title: Load the catalog
+  - id: provide-the-locale
+    title: Provide the locale
+  - id: translate-content
+    title: Translate content
+---
+
+## Load the catalog {#load-the-catalog}
+
+The generated catalog loader works in development, production, and SSR builds:
+
+```tsx
+import { use } from "react"
+import { loadMessageCatalog } from "@workspace/i18n/catalogs"
+
+const messages = use(loadMessageCatalog(locale))
+```
+
+## Provide the 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 {#translate-content}
+
+Use `Translate` for JSX content, `useTranslate` for an imperative translation function, and `useMessage` for a single descriptor. `useLocale`, `useLocales`, and `useFormatters` expose locale state and `Intl` formatters.
+
+`Translate` delegates to Lingui without adding a wrapper DOM element.
@@ -0,0 +1,48 @@
+---
+title: Project setup
+description: Create the application configuration and mount the Vite integration.
+order: 10
+toc:
+  - id: configuration
+    title: Configuration
+  - id: catalog-sources
+    title: Catalog sources
+  - id: vite-plugin
+    title: Vite plugin
+---
+
+## Configuration {#configuration}
+
+Create `i18n.config.json` in the consuming application:
+
+```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}"]
+}
+```
+
+This file is the application's single persistent internationalization configuration. CLI commands create temporary Lingui configuration only for the child process.
+
+The workspace ships exactly two locales: American English (`en-US`) and Simplified Chinese (`zh-Hans`). Use those same locale keys for application catalogs and package catalog sources.
+
+## Catalog sources {#catalog-sources}
+
+Sources are merged from left to right, and the application catalog is always last. Put reusable package catalogs first so product-specific translations can override them.
+
+## Vite plugin {#vite-plugin}
+
+```ts
+import { i18n } from "@workspace/i18n/vite"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+  plugins: [i18n()],
+})
+```
+
+The plugin serves development catalog APIs and exposes the generated loader through `@workspace/i18n/catalogs`.
@@ -0,0 +1,35 @@
+---
+title: Overview
+description: Follow the complete path from application configuration to translated production catalogs.
+order: 1
+toc:
+  - id: ownership-model
+    title: Ownership model
+  - id: workflow
+    title: Workflow
+  - id: package-entries
+    title: Package entries
+---
+
+## Ownership model {#ownership-model}
+
+Every application owns its `i18n.config.json` and application catalogs. Reusable packages may ship built-in catalogs, but the application chooses which ones to merge and may override their messages.
+
+This keeps product copy under application control without duplicating translations from shared packages.
+
+## Workflow {#workflow}
+
+1. Configure locales and catalog sources.
+2. Install the Vite plugin.
+3. Load one catalog into `I18nProvider`.
+4. Extract and translate application messages.
+5. Use the Devtool or Message Studio during development.
+6. Compile compact, cacheable production assets.
+
+## Package entries {#package-entries}
+
+- `@workspace/i18n` provides the React runtime.
+- `@workspace/i18n/catalogs` loads generated catalogs.
+- `@workspace/i18n/devtool` provides development surfaces.
+- `@workspace/i18n/vite` configures Vite.
+- `workspace-i18n` exposes the CLI.
@@ -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` 提供命令行工具。