feat(docs): add bilingual package documentation site
This commit is contained in:
Maofeng
@@ -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.
|
||||
Reference in New Issue
Block a user