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: 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`.