You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fory.apache.org by ch...@apache.org on 2026/02/10 07:43:23 UTC
(fory-site) branch main updated: Fix translate (#412)
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git
The following commit(s) were added to refs/heads/main by this push:
new 07b4aadadb Fix translate (#412)
07b4aadadb is described below
commit 07b4aadadb9e511c9b0b3ef59e813f461ace16fd
Author: Shawn Yang <sh...@gmail.com>
AuthorDate: Tue Feb 10 15:43:19 2026 +0800
Fix translate (#412)
---
AGENTS.md | 140 +++
.../docusaurus-plugin-content-docs/current.json | 16 +
.../current/benchmarks/go/benchmark_report.md | 72 +-
.../current/compiler/_category_.json | 6 +
.../current/compiler/compiler-guide.md | 282 +++--
.../current/compiler/flatbuffers-idl.md | 147 +--
.../current/compiler/generated-code.md | 178 ++-
.../current/compiler/index.md | 125 +-
.../current/compiler/protobuf-idl.md | 255 ++--
.../current/compiler/schema-idl.md | 1315 +++++---------------
.../current/guide/cpp/field-configuration.md | 225 ++--
.../current/guide/cpp/schema-evolution.md | 2 +-
.../current/guide/go/configuration.md | 12 +-
.../current/guide/go/index.md | 26 +-
.../current/guide/go/struct-tags.md | 163 ++-
.../current/guide/java/field-configuration.md | 373 +++---
.../current/guide/python/field-configuration.md | 319 +++--
.../version-0.13/introduction/overview.md | 44 +-
.../version-0.14/guide/cpp/schema-evolution.md | 2 +-
.../version-0.15.json | 22 +
.../version-0.15/benchmarks/go/benchmark_report.md | 72 +-
.../version-0.15/compiler/_category_.json | 6 +
.../version-0.15/compiler/compiler-guide.md | 282 +++--
.../version-0.15/compiler/flatbuffers-idl.md | 147 +--
.../version-0.15/compiler/generated-code.md | 178 ++-
.../version-0.15/compiler/index.md | 125 +-
.../version-0.15/compiler/protobuf-idl.md | 255 ++--
.../version-0.15/compiler/schema-idl.md | 1315 +++++---------------
.../version-0.15/guide/cpp/field-configuration.md | 225 ++--
.../version-0.15/guide/cpp/schema-evolution.md | 2 +-
.../version-0.15/guide/go/configuration.md | 12 +-
.../version-0.15/guide/go/index.md | 26 +-
.../version-0.15/guide/go/struct-tags.md | 163 ++-
.../version-0.15/guide/java/field-configuration.md | 373 +++---
.../guide/python/field-configuration.md | 319 +++--
skills/translate-docs-zh/SKILL.md | 158 +++
skills/translate-docs-zh/references/terminology.md | 53 +
src/pages/download/index.md | 4 +-
.../version-0.13/introduction/overview.md | 26 +-
39 files changed, 3203 insertions(+), 4262 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..7cd142405d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,140 @@
+# Apache Fory Site: System Understanding (Agent View)
+
+## 1. Project Positioning
+
+This repository contains the Apache Fory website and documentation site source (Docusaurus).
+It is not the Fory core serialization library itself.
+
+Primary responsibilities:
+
+- Official homepage and marketing content (`src/pages` + custom components)
+- Documentation (multi-version, multi-language)
+- Blog
+- Community, download, and related pages
+
+Core objective: stable static site publishing plus high-quality documentation and Chinese localization maintenance.
+
+## 2. Tech Stack and Runtime
+
+- Framework: Docusaurus 3 (React 18 + TypeScript)
+- Styling and motion: CSS Modules, Tailwind (partial usage), AOS, Framer Motion
+- Search: `docusaurus-lunr-search`
+- Node requirement: `>=18`
+
+Common commands (`package.json`):
+
+- `npm run start` / `npm run start-en` / `npm run start-zh`
+- `npm run build` (runs `prebuild` first)
+- `npm run docusaurus docs:version <ver>` (wrapped command with i18n version copy support)
+- `npm run typecheck`
+
+## 3. Information Architecture and Directory Responsibilities
+
+Key directories:
+
+- `docs/`: current docs (current/dev)
+- `versioned_docs/version-*/`: historical docs by version
+- `versioned_sidebars/`: sidebars for versioned docs
+- `i18n/zh-CN/docusaurus-plugin-content-docs/`: Chinese docs (`current` + `version-*`)
+- `blog/`: blog content
+- `src/pages/`: homepage, users page, download page, security page, etc.
+- `src/theme/`: Docusaurus theme overrides (notably blog rendering behavior)
+- `src/plugin/redirect.js`: site redirect logic
+- `scripts/`: docs versioning and i18n helper scripts
+- `.github/workflows/`: CI/CD pipelines
+
+Current docs footprint (rough file count):
+
+- `docs/`: 158
+- `versioned_docs/`: 333
+- `i18n/zh-CN/docusaurus-plugin-content-docs/`: 500
+
+## 4. Docs Versioning Strategy
+
+- `versions.json` currently includes: `0.15, 0.14, 0.13, 0.12, 0.11, 0.10`
+- In `docusaurus.config.ts`, `docs.lastVersion = "0.15"`
+- The current docs label is `dev` (`current`)
+
+Recommended versioning entry point:
+
+- Use `npm run docusaurus docs:version <ver>`
+- This invokes `scripts/docusaurus-with-i18n.sh`
+- After native Docusaurus versioning, the wrapper copies each locale’s `current/` to `version-<ver>/`
+
+## 5. Internationalization (i18n) Mechanism
+
+Enabled locales:
+
+- `en-US` (default)
+- `zh-CN`
+
+Chinese docs paths:
+
+- `i18n/zh-CN/docusaurus-plugin-content-docs/current/`
+- `i18n/zh-CN/docusaurus-plugin-content-docs/version-*/`
+
+Chinese top-level sidebar labels are managed in:
+
+- `i18n/zh-CN/docusaurus-plugin-content-docs/current.json`
+
+Prebuild step:
+
+- `scripts/copy-i18n-fallback.sh`
+- It fills missing Chinese files for `specification` and `benchmarks` from English sources (`rsync --ignore-existing`) to prevent broken links
+
+This means Chinese docs may be a mix of translated content and English fallback files.
+
+## 6. Site Customization (vs. Default Docusaurus Behavior)
+
+- The homepage is composed of custom sections (Hero, Features, language cards, code carousel)
+- `src/plugin/redirect.js` has built-in redirects:
+ - `fury.apache.org` -> `fory.apache.org`
+ - Old routes `/docs/.../docs/{guide|introduction|start}` -> cleaned routes
+- Blog theme overrides:
+ - List pages prefer frontmatter `description` as summary
+ - Post detail pages remove the global blog sidebar for a focused reading layout
+
+## 7. CI/CD and Quality Gates
+
+### CI
+
+- `lint.yml`
+ - Markdown lint (`markdownlint-cli`)
+ - YAML lint (`yamllint`)
+- `link-check.yml`
+ - Workflow exists, but link-check steps are currently commented out (not effectively running)
+
+### CD
+
+- `deploy.yml`
+ - Runs on push to `main` and on pull requests
+ - Calls `scripts/unified-docs/script.py`
+ - Runs `npm run download-avatars` + `npm run build`
+ - Publishes to `deploy` branch for non-PR events (`peaceiris/actions-gh-pages`)
+
+## 8. Key Repository Caveats
+
+- `CONTRIBUTING.md` states that `docs/guide` and `docs/specification` are mainly synced from `apache/fory`.
+ For those sections, confirm whether changes should go to the main `apache/fory` repo instead.
+- `scripts/unified-docs/script.py` uses `i18n/eu-US/...` paths (not `en-US`); treat this as existing behavior and validate intent before changing.
+- Since link-check is not effectively active, external link regressions may pass PR checks.
+- The repo has substantial versioned/mirrored docs; avoid accidental bulk edits in `versioned_docs` and `i18n/version-*`.
+
+## 9. Recommended Agent Workflow
+
+- Before editing docs, scope the target explicitly:
+ - `docs/current`
+ - `versioned_docs/version-*`
+ - `i18n/zh-CN/current`
+ - `i18n/zh-CN/version-*`
+- For Chinese translation tasks:
+ - Follow `skills/translate-docs-zh/SKILL.md`
+ - Use terminology from `skills/translate-docs-zh/references/terminology.md`
+ - Do not use external translation tools/APIs/websites
+- When changing top-level sidebar categories (Introduction/Start/Schema IDL & Compiler/Guide):
+ - Update `sidebars.ts`
+ - Update `i18n/zh-CN/docusaurus-plugin-content-docs/current.json` (and version JSON files if needed)
+- Minimum pre-commit validation:
+ - `npm run build`
+ - `npm run typecheck`
+ - Manually verify critical routes: `/`, `/docs`, `/zh-CN/docs`, `/blog`
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
index a3936023b9..ac5312509b 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
@@ -2,5 +2,21 @@
"version.label": {
"message": "dev",
"description": "The label for version current"
+ },
+ "sidebar.docsSidebar.category.Introduction": {
+ "message": "Apache Fory 介绍",
+ "description": "The label for category Introduction in sidebar docsSidebar"
+ },
+ "sidebar.docsSidebar.category.Start": {
+ "message": "快速开始",
+ "description": "The label for category Start in sidebar docsSidebar"
+ },
+ "sidebar.docsSidebar.category.Schema IDL & Compiler": {
+ "message": "Schema IDL 与编译器",
+ "description": "The label for category Schema IDL & Compiler in sidebar docsSidebar"
+ },
+ "sidebar.docsSidebar.category.Guide": {
+ "message": "用户指南",
+ "description": "The label for category Guide in sidebar docsSidebar"
}
}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/go/benchmark_report.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/go/benchmark_report.md
index a1c3d635f2..f73aacf0a2 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/go/benchmark_report.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/go/benchmark_report.md
@@ -10,48 +10,48 @@
## 性能摘要
-| 数据类型 | 操作 | Fory (ops/s) | Protobuf (ops/s) | Msgpack (ops/s) | Fory vs PB | Fory vs MP |
-|---------|------|--------------|------------------|-----------------|------------|------------|
-| Struct | 序列化 | 15.16M | 10.23M | 5.41M | 1.48x | 2.80x |
-| Struct | 反序列化 | 12.10M | 11.01M | 3.23M | 1.10x | 3.75x |
-| Structlist | 序列化 | 1.58M | 561K | 299K | 2.82x | 5.28x |
-| Structlist | 反序列化 | 1.10M | 529K | 175K | 2.09x | 6.30x |
-| Sample | 序列化 | 7.28M | 2.72M | 670K | 2.68x | 10.87x |
-| Sample | 反序列化 | 3.79M | 2.37M | 376K | 1.60x | 10.09x |
-| Samplelist | 序列化 | 510K | 141K | 38K | 3.61x | 13.34x |
-| Samplelist | 反序列化 | 236K | 107K | 19K | 2.20x | 12.66x |
-| Mediacontent | 序列化 | 3.72M | 2.12M | 1.29M | 1.75x | 2.88x |
-| Mediacontent | 反序列化 | 2.34M | 1.81M | 698K | 1.30x | 3.35x |
-| Mediacontentlist | 序列化 | 268K | 110K | 72K | 2.44x | 3.72x |
-| Mediacontentlist | 反序列化 | 138K | 87K | 36K | 1.58x | 3.86x |
+| 数据类型 | 操作 | Fory (ops/s) | Protobuf (ops/s) | Msgpack (ops/s) | Fory vs PB | Fory vs MP |
+| ---------------- | -------- | ------------ | ---------------- | --------------- | ---------- | ---------- |
+| Struct | 序列化 | 15.16M | 10.23M | 5.41M | 1.48x | 2.80x |
+| Struct | 反序列化 | 12.10M | 11.01M | 3.23M | 1.10x | 3.75x |
+| Structlist | 序列化 | 1.58M | 561K | 299K | 2.82x | 5.28x |
+| Structlist | 反序列化 | 1.10M | 529K | 175K | 2.09x | 6.30x |
+| Sample | 序列化 | 7.28M | 2.72M | 670K | 2.68x | 10.87x |
+| Sample | 反序列化 | 3.79M | 2.37M | 376K | 1.60x | 10.09x |
+| Samplelist | 序列化 | 510K | 141K | 38K | 3.61x | 13.34x |
+| Samplelist | 反序列化 | 236K | 107K | 19K | 2.20x | 12.66x |
+| Mediacontent | 序列化 | 3.72M | 2.12M | 1.29M | 1.75x | 2.88x |
+| Mediacontent | 反序列化 | 2.34M | 1.81M | 698K | 1.30x | 3.35x |
+| Mediacontentlist | 序列化 | 268K | 110K | 72K | 2.44x | 3.72x |
+| Mediacontentlist | 反序列化 | 138K | 87K | 36K | 1.58x | 3.86x |
## 详细耗时（ns/op）
-| 数据类型 | 操作 | Fory | Protobuf | Msgpack |
-|---------|------|------|----------|---------|
-| Struct | 序列化 | 66.0 | 97.8 | 184.9 |
-| Struct | 反序列化 | 82.7 | 90.9 | 309.6 |
-| Structlist | 序列化 | 632.8 | 1783.0 | 3340.0 |
-| Structlist | 反序列化 | 906.4 | 1891.0 | 5709.0 |
-| Sample | 序列化 | 137.3 | 367.3 | 1492.0 |
-| Sample | 反序列化 | 263.6 | 422.2 | 2661.0 |
-| Samplelist | 序列化 | 1962.0 | 7087.0 | 26169.0 |
-| Samplelist | 反序列化 | 4234.0 | 9321.0 | 53615.0 |
-| Mediacontent | 序列化 | 268.8 | 471.1 | 773.7 |
-| Mediacontent | 反序列化 | 426.9 | 553.1 | 1432.0 |
-| Mediacontentlist | 序列化 | 3736.0 | 9107.0 | 13911.0 |
-| Mediacontentlist | 反序列化 | 7247.0 | 11435.0 | 27975.0 |
+| 数据类型 | 操作 | Fory | Protobuf | Msgpack |
+| ---------------- | -------- | ------ | -------- | ------- |
+| Struct | 序列化 | 66.0 | 97.8 | 184.9 |
+| Struct | 反序列化 | 82.7 | 90.9 | 309.6 |
+| Structlist | 序列化 | 632.8 | 1783.0 | 3340.0 |
+| Structlist | 反序列化 | 906.4 | 1891.0 | 5709.0 |
+| Sample | 序列化 | 137.3 | 367.3 | 1492.0 |
+| Sample | 反序列化 | 263.6 | 422.2 | 2661.0 |
+| Samplelist | 序列化 | 1962.0 | 7087.0 | 26169.0 |
+| Samplelist | 反序列化 | 4234.0 | 9321.0 | 53615.0 |
+| Mediacontent | 序列化 | 268.8 | 471.1 | 773.7 |
+| Mediacontent | 反序列化 | 426.9 | 553.1 | 1432.0 |
+| Mediacontentlist | 序列化 | 3736.0 | 9107.0 | 13911.0 |
+| Mediacontentlist | 反序列化 | 7247.0 | 11435.0 | 27975.0 |
### 序列化后数据大小（字节）
-| 数据类型 | Fory | Protobuf | Msgpack |
-|---------|------|----------|---------|
-| Struct | 58 | 61 | 57 |
-| Sample | 446 | 375 | 524 |
-| MediaContent | 342 | 301 | 400 |
-| StructList | 560 | 1260 | 1146 |
-| SampleList | 7600 | 7560 | 10486 |
-| MediaContentList | 5776 | 6080 | 8006 |
+| 数据类型 | Fory | Protobuf | Msgpack |
+| ---------------- | ---- | -------- | ------- |
+| Struct | 58 | 61 | 57 |
+| Sample | 446 | 375 | 524 |
+| MediaContent | 342 | 301 | 400 |
+| StructList | 560 | 1260 | 1146 |
+| SampleList | 7600 | 7560 | 10486 |
+| MediaContentList | 5776 | 6080 | 8006 |
## 性能图表
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/_category_.json
new file mode 100644
index 0000000000..abf19e9fcb
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/_category_.json
@@ -0,0 +1,6 @@
+{
+ "position": 3,
+ "label": "Schema IDL 与编译器",
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/compiler-guide.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/compiler-guide.md
index 1c8184bfda..0046cbcd3b 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/compiler-guide.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/compiler-guide.md
@@ -19,9 +19,7 @@ license: |
limitations under the License.
---
-> 中文导读：本文档为 Fory 编译器/协议规范文档的中文译稿。为避免改变规范语义，代码片段、类型名、协议字段名保持英文，说明性文字优先翻译为中文。
-
-本指南介绍 Fory IDL 编译器的安装、使用与集成。
+本指南介绍 Fory IDL 编译器的安装、命令行使用方式以及构建系统集成方案。
## 安装
@@ -52,155 +50,153 @@ foryc --scan-generated [OPTIONS]
### 选项
-Compile options:
-
-| Option | Description | Default |
-| ------------------------------------- | ----------------------------------------------------- | ------------------- |
-| `--lang` | Comma-separated target languages | `all` |
-| `--output`, `-o` | Output directory | `./generated` |
-| `--package` | Override package name from Fory IDL file | (from file) |
-| `-I`, `--proto_path`, `--import_path` | Add directory to import search path (can be repeated) | (none) |
-| `--java_out=DST_DIR` | Generate Java code in DST_DIR | (none) |
-| `--python_out=DST_DIR` | Generate Python code in DST_DIR | (none) |
-| `--cpp_out=DST_DIR` | Generate C++ code in DST_DIR | (none) |
-| `--go_out=DST_DIR` | Generate Go code in DST_DIR | (none) |
-| `--rust_out=DST_DIR` | Generate Rust code in DST_DIR | (none) |
-| `--go_nested_type_style` | Go nested type naming: `camelcase` or `underscore` | from schema/default |
-| `--emit-fdl` | Print translated Fory IDL for non-`.fdl` inputs | `false` |
-| `--emit-fdl-path` | Write translated Fory IDL to a file or directory | (stdout) |
-
-Scan options (with `--scan-generated`):
-
-| Option | Description | Default |
-| ------------ | ------------------------------ | ------- |
-| `--root` | Root directory to scan | `.` |
-| `--relative` | Print paths relative to root | `false` |
-| `--delete` | Delete matched generated files | `false` |
-| `--dry-run` | Scan/print only, do not delete | `false` |
-
-### Scan Generated Files
-
-Use `--scan-generated` to find files produced by `foryc`. The scanner walks
-the tree recursively, skips `build/`, `target/`, and hidden directories, and prints
-each generated file as it is found.
+编译选项：
+
+| 选项 | 说明 | 默认值 |
+| ------------------------------------- | ------------------------------------------------ | ------------- |
+| `--lang` | 目标语言列表（逗号分隔） | `all` |
+| `--output`, `-o` | 输出目录 | `./generated` |
+| `--package` | 覆盖 Fory IDL 文件中的 package | （来自文件） |
+| `-I`, `--proto_path`, `--import_path` | 添加 import 搜索路径（可重复） | （无） |
+| `--java_out=DST_DIR` | 将 Java 代码输出到 `DST_DIR` | （无） |
+| `--python_out=DST_DIR` | 将 Python 代码输出到 `DST_DIR` | （无） |
+| `--cpp_out=DST_DIR` | 将 C++ 代码输出到 `DST_DIR` | （无） |
+| `--go_out=DST_DIR` | 将 Go 代码输出到 `DST_DIR` | （无） |
+| `--rust_out=DST_DIR` | 将 Rust 代码输出到 `DST_DIR` | （无） |
+| `--go_nested_type_style` | Go 嵌套类型命名风格：`camelcase` 或 `underscore` | schema/默认值 |
+| `--emit-fdl` | 对非 `.fdl` 输入打印转换后的 Fory IDL | `false` |
+| `--emit-fdl-path` | 将转换后的 Fory IDL 写入文件或目录 | （stdout） |
+
+扫描选项（配合 `--scan-generated`）：
+
+| 选项 | 说明 | 默认值 |
+| ------------ | ---------------------- | ------- |
+| `--root` | 扫描根目录 | `.` |
+| `--relative` | 以相对路径输出 | `false` |
+| `--delete` | 删除匹配到的生成文件 | `false` |
+| `--dry-run` | 仅扫描输出，不执行删除 | `false` |
+
+### 扫描生成文件
+
+使用 `--scan-generated` 可以定位 `foryc` 生成的文件。扫描器会递归遍历目录树，跳过 `build/`、`target/` 和隐藏目录，并输出找到的每个生成文件。
```bash
-# Scan current directory
+# 扫描当前目录
foryc --scan-generated
-# Scan a specific root
+# 扫描指定根目录
foryc --scan-generated --root ./src
-# Print paths relative to the scan root
+# 输出相对路径
foryc --scan-generated --root ./src --relative
-# Delete scanned generated files
+# 删除扫描到的生成文件
foryc --scan-generated --root ./src --delete
-# Dry-run (scan and print only)
+# Dry-run（仅扫描与输出）
foryc --scan-generated --root ./src --dry-run
```
-### Examples
+### 示例
-**Compile for all languages:**
+**为所有语言编译：**
```bash
foryc schema.fdl
```
-**Compile for specific languages:**
+**为指定语言编译：**
```bash
foryc schema.fdl --lang java,python
```
-**Specify output directory:**
+**指定输出目录：**
```bash
foryc schema.fdl --output ./src/generated
```
-**Override package name:**
+**覆盖 package：**
```bash
foryc schema.fdl --package com.myapp.models
```
-**Compile multiple files:**
+**编译多个文件：**
```bash
foryc user.fdl order.fdl product.fdl --output ./generated
```
-**Use import search paths:**
+**使用 import 搜索路径：**
```bash
-# Add a single import path
+# 单个路径
foryc src/main.fdl -I libs/common
-# Add multiple import paths (repeated option)
+# 多个路径（重复参数）
foryc src/main.fdl -I libs/common -I libs/types
-# Add multiple import paths (comma-separated)
+# 多个路径（逗号分隔）
foryc src/main.fdl -I libs/common,libs/types,third_party/
-# Using --proto_path (protoc-compatible alias)
+# --proto_path（protoc 兼容别名）
foryc src/main.fdl --proto_path=libs/common
-# Mix all styles
+# 混合写法
foryc src/main.fdl -I libs/common,libs/types --proto_path third_party/
```
-**Language-specific output directories (protoc-style):**
+**语言定向输出目录（protoc 风格）：**
```bash
-# Generate only Java code to a specific directory
+# 仅生成 Java
foryc schema.fdl --java_out=./src/main/java
-# Generate multiple languages to different directories
+# 多语言分别输出到不同目录
foryc schema.fdl --java_out=./java/gen --python_out=./python/src --go_out=./go/gen
-# Combine with import paths
+# 结合 import 路径
foryc schema.fdl --java_out=./gen/java -I proto/ -I common/
```
-When using `--{lang}_out` options:
+使用 `--{lang}_out` 时：
-- Only the specified languages are generated (not all languages)
-- The compiler writes under the specified directory (language-specific generators may still create package/module subdirectories)
-- This is compatible with protoc-style workflows
+- 只生成显式指定的语言（不会生成全部语言）
+- 输出写入指定目录（语言生成器可能继续按包/模块分层）
+- 兼容 protoc 风格工作流
-**Inspect translated Fory IDL from proto/fbs input:**
+**查看 proto/fbs 输入转换后的 Fory IDL：**
```bash
-# Print translated Fory IDL to stdout
+# 输出到 stdout
foryc schema.proto --emit-fdl
-# Write translated Fory IDL to a directory
+# 输出到目录
foryc schema.fbs --emit-fdl --emit-fdl-path ./translated
```
-## Import Path Resolution
+## Import 路径解析
-When compiling Fory IDL files with imports, the compiler searches for imported files in this order:
+编译含 import 的 Fory IDL 文件时，导入文件按以下顺序查找：
-1. **Relative to the importing file (default)** - The directory containing the file with the import statement is always searched first, automatically. No `-I` flag needed for same-directory imports.
-2. **Each `-I` path in order** - Additional search paths specified on the command line
+1. **相对于导入者文件目录（默认）**：始终优先查找，无需 `-I`
+2. **按顺序遍历每个 `-I` 路径**
-**Same-directory imports work automatically:**
+**同目录 import 可直接生效：**
```protobuf
// main.fdl
-import "common.fdl"; // Found if common.fdl is in the same directory
+import "common.fdl"; // 若 common.fdl 在同目录，将自动找到
```
```bash
-# No -I needed for same-directory imports
+# 同目录导入无需 -I
foryc main.fdl
```
-**Example project structure:**
+**示例目录结构：**
```
project/
@@ -210,7 +206,7 @@ project/
└── common.fdl
```
-**Without `-I` (fails):**
+**不加 `-I`（失败）：**
```bash
$ foryc src/main.fdl
@@ -218,7 +214,7 @@ Import error: Import not found: common.fdl
Searched in: /project/src
```
-**With `-I` (succeeds):**
+**加 `-I`（成功）：**
```bash
$ foryc src/main.fdl -I libs/
@@ -226,17 +222,17 @@ Compiling src/main.fdl...
Resolved 1 import(s)
```
-## Supported Languages
+## 支持语言
-| Language | Flag | Output Extension | Description |
-| -------- | -------- | ---------------- | --------------------------- |
-| Java | `java` | `.java` | POJOs with Fory annotations |
-| Python | `python` | `.py` | Dataclasses with type hints |
-| Go | `go` | `.go` | Structs with struct tags |
-| Rust | `rust` | `.rs` | Structs with derive macros |
-| C++ | `cpp` | `.h` | Structs with FORY macros |
+| 语言 | 标记 | 输出后缀 | 说明 |
+| ------ | -------- | -------- | ---------------------- |
+| Java | `java` | `.java` | 带 Fory 注解的 POJO |
+| Python | `python` | `.py` | 带类型提示的 dataclass |
+| Go | `go` | `.go` | 带 struct tag 的结构体 |
+| Rust | `rust` | `.rs` | 带 derive 宏的结构体 |
+| C++ | `cpp` | `.h` | 带 FORY 宏的结构体 |
-## Output Structure
+## 输出结构
### Java
@@ -251,9 +247,9 @@ generated/
└── ExampleForyRegistration.java
```
-- One file per type (enum or message)
-- Package structure matches Fory IDL package
-- Registration helper class generated
+- 每个类型（enum/message）单独一个文件
+- 包路径与 Fory IDL package 一致
+- 会生成注册辅助类
### Python
@@ -263,9 +259,9 @@ generated/
└── example.py
```
-- Single module with all types
-- Module name derived from package
-- Registration function included
+- 所有类型位于单模块
+- 模块名由 package 派生
+- 包含注册函数
### Go
@@ -276,9 +272,9 @@ generated/
└── example.go
```
-- Single file with all types
-- Directory and package name are derived from `go_package` or the Fory IDL package
-- Registration function included
+- 所有类型在单文件中
+- 目录名与包名来自 `go_package` 或 Fory IDL package
+- 包含注册函数
### Rust
@@ -288,9 +284,9 @@ generated/
└── example.rs
```
-- Single module with all types
-- Module name derived from package
-- Registration function included
+- 所有类型位于单模块
+- 模块名由 package 派生
+- 包含注册函数
### C++
@@ -300,15 +296,15 @@ generated/
└── example.h
```
-- Single header file
-- Namespace matches package (dots to `::`)
-- Header guards and forward declarations
+- 单头文件输出
+- 命名空间与 package 对齐（点号转换为 `::`）
+- 自动包含 header guard 与前向声明
-## Build Integration
+## 构建系统集成
### Maven (Java)
-Add to your `pom.xml`:
+在 `pom.xml` 中添加：
```xml
<build>
@@ -339,7 +335,7 @@ Add to your `pom.xml`:
</build>
```
-Add generated sources:
+添加生成源码目录：
```xml
<build>
@@ -368,7 +364,7 @@ Add generated sources:
### Gradle (Java/Kotlin)
-Add to `build.gradle`:
+在 `build.gradle` 中添加：
```groovy
task generateForyTypes(type: Exec) {
@@ -390,7 +386,7 @@ sourceSets {
### Python (setuptools)
-Add to `setup.py` or `pyproject.toml`:
+在 `setup.py` 或 `pyproject.toml` 中加入生成步骤：
```python
# setup.py
@@ -413,24 +409,24 @@ setup(
)
```
-### Go (go generate)
+### Go (`go generate`)
-Add to your Go file:
+在 Go 文件中添加：
```go
//go:generate foryc ../schema.fdl --lang go --output .
package models
```
-Run:
+执行：
```bash
go generate ./...
```
-### Rust (build.rs)
+### Rust (`build.rs`)
-Add to `build.rs`:
+在 `build.rs` 中添加：
```rust
use std::process::Command;
@@ -451,7 +447,7 @@ fn main() {
### CMake (C++)
-Add to `CMakeLists.txt`:
+在 `CMakeLists.txt` 中添加：
```cmake
find_program(FORY_COMPILER foryc)
@@ -474,7 +470,7 @@ target_include_directories(mylib PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/generated)
### Bazel
-Create a rule in `BUILD`:
+在 `BUILD` 中添加规则：
```python
genrule(
@@ -492,51 +488,51 @@ cc_library(
)
```
-## Error Handling
+## 错误处理
-### Syntax Errors
+### 语法错误
```
Error: Line 5, Column 12: Expected ';' after field declaration
```
-Fix: Check the indicated line for missing semicolons or syntax issues.
+修复方式：检查对应行是否缺少分号或存在语法问题。
-### Duplicate Type Names
+### 类型名重复
```
Error: Duplicate type name: User
```
-Fix: Ensure each enum and message has a unique name within the file.
+修复方式：确保同一文件内每个 enum/message 名称唯一。
-### Duplicate Type IDs
+### 类型 ID 重复
```
Error: Duplicate type ID 100: User and Order
```
-Fix: Assign unique type IDs to each type.
+修复方式：为每个类型分配唯一 ID。
-### Unknown Type References
+### 未知类型引用
```
Error: Unknown type 'Address' in Customer.address
```
-Fix: Define the referenced type before using it, or check for typos.
+修复方式：先定义被引用类型，或检查类型名拼写。
-### Duplicate Field Numbers
+### 字段号重复
```
Error: Duplicate field number 1 in User: name and id
```
-Fix: Assign unique field numbers within each message.
+修复方式：确保同一 message 内字段号唯一。
-## Best Practices
+## 最佳实践
-### Project Structure
+### 项目结构
```
project/
@@ -549,12 +545,12 @@ project/
└── build.gradle
```
-### Version Control
+### 版本控制
-- **Track**: Fory IDL schema files
-- **Ignore**: Generated code (can be regenerated)
+- **纳入版本控制**：Fory IDL schema 文件
+- **忽略生成代码**：可在构建时再生成
-Add to `.gitignore`:
+在 `.gitignore` 中加入：
```
# Generated Fory IDL code
@@ -562,12 +558,12 @@ src/generated/
generated/
```
-### CI/CD Integration
+### CI/CD 集成
-Always regenerate during builds:
+在构建流程中始终重新生成代码：
```yaml
-# GitHub Actions example
+# GitHub Actions 示例
steps:
- name: Install Fory IDL Compiler
run: pip install ./compiler
@@ -579,14 +575,14 @@ steps:
run: ./gradlew build
```
-### Schema Evolution
+### Schema 演进
-When modifying schemas:
+修改 schema 时建议遵循：
-1. **Never reuse field numbers** - Mark as reserved instead
-2. **Never change type IDs** - They're part of the binary format
-3. **Add new fields** - Use new field numbers
-4. **Use `optional`** - For backward compatibility
+1. **不要复用字段号**：删除字段后应保留/预留
+2. **不要改动类型 ID**：类型 ID 属于二进制协议的一部分
+3. **新增字段使用新字段号**
+4. **优先使用 `optional`**：保持向后兼容
```protobuf
message User [id=100] {
@@ -597,7 +593,7 @@ message User [id=100] {
}
```
-## Troubleshooting
+## 故障排查
### Command Not Found
@@ -605,7 +601,7 @@ message User [id=100] {
foryc: command not found
```
-**Solution:** Ensure the compiler is installed and in your PATH:
+**解决：** 确认编译器已安装且在 PATH 中：
```bash
pip install -e ./compiler
@@ -619,15 +615,15 @@ export PATH=$PATH:~/.local/bin
Permission denied: ./generated
```
-**Solution:** Ensure write permissions on the output directory:
+**解决：** 确保输出目录具备写权限：
```bash
chmod -R u+w ./generated
```
-### Import Errors in Generated Code
+### 生成代码 import 错误
-**Java:** Ensure Fory dependency is in your project:
+**Java：** 确保项目包含 Fory 依赖：
```xml
<dependency>
@@ -637,23 +633,23 @@ chmod -R u+w ./generated
</dependency>
```
-**Python:** Ensure pyfory is installed:
+**Python：** 确保安装 `pyfory`：
```bash
pip install pyfory
```
-**Go:** Ensure fory module is available:
+**Go：** 确保可获取 fory 模块：
```bash
go get github.com/apache/fory/go/fory
```
-**Rust:** Ensure fory crate is in `Cargo.toml`:
+**Rust：** 确保 `Cargo.toml` 中包含 fory crate：
```toml
[dependencies]
fory = "x.y.z"
```
-**C++:** Ensure Fory headers are in include path.
+**C++：** 确保编译器 include 路径可找到 Fory 头文件。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/flatbuffers-idl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/flatbuffers-idl.md
index 579ac6c3fc..6a2bfd2885 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/flatbuffers-idl.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/flatbuffers-idl.md
@@ -19,59 +19,49 @@ license: |
limitations under the License.
---
-> 中文导读：本文档为 Fory 编译器/协议规范文档的中文译稿。为避免改变规范语义，代码片段、类型名、协议字段名保持英文，说明性文字优先翻译为中文。
-
本页说明 Apache Fory 如何读取 FlatBuffers schema（`.fbs`）并将其转换为 Fory IR 以生成代码。
## 本页内容
-- When to use FlatBuffers input with Fory
-- Exact FlatBuffers to Fory mapping behavior
-- Supported Fory-specific attributes in `.fbs`
-- Migration notes and generated-code differences
+- 何时应在 Fory 中使用 FlatBuffers 输入
+- FlatBuffers 到 Fory 的精确映射行为
+- `.fbs` 中支持的 Fory 扩展属性
+- 迁移注意事项与生成代码差异
## 为什么使用 Apache Fory
-- Idiomatic generated code: Fory generates language-idiomatic classes/structs
- that can be used directly as domain objects.
-- Java performance: In Java object-serialization workloads, Fory is faster than
- FlatBuffers in Fory benchmarks.
-- Other languages: serialization performance is generally in a similar range.
-- Deserialization in practice: FlatBuffers does not perform native-object deserialization and is
- faster by default, but if your application needs native objects, it requires
- conversion and that conversion step can dominate read cost. In those cases,
- Fory deserialization is often faster end-to-end.
-- Easier APIs: Fory uses direct native objects, so you do not need to
- reverse-build tables or manually manage offsets.
-- Better graph modeling: Shared and circular references are first-class features
- in Fory.
+- **生成代码更符合语言习惯**：Fory 会生成各语言常用风格的类/结构体，可直接作为领域对象使用。
+- **Java 性能更优**：在 Fory 的 Java 对象序列化基准中，Fory 通常快于 FlatBuffers。
+- **其他语言性能相近**：序列化性能通常处于同一量级。
+- **实际反序列化链路更高效**：FlatBuffers 默认并不做原生对象反序列化，因此看起来更快；但当业务需要原生对象时，还需额外转换，这一步往往成为主要开销。在这种场景下，Fory 端到端反序列化通常更快。
+- **API 更简单**：Fory 直接操作原生对象，无需反向构建 table 或手动管理 offset。
+- **对象图建模能力更强**：Fory 原生支持共享引用和循环引用。
## 快速决策指南
-| Situation | Recommended Path |
-| ------------------------------------------------------------------ | ---------------------- |
-| You already have `.fbs` schemas and want Fory runtime/codegen | Use FlatBuffers input |
-| You are starting new schema work and want full Fory syntax control | Use native Fory IDL |
-| You need FlatBuffers wire compatibility at runtime | Keep FlatBuffers stack |
-| You need Fory object-graph semantics (`ref`, weak refs, etc.) | Use Fory |
+| 场景 | 建议路径 |
+| ----------------------------------------------- | ----------------------- |
+| 已有 `.fbs` schema，想接入 Fory 运行时/代码生成 | 使用 FlatBuffers 输入 |
+| 新建 schema，希望完整使用 Fory 语法能力 | 使用原生 Fory IDL |
+| 运行时必须保持 FlatBuffers 线格式兼容 | 继续使用 FlatBuffers 栈 |
+| 需要 Fory 对象图语义（`ref`、弱引用等） | 使用 Fory |
## FlatBuffers 到 Fory 的映射
-### Schema-Level Rules
+### Schema 级规则
-- `namespace` maps to Fory package namespace.
-- `include` entries map to Fory imports.
-- `table` is translated as `evolving=true`.
-- `struct` is translated as `evolving=false`.
-- `root_type` is parsed but ignored by Fory runtime/codegen.
-- `file_identifier` and `file_extension` are parsed but not used by Fory codegen.
+- `namespace` 映射为 Fory package 命名空间。
+- `include` 映射为 Fory import。
+- `table` 会被翻译为 `evolving=true`。
+- `struct` 会被翻译为 `evolving=false`。
+- `root_type` 会被解析，但 Fory 运行时/代码生成不会使用。
+- `file_identifier` 与 `file_extension` 会被解析，但 Fory 代码生成不会使用。
-### Field Numbering
+### 字段编号
-FlatBuffers fields do not have explicit field IDs. Fory assigns field numbers by
-source declaration order, starting at `1`.
+FlatBuffers 字段没有显式 field ID。Fory 会按源码声明顺序分配字段号，从 `1` 开始。
-### Scalar Type Mapping
+### 标量类型映射
| FlatBuffers | Fory Type |
| ----------- | --------- |
@@ -88,14 +78,14 @@ source declaration order, starting at `1`.
| `bool` | `bool` |
| `string` | `string` |
-Vectors (`[T]`) map to Fory lists.
+向量（`[T]`）映射为 Fory 列表类型。
-### Unions
+### 联合类型
-FlatBuffers unions map to Fory unions.
+FlatBuffers union 映射为 Fory union。
-- Case IDs are assigned by declaration order, starting at `1`.
-- Case names are derived from type names using snake_case field naming.
+- case ID 按声明顺序分配，从 `1` 开始。
+- case 名称由类型名转换为 snake_case 字段名。
**FlatBuffers**
@@ -110,7 +100,7 @@ table Container {
}
```
-**Fory shape after translation**
+**转换后的 Fory 结构**
```protobuf
union Payload {
@@ -123,33 +113,31 @@ message Container {
}
```
-### Defaults and Metadata
+### 默认值与元数据
-- FlatBuffers default values are parsed but not applied as Fory runtime defaults.
-- Non-Fory metadata attributes are preserved as generic options in IR and may be
- consumed by downstream tooling.
+- FlatBuffers 默认值会被解析，但不会作为 Fory 运行时默认值生效。
+- 非 Fory 的 metadata 属性会作为通用 option 保留在 IR 中，供下游工具按需消费。
-## Fory-Specific Attributes in FlatBuffers
+## FlatBuffers 中的 Fory 扩展属性
-FlatBuffers metadata attributes use `key:value`. For Fory-specific options, use
-`fory_` (or `fory.`) prefix in `.fbs`; the prefix is removed during parsing.
+FlatBuffers metadata 属性写法为 `key:value`。对于 Fory 扩展选项，在 `.fbs` 中使用 `fory_`（或 `fory.`）前缀；解析时会去掉该前缀。
-### Supported Field Attributes
+### 支持的字段属性
-| FlatBuffers Attribute | Effect in Fory |
-| -------------------------------- | ----------------------------------------------------- |
-| `fory_ref:true` | Enable reference tracking for the field |
-| `fory_nullable:true` | Mark field optional/nullable |
-| `fory_weak_ref:true` | Enable weak reference semantics and implies `ref` |
-| `fory_thread_safe_pointer:false` | For ref fields, select non-thread-safe pointer flavor |
+| FlatBuffers Attribute | 在 Fory 中的效果 |
+| -------------------------------- | --------------------------------- |
+| `fory_ref:true` | 为字段启用引用跟踪 |
+| `fory_nullable:true` | 将字段标记为 optional/nullable |
+| `fory_weak_ref:true` | 启用弱引用语义，并隐含开启 `ref` |
+| `fory_thread_safe_pointer:false` | 对 ref 字段选择非线程安全指针类型 |
-Semantics:
+语义说明：
-- `fory_weak_ref:true` implies `ref`.
-- `fory_thread_safe_pointer` only takes effect when the field is ref-tracked.
-- For list fields, `fory_ref:true` applies to list elements.
+- `fory_weak_ref:true` 隐含 `ref`。
+- `fory_thread_safe_pointer` 仅在字段启用 ref 跟踪时生效。
+- 对列表字段，`fory_ref:true` 作用于列表元素。
-Example:
+示例：
```fbs
table Node {
@@ -159,42 +147,37 @@ table Node {
}
```
-## Generated Code Differences
+## 生成代码差异
-Using `.fbs` as input to Fory still produces normal Fory-generated code, not
-FlatBuffers `ByteBuffer`-style APIs.
+即使用 `.fbs` 作为 Fory 输入，生成的依然是标准 Fory 代码，而不是 FlatBuffers 的 `ByteBuffer` 风格 API。
-- Java: POJOs/records with Fory metadata
-- Python: dataclasses plus registration helpers
-- Go/Rust/C++: native structs and Fory metadata
+- Java：带 Fory 元数据的 POJO/record
+- Python：dataclass 与注册辅助代码
+- Go/Rust/C++：原生结构体与 Fory 元数据
-The serialization format is Fory binary protocol, not FlatBuffers wire format.
+最终序列化格式是 Fory 二进制协议，而不是 FlatBuffers 线格式。
-## Usage
+## 用法
-Compile a FlatBuffers schema directly:
+直接编译 FlatBuffers schema：
```bash
foryc schema.fbs --lang java,python --output ./generated
```
-Inspect translated schema syntax for debugging:
+输出转换后的 Fory schema 语法以便调试：
```bash
foryc schema.fbs --emit-fdl --emit-fdl-path ./translated
```
-## Migration Notes
+## 迁移注意事项
-1. Keep existing `namespace` values stable to keep type registration stable.
-2. Review fields that relied on FlatBuffers default literals and set explicit
- defaults in application code if needed.
-3. Add `fory_ref`/`fory_weak_ref` where object-graph semantics are required.
-4. Validate generated model behavior with roundtrip tests before replacing
- existing serialization paths.
+1. 保持现有 `namespace` 稳定，以保证类型注册稳定。
+2. 检查依赖 FlatBuffers 字面量默认值的字段，并在业务代码中补充显式默认值。
+3. 在需要对象图语义的字段上添加 `fory_ref`/`fory_weak_ref`。
+4. 替换现有序列化路径前，先用 roundtrip 测试验证生成模型行为。
-## Summary
+## 总结
-FlatBuffers input lets you reuse existing `.fbs` schemas while moving to Fory's
-runtime and code generation model. This is useful for incremental migration,
-while preserving schema investment and adopting Fory-native object APIs.
+FlatBuffers 输入模式可让你复用现有 `.fbs` schema，同时迁移到 Fory 运行时与代码生成模型。它适合渐进式迁移场景：既保留既有 schema 投入，又能采用 Fory 原生对象 API。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code.md
index ce33bac1e9..cadf241ab8 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code.md
@@ -19,20 +19,18 @@ license: |
limitations under the License.
---
-> 中文导读：本文档为 Fory 编译器/协议规范文档的中文译稿。为避免改变规范语义，代码片段、类型名、协议字段名保持英文，说明性文字优先翻译为中文。
+本文档说明各目标语言的代码生成结果与结构。
-本文档说明各目标语言的生成代码结构。
+Fory IDL 生成的类型遵循宿主语言习惯，可直接作为领域对象使用。生成代码同时包含 `to/from bytes` 辅助方法和类型注册辅助逻辑。
-Fory IDL generated types are idiomatic in host languages and can be used directly as domain objects. Generated types also include `to/from bytes` helpers and registration helpers.
+## 参考 Schema
-## Reference Schemas
+下面示例基于两个真实 schema：
-The examples below use two real schemas:
+1. `addressbook.fdl`（显式类型 ID）
+2. `auto_id.fdl`（未显式声明类型 ID）
-1. `addressbook.fdl` (explicit type IDs)
-2. `auto_id.fdl` (no explicit type IDs)
-
-### `addressbook.fdl` (excerpt)
+### `addressbook.fdl`（节选）
```protobuf
package addressbook;
@@ -79,7 +77,7 @@ message AddressBook [id=103] {
}
```
-### `auto_id.fdl` (excerpt)
+### `auto_id.fdl`（节选）
```protobuf
package auto_id;
@@ -114,17 +112,17 @@ union Wrapper {
## Java
-### Output Layout
+### 输出布局
-For `package addressbook`, Java output is generated under:
+对于 `package addressbook`，Java 输出通常位于：
- `<java_out>/addressbook/`
-- Type files: `AddressBook.java`, `Person.java`, `Dog.java`, `Cat.java`, `Animal.java`
-- Registration helper: `AddressbookForyRegistration.java`
+- 类型文件：`AddressBook.java`、`Person.java`、`Dog.java`、`Cat.java`、`Animal.java`
+- 注册辅助类：`AddressbookForyRegistration.java`
-### Type Generation
+### 类型生成
-Messages generate Java classes with `@ForyField`, default constructors, getters/setters, and byte helpers:
+message 会生成带 `@ForyField`、默认构造器、getter/setter 以及字节辅助方法的 Java 类：
```java
public class Person {
@@ -156,7 +154,7 @@ public class Person {
}
```
-Unions generate classes extending `org.apache.fory.type.union.Union`:
+union 会生成继承 `org.apache.fory.type.union.Union` 的类：
```java
public final class Animal extends Union {
@@ -177,9 +175,9 @@ public final class Animal extends Union {
}
```
-### Registration
+### 注册
-Generated registration helper:
+生成的注册辅助方法：
```java
public static void register(Fory fory) {
@@ -194,7 +192,7 @@ public static void register(Fory fory) {
}
```
-For schemas without explicit `[id=...]`, generated registration uses computed numeric IDs (for example from `auto_id.fdl`):
+对于未显式 `[id=...]` 的 schema，注册代码会使用计算得到的数值 ID（例如 `auto_id.fdl`）：
```java
resolver.register(Status.class, 1124725126L);
@@ -204,7 +202,7 @@ resolver.registerUnion(Envelope.Detail.class, 1609214087L, new org.apache.fory.s
resolver.register(Envelope.Payload.class, 2862577837L);
```
-If `option enable_auto_type_id = false;` is set, registration uses namespace and type name:
+若设置 `option enable_auto_type_id = false;`，则按命名空间与类型名注册：
```java
resolver.register(Config.class, "myapp.models", "Config");
@@ -215,7 +213,7 @@ resolver.registerUnion(
new org.apache.fory.serializer.UnionSerializer(fory, Holder.class));
```
-### Usage
+### 使用示例
```java
Person person = new Person();
@@ -228,15 +226,15 @@ Person restored = Person.fromBytes(data);
## Python
-### Output Layout
+### 输出布局
-Python output is one module per schema file, for example:
+Python 每个 schema 文件生成一个模块，例如：
- `<python_out>/addressbook.py`
-### Type Generation
+### 类型生成
-Unions generate a case enum plus a `Union` subclass with typed helpers:
+union 生成 case 枚举与 `Union` 子类，并提供类型化辅助方法：
```python
class AnimalCase(Enum):
@@ -255,7 +253,7 @@ class Animal(Union):
def set_dog(self, v: Dog) -> None: ...
```
-Messages generate `@pyfory.dataclass` types, and nested types stay nested:
+message 生成 `@pyfory.dataclass` 类型，嵌套类型保持嵌套：
```python
@pyfory.dataclass
@@ -279,9 +277,9 @@ class Person:
def from_bytes(cls, data: bytes) -> "Person": ...
```
-### Registration
+### 注册
-Generated registration function:
+生成注册函数：
```python
def register_addressbook_types(fory: pyfory.Fory):
@@ -294,7 +292,7 @@ def register_addressbook_types(fory: pyfory.Fory):
fory.register_type(AddressBook, type_id=103)
```
-For schemas without explicit `[id=...]`, generated registration uses computed numeric IDs:
+未显式 `[id=...]` 时，注册代码使用计算得到的数值 ID：
```python
fory.register_type(Status, type_id=1124725126)
@@ -304,7 +302,7 @@ fory.register_union(Envelope.Detail, type_id=1609214087, serializer=Envelope.Det
fory.register_type(Envelope.Payload, type_id=2862577837)
```
-If `option enable_auto_type_id = false;` is set:
+若设置 `option enable_auto_type_id = false;`：
```python
fory.register_type(Config, namespace="myapp.models", typename="Config")
@@ -316,7 +314,7 @@ fory.register_union(
)
```
-### Usage
+### 使用示例
```python
person = Person(name="Alice", pet=Animal.dog(Dog(name="Rex", bark_volume=10)))
@@ -327,15 +325,15 @@ restored = Person.from_bytes(data)
## Rust
-### Output Layout
+### 输出布局
-Rust output is one module file per schema, for example:
+Rust 每个 schema 生成一个模块文件，例如：
- `<rust_out>/addressbook.rs`
-### Type Generation
+### 类型生成
-Unions map to Rust enums with `#[fory(id = ...)]` case attributes:
+union 映射为 Rust enum，并用 `#[fory(id = ...)]` 声明 case ID：
```rust
#[derive(ForyObject, Debug, Clone, PartialEq)]
@@ -347,7 +345,7 @@ pub enum Animal {
}
```
-Nested types generate nested modules:
+嵌套类型生成嵌套 module：
```rust
pub mod person {
@@ -370,7 +368,7 @@ pub mod person {
}
```
-Messages derive `ForyObject` and include `to_bytes`/`from_bytes` helpers:
+message 会 `derive(ForyObject)` 并生成 `to_bytes`/`from_bytes`：
```rust
#[derive(ForyObject, Debug, Clone, PartialEq, Default)]
@@ -384,9 +382,9 @@ pub struct Person {
}
```
-### Registration
+### 注册
-Generated registration function:
+生成注册函数：
```rust
pub fn register_types(fory: &mut Fory) -> Result<(), fory::Error> {
@@ -401,7 +399,7 @@ pub fn register_types(fory: &mut Fory) -> Result<(), fory::Error> {
}
```
-For schemas without explicit `[id=...]`, generated registration uses computed numeric IDs:
+未显式 `[id=...]` 时，注册代码使用计算得到的数值 ID：
```rust
fory.register::<Status>(1124725126)?;
@@ -411,14 +409,14 @@ fory.register_union::<envelope::Detail>(1609214087)?;
fory.register::<envelope::Payload>(2862577837)?;
```
-If `option enable_auto_type_id = false;` is set:
+若设置 `option enable_auto_type_id = false;`：
```rust
fory.register_by_namespace::<Config>("myapp.models", "Config")?;
fory.register_union_by_namespace::<Holder>("myapp.models", "Holder")?;
```
-### Usage
+### 使用示例
```rust
let person = Person {
@@ -433,15 +431,15 @@ let restored = Person::from_bytes(&bytes)?;
## C++
-### Output Layout
+### 输出布局
-C++ output is one header per schema file, for example:
+C++ 每个 schema 文件生成一个头文件，例如：
- `<cpp_out>/addressbook.h`
-### Type Generation
+### 类型生成
-Messages generate `final` classes with typed accessors and byte helpers:
+message 会生成 `final` 类，并包含类型化访问器与字节辅助方法：
```cpp
class Person final {
@@ -467,7 +465,7 @@ class Person final {
};
```
-Optional message fields generate `has_xxx`, `mutable_xxx`, and `clear_xxx` APIs:
+可选 message 字段会生成 `has_xxx`、`mutable_xxx`、`clear_xxx` API：
```cpp
class Envelope final {
@@ -487,7 +485,7 @@ class Envelope final {
};
```
-Unions generate `std::variant` wrappers:
+union 会生成基于 `std::variant` 的封装：
```cpp
class Animal final {
@@ -517,11 +515,11 @@ class Animal final {
};
```
-Generated headers also include `FORY_UNION`, `FORY_FIELD_CONFIG`, `FORY_ENUM`, and `FORY_STRUCT` macros for serialization metadata.
+生成头文件还会包含 `FORY_UNION`、`FORY_FIELD_CONFIG`、`FORY_ENUM`、`FORY_STRUCT` 等序列化元信息宏。
-### Registration
+### 注册
-Generated registration function:
+生成注册函数：
```cpp
inline void register_types(fory::serialization::BaseFory& fory) {
@@ -535,7 +533,7 @@ inline void register_types(fory::serialization::BaseFory& fory) {
}
```
-For schemas without explicit `[id=...]`, generated registration uses computed numeric IDs:
+未显式 `[id=...]` 时，注册代码使用计算得到的数值 ID：
```cpp
fory.register_enum<Status>(1124725126);
@@ -545,14 +543,14 @@ fory.register_union<Envelope::Detail>(1609214087);
fory.register_struct<Envelope::Payload>(2862577837);
```
-If `option enable_auto_type_id = false;` is set:
+若设置 `option enable_auto_type_id = false;`：
```cpp
fory.register_struct<Config>("myapp.models", "Config");
fory.register_union<Holder>("myapp.models", "Holder");
```
-### Usage
+### 使用示例
```cpp
addressbook::Person person;
@@ -565,17 +563,17 @@ auto restored = addressbook::Person::from_bytes(bytes.value());
## Go
-### Output Layout
+### 输出布局
-Go output path depends on schema options and `--go_out`.
+Go 输出路径受 schema 选项与 `--go_out` 共同影响。
-For `addressbook.fdl`, `go_package` is configured and generated output follows the configured import path/package (for example under your `--go_out` root).
+对于 `addressbook.fdl`，若配置了 `go_package`，生成结果会遵循对应 import path/package（位于 `--go_out` 根目录下）。
-Without `go_package`, output uses the requested `--go_out` directory and package-derived file naming.
+若未配置 `go_package`，则使用 `--go_out` 指定目录，并按 package 规则生成文件名与包名。
-### Type Generation
+### 类型生成
-Nested types use underscore naming by default (`Person_PhoneType`, `Person_PhoneNumber`):
+嵌套类型默认使用下划线命名（`Person_PhoneType`、`Person_PhoneNumber`）：
```go
type Person_PhoneType int32
@@ -592,7 +590,7 @@ type Person_PhoneNumber struct {
}
```
-Messages generate structs with `fory` tags and byte helpers:
+message 会生成带 `fory` tag 的 struct 与字节辅助方法：
```go
type Person struct {
@@ -606,7 +604,7 @@ func (m *Person) ToBytes() ([]byte, error) { ... }
func (m *Person) FromBytes(data []byte) error { ... }
```
-Unions generate typed case structs with constructors/accessors/visitor APIs:
+union 会生成 case struct，并提供构造器/访问器/visitor API：
```go
type AnimalCase uint32
@@ -624,9 +622,9 @@ func (u Animal) AsDog() (*Dog, bool) { ... }
func (u Animal) Visit(visitor AnimalVisitor) error { ... }
```
-### Registration
+### 注册
-Generated registration function:
+生成注册函数：
```go
func RegisterTypes(f *fory.Fory) error {
@@ -646,7 +644,7 @@ func RegisterTypes(f *fory.Fory) error {
}
```
-For schemas without explicit `[id=...]`, generated registration uses computed numeric IDs:
+未显式 `[id=...]` 时，注册代码使用计算得到的数值 ID：
```go
if err := f.RegisterEnum(Status(0), 1124725126); err != nil { ... }
@@ -656,20 +654,20 @@ if err := f.RegisterUnion(Envelope_Detail{}, 1609214087, fory.NewUnionSerializer
if err := f.RegisterStruct(Envelope_Payload{}, 2862577837); err != nil { ... }
```
-If `option enable_auto_type_id = false;` is set:
+若设置 `option enable_auto_type_id = false;`：
```go
if err := f.RegisterNamedStruct(Config{}, "myapp.models.Config"); err != nil { ... }
if err := f.RegisterNamedUnion(Holder{}, "myapp.models.Holder", fory.NewUnionSerializer(...)); err != nil { ... }
```
-`go_nested_type_style` controls nested type naming:
+`go_nested_type_style` 可控制嵌套类型命名风格：
```protobuf
option go_nested_type_style = "camelcase";
```
-### Usage
+### 使用示例
```go
person := &Person{
@@ -687,30 +685,30 @@ if err := restored.FromBytes(data); err != nil {
}
```
-## Cross-Language Notes
+## 跨语言说明
-### Type ID Behavior
+### 类型 ID 行为
-- Explicit `[id=...]` values are used directly in generated registration.
-- When type IDs are omitted, generated code uses computed numeric IDs (see `auto_id.*` outputs).
-- If `option enable_auto_type_id = false;` is set, generated registration uses namespace/type-name APIs instead of numeric IDs.
+- 显式 `[id=...]` 会直接用于生成注册代码。
+- 未声明类型 ID 时，生成代码会使用计算得到的数值 ID（参见 `auto_id.*` 输出）。
+- 若设置 `option enable_auto_type_id = false;`，则生成代码改为使用 namespace/type-name 注册 API，而非数值 ID。
-### Nested Type Shape
+### 嵌套类型形态
-| Language | Nested type form |
-| -------- | ------------------------------ |
-| Java | `Person.PhoneNumber` |
-| Python | `Person.PhoneNumber` |
-| Rust | `person::PhoneNumber` |
-| C++ | `Person::PhoneNumber` |
-| Go | `Person_PhoneNumber` (default) |
+| 语言 | 嵌套类型形式 |
+| ------ | ---------------------------- |
+| Java | `Person.PhoneNumber` |
+| Python | `Person.PhoneNumber` |
+| Rust | `person::PhoneNumber` |
+| C++ | `Person::PhoneNumber` |
+| Go | `Person_PhoneNumber`（默认） |
-### Byte Helper Naming
+### 字节辅助方法命名
-| Language | Helpers |
-| -------- | ------------------------- |
-| Java | `toBytes` / `fromBytes` |
-| Python | `to_bytes` / `from_bytes` |
-| Rust | `to_bytes` / `from_bytes` |
-| C++ | `to_bytes` / `from_bytes` |
-| Go | `ToBytes` / `FromBytes` |
+| 语言 | 辅助方法名称 |
+| ------ | ------------------------- |
+| Java | `toBytes` / `fromBytes` |
+| Python | `to_bytes` / `from_bytes` |
+| Rust | `to_bytes` / `from_bytes` |
+| C++ | `to_bytes` / `from_bytes` |
+| Go | `ToBytes` / `FromBytes` |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/index.md
index 58a4817492..8e26cdd387 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/index.md
@@ -19,15 +19,12 @@ license: |
limitations under the License.
---
-> 中文导读：本文档为 Fory 编译器/协议规范文档的中文译稿。为避免改变规范语义，代码片段、类型名、协议字段名保持英文，说明性文字优先翻译为中文。
-
-Fory IDL is a schema definition language for Apache Fory that enables type-safe
-cross-language serialization. Define your data structures once and generate
-native data structure code for Java, Python, Go, Rust, and C++.
+Fory IDL 是 Apache Fory 的 Schema 定义语言，可实现类型安全的跨语言序列化。
+你只需定义一次数据结构，即可为 Java、Python、Go、Rust 和 C++ 生成原生数据结构代码。
## 示例 Schema
-Fory IDL provides a simple, intuitive syntax for defining cross-language data structures:
+Fory IDL 提供了简单直观的语法来定义跨语言数据结构：
```protobuf
package example;
@@ -73,54 +70,54 @@ union Animal [id=106] {
}
```
-## Why Fory IDL?
+## 为什么选择 Fory IDL？
-### Schema-First Development
+### Schema 优先开发
-Define your data model once in Fory IDL and generate consistent, type-safe code across all languages. This ensures:
+在 Fory IDL 中一次定义数据模型，即可在所有语言中生成一致且类型安全的代码。这样可以确保：
-- **Type Safety**: Catch type errors at compile time, not runtime
-- **Consistency**: All languages use the same field names, types, and structures
-- **Documentation**: Schema serves as living documentation
-- **Evolution**: Managed schema changes across all implementations
+- **类型安全**：在编译期而不是运行期发现类型错误
+- **一致性**：各语言使用相同字段名、类型和结构
+- **文档性**：Schema 本身就是可持续演进的文档
+- **可演进性**：可在所有实现中受控地进行 Schema 变更
-### Fory-Native Features
+### Fory 原生能力
-Unlike generic IDLs, Fory IDL is designed specifically for Fory serialization:
+与通用 IDL 不同，Fory IDL 专门为 Fory 序列化设计：
-- **Reference Tracking**: First-class support for shared and circular references via `ref`
-- **Nullable Fields**: Explicit `optional` modifier for nullable types
-- **Type Registration**: Built-in support for both numeric IDs and namespace-based registration
-- **Native Code Generation**: Generates idiomatic code with Fory annotations/macros
+- **引用跟踪**：通过 `ref` 一等支持共享引用和循环引用
+- **可空字段**：通过 `optional` 显式声明可空类型
+- **类型注册**：内置支持数值 ID 与基于命名空间的注册
+- **原生代码生成**：生成带 Fory 注解/宏的语言惯用代码
-### Low Integration Overhead
+### 集成开销低
-Generated code uses native language constructs:
+生成代码直接使用各语言原生构造：
-- Java: Plain POJOs with `@ForyField` annotations
-- Python: Dataclasses with type hints
-- Go: Structs with struct tags
-- Rust: Structs with `#[derive(ForyObject)]`
-- C++: Structs with `FORY_STRUCT` macros
+- Java：带 `@ForyField` 注解的普通 POJO
+- Python：带类型提示的 dataclass
+- Go：带 struct tag 的结构体
+- Rust：带 `#[derive(ForyObject)]` 的结构体
+- C++：带 `FORY_STRUCT` 宏的结构体
-## Quick Start
+## 快速开始
-### 1. Install the Compiler
+### 1. 安装编译器
```bash
pip install fory-compiler
```
-Or install from source:
+或从源码安装：
```bash
cd compiler
pip install -e .
```
-### 2. Write Your Schema
+### 2. 编写 Schema
-Create `example.fdl`:
+创建 `example.fdl`：
```protobuf
package example;
@@ -132,19 +129,19 @@ message Person {
}
```
-### 3. Generate Code
+### 3. 生成代码
```bash
-# Generate for all languages
+# 为所有语言生成
foryc example.fdl --output ./generated
-# Generate for specific languages
+# 为指定语言生成
foryc example.fdl --lang java,python --output ./generated
```
-### 4. Use Generated Code
+### 4. 使用生成代码
-**Java:**
+**Java：**
```java
Person person = new Person();
@@ -153,34 +150,34 @@ person.setAge(30);
byte[] data = person.toBytes();
```
-**Python:**
+**Python：**
```python
import pyfory
from example import Person
person = Person(name="Alice", age=30)
-data = bytes(person) # or `person.to_bytes()`
+data = bytes(person) # 或 `person.to_bytes()`
```
-## Documentation
+## 文档导航
-| Document | Description |
-| ----------------------------------------------- | ------------------------------------------------- |
-| [Fory IDL Syntax](schema-idl.md) | Complete language syntax and grammar |
-| [Type System](schema-idl.md#type-system) | Primitive types, collections, and type rules |
-| [Compiler Guide](compiler-guide.md) | CLI options and build integration |
-| [Generated Code](generated-code.md) | Output format for each target language |
-| [Protocol Buffers IDL Support](protobuf-idl.md) | Comparison with protobuf and migration guide |
-| [FlatBuffers IDL Support](flatbuffers-idl.md) | FlatBuffers mapping rules and codegen differences |
+| 文档 | 说明 |
+| -------------------------------------------- | ---------------------------------- |
+| [Fory IDL 语法](schema-idl.md) | 完整语言语法与文法 |
+| [类型系统](schema-idl.md#type-system) | 基础类型、集合类型与类型规则 |
+| [编译器指南](compiler-guide.md) | CLI 选项与构建集成 |
+| [生成代码](generated-code.md) | 各目标语言的输出格式 |
+| [Protocol Buffers IDL 支持](protobuf-idl.md) | 与 protobuf 的对比及迁移指南 |
+| [FlatBuffers IDL 支持](flatbuffers-idl.md) | FlatBuffers 映射规则与代码生成差异 |
-## Key Concepts
+## 核心概念
-### Field Modifiers
+### 字段修饰符
-- **`optional`**: Field can be null/None
-- **`ref`**: Enable reference tracking for shared/circular references
-- **`list`**: Field is a list/array (alias: `repeated`)
+- **`optional`**：字段可为 null/None
+- **`ref`**：为共享/循环引用启用引用跟踪
+- **`list`**：字段为列表/数组（别名：`repeated`）
```protobuf
message Example {
@@ -190,26 +187,26 @@ message Example {
}
```
-### Cross-Language Compatibility
+### 跨语言兼容
-Fory IDL types map to native types in each language:
+Fory IDL 类型会映射为各语言原生类型：
-| Fory IDL Type | Java | Python | Go | Rust | C++ |
+| Fory IDL 类型 | Java | Python | Go | Rust | C++ |
| ------------- | --------- | -------------- | -------- | -------- | ------------- |
| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` |
| `string` | `String` | `str` | `string` | `String` | `std::string` |
| `bool` | `boolean` | `bool` | `bool` | `bool` | `bool` |
-See [Type System](schema-idl.md#type-system) for complete mappings.
+完整映射请参见 [类型系统](schema-idl.md#type-system)。
-## Best Practices
+## 最佳实践
-1. **Use meaningful package names**: Group related types together
-2. **Assign type IDs for performance**: Numeric IDs are faster than name-based registration
-3. **Reserve ID ranges**: Leave gaps for future additions (e.g., 100-199 for users, 200-299 for orders)
-4. **Use `optional` explicitly**: Make nullability clear in the schema
-5. **Use `ref` for shared objects**: Enable reference tracking when objects are shared
+1. **使用有意义的 package 名称**：将相关类型分组管理
+2. **为性能分配类型 ID**：数值 ID 比基于名称的注册更高效
+3. **预留 ID 范围**：为后续扩展保留空隙（例如用户 100-199，订单 200-299）
+4. **显式使用 `optional`**：清晰表达可空语义
+5. **共享对象使用 `ref`**：对象可能被多处引用时开启引用跟踪
-## Examples
+## 示例
-See the [examples](https://github.com/apache/fory/tree/main/compiler/examples) directory for complete working examples.
+完整可运行示例见 [examples](https://github.com/apache/fory/tree/main/compiler/examples) 目录。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/protobuf-idl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/protobuf-idl.md
index 2a6865d1e2..d5bb1d8791 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/protobuf-idl.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/protobuf-idl.md
@@ -19,56 +19,50 @@ license: |
limitations under the License.
---
-> 中文导读：本文档为 Fory 编译器/协议规范文档的中文译稿。为避免改变规范语义，代码片段、类型名、协议字段名保持英文，说明性文字优先翻译为中文。
-
本页说明 Apache Fory 如何处理 Protocol Buffers（`.proto`）schema、protobuf 概念如何映射到 Fory，以及 protobuf 专用 Fory 扩展选项的使用方式。
## 本页内容
-- Choosing protobuf vs Fory for your use case
-- Syntax and semantic differences that matter during migration
-- Supported Fory extension options in protobuf files
-- Practical migration patterns from protobuf to Fory
+- 如何在具体场景下选择 protobuf 或 Fory
+- 迁移时需要关注的语法与语义差异
+- `.proto` 文件中支持的 Fory 扩展选项
+- 从 protobuf 迁移到 Fory 的实践路径
## 快速决策指南
-| Situation | Recommended Format |
-| ------------------------------------------------------------- | ------------------ |
-| You are building gRPC APIs and rely on protobuf tooling | Protocol Buffers |
-| You need maximum object-graph performance and ref tracking | Fory |
-| You need circular/shared references in serialized data | Fory |
-| You need strong unknown-field behavior for wire compatibility | Protocol Buffers |
-| You need native structs/classes instead of protobuf wrappers | Fory |
+| 场景 | 建议格式 |
+| ----------------------------------------------------- | ---------------- |
+| 主要构建 gRPC API，依赖 protobuf 工具链 | Protocol Buffers |
+| 需要极致对象图性能与引用跟踪 | Fory |
+| 需要在序列化数据中表达循环/共享引用 | Fory |
+| 需要强 unknown-field 语义保证线格式兼容 | Protocol Buffers |
+| 希望直接使用原生 struct/class，而非 protobuf 包装类型 | Fory |
## Protobuf 与 Fory 对比
-| Aspect | Protocol Buffers | Fory |
-| ------------------ | ----------------------------- | ------------------------------------- |
-| Primary purpose | RPC/message contracts | High-performance object serialization |
-| Encoding model | Tag-length-value | Fory binary protocol |
-| Reference tracking | Not built-in | First-class (`ref`) |
-| Circular refs | Not supported | Supported |
-| Unknown fields | Preserved | Not preserved |
-| Generated types | Protobuf-specific model types | Native language constructs |
-| gRPC ecosystem | Native | In progress (active development) |
+| 维度 | Protocol Buffers | Fory |
+| --------- | --------------------- | ---------------------- |
+| 主要目标 | RPC/消息契约 | 高性能对象序列化 |
+| 编码模型 | Tag-Length-Value | Fory 二进制协议 |
+| 引用跟踪 | 非内建 | 一等支持（`ref`） |
+| 循环引用 | 不支持 | 支持 |
+| 未知字段 | 保留 | 不保留 |
+| 生成类型 | protobuf 专用模型类型 | 语言原生构造 |
+| gRPC 生态 | 原生成熟 | 持续建设中（活跃开发） |
-Fory gRPC support is under active development. For production gRPC
-workflows today, protobuf remains the mature/default choice.
+Fory 的 gRPC 支持仍在持续开发中。当前生产级 gRPC 工作流里，protobuf 仍是更成熟的默认选择。
## 为什么使用 Apache Fory
-- Idiomatic generated code: Fory IDL generates language-idiomatic classes and
- structs that can be used directly as domain objects.
-- Faster serialization: In Fory benchmarks, Fory can be around 10x faster than
- protobuf for object serialization workloads.
-- Better graph modeling: Shared and circular references are first-class features
- instead of application-level ID-link workarounds.
+- **代码更贴近语言习惯**：Fory IDL 生成的类和结构体可直接作为业务领域对象使用。
+- **序列化性能更高**：在 Fory 基准中，Fory 在对象序列化场景中可显著快于 protobuf。
+- **对象图表达更自然**：共享引用和循环引用是内建能力，无需通过业务层 ID 关联绕过。
-See benchmark details under [Performance References](#performance-references).
+性能细节请参见 [性能参考](#性能参考)。
-## Syntax and Semantic Mapping
+## 语法与语义映射
-### Package and File Options
+### Package 与文件级选项
**Protocol Buffers**
@@ -85,10 +79,9 @@ option go_package = "example.com/models";
package example.models;
```
-Fory uses one package namespace for cross-language registration. Language-specific
-package placement is still configurable in code generation.
+Fory 使用统一 package 命名空间做跨语言注册。语言特定的包路径仍可在代码生成阶段单独配置。
-### Message and Enum Definitions
+### Message 与 Enum 定义
**Protocol Buffers**
@@ -126,16 +119,15 @@ enum Status [id=102] {
}
```
-Key differences:
+关键差异：
-- Fory can assign stable type IDs directly (`[id=...]`).
-- Fory uses `list<T>` (with `repeated T` as alias).
-- Enum naming conventions are language-driven instead of protobuf prefix style.
+- Fory 可直接分配稳定类型 ID（`[id=...]`）。
+- Fory 使用 `list<T>`（`repeated T` 为兼容别名）。
+- 枚举命名更偏向语言习惯，而非 protobuf 前缀风格。
-### `oneof` to `union`
+### `oneof` 到 `union`
-Protobuf `oneof` is translated to a nested Fory `union` plus an optional field
-referencing that union.
+protobuf 的 `oneof` 会被翻译为嵌套 Fory `union`，并增加一个可选字段指向该 union。
**Protocol Buffers**
@@ -148,7 +140,7 @@ message Event {
}
```
-**Fory-style shape after translation**
+**转换后的 Fory 结构**
```protobuf
message Event {
@@ -160,42 +152,42 @@ message Event {
}
```
-Notes:
+说明：
-- Union case IDs are derived from the original `oneof` field numbers.
-- The synthetic union field uses the smallest `oneof` case number.
+- union case ID 来自原 `oneof` 字段号。
+- 自动生成的 union 引用字段使用 `oneof` 中最小字段号。
-### Imports and Well-Known Types
+### Import 与 Well-Known Types
-Protobuf imports are supported. Common well-known types map directly:
+支持 protobuf import。常见 well-known types 会直接映射：
- `google.protobuf.Timestamp` -> `timestamp`
- `google.protobuf.Duration` -> `duration`
- `google.protobuf.Any` -> `any`
-## 类型映射 Highlights
-
-| Protobuf Type | Fory Mapping |
-| ---------------------------------------- | ---------------------------------------- |
-| `bool` | `bool` |
-| `int32`, `uint32` | variable-length 32-bit integer kinds |
-| `sint32` | zigzag 32-bit integer |
-| `int64`, `uint64` | variable-length 64-bit integer kinds |
-| `sint64` | zigzag 64-bit integer |
-| `fixed32`, `fixed64` | fixed-width unsigned integer kinds |
-| `sfixed32`, `sfixed64` | fixed-width signed integer kinds |
-| `float`, `double` | `float32`, `float64` |
-| `string`, `bytes` | `string`, `bytes` |
-| `repeated T` | `list<T>` |
-| `map<K, V>` | `map<K, V>` |
-| `optional T` | `optional T` |
-| `oneof` | `union` + optional union reference field |
-| `int64 [(fory).type = "tagged_int64"]` | `tagged_int64` encoding |
-| `uint64 [(fory).type = "tagged_uint64"]` | `tagged_uint64` encoding |
-
-## Fory Extension Options (Protobuf)
-
-Fory-specific options in `.proto` use the `(fory).` prefix.
+## 类型映射要点
+
+| Protobuf Type | Fory 映射 |
+| ---------------------------------------- | ----------------------------- |
+| `bool` | `bool` |
+| `int32`, `uint32` | 可变长 32 位整型家族 |
+| `sint32` | zigzag 32 位整型 |
+| `int64`, `uint64` | 可变长 64 位整型家族 |
+| `sint64` | zigzag 64 位整型 |
+| `fixed32`, `fixed64` | 定长无符号整型家族 |
+| `sfixed32`, `sfixed64` | 定长有符号整型家族 |
+| `float`, `double` | `float32`, `float64` |
+| `string`, `bytes` | `string`, `bytes` |
+| `repeated T` | `list<T>` |
+| `map<K, V>` | `map<K, V>` |
+| `optional T` | `optional T` |
+| `oneof` | `union` + 可选 union 引用字段 |
+| `int64 [(fory).type = "tagged_int64"]` | `tagged_int64` 编码 |
+| `uint64 [(fory).type = "tagged_uint64"]` | `tagged_uint64` 编码 |
+
+## Fory 扩展选项（Protobuf）
+
+`.proto` 文件中的 Fory 专用选项使用 `(fory).` 前缀。
```protobuf
option (fory).enable_auto_type_id = true;
@@ -206,46 +198,46 @@ message TreeNode {
}
```
-### File-Level Options
+### 文件级选项
-| Option | Type | Description |
-| ------------------------------------ | ------ | -------------------------------------------------------------- |
-| `(fory).use_record_for_java_message` | bool | Generate Java records for all messages in this file |
-| `(fory).polymorphism` | bool | Enable polymorphic serialization metadata by default |
-| `(fory).enable_auto_type_id` | bool | Auto-generate type IDs when omitted (compiler default is true) |
-| `(fory).evolving` | bool | Default schema-evolution behavior for messages |
-| `(fory).go_nested_type_style` | string | Go nested naming style: `underscore` (default) or `camelcase` |
+| 选项 | 类型 | 说明 |
+| ------------------------------------ | ------ | --------------------------------------------------- |
+| `(fory).use_record_for_java_message` | bool | 对该文件所有 message 生成 Java record |
+| `(fory).polymorphism` | bool | 默认开启多态序列化元信息 |
+| `(fory).enable_auto_type_id` | bool | 缺失时自动生成类型 ID（编译器默认 true） |
+| `(fory).evolving` | bool | message 的默认 schema 演进行为 |
+| `(fory).go_nested_type_style` | string | Go 嵌套命名风格：`underscore`（默认）或 `camelcase` |
-### Message and Enum Options
+### Message 与 Enum 级选项
-| Option | Applies To | Type | Description |
-| ---------------------------- | ------------- | ------ | ---------------------------------------- |
-| `(fory).id` | message, enum | int | Explicit type ID for registration |
-| `(fory).alias` | message, enum | string | Alternate name used for auto-ID hashing |
-| `(fory).evolving` | message | bool | Override file-level evolution setting |
-| `(fory).use_record_for_java` | message | bool | Generate Java record for this message |
-| `(fory).deprecated` | message, enum | bool | Mark type as deprecated |
-| `(fory).namespace` | message | string | Override default package-based namespace |
+| 选项 | 作用对象 | 类型 | 说明 |
+| ---------------------------- | ------------- | ------ | ----------------------------- |
+| `(fory).id` | message, enum | int | 显式类型 ID（用于注册） |
+| `(fory).alias` | message, enum | string | 自动 ID 哈希使用的别名 |
+| `(fory).evolving` | message | bool | 覆盖文件级演进设置 |
+| `(fory).use_record_for_java` | message | bool | 为该 message 生成 Java record |
+| `(fory).deprecated` | message, enum | bool | 标记类型为弃用 |
+| `(fory).namespace` | message | string | 覆盖默认 package 命名空间 |
-### Field-Level Options
+### 字段级选项
-| Option | Type | Description |
-| ---------------------------- | ------ | ------------------------------------------------------------ |
-| `(fory).ref` | bool | Enable reference tracking for this field |
-| `(fory).nullable` | bool | Treat field as nullable (`optional`) |
-| `(fory).weak_ref` | bool | Generate weak pointer semantics (C++/Rust codegen) |
-| `(fory).thread_safe_pointer` | bool | Rust pointer flavor for ref fields (`Arc` vs `Rc`) |
-| `(fory).deprecated` | bool | Mark field as deprecated |
-| `(fory).type` | string | Primitive override, currently `tagged_int64`/`tagged_uint64` |
+| 选项 | 类型 | 说明 |
+| ---------------------------- | ------ | ----------------------------------------------------- |
+| `(fory).ref` | bool | 为该字段启用引用跟踪 |
+| `(fory).nullable` | bool | 将字段视为可空（`optional`） |
+| `(fory).weak_ref` | bool | 生成弱指针语义（C++/Rust 代码生成） |
+| `(fory).thread_safe_pointer` | bool | ref 字段在 Rust 中的指针类型（`Arc` vs `Rc`） |
+| `(fory).deprecated` | bool | 标记字段为弃用 |
+| `(fory).type` | string | 基础类型覆盖，目前支持 `tagged_int64`/`tagged_uint64` |
-Reference option behavior:
+引用相关行为：
-- `weak_ref = true` implies ref tracking.
-- For `repeated` fields, `(fory).ref = true` applies to list elements.
-- For `map<K, V>` fields, `(fory).ref = true` applies to map values.
-- `weak_ref` and `thread_safe_pointer` are codegen hints for C++/Rust.
+- `weak_ref = true` 隐含开启 ref 跟踪。
+- 对 `repeated` 字段，`(fory).ref = true` 作用于列表元素。
+- 对 `map<K, V>` 字段，`(fory).ref = true` 作用于 map value。
+- `weak_ref` 与 `thread_safe_pointer` 是 C++/Rust 代码生成提示。
-### Option Examples by Shape
+### 典型选项组合示例
```protobuf
message Graph {
@@ -256,12 +248,11 @@ message Graph {
}
```
-## Reference Tracking vs Protobuf IDs
+## 引用跟踪 vs Protobuf ID 关联
-Protobuf itself does not preserve shared/cyclic object graphs. With Fory
-protobuf extensions, you can opt into graph semantics.
+protobuf 本身不保留共享/循环对象图。借助 Fory protobuf 扩展，可以显式启用对象图语义。
-**Without Fory ref options (protobuf-style IDs):**
+**不使用 Fory ref 选项（protobuf 风格 ID 关联）：**
```protobuf
message TreeNode {
@@ -271,7 +262,7 @@ message TreeNode {
}
```
-**With Fory ref options (object graph):**
+**使用 Fory ref 选项（对象图语义）：**
```protobuf
message TreeNode {
@@ -280,37 +271,34 @@ message TreeNode {
}
```
-## Migration Guide: Protobuf to Fory
+## 迁移指南：Protobuf 到 Fory
-### Step 1: Translate Schema Syntax
+### 第 1 步：转换 schema 语法
-- Keep package names stable.
-- Replace `repeated T` with `list<T>` (or keep `repeated` alias).
-- Add explicit `[id=...]` where you need stable numeric registration.
+- 保持 package 名称稳定。
+- 将 `repeated T` 改为 `list<T>`（或保留 `repeated` 别名）。
+- 在需要稳定数值注册的位置添加显式 `[id=...]`。
-### Step 2: Convert `oneof` and Special Types
+### 第 2 步：处理 `oneof` 与特殊类型
-- `oneof` -> `union` + optional union field.
-- Map protobuf well-known types to Fory primitives (`timestamp`, `duration`, `any`).
+- `oneof` -> `union` + 可选 union 字段。
+- 将 protobuf well-known types 映射到 Fory 基础类型（`timestamp`、`duration`、`any`）。
-### Step 3: Replace Protobuf Workarounds with `ref`
+### 第 3 步：用 `ref` 替换 protobuf 的对象图绕过方案
-Where protobuf used manual ID links for object graphs, switch to Fory `ref`
-modifiers (and optional `ref(weak=true)` where needed).
+若 protobuf 里通过手工 ID 关联表达对象图，迁移到 Fory 后应改用 `ref` 修饰符（必要时使用 `ref(weak=true)`）。
-### Step 4: Update Build/Codegen
+### 第 4 步：更新构建与代码生成
-Replace protobuf generation steps with the Fory compiler invocation for target
-languages.
+将 protobuf 代码生成步骤替换为 Fory 编译器针对目标语言的生成命令。
-### Step 5: Run Compatibility Checks
+### 第 5 步：执行兼容性验证
-For staged migrations, keep both formats in parallel and verify payload-level
-parity with integration tests.
+分阶段迁移时，可并行保留两种格式，并通过集成测试验证 payload 级一致性。
-## Coexistence Strategy
+## 共存策略
-You can run protobuf and Fory in parallel during migration:
+迁移期间可以并行运行 protobuf 与 Fory：
```java
public byte[] serialize(Object obj, Format format) {
@@ -321,16 +309,13 @@ public byte[] serialize(Object obj, Format format) {
}
```
-Use translators at service boundaries while internal object-graph heavy paths
-migrate first.
+可在服务边界设置转换层，并优先迁移内部对象图较重的链路。
-## Performance References
+## 性能参考
- Benchmarks: https://fory.apache.org/docs/introduction/benchmark
- Benchmark code: https://github.com/apache/fory/tree/main/benchmarks
-## Summary
+## 总结
-Use protobuf when your primary concern is API contracts and gRPC ecosystem
-integration. Use Fory when object-graph performance, native models, and
-reference semantics are the primary concern.
+当主要关注 API 契约与 gRPC 生态时，建议使用 protobuf。若主要关注对象图性能、原生数据模型与引用语义，建议使用 Fory。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/schema-idl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/schema-idl.md
index ee420bd790..be6d5c6b2a 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/schema-idl.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/schema-idl.md
@@ -19,37 +19,19 @@ license: |
limitations under the License.
---
-## 中文章节导读
+本文档给出 Fory IDL 的语法与语义参考，覆盖文件结构、类型系统、字段规则、选项与类型注册策略。
-本文描述 Fory IDL 的语法与语义规则，覆盖文件结构、声明、类型定义、字段约束、注解与扩展选项。它是编译器前端解析与代码生成的基础约束文档。
-
-阅读时可重点关注：
-
-1. **文件级结构**：package、option、import 与类型声明顺序。
-2. **类型系统语法**：enum/message/union 及字段声明规则。
-3. **字段标签与属性**：字段 ID、可空、引用、默认值与兼容性约束。
-4. **命名与作用域**：类型可见性、嵌套声明与名称解析。
-5. **与 protobuf/flatbuffers 的映射关系**：迁移与互操作规则。
-
-为保证编译行为一致，语法关键字、示例 schema 与标识符保持英文；说明性段落使用中文。
-
-> 中文导读：本文档为 Fory 编译器/协议规范文档的中文译稿。为避免改变规范语义，代码片段、类型名、协议字段名保持英文，说明性文字优先翻译为中文。
-
-本文档提供 Fory IDL 的语法与语义参考。
-
-For compiler usage and build integration, see
-[Compiler Guide](compiler-guide.md). For protobuf/FlatBuffers frontend mapping
-rules, see [Protocol Buffers IDL Support](protobuf-idl.md) and
-[FlatBuffers IDL Support](flatbuffers-idl.md).
+编译器使用方式与构建集成请参见 [Compiler Guide](compiler-guide.md)。
+protobuf/FlatBuffers 前端映射请参见 [Protocol Buffers IDL Support](protobuf-idl.md) 与 [FlatBuffers IDL Support](flatbuffers-idl.md)。
## 文件结构
-An Fory IDL file typically consists of:
+一个 Fory IDL 文件通常包含：
-1. Optional package declaration
-2. Optional file-level options
-3. Optional import statements
-4. Type definitions (enums, messages, and unions)
+1. 可选 `package` 声明
+2. 可选文件级 `option`
+3. 可选 `import` 语句
+4. 类型定义（`enum`、`message`、`union`）
```protobuf
// Optional package declaration
@@ -70,7 +52,7 @@ union Event [id=103] { ... }
## 注释
-Fory IDL supports both single-line and block comments:
+支持单行注释与块注释：
```protobuf
// This is a single-line comment
@@ -85,51 +67,51 @@ message Example {
}
```
-## Package Declaration
+## Package 声明
-The package declaration defines the namespace for all types in the file.
+`package` 定义文件中所有类型的命名空间。
```protobuf
package com.example.models;
```
-You can optionally specify a package alias used for auto-generated type IDs:
+也可以配置 alias（用于自动类型 ID 计算）：
```protobuf
package com.example.models alias models_v1;
```
-**Rules:**
+规则：
-- Optional but recommended
-- Must appear before any type definitions
-- Only one package declaration per file
-- Used for namespace-based type registration
-- Package alias is used for auto-ID hashing
+- 可选但推荐
+- 必须位于任何类型定义之前
+- 每个文件最多一个 `package`
+- 用于命名空间注册
+- `alias` 会参与 auto-ID 哈希
-**Language Mapping:**
+语言映射：
-| Language | Package Usage |
-| -------- | --------------------------------- |
-| Java | Java package |
-| Python | Module name (dots to underscores) |
-| Go | Package name (last component) |
-| Rust | Module name (dots to underscores) |
-| C++ | Namespace (dots to `::`) |
+| 语言 | package 用法 |
+| ------ | ----------------------- |
+| Java | Java package |
+| Python | 模块名（`.` 转 `_`） |
+| Go | 包名（通常取最后一段） |
+| Rust | 模块名（`.` 转 `_`） |
+| C++ | 命名空间（`.` 转 `::`） |
-## File-Level Options
+## 文件级选项
-Options can be specified at file level to control language-specific code generation.
+文件级选项用于控制语言定制代码生成。
-### Syntax
+### 语法
```protobuf
option option_name = value;
```
-### Java Package Option
+### Java Package 选项
-Override the Java package for generated code:
+通过 `java_package` 覆盖 Java 输出包名：
```protobuf
package payment;
@@ -140,15 +122,15 @@ message Payment {
}
```
-**Effect:**
+效果：
-- Generated Java files will be in `com/mycorp/payment/v1/` directory
-- Java package declaration will be `package com.mycorp.payment.v1;`
-- Type registration still uses the Fory IDL package (`payment`) for cross-language compatibility
+- Java 文件输出到 `com/mycorp/payment/v1/`
+- Java `package` 声明使用该值
+- 跨语言类型注册仍以 Fory package（如 `payment`）为准
-### Go Package Option
+### Go Package 选项
-Specify the Go import path and package name:
+通过 `go_package` 指定 Go import path 与包名：
```protobuf
package payment;
@@ -159,17 +141,11 @@ message Payment {
}
```
-**Format:** `"import/path;package_name"` or just `"import/path"` (last segment used as package name)
-
-**Effect:**
-
-- Generated Go files will have `package paymentv1`
-- The import path can be used in other Go code
-- Type registration still uses the Fory IDL package (`payment`) for cross-language compatibility
+格式：`"import/path;package_name"` 或仅 `"import/path"`（包名取最后一段）。
-### Java Outer Classname Option
+### Java Outer Classname 选项
-Generate all types as inner classes of a single outer wrapper class:
+将多个类型包装到一个外层类：
```protobuf
package payment;
@@ -186,49 +162,11 @@ message Payment {
}
```
-**Effect:**
-
-- Generates a single file `DescriptorProtos.java` instead of separate files
-- All enums and messages become `public static` inner classes
-- The outer class is `public final` with a private constructor
-- Useful for grouping related types together
-
-**Generated structure:**
-
-```java
-public final class DescriptorProtos {
- private DescriptorProtos() {}
-
- public static enum Status {
- UNKNOWN,
- ACTIVE;
- }
-
- public static class Payment {
- private String id;
- private Status status;
- // ...
- }
-}
-```
-
-**Combined with java_package:**
+默认会生成单文件，枚举与消息作为静态内部类型。
-```protobuf
-package payment;
-option java_package = "com.example.proto";
-option java_outer_classname = "PaymentProtos";
+### Java Multiple Files 选项
-message Payment {
- string id = 1;
-}
-```
-
-This generates `com/example/proto/PaymentProtos.java` with all types as inner classes.
-
-### Java Multiple Files Option
-
-Control whether types are generated in separate files or as inner classes:
+控制 Java 是否拆分多文件：
```protobuf
package payment;
@@ -244,1171 +182,556 @@ message Receipt {
}
```
-**Behavior:**
-
-| `java_outer_classname` | `java_multiple_files` | Result |
-| ---------------------- | --------------------- | ------------------------------------------- |
-| Not set | Any | Separate files (one per type) |
-| Set | `false` (default) | Single file with all types as inner classes |
-| Set | `true` | Separate files (overrides outer class) |
+行为：
-**Effect of `java_multiple_files = true`:**
+| `java_outer_classname` | `java_multiple_files` | 结果 |
+| ---------------------- | --------------------- | ---------------- |
+| 未设置 | 任意 | 每个类型一个文件 |
+| 已设置 | `false`（默认） | 单文件 + 内部类 |
+| 已设置 | `true` | 强制拆分为多文件 |
-- Each top-level enum and message gets its own `.java` file
-- Overrides `java_outer_classname` behavior
-- Useful when you want separate files but still specify an outer class name for other purposes
-
-**Example without java_multiple_files (default):**
-
-```protobuf
-option java_outer_classname = "PaymentProtos";
-// Generates: PaymentProtos.java containing Payment and Receipt as inner classes
-```
-
-**Example with java_multiple_files = true:**
-
-```protobuf
-option java_outer_classname = "PaymentProtos";
-option java_multiple_files = true;
-// Generates: Payment.java, Receipt.java (separate files)
-```
-
-### Multiple Options
-
-Multiple options can be specified:
+### 多个选项组合
```protobuf
package payment;
option java_package = "com.mycorp.payment.v1";
option go_package = "github.com/mycorp/apis/gen/payment/v1;paymentv1";
option deprecated = true;
-
-message Payment {
- string id = 1;
-}
```
-### Protobuf Extension Syntax
+### Protobuf 扩展语法说明
-In `.fdl` files, use native Fory IDL syntax only (for example, `[id=100]`, `ref`,
-`optional`, `nullable=true`).
+在 `.fdl` 中请使用 Fory 原生语法（如 `[id=100]`、`ref`、`optional`、`nullable=true`）。
+`(fory).xxx` 形式仅用于 `.proto`（protobuf 前端）。
-Protobuf extension syntax with `(fory).` is for `.proto` files and the protobuf
-frontend only.
+### 选项优先级
-For protobuf extension options, see
-[Protocol Buffers IDL Support](protobuf-idl.md#fory-extension-options-protobuf).
+语言包路径优先级：
-### Option Priority
+1. 命令行覆盖（最高）
+2. 语言选项（`java_package`、`go_package`）
+3. Fory IDL `package`（兜底）
-For language-specific packages:
+### 跨语言类型注册
-1. Command-line package override (highest priority)
-2. Language-specific option (`java_package`, `go_package`)
-3. Fory IDL package declaration (fallback)
-
-**Example:**
-
-```protobuf
-package myapp.models;
-option java_package = "com.example.generated";
-```
+默认情况下，注册名由 `package + type name`（或类型 ID）确定。建议长期保持 `package` 稳定，以避免跨版本注册不一致。
-| Scenario | Java Package Used |
-| ------------------------- | ------------------------- |
-| No override | `com.example.generated` |
-| CLI: `--package=override` | `override` |
-| No java_package option | `myapp.models` (fallback) |
+## Import 语句
-### Cross-Language Type Registration
-
-Language-specific options only affect where code is generated, not the type namespace used for serialization. This ensures cross-language compatibility:
-
-```protobuf
-package myapp.models;
-option java_package = "com.mycorp.generated";
-option go_package = "github.com/mycorp/gen;genmodels";
-
-message User {
- string name = 1;
-}
-```
-
-All languages will register `User` with namespace `myapp.models`, enabling:
-
-- Java serialized data → Go deserialization
-- Go serialized data → Java deserialization
-- Any language combination works seamlessly
-
-## Import Statement
-
-Import statements allow you to use types defined in other Fory IDL files.
-
-### Basic Syntax
+### 基本语法
```protobuf
-import "path/to/file.fdl";
+import "common/types.fdl";
```
-### Multiple Imports
+### 多个导入
```protobuf
import "common/types.fdl";
-import "common/enums.fdl";
-import "models/address.fdl";
+import "domain/user.fdl";
+import "domain/order.fdl";
```
-### Path Resolution
+### 路径解析
-Import paths are resolved relative to the importing file:
+导入解析顺序：
-```
-project/
-├── common/
-│ └── types.fdl
-├── models/
-│ ├── user.fdl # import "../common/types.fdl"
-│ └── order.fdl # import "../common/types.fdl"
-└── main.fdl # import "common/types.fdl"
-```
+1. 导入者文件所在目录
+2. 命令行 `-I/--proto_path/--import_path` 指定目录（按给定顺序）
-**Rules:**
-
-- Import paths are quoted strings (double or single quotes)
-- Paths are resolved relative to the importing file's directory
-- Imported types become available as if defined in the current file
-- Circular imports are detected and reported as errors
-- Transitive imports work (if A imports B and B imports C, A has access to C's types)
-
-### Complete Example
-
-**common/types.fdl:**
+### 完整示例
```protobuf
-package common;
+// src/main.fdl
+package app;
-enum Status [id=100] {
- PENDING = 0;
- ACTIVE = 1;
- COMPLETED = 2;
-}
+import "common.fdl";
+import "models/user.fdl";
-message Address [id=101] {
- string street = 1;
- string city = 2;
- string country = 3;
+message Main {
+ common.Meta meta = 1;
+ models.User user = 2;
}
```
-**models/user.fdl:**
-
-```protobuf
-package models;
-import "../common/types.fdl";
-
-message User [id=200] {
- string id = 1;
- string name = 2;
- Address home_address = 3; // Uses imported type
- Status status = 4; // Uses imported enum
-}
-```
-
-### Unsupported Import Syntax
-
-The following protobuf import modifiers are **not supported**:
-
-```protobuf
-// NOT SUPPORTED - will produce an error
-import public "other.fdl";
-import weak "other.fdl";
-```
+### 不支持的 import 写法
-**`import public`**: Fory IDL uses a simpler import model. All imported types are available to the importing file only. Re-exporting is not supported. Import each file directly where needed.
+- URL 形式（如 `https://...`）
+- 绝对路径依赖（不推荐，会破坏可移植性）
-**`import weak`**: Fory IDL requires all imports to be present at compile time. Optional dependencies are not supported.
+### import 错误
-### Import Errors
+典型错误：
-The compiler reports errors for:
+- 文件不存在
+- 搜索路径未包含依赖目录
+- 同名文件冲突导致解析到错误版本
-- **File not found**: The imported file doesn't exist
-- **Circular import**: A imports B which imports A (directly or indirectly)
-- **Parse errors**: Syntax errors in imported files
-- **Unsupported syntax**: `import public` or `import weak`
+## Enum 定义
-## Enum Definition
-
-Enums define a set of named integer constants.
-
-### Basic Syntax
+### 基本语法
```protobuf
enum Status {
- PENDING = 0;
+ UNKNOWN = 0;
ACTIVE = 1;
- COMPLETED = 2;
+ DISABLED = 2;
}
```
-### With Explicit Type ID
+### 显式类型 ID
```protobuf
-enum Status [id=100] {
- PENDING = 0;
+enum Status [id=101] {
+ UNKNOWN = 0;
ACTIVE = 1;
- COMPLETED = 2;
+ DISABLED = 2;
}
```
-### Reserved Values
-
-Reserve field numbers or names to prevent reuse:
+### 预留值
```protobuf
enum Status {
- reserved 2, 15, 9 to 11, 40 to max; // Reserved numbers
- reserved "OLD_STATUS", "DEPRECATED"; // Reserved names
- PENDING = 0;
- ACTIVE = 1;
- COMPLETED = 3;
-}
-```
-
-### Enum Type Options
-
-Enum-level options are declared inline in `[]` after the enum name:
-
-```protobuf
-enum Status [deprecated=true] {
- PENDING = 0;
+ UNKNOWN = 0;
ACTIVE = 1;
+ reserved 2, 3;
+ reserved 10 to 20;
}
```
-FDL does not support `option ...;` statements inside enum bodies.
-
-**Unsupported:**
-
-- `allow_alias` is **not supported**. Each enum value must have a unique integer.
-
-### Language Mapping
-
-| Language | Implementation |
-| -------- | -------------------------------------- |
-| Java | `enum Status { UNKNOWN, ACTIVE, ... }` |
-| Python | `class Status(IntEnum): UNKNOWN = 0` |
-| Go | `type Status int32` with constants |
-| Rust | `#[repr(i32)] enum Status { Unknown }` |
-| C++ | `enum class Status : int32_t { ... }` |
-
-### Enum Prefix Stripping
-
-When enum values use a protobuf-style prefix (enum name in UPPER_SNAKE_CASE), the compiler automatically strips the prefix for languages with scoped enums:
-
-```protobuf
-// Input with prefix
-enum DeviceTier {
- DEVICE_TIER_UNKNOWN = 0;
- DEVICE_TIER_TIER1 = 1;
- DEVICE_TIER_TIER2 = 2;
-}
-```
-
-**Generated code:**
+### enum 类型选项
-| Language | Output | Style |
-| -------- | ----------------------------------------- | -------------- |
-| Java | `UNKNOWN, TIER1, TIER2` | Scoped enum |
-| Rust | `Unknown, Tier1, Tier2` | Scoped enum |
-| C++ | `UNKNOWN, TIER1, TIER2` | Scoped enum |
-| Python | `UNKNOWN, TIER1, TIER2` | Scoped IntEnum |
-| Go | `DeviceTierUnknown, DeviceTierTier1, ...` | Unscoped const |
+常见：`id`、`alias`、`deprecated`。
-**Note:** The prefix is only stripped if the remainder is a valid identifier. For example, `DEVICE_TIER_1` is kept unchanged because `1` is not a valid identifier name.
+### 语言映射
-**Grammar:**
+- Java：`enum`
+- Python：`IntEnum`
+- Go：`type + const`
+- Rust：`repr(i32)` 枚举
+- C++：`enum class`
-```
-enum_def := 'enum' IDENTIFIER [type_options] '{' enum_body '}'
-type_options := '[' type_option (',' type_option)* ']'
-type_option := IDENTIFIER '=' option_value
-enum_body := (reserved_stmt | enum_value)*
-reserved_stmt := 'reserved' reserved_items ';'
-enum_value := IDENTIFIER '=' INTEGER ';'
-```
-
-**Rules:**
-
-- Enum names must be unique within the file
-- Enum values must have explicit integer assignments
-- Value integers must be unique within the enum (no aliases)
-- Type ID (`[id=100]`) is optional for enums but recommended for cross-language use
-
-**Example with All Features:**
-
-```protobuf
-// HTTP status code categories
-enum HttpCategory [id=200] {
- reserved 10 to 20; // Reserved for future use
- reserved "UNKNOWN"; // Reserved name
- INFORMATIONAL = 1;
- SUCCESS = 2;
- REDIRECTION = 3;
- CLIENT_ERROR = 4;
- SERVER_ERROR = 5;
-}
-```
+### 枚举前缀处理
-## Message Definition
+针对 protobuf 风格 `TYPE_NAME_VALUE`，生成器通常会按语言习惯去除冗余前缀，使 API 更自然。
-Messages define structured data types with typed fields.
+## Message 定义
-### Basic Syntax
+### 基本语法
```protobuf
-message Person {
- string name = 1;
- int32 age = 2;
-}
-```
-
-### With Explicit Type ID
-
-```protobuf
-message Person [id=101] {
+message User {
string name = 1;
int32 age = 2;
}
```
-### Without Explicit Type ID
+### 显式类型 ID
```protobuf
-message Person { // Auto-generated when enable_auto_type_id = true
+message User [id=100] {
string name = 1;
int32 age = 2;
}
```
-### Language Mapping
+### 无显式类型 ID
-| Language | Implementation |
-| -------- | ----------------------------------- |
-| Java | POJO class with getters/setters |
-| Python | `@dataclass` class |
-| Go | Struct with exported fields |
-| Rust | Struct with `#[derive(ForyObject)]` |
-| C++ | Struct with `FORY_STRUCT` macro |
+未声明 `[id=...]` 时，编译器可按配置自动生成类型 ID，或使用 namespace/name 注册。
-Type IDs control cross-language registration for messages, unions, and enums. See
-[Type IDs](#type-ids) for auto-generation, aliases, and collision handling.
+### 语言映射
-### Reserved Fields
+- Java：类 / record（按选项）
+- Python：dataclass
+- Go：struct
+- Rust：struct
+- C++：class/struct + 宏元信息
-Reserve field numbers or names to prevent reuse after removing fields:
+### 预留字段
```protobuf
message User {
- reserved 2, 15, 9 to 11; // Reserved field numbers
- reserved "old_field", "temp"; // Reserved field names
- string id = 1;
- string name = 3;
-}
-```
-
-### Message Type Options
-
-Message-level options are declared inline in `[]` after the message name:
-
-```protobuf
-message User [deprecated=true] {
- string id = 1;
- string name = 2;
+ string name = 1;
+ reserved 2, 3;
+ reserved 10 to 20;
}
```
-FDL does not support `option ...;` statements inside message or enum bodies.
-
-**Grammar:**
-
-```
-message_def := 'message' IDENTIFIER [type_options] '{' message_body '}'
-type_options := '[' type_option (',' type_option)* ']'
-type_option := IDENTIFIER '=' option_value
-message_body := (reserved_stmt | nested_type | field_def)*
-nested_type := enum_def | message_def | union_def
-```
-
-**Rules:**
-
-- Type IDs follow the rules in [Type IDs](#type-ids).
+### message 类型选项
-## Nested Types
+常见选项：`id`、`alias`、`evolving`、`deprecated`、`namespace`、`use_record_for_java`。
-Messages can contain nested message, enum, and union definitions. This is useful for defining types that are closely related to their parent message.
+## 嵌套类型
-### Nested Messages
+### 嵌套 message
```protobuf
-message SearchResponse {
- message Result {
- string url = 1;
- string title = 2;
- list<string> snippets = 3;
- }
- list<Result> results = 1;
-}
-```
-
-### Nested Enums
-
-```protobuf
-message Container {
- enum Status {
- STATUS_UNKNOWN = 0;
- STATUS_ACTIVE = 1;
- STATUS_INACTIVE = 2;
+message Person {
+ message PhoneNumber {
+ string number = 1;
}
- Status status = 1;
+ PhoneNumber phone = 1;
}
```
-### Qualified Type Names
-
-Nested types can be referenced from other messages using qualified names (Parent.Child):
+### 嵌套 enum
```protobuf
-message SearchResponse {
- message Result {
- string url = 1;
- string title = 2;
+message Person {
+ enum PhoneType {
+ MOBILE = 0;
+ HOME = 1;
}
-}
-
-message SearchResultCache {
- // Reference nested type with qualified name
- SearchResponse.Result cached_result = 1;
- list<SearchResponse.Result> all_results = 2;
+ PhoneType type = 1;
}
```
-### Deeply Nested Types
+### 限定类型名
-Nesting can be multiple levels deep:
+可使用完整限定名引用嵌套类型，例如 `Person.PhoneNumber`。
-```protobuf
-message Outer {
- message Middle {
- message Inner {
- string value = 1;
- }
- Inner inner = 1;
- }
- Middle middle = 1;
-}
-
-message OtherMessage {
- // Reference deeply nested type
- Outer.Middle.Inner deep_ref = 1;
-}
-```
+### 深层嵌套类型
-### Language-Specific Generation
+支持多层嵌套，但建议控制层级，避免可读性下降。
-| Language | Nested Type Generation |
-| -------- | --------------------------------------------------------------------------------- |
-| Java | Static inner classes (`SearchResponse.Result`) |
-| Python | Nested classes within dataclass |
-| Go | Flat structs with underscore (`SearchResponse_Result`, configurable to camelcase) |
-| Rust | Nested modules (`search_response::Result`) |
-| C++ | Nested classes (`SearchResponse::Result`) |
+### 各语言生成形态
-**Note:** Go defaults to underscore-separated nested names; set `option go_nested_type_style = "camelcase";` to use concatenated names. Rust emits nested modules for nested types.
+| 语言 | 嵌套类型形态 |
+| ------ | --------------------- |
+| Java | `Outer.Inner` |
+| Python | `Outer.Inner` |
+| Rust | `outer::Inner` |
+| C++ | `Outer::Inner` |
+| Go | `Outer_Inner`（默认） |
-### Nested Type Rules
+### 嵌套规则
-- Nested type names must be unique within their parent message
-- Nested types can have their own type IDs
-- Numeric type IDs must be globally unique (including nested types); see [Type IDs](#type-ids)
- for auto-generation and collision handling
-- Within a message, you can reference nested types by simple name
-- From outside, use the qualified name (Parent.Child)
+- 嵌套类型名在其父作用域内必须唯一
+- 可被同文件后续类型引用
+- 可通过 import + 限定名跨文件引用
-## Union Definition
+## Union 定义
-Unions define a value that can hold exactly one of several case types.
-
-### Basic Syntax
+### 基本语法
```protobuf
-union Animal [id=106] {
+union Animal {
Dog dog = 1;
Cat cat = 2;
}
```
-### Using a Union in a Message
+### 在 message 中使用 union
```protobuf
-message Person [id=100] {
+message Person {
Animal pet = 1;
- optional Animal favorite_pet = 2;
}
```
-### Rules
-
-- Case IDs must be unique within the union
-- Cases cannot be `optional` or `ref`
-- Union cases do not support field options
-- Case types can be primitives, enums, messages, or other named types
-- Union type IDs follow the rules in [Type IDs](#type-ids).
-
-**Grammar:**
+### 规则
-```
-union_def := 'union' IDENTIFIER [type_options] '{' union_field* '}'
-union_field := field_type IDENTIFIER '=' INTEGER ';'
-```
+- case 字段号必须唯一
+- case 类型通常为消息类型或可序列化复合类型
+- 各语言会生成带 case 判别和访问器的 union 表达
-## Field Definition
+## 字段定义
-Fields define the properties of a message.
-
-### Basic Syntax
+### 基本语法
```protobuf
-field_type field_name = field_number;
+string name = 1;
```
-### With Modifiers
+### 带修饰符语法
```protobuf
-optional list<string> tags = 1; // Nullable list
-list<optional string> tags = 2; // Elements may be null
-ref list<Node> nodes = 3; // Collection tracked as a reference
-list<ref Node> nodes = 4; // Elements tracked as references
+optional string nickname = 2;
+ref Node parent = 3;
+list<int32> scores = 4;
```
-**Grammar:**
-
-```
-field_def := [modifiers] field_type IDENTIFIER '=' INTEGER ';'
-modifiers := { 'optional' | 'ref' }
-field_type := primitive_type | named_type | list_type | map_type
-list_type := 'list' '<' { 'optional' | 'ref' } field_type '>'
-```
-
-Modifiers apply to the field/collection. Use `list<...>` to describe element
-modifiers. `repeated` is accepted as an alias for `list`.
-
-### Field Modifiers
+### 字段修饰符
#### `optional`
-Marks the field as nullable:
+声明字段可为空（null/None）：
```protobuf
message User {
- string name = 1; // Required, non-null
- optional string email = 2; // Nullable
+ optional string email = 1;
}
```
-**Generated Code:**
-
-| Language | Non-optional | Optional |
-| -------- | ------------------ | ----------------------------------------------- |
-| Java | `String name` | `String email` with `@ForyField(nullable=true)` |
-| Python | `name: str` | `name: Optional[str]` |
-| Go | `Name string` | `Name *string` |
-| Rust | `name: String` | `name: Option<String>` |
-| C++ | `std::string name` | `std::optional<std::string> name` |
-
-**Default Values:**
-
-| Type | Default Value |
-| ------------------ | ------------------- |
-| Non-optional types | Language default |
-| Optional types | `null`/`None`/`nil` |
+建议在跨语言场景显式使用，以避免默认值差异。
#### `ref`
-Enables reference tracking for shared/circular references:
+开启引用跟踪，用于共享对象与循环结构：
```protobuf
message Node {
- string value = 1;
- ref Node parent = 2; // Can point to shared object
+ string name = 1;
+ ref Node parent = 2;
list<ref Node> children = 3;
}
```
-**Use Cases:**
-
-- Shared objects (same object referenced multiple times)
-- Circular references (object graphs with cycles)
-- Tree structures with parent pointers
-
-**Generated Code:**
-
-| Language | Without `ref` | With `ref` |
-| -------- | -------------- | ----------------------------------------- |
-| Java | `Node parent` | `Node parent` with `@ForyField(ref=true)` |
-| Python | `parent: Node` | `parent: Node = pyfory.field(ref=True)` |
-| Go | `Parent Node` | `Parent *Node` with `fory:"ref"` |
-| Rust | `parent: Node` | `parent: Arc<Node>` |
-| C++ | `Node parent` | `std::shared_ptr<Node> parent` |
-
-Rust uses `Arc` by default; use `ref(thread_safe=false)` or `ref(weak=true)`
-to customize pointer types. For protobuf option syntax, see
-[Protocol Buffers IDL Support](protobuf-idl.md#field-level-options).
+当运行时全局 ref tracking 开启时，字段级 `ref` 才会生效。
#### `list`
-Marks the field as a list/array:
+列表字段（`repeated` 为等价别名）：
```protobuf
-message Document {
+message Group {
list<string> tags = 1;
- list<User> authors = 2;
}
```
-**Generated Code:**
-
-| Language | Type |
-| -------- | -------------------------- |
-| Java | `List<String>` |
-| Python | `List[str]` |
-| Go | `[]string` |
-| Rust | `Vec<String>` |
-| C++ | `std::vector<std::string>` |
+### 组合修饰符
-### Combining Modifiers
-
-Modifiers can be combined:
-
-```fdl
-message Example {
- optional list<string> tags = 1; // Nullable list
- list<optional string> aliases = 2; // Elements may be null
- ref list<Node> nodes = 3; // Collection tracked as a reference
- list<ref Node> children = 4; // Elements tracked as references
- optional ref User owner = 5; // Nullable tracked reference
-}
-```
-
-Modifiers before `list` apply to the field/collection. Modifiers after `list`
-apply to elements. `repeated` is accepted as an alias for `list`.
-
-**List modifier mapping:**
-
-| Fory IDL | Java | Python | Go | Rust | C++ |
-| ----------------------- | ---------------------------------------------- | --------------------------------------- | ----------------------- | --------------------- | ----------------------------------------- |
-| `optional list<string>` | `List<String>` + `@ForyField(nullable = true)` | `Optional[List[str]]` | `[]string` + `nullable` | `Option<Vec<String>>` | `std::optional<std::vector<std::string>>` |
-| `list<optional string>` | `List<String>` (nullable elements) | `List[Optional[str]]` | `[]*string` | `Vec<Option<String>>` | `std::vector<std::optional<std::string>>` |
-| `ref list<User>` | `List<User>` + `@ForyField(ref = true)` | `List[User]` + `pyfory.field(ref=True)` | `[]User` + `ref` | `Arc<Vec<User>>` | `std::shared_ptr<std::vector<User>>` |
-| `list<ref User>` | `List<User>` | `List[User]` | `[]*User` + `ref=false` | `Vec<Arc<User>>` | `std::vector<std::shared_ptr<User>>` |
-
-Use `ref(thread_safe=false)` in Fory IDL (or `[(fory).thread_safe_pointer = false]` in protobuf)
-to generate `Rc` instead of `Arc` in Rust.
-
-## Field Numbers
-
-Each field must have a unique positive integer identifier:
+可组合使用：
```protobuf
-message Example {
- string first = 1;
- string second = 2;
- string third = 3;
+message Graph {
+ optional ref Node root = 1;
+ list<ref Node> nodes = 2;
}
```
-**Rules and best practices:**
+## 字段号
-- Numbers must be unique within a message.
-- Numbers must be positive integers.
-- Gaps are allowed and are useful when fields are removed.
-- Prefer sequential numbering from `1`.
-- Never reuse a removed field number for a different field.
+字段号规则：
-## Type System
+- 同一 message 内必须唯一
+- 必须为正整数
+- 不应复用已删除字段号（建议使用 `reserved`）
+- 建议预留编号区间以便演进
-Fory IDL provides a cross-language type system for primitives, named types, and
-collections. Field modifiers (`optional`, `list`, `ref`) control nullability,
-collection behavior, and reference tracking (see
-[Field Modifiers](#field-modifiers)).
+## Type System {#type-system}
+
+Fory IDL 类型系统包括基础类型、命名类型和集合类型。
### Primitive Types
-| Type | Description | Size |
-| --------------- | ----------------------------------------- | -------- |
-| `bool` | Boolean value | 1 byte |
-| `int8` | Signed 8-bit integer | 1 byte |
-| `int16` | Signed 16-bit integer | 2 bytes |
-| `int32` | Signed 32-bit integer (varint encoding) | 4 bytes |
-| `int64` | Signed 64-bit integer (varint encoding) | 8 bytes |
-| `uint8` | Unsigned 8-bit integer | 1 byte |
-| `uint16` | Unsigned 16-bit integer | 2 bytes |
-| `uint32` | Unsigned 32-bit integer (varint encoding) | 4 bytes |
-| `uint64` | Unsigned 64-bit integer (varint encoding) | 8 bytes |
-| `fixed_int32` | Signed 32-bit integer (fixed encoding) | 4 bytes |
-| `fixed_int64` | Signed 64-bit integer (fixed encoding) | 8 bytes |
-| `fixed_uint32` | Unsigned 32-bit integer (fixed encoding) | 4 bytes |
-| `fixed_uint64` | Unsigned 64-bit integer (fixed encoding) | 8 bytes |
-| `tagged_int64` | Signed 64-bit integer (tagged encoding) | 8 bytes |
-| `tagged_uint64` | Unsigned 64-bit integer (tagged encoding) | 8 bytes |
-| `float32` | 32-bit floating point | 4 bytes |
-| `float64` | 64-bit floating point | 8 bytes |
-| `string` | UTF-8 string | Variable |
-| `bytes` | Binary data | Variable |
-| `date` | Calendar date | Variable |
-| `timestamp` | Date and time with timezone | Variable |
-| `duration` | Duration | Variable |
-| `decimal` | Decimal value | Variable |
-| `any` | Dynamic value (runtime type) | Variable |
+| 类型族 | 示例 |
+| -------- | --------------------------------- |
+| 布尔 | `bool` |
+| 整数 | `int8/int16/int32/int64`、`uint*` |
+| 浮点 | `float32`、`float64` |
+| 字符串 | `string` |
+| 字节数组 | `bytes` |
+| 时间 | `date`、`timestamp`、`duration` |
+| 动态类型 | `any` |
#### Boolean
-| Language | Type | Notes |
-| -------- | --------------------- | ------------------ |
-| Java | `boolean` / `Boolean` | Primitive or boxed |
-| Python | `bool` | |
-| Go | `bool` | |
-| Rust | `bool` | |
-| C++ | `bool` | |
+`bool` 表示布尔值。
#### Integer Types
-Fory IDL provides fixed-width signed integers (varint encoding for 32/64-bit by default):
-
-| Fory IDL Type | Size | Range |
-| ------------- | ------ | ----------------- |
-| `int8` | 8-bit | -128 to 127 |
-| `int16` | 16-bit | -32,768 to 32,767 |
-| `int32` | 32-bit | -2^31 to 2^31 - 1 |
-| `int64` | 64-bit | -2^63 to 2^63 - 1 |
-
-**Language Mapping (Signed):**
-
-| Fory IDL | Java | Python | Go | Rust | C++ |
-| -------- | ------- | -------------- | ------- | ----- | --------- |
-| `int8` | `byte` | `pyfory.int8` | `int8` | `i8` | `int8_t` |
-| `int16` | `short` | `pyfory.int16` | `int16` | `i16` | `int16_t` |
-| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` |
-| `int64` | `long` | `pyfory.int64` | `int64` | `i64` | `int64_t` |
-
-Fory IDL provides fixed-width unsigned integers (varint encoding for 32/64-bit by default):
-
-| Fory IDL | Size | Range |
-| -------- | ------ | ------------- |
-| `uint8` | 8-bit | 0 to 255 |
-| `uint16` | 16-bit | 0 to 65,535 |
-| `uint32` | 32-bit | 0 to 2^32 - 1 |
-| `uint64` | 64-bit | 0 to 2^64 - 1 |
-
-**Language Mapping (Unsigned):**
-
-| Fory IDL | Java | Python | Go | Rust | C++ |
-| -------- | ------- | --------------- | -------- | ----- | ---------- |
-| `uint8` | `short` | `pyfory.uint8` | `uint8` | `u8` | `uint8_t` |
-| `uint16` | `int` | `pyfory.uint16` | `uint16` | `u16` | `uint16_t` |
-| `uint32` | `long` | `pyfory.uint32` | `uint32` | `u32` | `uint32_t` |
-| `uint64` | `long` | `pyfory.uint64` | `uint64` | `u64` | `uint64_t` |
+支持有符号/无符号与不同位宽。跨语言场景建议明确编码策略并保持字段语义稳定。
#### Integer Encoding Variants
-For 32/64-bit integers, Fory IDL uses varint encoding by default. Use explicit types when
-you need fixed-width or tagged encoding:
+常见编码：
-| Fory IDL Type | Encoding | Notes |
-| --------------- | -------- | ------------------------ |
-| `fixed_int32` | fixed | Signed 32-bit |
-| `fixed_int64` | fixed | Signed 64-bit |
-| `fixed_uint32` | fixed | Unsigned 32-bit |
-| `fixed_uint64` | fixed | Unsigned 64-bit |
-| `tagged_int64` | tagged | Signed 64-bit (hybrid) |
-| `tagged_uint64` | tagged | Unsigned 64-bit (hybrid) |
+- `varint`：小值更省空间
+- `fixed`：固定长度，性能稳定
+- `tagged`：混合编码（特定类型可用）
#### Floating-Point Types
-| Fory IDL Type | Size | Precision |
-| ------------- | ------ | ------------- |
-| `float32` | 32-bit | ~7 digits |
-| `float64` | 64-bit | ~15-16 digits |
-
-**Language Mapping:**
-
-| Fory IDL | Java | Python | Go | Rust | C++ |
-| --------- | -------- | ---------------- | --------- | ----- | -------- |
-| `float32` | `float` | `pyfory.float32` | `float32` | `f32` | `float` |
-| `float64` | `double` | `pyfory.float64` | `float64` | `f64` | `double` |
+- `float32`
+- `float64`
#### String Type
-| Language | Type | Notes |
-| -------- | ------------- | --------------------- |
-| Java | `String` | Immutable |
-| Python | `str` | |
-| Go | `string` | Immutable |
-| Rust | `String` | Owned, heap-allocated |
-| C++ | `std::string` | |
+`string` 使用 UTF-8 文本语义。
#### Bytes Type
-| Language | Type | Notes |
-| -------- | ---------------------- | --------- |
-| Java | `byte[]` | |
-| Python | `bytes` | Immutable |
-| Go | `[]byte` | |
-| Rust | `Vec<u8>` | |
-| C++ | `std::vector<uint8_t>` | |
+`bytes` 用于原始二进制载荷。
#### Temporal Types
##### Date
-| Language | Type | Notes |
-| -------- | --------------------------- | ----------------------- |
-| Java | `java.time.LocalDate` | |
-| Python | `datetime.date` | |
-| Go | `time.Time` | Time portion ignored |
-| Rust | `chrono::NaiveDate` | Requires `chrono` crate |
-| C++ | `fory::serialization::Date` | |
+`date` 表示日期（不含时区时间部分）。
##### Timestamp
-| Language | Type | Notes |
-| -------- | -------------------------------- | ----------------------- |
-| Java | `java.time.Instant` | UTC-based |
-| Python | `datetime.datetime` | |
-| Go | `time.Time` | |
-| Rust | `chrono::NaiveDateTime` | Requires `chrono` crate |
-| C++ | `fory::serialization::Timestamp` | |
+`timestamp` 表示时间点（跨语言应统一时间语义与精度预期）。
#### Any
-| Language | Type | Notes |
-| -------- | -------------- | -------------------- |
-| Java | `Object` | Runtime type written |
-| Python | `Any` | Runtime type written |
-| Go | `any` | Runtime type written |
-| Rust | `Box<dyn Any>` | Runtime type written |
-| C++ | `std::any` | Runtime type written |
-
-**Example:**
-
-```protobuf
-enum EventType [id=120] {
- CREATED = 0;
- DELETED = 1;
-}
-
-message UserCreated [id=121] {
- string user_id = 1;
-}
-
-message Envelope [id=122] {
- EventType type = 1;
- any payload = 2;
-}
-```
-
-**Generated Code (`Envelope.payload`):**
-
-| Language | Generated Field Type |
-| -------- | ----------------------- |
-| Java | `Object payload` |
-| Python | `payload: Any` |
-| Go | `Payload any` |
-| Rust | `payload: Box<dyn Any>` |
-| C++ | `std::any payload` |
-
-**Notes:**
-
-- `any` always writes a null flag (same as `nullable`) because values may be empty.
-- Allowed runtime values are limited to `bool`, `string`, `enum`, `message`, and `union`.
- Other primitives (numeric, bytes, date/time) and list/map are not supported; wrap them in a
- message or use explicit fields instead.
-- `ref` is not allowed on `any` fields (including list/map values). Wrap `any` in a message
- if you need reference tracking.
-- The runtime type must be registered in the target language schema/IDL registration; unknown
- types fail to deserialize.
+`any` 允许存储动态类型值。使用 `any` 时建议配合清晰的业务约束，避免滥用导致模型不稳定。
### Named Types
-Reference other messages, enums, or unions by name:
+命名类型包括：
-```protobuf
-enum Status { ... }
-message User { ... }
+- `enum`
+- `message`
+- `union`
-message Order {
- User customer = 1; // Reference to User message
- Status status = 2; // Reference to Status enum
-}
-```
+支持跨文件 import 和限定名引用。
### Collection Types
#### List (`list`)
-Use the `list<...>` type for list fields. `repeated` is accepted as an alias. See [Field Modifiers](#field-modifiers) for
-modifier combinations and language mapping.
+```protobuf
+list<T>
+```
-Nested collection types are not supported. Use a message wrapper if you need
-`list<list<...>>`, `list<map<...>>`, or `map<..., list<...>>`.
+等价别名：`repeated T`。
#### Map
-Maps with typed keys and values:
-
```protobuf
-message Config {
- map<string, string> properties = 1;
- map<string, int32> counts = 2;
- map<int32, User> users = 3;
-}
+map<K, V>
```
-**Language Mapping:**
-
-| Fory IDL | Java | Python | Go | Rust | C++ |
-| -------------------- | ---------------------- | ----------------- | ------------------ | ----------------------- | -------------------------------- |
-| `map<string, int32>` | `Map<String, Integer>` | `Dict[str, int]` | `map[string]int32` | `HashMap<String, i32>` | `std::map<std::string, int32_t>` |
-| `map<string, User>` | `Map<String, User>` | `Dict[str, User]` | `map[string]User` | `HashMap<String, User>` | `std::map<std::string, User>` |
-
-**Key Type Restrictions:**
+约束：
-- `string` (most common)
-- Integer types (`int8`, `int16`, `int32`, `int64`)
-- `bool`
-
-Avoid using messages or complex types as keys.
+- `K` 一般应为可稳定比较的标量类型
+- `V` 可为任意支持类型
### Type Compatibility Matrix
-This matrix shows which type conversions are safe across languages:
-
-| From -> To | bool | int8 | int16 | int32 | int64 | float32 | float64 | string |
-| ---------- | ---- | ---- | ----- | ----- | ----- | ------- | ------- | ------ |
-| bool | Y | Y | Y | Y | Y | - | - | - |
-| int8 | - | Y | Y | Y | Y | Y | Y | - |
-| int16 | - | - | Y | Y | Y | Y | Y | - |
-| int32 | - | - | - | Y | Y | - | Y | - |
-| int64 | - | - | - | - | Y | - | - | - |
-| float32 | - | - | - | - | - | Y | Y | - |
-| float64 | - | - | - | - | - | - | Y | - |
-| string | - | - | - | - | - | - | - | Y |
+跨语言建议：
-Y = Safe conversion, - = Not recommended
+- 使用各语言都稳定支持的公共子集
+- 尽量避免平台相关宽度/语义差异
+- 对整数编码与可空语义显式声明
### Best Practices
-- Use `int32` as the default for most integers; use `int64` for large values.
-- Use `string` for text data (UTF-8) and `bytes` for binary data.
-- Use `optional` only when the field may legitimately be absent.
-- Use `ref` only when needed for shared or circular references.
-- Prefer `list` for ordered sequences and `map` for key-value lookups.
+1. 优先使用显式字段号与稳定命名
+2. 需要可空就显式 `optional`
+3. 存在共享/循环关系时使用 `ref`
+4. 降低 `any` 使用范围，优先强类型建模
+5. 预留字段号与枚举值区间
## Type IDs
-Type IDs enable efficient cross-language serialization and are used for
-messages, unions, and enums. When `enable_auto_type_id = true` (default) and
-`id` is omitted, the compiler auto-generates one using
-`MurmurHash3(utf8(package.type_name))` (32-bit) and annotates it in generated
-code. When `enable_auto_type_id = false`, types without explicit IDs are
-registered by namespace and name instead. Collisions are detected at
-compile-time across the current file and all imports; when a collision occurs,
-the compiler raises an error and asks for an explicit `id` or an `alias`.
-
-```protobuf
-enum Color [id=100] { ... }
-message User [id=101] { ... }
-union Event [id=102] { ... }
-```
-
-Enum type IDs remain optional; if omitted they are auto-generated using the same
-hash when `enable_auto_type_id = true`.
+类型 ID 用于跨语言快速注册与解码匹配。
-### With Explicit Type ID
+### 显式类型 ID
```protobuf
-message User [id=101] { ... }
-message User [id=101, deprecated=true] { ... } // Multiple options
+message User [id=100] {
+ string name = 1;
+}
```
-### Without Explicit Type ID
+### 无显式类型 ID
-```protobuf
-message Config { ... } // Auto-generated when enable_auto_type_id = true
-```
+未显式声明时可：
-You can set `[alias="..."]` to change the hash source without renaming the type.
+- 自动生成数值 ID（默认配置）
+- 禁用自动 ID，改用 namespace/type-name 注册
-### Practical Notes
+### 实践说明
-- If a type omits `id` and `enable_auto_type_id = true`, Fory generates an ID
- with `MurmurHash3(utf8(package.type_name))` (32-bit).
-- Package alias and type alias change the hash input and can be used to resolve
- hash collisions without renaming public types.
-- Manual IDs in the small varint range (`0-127`) are compact on the wire; auto
- IDs are typically larger and usually consume 4-5 bytes.
+- 类型 ID 在协议层面应视为稳定标识
+- 一经发布，不建议更改
+- 建议按域规划 ID 段（如 100-199 用户域）
-### ID Assignment Strategy
+### ID 分配策略
-```protobuf
-// Enums: 100-199
-enum Status [id=100] { ... }
-enum Priority [id=101] { ... }
+- 核心高频模型优先分配固定 ID
+- 团队统一管理 ID 区间与分配规范
+- 在 CI 中增加 ID 冲突检查
-// User domain: 200-299
-message User [id=200] { ... }
-message UserProfile [id=201] { ... }
+## 完整示例
-// Order domain: 300-399
-message Order [id=300] { ... }
-message OrderItem [id=301] { ... }
-```
+```protobuf
+package demo.order;
-## Complete Example
+option java_package = "com.example.demo.order";
+option go_package = "github.com/example/demo/gen/order;order";
-```protobuf
-// E-commerce domain model
-package com.shop.models;
-
-// Enums with type IDs
-enum OrderStatus [id=100] {
- PENDING = 0;
- CONFIRMED = 1;
- SHIPPED = 2;
- DELIVERED = 3;
- CANCELLED = 4;
-}
+import "demo/common.fdl";
-enum PaymentMethod [id=101] {
- CREDIT_CARD = 0;
- DEBIT_CARD = 1;
- PAYPAL = 2;
- BANK_TRANSFER = 3;
+enum Status [id=200] {
+ UNKNOWN = 0;
+ CREATED = 1;
+ PAID = 2;
+ SHIPPED = 3;
}
-// Messages with type IDs
-message Address [id=200] {
- string street = 1;
- string city = 2;
- string state = 3;
- string country = 4;
- string postal_code = 5;
+message Item [id=201] {
+ string sku = 1;
+ int32 quantity = 2;
}
-message Customer [id=201] {
+message User [id=202] {
string id = 1;
string name = 2;
optional string email = 3;
- optional string phone = 4;
- optional Address billing_address = 5;
- optional Address shipping_address = 6;
}
-message Product [id=202] {
- string sku = 1;
- string name = 2;
- string description = 3;
- float64 price = 4;
- int32 stock = 5;
- list<string> categories = 6;
- map<string, string> attributes = 7;
+union Animal [id=203] {
+ Dog dog = 1;
+ Cat cat = 2;
}
-message OrderItem [id=203] {
- ref Product product = 1; // Track reference to avoid duplication
- int32 quantity = 2;
- float64 unit_price = 3;
+message Dog [id=204] {
+ string name = 1;
}
-message Order [id=204] {
- string id = 1;
- ref Customer customer = 2;
- list<OrderItem> items = 3;
- OrderStatus status = 4;
- PaymentMethod payment_method = 5;
- float64 total = 6;
- optional string notes = 7;
- timestamp created_at = 8;
- optional timestamp shipped_at = 9;
+message Cat [id=205] {
+ string name = 1;
}
-// Config without explicit type ID (auto-generated when enable_auto_type_id = true)
-message ShopConfig {
- string store_name = 1;
- string currency = 2;
- float64 tax_rate = 3;
- list<string> supported_countries = 4;
+message Order [id=206] {
+ string id = 1;
+ ref User buyer = 2;
+ list<Item> items = 3;
+ Status status = 4;
+ map<string, string> metadata = 5;
+ optional Animal pet = 6;
}
```
-For protobuf-specific extension options and `(fory).` syntax, see
-[Protocol Buffers IDL Support](protobuf-idl.md#fory-extension-options-protobuf).
+## 语法摘要
-## Grammar Summary
+以下为简化文法（便于快速查阅，具体以编译器实现为准）：
+```ebnf
+file = [packageDecl] {optionDecl} {importDecl} {typeDecl} ;
+
+packageDecl = "package" qualifiedName ["alias" identifier] ";" ;
+optionDecl = "option" identifier "=" optionValue ";" ;
+importDecl = "import" stringLiteral ";" ;
+
+typeDecl = enumDecl | messageDecl | unionDecl ;
+
+enumDecl = "enum" identifier [typeOptions] "{" {enumField | reservedDecl} "}" ;
+enumField = identifier "=" intLiteral ";" ;
+
+messageDecl = "message" identifier [typeOptions] "{" {fieldDecl | nestedTypeDecl | reservedDecl} "}" ;
+unionDecl = "union" identifier [typeOptions] "{" {unionCaseDecl} "}" ;
+
+fieldDecl = [fieldModifier] typeRef identifier "=" intLiteral [fieldOptions] ";" ;
+unionCaseDecl = typeRef identifier "=" intLiteral [fieldOptions] ";" ;
+
+fieldModifier = "optional" | "ref" | "list" ;
+
+typeRef = primitiveType | qualifiedName | listType | mapType ;
+listType = "list" "<" typeRef ">" ;
+mapType = "map" "<" typeRef "," typeRef ">" ;
+
+typeOptions = "[" optionPair {"," optionPair} "]" ;
+fieldOptions = "[" optionPair {"," optionPair} "]" ;
+optionPair = identifier "=" optionValue ;
+
+reservedDecl = "reserved" reservedItem {"," reservedItem} ";" ;
+reservedItem = intLiteral | intLiteral "to" intLiteral | stringLiteral ;
```
-file := [package_decl] file_option* import_decl* type_def*
-
-package_decl := 'package' package_name ['alias' package_name] ';'
-package_name := IDENTIFIER ('.' IDENTIFIER)*
-
-file_option := 'option' option_name '=' option_value ';'
-option_name := IDENTIFIER
-
-import_decl := 'import' STRING ';'
-
-type_def := enum_def | message_def | union_def
-
-enum_def := 'enum' IDENTIFIER [type_options] '{' enum_body '}'
-enum_body := (reserved_stmt | enum_value)*
-enum_value := IDENTIFIER '=' INTEGER ';'
-
-message_def := 'message' IDENTIFIER [type_options] '{' message_body '}'
-message_body := (reserved_stmt | nested_type | field_def)*
-nested_type := enum_def | message_def | union_def
-field_def := [modifiers] field_type IDENTIFIER '=' INTEGER [field_options] ';'
-
-union_def := 'union' IDENTIFIER [type_options] '{' union_field* '}'
-union_field := ['repeated'] field_type IDENTIFIER '=' INTEGER [field_options] ';'
-option_value := 'true' | 'false' | IDENTIFIER | INTEGER | STRING
-
-reserved_stmt := 'reserved' reserved_items ';'
-reserved_items := reserved_item (',' reserved_item)*
-reserved_item := INTEGER | INTEGER 'to' INTEGER | INTEGER 'to' 'max' | STRING
-
-modifiers := { 'optional' | 'ref' | 'repeated' }
-
-field_type := primitive_type | named_type | list_type | map_type
-primitive_type := 'bool'
- | 'int8' | 'int16' | 'int32' | 'int64'
- | 'uint8' | 'uint16' | 'uint32' | 'uint64'
- | 'fixed_int32' | 'fixed_int64' | 'fixed_uint32' | 'fixed_uint64'
- | 'tagged_int64' | 'tagged_uint64'
- | 'float32' | 'float64'
- | 'string' | 'bytes'
- | 'date' | 'timestamp' | 'duration' | 'decimal'
- | 'any'
-named_type := qualified_name
-qualified_name := IDENTIFIER ('.' IDENTIFIER)* // e.g., Parent.Child
-list_type := 'list' '<' { 'optional' | 'ref' } field_type '>'
-map_type := 'map' '<' field_type ',' field_type '>'
-
-type_options := '[' type_option (',' type_option)* ']'
-type_option := IDENTIFIER '=' option_value // e.g., id=100, deprecated=true
-field_options := '[' field_option (',' field_option)* ']'
-field_option := IDENTIFIER '=' option_value // e.g., deprecated=true, ref=true
-
-STRING := '"' [^"\n]* '"' | "'" [^'\n]* "'"
-IDENTIFIER := [a-zA-Z_][a-zA-Z0-9_]*
-INTEGER := '-'? [0-9]+
-```
+
+实现建议：如需严谨验证，请以编译器语法解析器和测试用例为准。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/field-configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/field-configuration.md
index 0c18e125ce..4dd404c290 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/field-configuration.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/field-configuration.md
@@ -19,25 +19,22 @@ license: |
limitations under the License.
---
-> 中文导读：本页介绍字段级序列化配置，包括字段 ID、可空控制、引用跟踪、忽略字段与动态类型控制等。
-> 建议在跨语言和兼容模式场景中优先显式配置字段 ID，并在需要时开启 ref/nullable 以保证行为一致。
-
-本页说明如何配置序列化的字段级元信息。
+本页说明如何在 C++ 中配置序列化字段级元信息。
## 概述
-Apache Fory™ provides two ways to specify field-level metadata at compile time:
+Apache Fory™ 在编译期提供两种字段元信息配置方式：
-1. **`fory::field<>` template** - Inline metadata in struct definition
-2. **`FORY_FIELD_TAGS` macro** - Non-invasive metadata added separately
+1. **`fory::field<>` 模板**：在 struct 定义中内联声明元信息
+2. **`FORY_FIELD_TAGS` 宏**：在 struct 外部附加元信息（非侵入）
-These enable:
+这些机制可用于：
-- **Tag IDs**: Assign compact numeric IDs for schema evolution
-- **Nullability**: Mark pointer fields as nullable
-- **Reference Tracking**: Enable reference tracking for shared pointers
+- **Tag ID**：为 schema 演进分配紧凑数值 ID
+- **可空控制**：将指针字段标记为可空
+- **引用跟踪**：为共享指针启用引用跟踪
-## fory::field 模板
+## `fory::field` 模板
```cpp
template <typename T, int16_t Id, typename... Options>
@@ -46,11 +43,11 @@ class field;
### 模板参数
-| Parameter | Description |
-| --------- | ------------------------------------------------ |
-| `T` | The underlying field type |
-| `Id` | Field tag ID (int16_t) for compact serialization |
-| `Options` | Optional tags: `fory::nullable`, `fory::ref` |
+| 参数 | 说明 |
+| --------- | ------------------------------------------ |
+| `T` | 底层字段类型 |
+| `Id` | 字段 tag ID（`int16_t`），用于紧凑序列化 |
+| `Options` | 可选标签：`fory::nullable`、`fory::ref` 等 |
### 基本用法
@@ -67,7 +64,7 @@ struct Person {
FORY_STRUCT(Person, name, age, nickname);
```
-The `fory::field<>` wrapper is transparent - you can use it like the underlying type:
+`fory::field<>` 是透明包装，可像底层类型一样使用：
```cpp
Person person;
@@ -79,9 +76,9 @@ int a = person.age.get(); // Explicit get()
## 标签类型
-### fory::nullable
+### `fory::nullable`
-Marks a smart pointer field as nullable (can be `nullptr`):
+将智能指针字段标记为可空（可为 `nullptr`）：
```cpp
struct Node {
@@ -91,9 +88,9 @@ struct Node {
FORY_STRUCT(Node, name, next);
```
-**Valid for:** `std::shared_ptr<T>`, `std::unique_ptr<T>`
+**适用类型：** `std::shared_ptr<T>`、`std::unique_ptr<T>`
-**Note:** For nullable primitives or strings, use `std::optional<T>` instead:
+**说明：** 对原生值类型或字符串的可空语义，请使用 `std::optional<T>`：
```cpp
// Correct: use std::optional for nullable primitives
@@ -103,19 +100,19 @@ fory::field<std::optional<int32_t>, 0> optional_value;
// fory::field<int32_t, 0, fory::nullable> value; // Compile error!
```
-### fory::not_null
+### `fory::not_null`
-Explicitly marks a pointer field as non-nullable. This is the default for smart pointers, but can be used for documentation:
+显式声明指针字段不可空。虽然这是智能指针的默认行为，但可用于增强可读性：
```cpp
fory::field<std::shared_ptr<Data>, 0, fory::not_null> data; // Must not be nullptr
```
-**Valid for:** `std::shared_ptr<T>`, `std::unique_ptr<T>`
+**适用类型：** `std::shared_ptr<T>`、`std::unique_ptr<T>`
-### fory::ref
+### `fory::ref`
-Enables reference tracking for shared pointer fields. When multiple fields reference the same object, it will be serialized once and shared:
+为共享指针字段启用引用跟踪。多个字段引用同一对象时，仅序列化一次并保持共享关系：
```cpp
struct Graph {
@@ -126,27 +123,27 @@ struct Graph {
FORY_STRUCT(Graph, name, left, right);
```
-**Valid for:** `std::shared_ptr<T>` only (requires shared ownership)
+**适用类型：** 仅 `std::shared_ptr<T>`（需要共享所有权）
-### Combining Tags
+### 组合标签
-Multiple tags can be combined for shared pointers:
+共享指针可组合多个标签：
```cpp
// Nullable + ref tracking
fory::field<std::shared_ptr<Node>, 0, fory::nullable, fory::ref> link;
```
-## Type Rules
+## 类型规则
-| Type | Allowed Options | Nullability |
-| -------------------- | ----------------- | ---------------------------------- |
-| Primitives, strings | None | Use `std::optional<T>` if nullable |
-| `std::optional<T>` | None | Inherently nullable |
-| `std::shared_ptr<T>` | `nullable`, `ref` | Non-null by default |
-| `std::unique_ptr<T>` | `nullable` | Non-null by default |
+| 类型 | 可用选项 | 可空语义 |
+| -------------------- | ----------------- | --------------------------------- |
+| 原生类型、字符串 | 无 | 若需可空请使用 `std::optional<T>` |
+| `std::optional<T>` | 无 | 天然可空 |
+| `std::shared_ptr<T>` | `nullable`、`ref` | 默认不可空 |
+| `std::unique_ptr<T>` | `nullable` | 默认不可空 |
-## Complete Example
+## 完整示例
```cpp
#include "fory/serialization/fory.h"
@@ -191,9 +188,9 @@ int main() {
}
```
-## Compile-Time Validation
+## 编译期校验
-Invalid configurations are caught at compile time:
+非法配置会在编译期报错：
```cpp
// Error: nullable and not_null are mutually exclusive
@@ -209,9 +206,9 @@ fory::field<std::unique_ptr<int>, 0, fory::ref> bad3;
fory::field<std::optional<int>, 0, fory::nullable> bad4;
```
-## Backwards Compatibility
+## 向后兼容
-Existing structs without `fory::field<>` wrappers continue to work:
+未使用 `fory::field<>` 包装的旧 struct 仍可正常工作：
```cpp
// Old style - still works
@@ -229,15 +226,15 @@ struct ModernPerson {
FORY_STRUCT(ModernPerson, name, age);
```
-## FORY_FIELD_TAGS Macro
+## `FORY_FIELD_TAGS` 宏
-The `FORY_FIELD_TAGS` macro provides a non-invasive way to add field metadata without modifying struct definitions. This is useful for:
+`FORY_FIELD_TAGS` 提供了一种非侵入式方案：无需修改 struct 定义即可附加字段元信息。适用场景：
-- **Third-party types**: Add metadata to types you don't own
-- **Clean structs**: Keep struct definitions as pure C++
-- **Isolated dependencies**: Confine Fory headers to serialization config files
+- **第三方类型**：为非自有类型添加元信息
+- **纯净结构定义**：保持 struct 仅包含标准 C++ 类型
+- **依赖隔离**：将 Fory 头文件限制在序列化配置文件中
-### Usage
+### 用法
```cpp
// user_types.h - NO fory headers needed!
@@ -268,33 +265,33 @@ FORY_FIELD_TAGS(Document,
)
```
-### FORY_FIELD_TAGS Options
+### `FORY_FIELD_TAGS` 选项
-| Field Type | Valid Combinations |
+| 字段类型 | 合法组合 |
| -------------------- | ---------------------------------------------------------------------------------------- |
-| Primitives, strings | `(field, id)` only |
-| `std::optional<T>` | `(field, id)` only |
-| `std::shared_ptr<T>` | `(field, id)`, `(field, id, nullable)`, `(field, id, ref)`, `(field, id, nullable, ref)` |
-| `std::unique_ptr<T>` | `(field, id)`, `(field, id, nullable)` |
+| 原生类型、字符串 | 仅 `(field, id)` |
+| `std::optional<T>` | 仅 `(field, id)` |
+| `std::shared_ptr<T>` | `(field, id)`、`(field, id, nullable)`、`(field, id, ref)`、`(field, id, nullable, ref)` |
+| `std::unique_ptr<T>` | `(field, id)`、`(field, id, nullable)` |
-### API Comparison
+### API 对比
-| Aspect | `fory::field<>` Wrapper | `FORY_FIELD_TAGS` Macro |
-| ----------------------- | ------------------------ | ----------------------- |
-| **Struct definition** | Modified (wrapped types) | Unchanged (pure C++) |
-| **IDE support** | Template noise | Excellent (clean types) |
-| **Third-party classes** | Not supported | Supported |
-| **Header dependencies** | Required everywhere | Isolated to config |
-| **Migration effort** | High (change all fields) | Low (add one macro) |
+| 维度 | `fory::field<>` 包装 | `FORY_FIELD_TAGS` 宏 |
+| -------------- | ------------------------ | ---------------------- |
+| **结构定义** | 需要改动（包装字段类型） | 无需改动（保持纯 C++） |
+| **IDE 体验** | 有模板噪音 | 更清晰（原生字段类型） |
+| **第三方类型** | 不支持 | 支持 |
+| **头文件依赖** | 各处都需要 | 可集中在配置文件 |
+| **迁移成本** | 高（修改全部字段） | 低（新增一个宏） |
-## FORY_FIELD_CONFIG Macro
+## `FORY_FIELD_CONFIG` 宏
-The `FORY_FIELD_CONFIG` macro is the most powerful and flexible way to configure field-level serialization. It provides:
+`FORY_FIELD_CONFIG` 是更强、更灵活的字段配置方式，提供：
-- **Builder pattern API**: Fluent, chainable configuration with `F(id).option1().option2()`
-- **Encoding control**: Specify how unsigned integers are encoded (varint, fixed, tagged)
-- **Compile-time verification**: Field names are verified against member pointers
-- **Cross-language compatibility**: Configure encoding to match other languages (Java, Rust, etc.)
+- **Builder 风格 API**：链式配置 `F(id).option1().option2()`
+- **编码控制**：指定无符号整数编码（varint、fixed、tagged）
+- **编译期校验**：通过成员指针校验字段名
+- **跨语言兼容**：按 Java、Rust 等语言期望配置编码
### 基本语法
@@ -308,9 +305,9 @@ FORY_FIELD_CONFIG(StructType,
);
```
-### The F() Builder
+### `F()` Builder
-The `fory::F(id)` factory creates a `FieldMeta` object that supports method chaining:
+`fory::F(id)` 工厂函数会创建支持链式调用的 `FieldMeta` 对象：
```cpp
fory::F(0) // Create with field ID 0
@@ -323,7 +320,7 @@ fory::F(0) // Create with field ID 0
.compress(false) // Disable compression
```
-**Tip:** To use `F()` without the `fory::` prefix, add a using declaration:
+**提示：** 若希望省略 `fory::` 前缀，可添加 `using` 声明：
```cpp
using fory::F;
@@ -334,19 +331,19 @@ FORY_FIELD_CONFIG(MyStruct,
);
```
-### Encoding Options for Unsigned Integers
+### 无符号整数编码选项
-For `uint32_t` and `uint64_t` fields, you can specify the wire encoding:
+对于 `uint32_t` 与 `uint64_t` 字段，可显式指定线格式编码：
-| Method | Type ID | Description | Use Case |
-| ----------- | ------------- | ---------------------------------------------- | ------------------------------------- |
-| `.varint()` | VAR_UINT32/64 | Variable-length encoding (1-5 or 1-10 bytes) | Values typically small |
-| `.fixed()` | UINT32/64 | Fixed-size encoding (always 4 or 8 bytes) | Values uniformly distributed |
-| `.tagged()` | TAGGED_UINT64 | Tagged hybrid encoding with size hint (uint64) | Mixed small and large values (uint64) |
+| 方法 | Type ID | 说明 | 适用场景 |
+| ----------- | ------------- | --------------------------------- | ------------------------ |
+| `.varint()` | VAR_UINT32/64 | 变长编码（1-5 或 1-10 字节） | 数值通常较小 |
+| `.fixed()` | UINT32/64 | 定长编码（固定 4 或 8 字节） | 数值分布较均匀 |
+| `.tagged()` | TAGGED_UINT64 | 带大小提示的混合编码（仅 uint64） | 小值与大值混合（uint64） |
-**Note:** `uint8_t` and `uint16_t` always use fixed encoding (UINT8, UINT16).
+**说明：** `uint8_t` 与 `uint16_t` 始终使用定长编码（UINT8、UINT16）。
-### Complete Example
+### 完整示例
```cpp
#include "fory/serialization/fory.h"
@@ -411,11 +408,11 @@ int main() {
}
```
-### Cross-Language Compatibility
+### 跨语言兼容
-When serializing data to be read by other languages, use `FORY_FIELD_CONFIG` to match their encoding expectations:
+当序列化数据会被其他语言读取时，建议通过 `FORY_FIELD_CONFIG` 显式匹配目标语言编码约定。
-**Java Compatibility:**
+**Java 兼容示例：**
```cpp
// Java uses these type IDs for unsigned integers:
@@ -446,9 +443,9 @@ FORY_FIELD_CONFIG(JavaCompatible,
);
```
-### Schema Evolution with FORY_FIELD_CONFIG
+### 使用 `FORY_FIELD_CONFIG` 做 Schema 演进
-In compatible mode, fields can have different nullability between sender and receiver:
+在兼容模式下，发送端和接收端可以对字段使用不同可空策略：
```cpp
// Version 1: All fields non-nullable
@@ -476,32 +473,32 @@ FORY_FIELD_CONFIG(DataV2,
);
```
-### FORY_FIELD_CONFIG Options Reference
-
-| Method | Description | Valid For |
-| ---------------- | ------------------------------------------- | -------------------------- |
-| `.nullable()` | Mark field as nullable | Smart pointers, primitives |
-| `.ref()` | Enable reference tracking | `std::shared_ptr` only |
-| `.monomorphic()` | Mark pointer as always pointing to one type | Smart pointers |
-| `.varint()` | Use variable-length encoding | `uint32_t`, `uint64_t` |
-| `.fixed()` | Use fixed-size encoding | `uint32_t`, `uint64_t` |
-| `.tagged()` | Use tagged hybrid encoding | `uint64_t` only |
-| `.compress(v)` | Enable/disable field compression | All types |
-
-### Comparing Field Configuration Macros
-
-| Feature | `fory::field<>` | `FORY_FIELD_TAGS` | `FORY_FIELD_CONFIG` |
-| ----------------------- | --------------------- | ----------------- | ------------------------- |
-| **Struct modification** | Required (wrap types) | None | None |
-| **Encoding control** | No | No | Yes (varint/fixed/tagged) |
-| **Builder pattern** | No | No | Yes |
-| **Compile-time verify** | Yes | Limited | Yes (member pointers) |
-| **Cross-lang compat** | Limited | Limited | Full |
-| **Recommended for** | Simple structs | Third-party types | Complex/xlang structs |
-
-## Related Topics
-
-- [Type Registration](type-registration.md) - Registering types with FORY_STRUCT
-- [Schema Evolution](schema-evolution.md) - Using tag IDs for schema evolution
-- [Configuration](configuration.md) - Enabling reference tracking globally
-- [Cross-Language](cross-language.md) - Interoperability with Java, Rust, Python
+### `FORY_FIELD_CONFIG` 选项速查
+
+| 方法 | 说明 | 适用范围 |
+| ---------------- | ------------------------ | ---------------------- |
+| `.nullable()` | 将字段标记为可空 | 智能指针、可空值类型 |
+| `.ref()` | 启用引用跟踪 | 仅 `std::shared_ptr` |
+| `.monomorphic()` | 标记指针始终指向单一类型 | 智能指针 |
+| `.varint()` | 变长编码 | `uint32_t`、`uint64_t` |
+| `.fixed()` | 定长编码 | `uint32_t`、`uint64_t` |
+| `.tagged()` | tagged 混合编码 | 仅 `uint64_t` |
+| `.compress(v)` | 启用/禁用字段压缩 | 所有类型 |
+
+### 字段配置方案对比
+
+| 特性 | `fory::field<>` | `FORY_FIELD_TAGS` | `FORY_FIELD_CONFIG` |
+| ------------------- | ------------------ | ----------------- | ------------------------- |
+| **需要修改 struct** | 是（包装字段类型） | 否 | 否 |
+| **编码控制** | 否 | 否 | 是（varint/fixed/tagged） |
+| **Builder 风格** | 否 | 否 | 是 |
+| **编译期校验** | 是 | 有限 | 是（成员指针校验） |
+| **跨语言兼容能力** | 有限 | 有限 | 完整 |
+| **推荐场景** | 简单结构体 | 第三方类型 | 复杂/跨语言结构体 |
+
+## 相关主题
+
+- [类型注册](type-registration.md) - 使用 FORY_STRUCT 注册类型
+- [Schema 演进](schema-evolution.md) - 基于 tag ID 的演进策略
+- [配置](configuration.md) - 全局启用引用跟踪等选项
+- [跨语言](cross-language.md) - 与 Java、Rust、Python 的互操作
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/schema-evolution.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/schema-evolution.md
index 3f89d97aad..fd8c7bfcad 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/schema-evolution.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/schema-evolution.md
@@ -85,7 +85,7 @@ Compatible 模式支持以下 schema 变更：
| 添加新字段 | ✅ | 缺失字段使用默认值 |
| 删除字段 | ✅ | 额外字段被跳过 |
| 重排字段顺序 | ✅ | 按名称匹配字段，而非位置 |
-| 更改可空性 | ✅ | `T` ↔ `std::optional<T>` |
+| 更改可空性 | ✅ | `T` ↔ `std::optional<T>` |
| 更改字段类型 | ❌ | 类型必须兼容 |
| 重命名字段 | ❌ | 字段名必须匹配（区分大小写） |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/configuration.md
index ca1a0e0b24..770e5a1022 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/configuration.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/configuration.md
@@ -33,12 +33,12 @@ f := fory.New()
默认设置：
-| Option | Default | Description |
-| ---------- | ------- | ------------------------------ |
-| TrackRef | false | 关闭引用跟踪 |
-| MaxDepth | 20 | 最大嵌套深度 |
-| IsXlang | false | 关闭跨语言模式 |
-| Compatible | false | 关闭 Schema 演进兼容模式 |
+| Option | Default | Description |
+| ---------- | ------- | ------------------------ |
+| TrackRef | false | 关闭引用跟踪 |
+| MaxDepth | 20 | 最大嵌套深度 |
+| IsXlang | false | 关闭跨语言模式 |
+| Compatible | false | 关闭 Schema 演进兼容模式 |
### 通过选项配置
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/index.md
index 4e695875ac..a161c83606 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/index.md
@@ -143,19 +143,19 @@ data, _ := f.Serialize(&User{ID: 1, Name: "Alice"})
## 文档导航
-| 主题 | 说明 |
-| -------------------------------------------- | -------------------------------------- |
-| [配置](configuration.md) | 配置项与运行参数 |
-| [基本序列化](basic-serialization.md) | 核心 API 与使用模式 |
-| [类型注册](type-registration.md) | 序列化前的类型注册 |
-| [支持类型](supported-types.md) | 完整类型支持说明 |
-| [引用](references.md) | 循环引用与共享对象 |
-| [Struct 标签](struct-tags.md) | 字段级配置 |
-| [Schema 演进](schema-evolution.md) | 前向/后向兼容策略 |
-| [跨语言](cross-language.md) | 多语言序列化 |
-| [代码生成](codegen.md) | 实验性的 AOT 代码生成 |
-| [线程安全](thread-safety.md) | 并发使用模式 |
-| [故障排查](troubleshooting.md) | 常见问题与解决方案 |
+| 主题 | 说明 |
+| ------------------------------------ | --------------------- |
+| [配置](configuration.md) | 配置项与运行参数 |
+| [基本序列化](basic-serialization.md) | 核心 API 与使用模式 |
+| [类型注册](type-registration.md) | 序列化前的类型注册 |
+| [支持类型](supported-types.md) | 完整类型支持说明 |
+| [引用](references.md) | 循环引用与共享对象 |
+| [Struct 标签](struct-tags.md) | 字段级配置 |
+| [Schema 演进](schema-evolution.md) | 前向/后向兼容策略 |
+| [跨语言](cross-language.md) | 多语言序列化 |
+| [代码生成](codegen.md) | 实验性的 AOT 代码生成 |
+| [线程安全](thread-safety.md) | 并发使用模式 |
+| [故障排查](troubleshooting.md) | 常见问题与解决方案 |
## 相关资源
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/struct-tags.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/struct-tags.md
index 4579a1d744..a62b32770a 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/struct-tags.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/struct-tags.md
@@ -19,14 +19,11 @@ license: |
limitations under the License.
---
-> 中文导读：本页介绍字段级序列化配置，包括字段 ID、可空控制、引用跟踪、忽略字段与动态类型控制等。
-> 建议在跨语言和兼容模式场景中优先显式配置字段 ID，并在需要时开启 ref/nullable 以保证行为一致。
-
-Fory Go uses struct tags to customize field-level serialization behavior. This allows fine-grained control over how individual fields are serialized.
+Fory Go 通过 struct tag 自定义字段级序列化行为，从而精细控制每个字段如何序列化。
## 标签语法
-The general syntax for Fory struct tags:
+Fory struct tag 的通用格式如下：
```go
type MyStruct struct {
@@ -34,13 +31,13 @@ type MyStruct struct {
}
```
-Multiple options are separated by commas (`,`).
+多个选项使用逗号（`,`）分隔。
## 可用标签
### 字段 ID
-Use `id=N` to assign a numeric ID to a field for compact encoding:
+使用 `id=N` 为字段分配数值 ID，以获得更紧凑编码：
```go
type User struct {
@@ -50,21 +47,21 @@ type User struct {
}
```
-**Benefits**:
+**收益：**
-- Smaller serialized size (numeric IDs vs field names)
-- Faster serialization/deserialization
-- Required for optimal cross-language compatibility
+- 序列化体积更小（数值 ID 替代字段名）
+- 序列化/反序列化更快
+- 跨语言兼容场景下更推荐
-**Notes**:
+**注意：**
-- IDs must be unique within a struct
-- IDs must be >= 0
-- If not specified, field name is used (larger payload)
+- 同一 struct 内 ID 必须唯一
+- ID 必须 `>= 0`
+- 未指定时使用字段名（payload 更大）
### 忽略字段
-Use `-` to exclude a field from serialization:
+使用 `-` 将字段排除在序列化之外：
```go
type User struct {
@@ -74,11 +71,11 @@ type User struct {
}
```
-The `Password` field will not be included in serialized output and will remain at its zero value after deserialization.
+`Password` 不会进入序列化结果，反序列化后将保持该类型零值。
### 可空控制
-Use `nullable` to control whether null flags are written for pointer fields:
+使用 `nullable` 控制是否为指针字段写入 null 标记：
```go
type Record struct {
@@ -90,15 +87,15 @@ type Record struct {
}
```
-**Notes**:
+**注意：**
-- Only applies to pointer, slice, and map fields
-- When `nullable=false`, serializing a nil value will cause an error
-- Default is `false` (no null flag written)
+- 仅适用于指针、slice、map 字段
+- `nullable=false` 时，序列化 nil 会报错
+- 默认是 `false`（不写 null 标记）
### 引用跟踪
-Control per-field reference tracking for slices, maps, or pointer to struct fields:
+可为 slice、map、或“指向 struct 的指针字段”设置字段级引用跟踪：
```go
type Container struct {
@@ -110,22 +107,22 @@ type Container struct {
}
```
-**Notes**:
+**注意：**
-- Applies to slices, maps, and pointer to struct fields
-- Pointer to primitive types (e.g., `*int`, `*string`) cannot use this tag
-- Default is `ref=false` (no reference tracking)
-- When global `WithTrackRef(false)` is set, field ref tags are ignored
-- When global `WithTrackRef(true)` is set, use `ref=false` to disable for specific fields
+- 适用于 slice、map 与“指向 struct 的指针字段”
+- 指向原生类型的指针（如 `*int`、`*string`）不能使用该标签
+- 默认 `ref=false`（不开启引用跟踪）
+- 全局 `WithTrackRef(false)` 时，字段级 ref 标签会被忽略
+- 全局 `WithTrackRef(true)` 时，可用 `ref=false` 对单字段禁用
-**Use cases**:
+**适用场景：**
-- Enable for fields that may be circular or shared
-- Disable for fields that are always unique (optimization)
+- 可能出现共享或循环引用的字段
+- 可明确唯一的字段可禁用（性能优化）
-### Encoding
+### 编码控制
-Use `encoding` to control how numeric fields are encoded:
+使用 `encoding` 控制数值字段编码方式：
```go
type Metrics struct {
@@ -140,24 +137,24 @@ type Metrics struct {
}
```
-**Supported encodings**:
+**支持编码：**
-| Type | Options | Default |
+| 类型 | 可选值 | 默认值 |
| -------- | --------------------------- | -------- |
-| `int32` | `varint`, `fixed` | `varint` |
-| `uint32` | `varint`, `fixed` | `varint` |
-| `int64` | `varint`, `fixed`, `tagged` | `varint` |
-| `uint64` | `varint`, `fixed`, `tagged` | `varint` |
+| `int32` | `varint`、`fixed` | `varint` |
+| `uint32` | `varint`、`fixed` | `varint` |
+| `int64` | `varint`、`fixed`、`tagged` | `varint` |
+| `uint64` | `varint`、`fixed`、`tagged` | `varint` |
-**When to use**:
+**何时使用：**
-- `varint`: Best for values that are often small (default)
-- `fixed`: Best for values that use full range (e.g., timestamps, hashes)
-- `tagged`: When type information needs to be preserved
+- `varint`：适合小值居多（默认）
+- `fixed`：适合接近全值域分布（如时间戳、哈希）
+- `tagged`：适合需保留类型信息的场景
-**Shorthand for int32/uint32**:
+**int32/uint32 简写：**
-Use `compress` as a convenience tag for int32/uint32 fields:
+对 int32/uint32 字段可使用 `compress` 作为便捷标签：
```go
type Data struct {
@@ -166,9 +163,9 @@ type Data struct {
}
```
-## Combining Tags
+## 组合标签
-Multiple tags can be combined using comma separator:
+多个标签可使用逗号组合：
```go
type Document struct {
@@ -178,9 +175,9 @@ type Document struct {
}
```
-## Integration with Other Tags
+## 与其他标签共存
-Fory tags coexist with other struct tags:
+Fory 标签可与其他 struct tag 并存：
```go
type User struct {
@@ -190,11 +187,11 @@ type User struct {
}
```
-Each tag namespace is independent.
+各标签命名空间互不影响。
-## Field Visibility
+## 字段可见性
-Only **exported fields** (starting with uppercase) are considered:
+仅处理**导出字段**（首字母大写）：
```go
type User struct {
@@ -204,26 +201,26 @@ type User struct {
}
```
-Unexported fields are always ignored, regardless of tags.
+未导出字段始终忽略，与是否配置 tag 无关。
-## Field Ordering
+## 字段顺序
-Fields are serialized in a consistent order based on:
+字段会按稳定顺序序列化，依据：
-1. Field name (alphabetically in snake_case)
-2. Field type
+1. 字段名（snake_case 字典序）
+2. 字段类型
-This ensures cross-language compatibility where field order matters.
+这可保证跨语言场景下的字段顺序一致性。
-## Struct Hash
+## Struct 哈希
-Fory computes a hash of struct fields for version checking:
+Fory 会基于 struct 字段计算哈希用于版本校验：
-- Hash includes field names and types
-- Hash is written to serialized data
-- Mismatch triggers `ErrKindHashMismatch`
+- 哈希包含字段名与字段类型
+- 哈希会写入序列化数据
+- 不匹配会触发 `ErrKindHashMismatch`
-Struct field changes affect the hash:
+结构字段变更会影响哈希：
```go
// These produce different hashes
@@ -236,9 +233,9 @@ type V2 struct {
}
```
-## Examples
+## 示例
-### API Response Struct
+### API 响应结构
```go
type APIResponse struct {
@@ -249,7 +246,7 @@ type APIResponse struct {
}
```
-### Caching with Shared References
+### 带共享引用的缓存结构
```go
type CacheEntry struct {
@@ -260,7 +257,7 @@ type CacheEntry struct {
}
```
-### Document with Circular References
+### 带循环引用的文档结构
```go
type Document struct {
@@ -271,9 +268,9 @@ type Document struct {
}
```
-## Tag Parsing Errors
+## 标签解析错误
-Invalid tags produce errors during registration:
+注册阶段若标签非法会报错：
```go
type BadStruct struct {
@@ -287,15 +284,15 @@ err := f.RegisterStruct(BadStruct{}, 1)
## 最佳实践
-1. **Use `-` for sensitive data**: Passwords, tokens, internal state
-2. **Enable ref tracking for shared objects**: When the same pointer appears multiple times
-3. **Disable ref tracking for simple fields**: Optimization when you know the field is unique
-4. **Keep names consistent**: Cross-language names should match
-5. **Document tag usage**: Especially for non-obvious configurations
+1. **敏感字段使用 `-`**：如密码、令牌、内部状态
+2. **共享对象启用 ref**：同一指针可能多次出现时开启
+3. **简单唯一字段禁用 ref**：可做性能优化
+4. **保持命名一致**：跨语言字段名应保持稳定
+5. **记录标签意图**：非显式配置建议补充注释说明
-## Common Patterns
+## 常见模式
-### Ignoring Computed Fields
+### 忽略计算字段
```go
type Rectangle struct {
@@ -309,7 +306,7 @@ func (r *Rectangle) ComputeArea() {
}
```
-### Circular Structure with Parent
+### 带父指针的循环结构
```go
type TreeNode struct {
@@ -319,7 +316,7 @@ type TreeNode struct {
}
```
-### Mixed Serialization Needs
+### 混合序列化需求
```go
type Session struct {
@@ -333,6 +330,6 @@ type Session struct {
## 相关主题
-- [References](references.md)
-- [Basic Serialization](basic-serialization.md)
-- [Schema Evolution](schema-evolution.md)
+- [引用](references.md)
+- [基础序列化](basic-serialization.md)
+- [Schema 演进](schema-evolution.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/field-configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/field-configuration.md
index 0182eeb129..2f21ab6c69 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/field-configuration.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/field-configuration.md
@@ -19,31 +19,28 @@ license: |
limitations under the License.
---
-> 中文导读：本页介绍字段级序列化配置，包括字段 ID、可空控制、引用跟踪、忽略字段与动态类型控制等。
-> 建议在跨语言和兼容模式场景中优先显式配置字段 ID，并在需要时开启 ref/nullable 以保证行为一致。
-
本页说明如何在 Java 中配置序列化字段级元信息。
## 概述
Apache ForyTM 通过注解提供字段级配置：
-- **`@ForyField`**: Configure field metadata (id, nullable, ref, dynamic)
-- **`@Ignore`**: Exclude fields from serialization
-- **Integer type annotations**: Control integer encoding (varint, fixed, tagged, unsigned)
+- **`@ForyField`**：配置字段元信息（id、nullable、ref、dynamic）
+- **`@Ignore`**：将字段排除在序列化之外
+- **整数类型注解**：控制整数编码方式（varint、fixed、tagged、unsigned）
-This enables:
+这些能力可用于：
-- **Tag IDs**: Assign compact numeric IDs to reduce struct field meta size overhead for compatible mode
-- **Nullability**: Control whether fields can be null
-- **Reference Tracking**: Enable reference tracking for shared objects
-- **Field Skipping**: Exclude fields from serialization
-- **Encoding Control**: Specify how integers are encoded
-- **Polymorphism Control**: Control type info writing for struct fields
+- **Tag ID**：为兼容模式分配紧凑数值 ID，降低 struct 字段元信息开销
+- **可空控制**：声明字段是否允许为 null
+- **引用跟踪**：为共享对象开启引用跟踪
+- **字段跳过**：显式排除不需要序列化的字段
+- **编码控制**：指定整数序列化编码策略
+- **多态控制**：控制 struct 字段是否写入运行时类型信息
## 基本语法
-Use annotations on fields:
+在字段上使用注解：
```java
import org.apache.fory.annotation.ForyField;
@@ -60,9 +57,9 @@ public class Person {
}
```
-## The `@ForyField` Annotation
+## `@ForyField` 注解
-Use `@ForyField` to configure field-level metadata:
+使用 `@ForyField` 配置字段级元信息：
```java
public class User {
@@ -85,16 +82,16 @@ public class User {
### 参数
-| Parameter | Type | Default | Description |
+| 参数 | 类型 | 默认值 | 说明 |
| ---------- | --------- | ------- | -------------------------------------- |
-| `id` | `int` | `-1` | Field tag ID (-1 = use field name) |
-| `nullable` | `boolean` | `false` | Whether the field can be null |
-| `ref` | `boolean` | `false` | Enable reference tracking |
-| `dynamic` | `Dynamic` | `AUTO` | Control polymorphism for struct fields |
+| `id` | `int` | `-1` | 字段 tag ID（`-1` 表示使用字段名编码） |
+| `nullable` | `boolean` | `false` | 字段是否可为 null |
+| `ref` | `boolean` | `false` | 是否开启引用跟踪 |
+| `dynamic` | `Dynamic` | `AUTO` | 控制 struct 字段多态行为 |
-## Field ID (`id`)
+## 字段 ID（`id`）
-Assigns a numeric ID to a field to minimize struct field meta size overhead for compatible mode:
+通过为字段分配数值 ID，可降低兼容模式下 struct 字段元信息开销：
```java
public class User {
@@ -109,21 +106,21 @@ public class User {
}
```
-**Benefits**:
+**收益：**
-- Smaller serialized size (numeric IDs vs field names in metadata)
-- Reduced struct field meta overhead
-- Allows renaming fields without breaking binary compatibility
+- 序列化体积更小（元信息里用数值 ID 而不是字段名）
+- struct 字段元信息开销更低
+- 可在不破坏二进制兼容性的前提下重命名字段
-**Recommendation**: It is recommended to configure field IDs for compatible mode since it reduces serialization cost.
+**建议：** 兼容模式下建议配置字段 ID，以降低序列化成本。
-**Notes**:
+**注意：**
-- IDs must be unique within a class
-- IDs must be >= 0 (use -1 to use field name encoding, which is the default)
-- If not specified, field name is used in metadata (larger overhead)
+- 同一个类内 ID 必须唯一
+- ID 必须 `>= 0`（`-1` 表示使用字段名编码，也是默认行为）
+- 未指定时，元信息将写字段名（开销更大）
-**Without field IDs** (field names used in metadata):
+**不配置字段 ID**（元信息使用字段名）示例：
```java
public class User {
@@ -132,39 +129,39 @@ public class User {
}
```
-## Nullable Fields (`nullable`)
+## 可空字段（`nullable`）
-Use `nullable = true` for fields that can be `null`:
+对可能为 `null` 的字段使用 `nullable = true`：
```java
public class Record {
- // Nullable string field
+ // 可空字符串字段
@ForyField(id = 0, nullable = true)
private String optionalName;
- // Nullable Integer field (boxed type)
+ // 可空 Integer 字段（装箱类型）
@ForyField(id = 1, nullable = true)
private Integer optionalCount;
- // Non-nullable field (default)
+ // 非可空字段（默认）
@ForyField(id = 2)
private String requiredName;
}
```
-**Notes**:
+**注意：**
-- Default is `nullable = false` (non-nullable)
-- When `nullable = false`, Fory skips writing the null flag (saves 1 byte)
-- Boxed types (`Integer`, `Long`, etc.) that can be null should use `nullable = true`
+- 默认是 `nullable = false`（不可空）
+- `nullable = false` 时，Fory 会省略 null 标记写入（节省 1 字节）
+- 可能为 null 的装箱类型（`Integer`、`Long` 等）建议显式设为 `nullable = true`
-## Reference Tracking (`ref`)
+## 引用跟踪（`ref`）
-Enable reference tracking for fields that may be shared or circular:
+对于可能共享或循环引用的字段，启用引用跟踪：
```java
public class RefOuter {
- // Both fields may point to the same inner object
+ // 两个字段可能指向同一个内部对象
@ForyField(id = 0, ref = true, nullable = true)
private RefInner inner1;
@@ -176,56 +173,56 @@ public class CircularRef {
@ForyField(id = 0)
private String name;
- // Self-referencing field for circular references
+ // 自引用字段，用于循环引用
@ForyField(id = 1, ref = true, nullable = true)
private CircularRef selfRef;
}
```
-**Use Cases**:
+**适用场景：**
-- Enable for fields that may be circular or shared
-- When the same object is referenced from multiple fields
+- 字段可能形成循环或共享关系
+- 同一对象被多个字段引用
-**Notes**:
+**注意：**
-- Default is `ref = false` (no reference tracking)
-- When `ref = false`, avoids IdentityMap overhead and skips ref tracking flag
-- Reference tracking only takes effect when global ref tracking is enabled
+- 默认是 `ref = false`（不跟踪引用）
+- `ref = false` 可避免 IdentityMap 开销，也会跳过引用跟踪标记
+- 仅在全局启用 ref tracking 时，字段级 ref 才生效
-## Dynamic (Polymorphism Control)
+## Dynamic（多态控制）
-Controls polymorphism behavior for struct fields in cross-language serialization:
+控制跨语言序列化时 struct 字段的多态行为：
```java
public class Container {
- // AUTO: Interface/abstract types are dynamic, concrete types are not
+ // AUTO：接口/抽象类型动态，具体类型非动态
@ForyField(id = 0, dynamic = ForyField.Dynamic.AUTO)
- private Animal animal; // Interface - type info written
+ private Animal animal; // 接口类型，写入类型信息
- // FALSE: No type info written, uses declared type's serializer
+ // FALSE：不写类型信息，直接按声明类型序列化
@ForyField(id = 1, dynamic = ForyField.Dynamic.FALSE)
- private Dog dog; // Concrete - no type info
+ private Dog dog; // 具体类型，不写类型信息
- // TRUE: Type info written to support runtime subtypes
+ // TRUE：写类型信息，支持运行时子类型
@ForyField(id = 2, dynamic = ForyField.Dynamic.TRUE)
- private Object data; // Force polymorphic
+ private Object data; // 强制多态
}
```
-**Options**:
+**取值：**
-| Value | Description |
-| ------- | ------------------------------------------------------------------- |
-| `AUTO` | Auto-detect: interface/abstract are dynamic, concrete types are not |
-| `FALSE` | No type info written, uses declared type's serializer directly |
-| `TRUE` | Type info written to support subtypes at runtime |
+| 值 | 说明 |
+| ------- | ------------------------------------------- |
+| `AUTO` | 自动判断：接口/抽象类型动态，具体类型非动态 |
+| `FALSE` | 不写类型信息，直接使用声明类型的序列化器 |
+| `TRUE` | 写入类型信息，以支持运行时子类型 |
-## Skipping Fields
+## 跳过字段
-### Using `@Ignore`
+### 使用 `@Ignore`
-Exclude fields from serialization:
+将字段排除在序列化之外：
```java
import org.apache.fory.annotation.Ignore;
@@ -238,69 +235,69 @@ public class User {
private String name;
@Ignore
- private String password; // Not serialized
+ private String password; // 不序列化
@Ignore
- private Object internalState; // Not serialized
+ private Object internalState; // 不序列化
}
```
-### Using `transient`
+### 使用 `transient`
-Java's `transient` keyword also excludes fields:
+Java 的 `transient` 关键字同样会排除字段：
```java
public class User {
@ForyField(id = 0)
private long id;
- private transient String password; // Not serialized
- private transient Object cache; // Not serialized
+ private transient String password; // 不序列化
+ private transient Object cache; // 不序列化
}
```
-## Integer Type Annotations
+## 整数类型注解
-Fory provides annotations to control integer encoding for cross-language compatibility.
+Fory 提供整数注解，用于在跨语言场景中控制编码方式。
-### Signed 32-bit Integer (`@Int32Type`)
+### 有符号 32 位整数（`@Int32Type`）
```java
import org.apache.fory.annotation.Int32Type;
public class MyStruct {
- // Variable-length encoding (default) - compact for small values
+ // 变长编码（默认），小值更紧凑
@Int32Type(compress = true)
private int compactId;
- // Fixed 4-byte encoding - consistent size
+ // 固定 4 字节编码，长度稳定
@Int32Type(compress = false)
private int fixedId;
}
```
-### Signed 64-bit Integer (`@Int64Type`)
+### 有符号 64 位整数（`@Int64Type`）
```java
import org.apache.fory.annotation.Int64Type;
import org.apache.fory.config.LongEncoding;
public class MyStruct {
- // Variable-length encoding (default)
+ // 变长编码（默认）
@Int64Type(encoding = LongEncoding.VARINT)
private long compactId;
- // Fixed 8-byte encoding
+ // 固定 8 字节编码
@Int64Type(encoding = LongEncoding.FIXED)
private long fixedTimestamp;
- // Tagged encoding (4 bytes for small values, 9 bytes otherwise)
+ // tagged 编码（小值 4 字节，否则 9 字节）
@Int64Type(encoding = LongEncoding.TAGGED)
private long taggedValue;
}
```
-### Unsigned Integers
+### 无符号整数
```java
import org.apache.fory.annotation.Uint8Type;
@@ -310,23 +307,23 @@ import org.apache.fory.annotation.Uint64Type;
import org.apache.fory.config.LongEncoding;
public class UnsignedStruct {
- // Unsigned 8-bit [0, 255]
+ // 无符号 8 位 [0, 255]
@Uint8Type
private short flags;
- // Unsigned 16-bit [0, 65535]
+ // 无符号 16 位 [0, 65535]
@Uint16Type
private int port;
- // Unsigned 32-bit with varint encoding (default)
+ // 无符号 32 位，varint 编码（默认）
@Uint32Type(compress = true)
private long compactCount;
- // Unsigned 32-bit with fixed encoding
+ // 无符号 32 位，fixed 编码
@Uint32Type(compress = false)
private long fixedCount;
- // Unsigned 64-bit with various encodings
+ // 无符号 64 位，多种编码
@Uint64Type(encoding = LongEncoding.VARINT)
private long varintU64;
@@ -338,31 +335,31 @@ public class UnsignedStruct {
}
```
-### Encoding Summary
+### 编码汇总
-| Annotation | Type ID | Encoding | Size |
-| -------------------------------- | ------- | -------- | ------------ |
-| `@Int32Type(compress = true)` | 5 | varint | 1-5 bytes |
-| `@Int32Type(compress = false)` | 4 | fixed | 4 bytes |
-| `@Int64Type(encoding = VARINT)` | 7 | varint | 1-10 bytes |
-| `@Int64Type(encoding = FIXED)` | 6 | fixed | 8 bytes |
-| `@Int64Type(encoding = TAGGED)` | 8 | tagged | 4 or 9 bytes |
-| `@Uint8Type` | 9 | fixed | 1 byte |
-| `@Uint16Type` | 10 | fixed | 2 bytes |
-| `@Uint32Type(compress = true)` | 12 | varint | 1-5 bytes |
-| `@Uint32Type(compress = false)` | 11 | fixed | 4 bytes |
-| `@Uint64Type(encoding = VARINT)` | 14 | varint | 1-10 bytes |
-| `@Uint64Type(encoding = FIXED)` | 13 | fixed | 8 bytes |
-| `@Uint64Type(encoding = TAGGED)` | 15 | tagged | 4 or 9 bytes |
+| 注解 | Type ID | 编码 | 大小 |
+| -------------------------------- | ------- | ------ | ----------- |
+| `@Int32Type(compress = true)` | 5 | varint | 1-5 字节 |
+| `@Int32Type(compress = false)` | 4 | fixed | 4 字节 |
+| `@Int64Type(encoding = VARINT)` | 7 | varint | 1-10 字节 |
+| `@Int64Type(encoding = FIXED)` | 6 | fixed | 8 字节 |
+| `@Int64Type(encoding = TAGGED)` | 8 | tagged | 4 或 9 字节 |
+| `@Uint8Type` | 9 | fixed | 1 字节 |
+| `@Uint16Type` | 10 | fixed | 2 字节 |
+| `@Uint32Type(compress = true)` | 12 | varint | 1-5 字节 |
+| `@Uint32Type(compress = false)` | 11 | fixed | 4 字节 |
+| `@Uint64Type(encoding = VARINT)` | 14 | varint | 1-10 字节 |
+| `@Uint64Type(encoding = FIXED)` | 13 | fixed | 8 字节 |
+| `@Uint64Type(encoding = TAGGED)` | 15 | tagged | 4 或 9 字节 |
-**When to Use**:
+**何时使用：**
-- `varint`: Best for values that are often small (default)
-- `fixed`: Best for values that use full range (e.g., timestamps, hashes)
-- `tagged`: Good balance between size and performance
-- Unsigned types: For cross-language compatibility with Rust, Go, C++
+- `varint`：数值通常较小时最优（默认）
+- `fixed`：数值分布接近全范围时更稳定（如时间戳、哈希）
+- `tagged`：在体积与性能间平衡较好
+- 无符号类型：适合与 Rust/Go/C++ 等语言进行无符号整数互操作
-## Complete Example
+## 完整示例
```java
import org.apache.fory.Fory;
@@ -377,18 +374,18 @@ import java.util.Map;
import java.util.Set;
public class Document {
- // Fields with tag IDs (recommended for compatible mode)
+ // 带 tag ID 的字段（兼容模式推荐）
@ForyField(id = 0)
private String title;
@ForyField(id = 1)
private int version;
- // Nullable field
+ // 可空字段
@ForyField(id = 2, nullable = true)
private String description;
- // Collection fields
+ // 集合字段
@ForyField(id = 3)
private List<String> tags;
@@ -398,24 +395,24 @@ public class Document {
@ForyField(id = 5)
private Set<String> categories;
- // Integer with different encodings
+ // 不同编码方式的整数
@ForyField(id = 6)
@Uint64Type(encoding = LongEncoding.VARINT)
- private long viewCount; // varint encoding
+ private long viewCount; // varint 编码
@ForyField(id = 7)
@Uint64Type(encoding = LongEncoding.FIXED)
- private long fileSize; // fixed encoding
+ private long fileSize; // fixed 编码
@ForyField(id = 8)
@Uint64Type(encoding = LongEncoding.TAGGED)
- private long checksum; // tagged encoding
+ private long checksum; // tagged 编码
- // Reference-tracked field for shared/circular references
+ // 共享/循环引用字段
@ForyField(id = 9, ref = true, nullable = true)
private Document parent;
- // Ignored field (not serialized)
+ // 忽略字段（不序列化）
private transient Object cache;
// Getters and setters...
@@ -446,13 +443,13 @@ public class Main {
}
```
-## Cross-Language Compatibility
+## 跨语言兼容
-When serializing data to be read by other languages (Python, Rust, C++, Go), use field IDs and matching type annotations:
+当数据需要被其他语言（Python、Rust、C++、Go）读取时，建议使用字段 ID 并配套类型注解：
```java
public class CrossLangData {
- // Use field IDs for cross-language compatibility
+ // 使用字段 ID 保证跨语言兼容
@ForyField(id = 0)
@Int32Type(compress = true)
private int intVar;
@@ -470,9 +467,9 @@ public class CrossLangData {
}
```
-## Schema Evolution
+## Schema 演进
-Compatible mode supports schema evolution. It is recommended to configure field IDs to reduce serialization cost:
+兼容模式支持 Schema 演进。建议配置字段 ID 以降低序列化成本：
```java
// Version 1
@@ -497,9 +494,9 @@ public class DataV2 {
}
```
-Data serialized with V1 can be deserialized with V2 (new field will be `null`).
+V1 写入的数据可由 V2 读取（新增字段会是 `null`）。
-Alternatively, field IDs can be omitted (field names will be used in metadata with larger overhead):
+也可以不配置字段 ID（元信息会使用字段名，开销更大）：
```java
public class Data {
@@ -508,23 +505,23 @@ public class Data {
}
```
-## Native Mode vs Xlang Mode
+## Native 模式与 Xlang 模式
-Field configuration behaves differently depending on the serialization mode:
+字段配置在不同序列化模式下的默认行为不同。
-### Native Mode (Java-only)
+### Native 模式（仅 Java）
-Native mode has **relaxed default values** for maximum compatibility:
+Native 模式以最大兼容性为目标，默认值更宽松：
-- **Nullable**: Reference types are nullable by default
-- **Ref tracking**: Enabled by default for object references (except `String`, boxed types, and time types)
-- **Polymorphism**: All non-final classes support polymorphism by default
+- **Nullable**：引用类型默认可空
+- **Ref tracking**：对象引用默认开启（`String`、装箱类型、时间类型除外）
+- **Polymorphism**：所有非 final 类默认支持多态
-In native mode, you typically **don't need to configure field annotations** unless you want to:
+在 Native 模式下，通常**不需要额外字段注解**，除非你希望：
-- Reduce serialized size by using field IDs
-- Optimize performance by disabling unnecessary ref tracking
-- Control integer encoding for specific fields
+- 用字段 ID 降低体积
+- 关闭不必要的 ref 跟踪以优化性能
+- 对特定字段精确控制整数编码
```java
// Native mode: works without any annotations
@@ -535,20 +532,20 @@ public class User {
}
```
-### Xlang Mode (Cross-language)
+### Xlang 模式（跨语言）
-Xlang mode has **stricter default values** due to type system differences between languages:
+由于不同语言类型系统差异，Xlang 模式默认值更严格：
-- **Nullable**: Fields are non-nullable by default (`nullable = false`)
-- **Ref tracking**: Disabled by default (`ref = false`)
-- **Polymorphism**: Concrete types are non-polymorphic by default
+- **Nullable**：字段默认不可空（`nullable = false`）
+- **Ref tracking**：默认关闭（`ref = false`）
+- **Polymorphism**：具体类型默认不写多态类型信息
-In xlang mode, you **need to configure fields** when:
+在 Xlang 模式下，以下情况需要显式配置：
-- A field can be null (use `nullable = true`)
-- A field needs reference tracking for shared/circular objects (use `ref = true`)
-- Integer types need specific encoding for cross-language compatibility
-- You want to reduce metadata size (use field IDs)
+- 字段可能为 null（使用 `nullable = true`）
+- 字段需要共享/循环引用语义（使用 `ref = true`）
+- 整数类型需要为跨语言兼容指定编码
+- 你希望减少元信息大小（使用字段 ID）
```java
// Xlang mode: explicit configuration required for nullable/ref fields
@@ -567,42 +564,42 @@ public class User {
}
```
-### Default Values Summary
-
-| Option | Native Mode Default | Xlang Mode Default |
-| ---------- | ------------------------ | --------------------------------- |
-| `nullable` | `true` (reference types) | `false` |
-| `ref` | `true` | `false` |
-| `dynamic` | `true` (non-final) | `AUTO` (concrete types are final) |
-
-## Best Practices
-
-1. **Configure field IDs**: Recommended for compatible mode to reduce serialization cost
-2. **Use `nullable = true` for nullable fields**: Required for fields that can be null
-3. **Enable ref tracking for shared objects**: Use `ref = true` when objects are shared or circular
-4. **Use `@Ignore` or `transient` for sensitive data**: Passwords, tokens, internal state
-5. **Choose appropriate encoding**: `varint` for small values, `fixed` for full-range values
-6. **Keep IDs stable**: Once assigned, don't change field IDs
-7. **Configure unsigned types for cross-language compatibility**: When interoperating with unsigned numbers in Rust, Go, C++
-
-## Annotations Reference
-
-| Annotation | Description |
-| ----------------------------- | -------------------------------------- |
-| `@ForyField(id = N)` | Field tag ID to reduce metadata size |
-| `@ForyField(nullable = true)` | Mark field as nullable |
-| `@ForyField(ref = true)` | Enable reference tracking |
-| `@ForyField(dynamic = ...)` | Control polymorphism for struct fields |
-| `@Ignore` | Exclude field from serialization |
-| `@Int32Type(compress = ...)` | 32-bit signed integer encoding |
-| `@Int64Type(encoding = ...)` | 64-bit signed integer encoding |
-| `@Uint8Type` | Unsigned 8-bit integer |
-| `@Uint16Type` | Unsigned 16-bit integer |
-| `@Uint32Type(compress = ...)` | Unsigned 32-bit integer encoding |
-| `@Uint64Type(encoding = ...)` | Unsigned 64-bit integer encoding |
-
-## Related Topics
-
-- [Basic Serialization](basic_serialization) - Getting started with Fory serialization
-- [Schema Evolution](schema_evolution) - Compatible mode and schema evolution
-- [Cross-Language](cross_language) - Interoperability with Python, Rust, C++, Go
+### 默认值汇总
+
+| 选项 | Native 模式默认值 | Xlang 模式默认值 |
+| ---------- | --------------------- | ---------------------------------- |
+| `nullable` | `true`（引用类型） | `false` |
+| `ref` | `true` | `false` |
+| `dynamic` | `true`（非 final 类） | `AUTO`（具体类型通常按非动态处理） |
+
+## 最佳实践
+
+1. **配置字段 ID**：兼容模式下建议配置，降低序列化成本
+2. **可空字段使用 `nullable = true`**：对可为 null 的字段必须显式声明
+3. **共享对象开启 `ref`**：对象共享或循环时使用 `ref = true`
+4. **敏感字段用 `@Ignore` 或 `transient`**：如密码、令牌、内部状态
+5. **选择合适编码**：小值用 `varint`，全范围值用 `fixed`
+6. **保持 ID 稳定**：一旦分配，不要随意改动字段 ID
+7. **跨语言场景显式无符号类型**：与 Rust、Go、C++ 互操作时尤其重要
+
+## 注解速查
+
+| 注解 | 说明 |
+| ----------------------------- | ------------------------------- |
+| `@ForyField(id = N)` | 配置字段 tag ID，减少元信息开销 |
+| `@ForyField(nullable = true)` | 将字段标记为可空 |
+| `@ForyField(ref = true)` | 为字段启用引用跟踪 |
+| `@ForyField(dynamic = ...)` | 控制 struct 字段多态行为 |
+| `@Ignore` | 将字段排除在序列化之外 |
+| `@Int32Type(compress = ...)` | 32 位有符号整数编码 |
+| `@Int64Type(encoding = ...)` | 64 位有符号整数编码 |
+| `@Uint8Type` | 8 位无符号整数 |
+| `@Uint16Type` | 16 位无符号整数 |
+| `@Uint32Type(compress = ...)` | 32 位无符号整数编码 |
+| `@Uint64Type(encoding = ...)` | 64 位无符号整数编码 |
+
+## 相关主题
+
+- [基础序列化](basic_serialization) - 快速上手 Fory 序列化
+- [Schema 演进](schema_evolution) - 兼容模式与 schema 演进
+- [跨语言](cross_language) - 与 Python、Rust、C++、Go 互操作
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/field-configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/field-configuration.md
index fb489d283b..65d7b04281 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/field-configuration.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/field-configuration.md
@@ -19,31 +19,28 @@ license: |
limitations under the License.
---
-> 中文导读：本页介绍字段级序列化配置，包括字段 ID、可空控制、引用跟踪、忽略字段与动态类型控制等。
-> 建议在跨语言和兼容模式场景中优先显式配置字段 ID，并在需要时开启 ref/nullable 以保证行为一致。
-
本页说明如何在 Python 中配置序列化字段级元信息。
## 概述
-Apache ForyTM 通过以下方式提供字段级配置：
+Apache ForyTM 通过以下机制提供字段级配置：
-- **`pyfory.field()`**: Configure field metadata (id, nullable, ref, ignore, dynamic)
-- **Type annotations**: Control integer encoding (varint, fixed, tagged)
-- **`Optional[T]`**: Mark fields as nullable
+- **`pyfory.field()`**：配置字段元信息（id、nullable、ref、ignore、dynamic）
+- **类型注解**：控制整数编码（varint、fixed、tagged）
+- **`Optional[T]`**：标记字段可空
-This enables:
+这些能力可用于：
-- **Tag IDs**: Assign compact numeric IDs to reduce struct field meta size overhead
-- **Nullability**: Control whether fields can be null
-- **Reference Tracking**: Enable reference tracking for shared objects
-- **Field Skipping**: Exclude fields from serialization
-- **Encoding Control**: Specify how integers are encoded (varint, fixed, tagged)
-- **Polymorphism**: Control whether type info is written for struct fields
+- **Tag ID**：分配紧凑数值 ID，降低 struct 字段元信息开销
+- **可空控制**：声明字段是否可为 null/None
+- **引用跟踪**：为共享对象启用引用跟踪
+- **字段跳过**：从序列化中排除字段
+- **编码控制**：指定整数编码方式（varint、fixed、tagged）
+- **多态控制**：控制 struct 字段是否写入类型信息
## 基本语法
-Use `@dataclass` decorator with type annotations and `pyfory.field()`:
+结合 `@dataclass`、类型注解与 `pyfory.field()`：
```python
from dataclasses import dataclass
@@ -59,7 +56,7 @@ class Person:
## `pyfory.field()` 函数
-Use `pyfory.field()` to configure field-level metadata:
+使用 `pyfory.field()` 配置字段级元信息：
```python
@dataclass
@@ -73,19 +70,19 @@ class User:
### 参数
-| Parameter | Type | Default | Description |
-| ----------------- | -------- | --------- | ------------------------------------ |
-| `id` | `int` | `-1` | Field tag ID (-1 = use field name) |
-| `nullable` | `bool` | `False` | Whether the field can be null |
-| `ref` | `bool` | `False` | Enable reference tracking |
-| `ignore` | `bool` | `False` | Exclude field from serialization |
-| `dynamic` | `bool` | `None` | Control whether type info is written |
-| `default` | Any | `MISSING` | Default value for the field |
-| `default_factory` | Callable | `MISSING` | Factory function for default value |
+| 参数 | 类型 | 默认值 | 说明 |
+| ----------------- | -------- | --------- | ---------------------------------- |
+| `id` | `int` | `-1` | 字段 tag ID（`-1` 表示使用字段名） |
+| `nullable` | `bool` | `False` | 字段是否可为 null/None |
+| `ref` | `bool` | `False` | 是否启用引用跟踪 |
+| `ignore` | `bool` | `False` | 是否从序列化中排除 |
+| `dynamic` | `bool` | `None` | 控制是否写入类型信息 |
+| `default` | Any | `MISSING` | 字段默认值 |
+| `default_factory` | Callable | `MISSING` | 默认值工厂函数 |
-## Field ID (`id`)
+## 字段 ID（`id`）
-Assigns a numeric ID to a field to minimize struct field meta size overhead:
+通过给字段分配数值 ID，可减少 struct 字段元信息开销：
```python
@dataclass
@@ -95,21 +92,21 @@ class User:
age: pyfory.int32 = pyfory.field(id=2, default=0)
```
-**Benefits**:
+**收益：**
-- Smaller serialized size (numeric IDs vs field names in metadata)
-- Reduced struct field meta overhead
-- Allows renaming fields without breaking binary compatibility
+- 序列化体积更小（元信息中数值 ID 替代字段名）
+- struct 字段元信息开销更低
+- 字段重命名时可保持二进制兼容
-**Recommendation**: It is recommended to configure field IDs for compatible mode since it reduces serialization cost.
+**建议：** 兼容模式下建议配置字段 ID，以降低序列化成本。
-**Notes**:
+**注意：**
-- IDs must be unique within a class
-- IDs must be >= 0 (use -1 to use field name encoding, which is the default)
-- If not specified, field name is used in metadata (larger overhead)
+- 同一类内 ID 必须唯一
+- ID 必须 `>= 0`（`-1` 表示使用字段名编码，默认行为）
+- 未指定时会使用字段名写入元信息（开销更大）
-**Without field IDs** (field names used in metadata):
+**不配置字段 ID**（元信息使用字段名）示例：
```python
@dataclass
@@ -118,35 +115,35 @@ class User:
name: str = ""
```
-## Nullable Fields (`nullable`)
+## 可空字段（`nullable`）
-Use `nullable=True` for fields that can be `None`:
+对可能为 `None` 的字段使用 `nullable=True`：
```python
from typing import Optional
@dataclass
class Record:
- # Nullable string field
+ # 可空字符串字段
optional_name: Optional[str] = pyfory.field(id=0, nullable=True, default=None)
- # Nullable integer field
+ # 可空整数字段
optional_count: Optional[pyfory.int32] = pyfory.field(id=1, nullable=True, default=None)
```
-**Notes**:
+**注意：**
-- `Optional[T]` fields must have `nullable=True`
-- Non-optional fields default to `nullable=False`
+- `Optional[T]` 字段应配合 `nullable=True`
+- 非 Optional 字段默认 `nullable=False`
-## Reference Tracking (`ref`)
+## 引用跟踪（`ref`）
-Enable reference tracking for fields that may be shared or circular:
+对于可能共享或循环引用的字段启用引用跟踪：
```python
@dataclass
class RefOuter:
- # Both fields may point to the same inner object
+ # 两个字段可能指向同一个内部对象
inner1: Optional[RefInner] = pyfory.field(id=0, ref=True, nullable=True, default=None)
inner2: Optional[RefInner] = pyfory.field(id=1, ref=True, nullable=True, default=None)
@@ -154,37 +151,37 @@ class RefOuter:
@dataclass
class CircularRef:
name: str = pyfory.field(id=0, default="")
- # Self-referencing field for circular references
+ # 自引用字段，用于循环引用
self_ref: Optional["CircularRef"] = pyfory.field(id=1, ref=True, nullable=True, default=None)
```
-**Use Cases**:
+**适用场景：**
-- Enable for fields that may be circular or shared
-- When the same object is referenced from multiple fields
+- 字段可能形成循环或共享关系
+- 同一对象被多个字段引用
-**Notes**:
+**注意：**
-- Reference tracking only takes effect when `Fory(ref=True)` is set globally
-- Field-level `ref=True` AND global `ref=True` must both be enabled
+- 只有全局设置 `Fory(ref=True)` 时，引用跟踪才生效
+- 字段级 `ref=True` 与全局 `ref=True` 必须同时开启
-## Skipping Fields (`ignore`)
+## 跳过字段（`ignore`）
-Exclude fields from serialization:
+将字段排除在序列化之外：
```python
@dataclass
class User:
id: pyfory.int64 = pyfory.field(id=0, default=0)
name: str = pyfory.field(id=1, default="")
- # Not serialized
+ # 不序列化
_cache: dict = pyfory.field(ignore=True, default_factory=dict)
_internal_state: str = pyfory.field(ignore=True, default="")
```
-## Dynamic Fields (`dynamic`)
+## Dynamic 字段（`dynamic`）
-Control whether type information is written for struct fields. This is essential for polymorphism support:
+控制 struct 字段是否写入类型信息，这是支持多态的关键：
```python
from abc import ABC, abstractmethod
@@ -203,36 +200,36 @@ class Circle(Shape):
@dataclass
class Container:
- # Abstract class: dynamic is always True (type info written)
+ # 抽象类：dynamic 总为 True（写类型信息）
shape: Shape = pyfory.field(id=0)
- # Force type info for concrete type (support runtime subtypes)
+ # 对具体类型强制写类型信息（支持运行时子类）
circle: Circle = pyfory.field(id=1, dynamic=True)
- # Skip type info for concrete type (use declared type directly)
+ # 对具体类型跳过类型信息（按声明类型处理）
fixed_circle: Circle = pyfory.field(id=2, dynamic=False)
```
-**Default Behavior**:
+**默认行为：**
-| Mode | Abstract Class | Concrete Object Types | Numeric/str/time Types |
-| ----------- | -------------- | --------------------- | ---------------------- |
-| Native mode | `True` | `True` | `False` |
-| Xlang mode | `True` | `False` | `False` |
+| 模式 | 抽象类 | 具体对象类型 | 数值/str/time 类型 |
+| ----------- | ------ | ------------ | ------------------ |
+| Native 模式 | `True` | `True` | `False` |
+| Xlang 模式 | `True` | `False` | `False` |
-**Notes**:
+**注意：**
-- **Abstract classes**: `dynamic` is always `True` (type info must be written)
-- **Native mode**: `dynamic` defaults to `True` for object types, `False` for numeric/str/time types
-- **Xlang mode**: `dynamic` defaults to `False` for concrete types
-- Use `dynamic=True` when a concrete field may hold subclass instances
-- Use `dynamic=False` for performance optimization when type is known
+- **抽象类**：`dynamic` 始终为 `True`（必须写类型信息）
+- **Native 模式**：对象类型默认 `dynamic=True`；数值/str/time 默认 `False`
+- **Xlang 模式**：具体类型默认 `dynamic=False`
+- 当具体字段可能持有子类实例时，使用 `dynamic=True`
+- 当类型固定且追求性能时，可使用 `dynamic=False`
-## Integer Type Annotations
+## 整数类型注解
-Fory provides type annotations to control integer encoding:
+Fory 提供类型注解来控制整数编码。
-### Signed Integers
+### 有符号整数
```python
@dataclass
@@ -243,7 +240,7 @@ class SignedIntegers:
long_val: pyfory.int64 = 0 # 64-bit signed (varint encoding)
```
-### Unsigned Integers
+### 无符号整数
```python
@dataclass
@@ -264,7 +261,7 @@ class UnsignedIntegers:
u64_tagged: pyfory.tagged_uint64 = 0 # 64-bit unsigned (tagged)
```
-### Floating Point
+### 浮点数
```python
@dataclass
@@ -273,31 +270,31 @@ class FloatingPoint:
double_val: pyfory.float64 = 0.0 # 64-bit double
```
-### Encoding Summary
+### 编码汇总
-| Type | Encoding | Size |
-| ---------------------- | -------- | ---------- |
-| `pyfory.int8` | fixed | 1 byte |
-| `pyfory.int16` | fixed | 2 bytes |
-| `pyfory.int32` | varint | 1-5 bytes |
-| `pyfory.int64` | varint | 1-10 bytes |
-| `pyfory.uint8` | fixed | 1 byte |
-| `pyfory.uint16` | fixed | 2 bytes |
-| `pyfory.uint32` | varint | 1-5 bytes |
-| `pyfory.uint64` | varint | 1-10 bytes |
-| `pyfory.fixed_uint32` | fixed | 4 bytes |
-| `pyfory.fixed_uint64` | fixed | 8 bytes |
-| `pyfory.tagged_uint64` | tagged | 1-9 bytes |
-| `pyfory.float32` | fixed | 4 bytes |
-| `pyfory.float64` | fixed | 8 bytes |
+| 类型 | 编码 | 大小 |
+| ---------------------- | ------ | --------- |
+| `pyfory.int8` | fixed | 1 字节 |
+| `pyfory.int16` | fixed | 2 字节 |
+| `pyfory.int32` | varint | 1-5 字节 |
+| `pyfory.int64` | varint | 1-10 字节 |
+| `pyfory.uint8` | fixed | 1 字节 |
+| `pyfory.uint16` | fixed | 2 字节 |
+| `pyfory.uint32` | varint | 1-5 字节 |
+| `pyfory.uint64` | varint | 1-10 字节 |
+| `pyfory.fixed_uint32` | fixed | 4 字节 |
+| `pyfory.fixed_uint64` | fixed | 8 字节 |
+| `pyfory.tagged_uint64` | tagged | 1-9 字节 |
+| `pyfory.float32` | fixed | 4 字节 |
+| `pyfory.float64` | fixed | 8 字节 |
-**When to Use**:
+**何时使用：**
-- `varint`: Best for values that are often small (default for int32/int64/uint32/uint64)
-- `fixed`: Best for values that use full range (e.g., timestamps, hashes)
-- `tagged`: When type information needs to be preserved (uint64 only)
+- `varint`：适合小值占多数的场景（int32/int64/uint32/uint64 默认）
+- `fixed`：适合覆盖全值域的场景（例如时间戳、哈希）
+- `tagged`：适合需要保留类型信息的场景（仅 uint64）
-## Complete Example
+## 完整示例
```python
from dataclasses import dataclass
@@ -361,9 +358,9 @@ if __name__ == "__main__":
main()
```
-## Cross-Language Compatibility
+## 跨语言兼容
-When serializing data to be read by other languages (Java, Rust, C++, Go), use field IDs and matching type annotations:
+当序列化数据将被其他语言（Java、Rust、C++、Go）读取时，建议使用字段 ID 并配套类型注解：
```python
@dataclass
@@ -375,9 +372,9 @@ class CrossLangData:
optional_value: Optional[str] = pyfory.field(id=3, nullable=True, default=None)
```
-## Schema Evolution
+## Schema 演进
-Compatible mode supports schema evolution. It is recommended to configure field IDs to reduce serialization cost:
+兼容模式支持 Schema 演进。建议通过字段 ID 降低序列化成本：
```python
# Version 1
@@ -395,9 +392,9 @@ class DataV2:
email: Optional[str] = pyfory.field(id=2, nullable=True, default=None) # New field
```
-Data serialized with V1 can be deserialized with V2 (new field will be `None`).
+V1 写出的数据可由 V2 读取（新增字段将为 `None`）。
-Alternatively, field IDs can be omitted (field names will be used in metadata with larger overhead):
+也可以不配置字段 ID（此时元信息使用字段名，开销更大）：
```python
@dataclass
@@ -406,21 +403,21 @@ class Data:
name: str = ""
```
-## Native Mode vs Xlang Mode
+## Native 模式与 Xlang 模式
-Field configuration behaves differently depending on the serialization mode:
+字段配置会随序列化模式不同而变化。
-### Native Mode (Python-only)
+### Native 模式（仅 Python）
-Native mode has **relaxed default values** for maximum compatibility:
+Native 模式默认值更宽松，以获得更高兼容性：
-- **Nullable**: `str` and numeric types are non-nullable by default unless `Optional` is used
-- **Ref tracking**: Enabled by default for object references (except `str` and numeric types)
+- **Nullable**：`str` 和数值类型默认不可空，除非使用 `Optional`
+- **Ref tracking**：对象引用默认开启（`str` 与数值类型除外）
-In native mode, you typically **don't need to configure field annotations** unless you want to:
+在 Native 模式中，通常**不需要显式字段配置**，除非你希望：
-- Reduce serialized size by using field IDs
-- Optimize performance by disabling unnecessary ref tracking
+- 通过字段 ID 降低序列化体积
+- 关闭不必要的 ref 跟踪以优化性能
```python
# Native mode: works without field configuration
@@ -431,19 +428,19 @@ class User:
tags: List[str] = None
```
-### Xlang Mode (Cross-language)
+### Xlang 模式（跨语言）
-Xlang mode has **stricter default values** due to type system differences between languages:
+由于语言间类型系统差异，Xlang 模式默认值更严格：
-- **Nullable**: Fields are non-nullable by default (`nullable=False`)
-- **Ref tracking**: Disabled by default (`ref=False`)
+- **Nullable**：默认不可空（`nullable=False`）
+- **Ref tracking**：默认关闭（`ref=False`）
-In xlang mode, you **need to configure fields** when:
+在 Xlang 模式中，以下情况需要显式配置：
-- A field can be None (use `Optional[T]` with `nullable=True`)
-- A field needs reference tracking for shared/circular objects (use `ref=True`)
-- Integer types need specific encoding for cross-language compatibility
-- You want to reduce metadata size (use field IDs)
+- 字段可能为 None（`Optional[T]` + `nullable=True`）
+- 字段需要共享/循环引用语义（`ref=True`）
+- 整数类型需要指定跨语言编码
+- 需要减少元信息开销（字段 ID）
```python
# Xlang mode: explicit configuration required for nullable/ref fields
@@ -455,41 +452,41 @@ class User:
friend: Optional["User"] = pyfory.field(id=3, ref=True, nullable=True, default=None) # Must declare ref
```
-### Default Values Summary
-
-| Option | Native Mode Default | Xlang Mode Default |
-| ---------- | ----------------------------------------------------- | ------------------ |
-| `nullable` | `False` for `str`/numeric; others nullable by default | `False` |
-| `ref` | `True` (except `str` and numeric types) | `False` |
-| `dynamic` | `True` (except numeric/str/time types) | `False` (concrete) |
-
-## Best Practices
-
-1. **Configure field IDs**: Recommended for compatible mode to reduce serialization cost
-2. **Use `Optional[T]` with `nullable=True`**: Required for nullable fields in xlang mode
-3. **Enable ref tracking for shared objects**: Use `ref=True` when objects are shared or circular
-4. **Use `ignore=True` for sensitive data**: Passwords, tokens, internal state
-5. **Choose appropriate encoding**: `varint` for small values, `fixed` for full-range values
-6. **Keep IDs stable**: Once assigned, don't change field IDs
-
-## Options Reference
-
-| Configuration | Description |
-| -------------------------------------------- | ------------------------------------ |
-| `pyfory.field(id=N)` | Field tag ID to reduce metadata size |
-| `pyfory.field(nullable=True)` | Mark field as nullable |
-| `pyfory.field(ref=True)` | Enable reference tracking |
-| `pyfory.field(ignore=True)` | Exclude field from serialization |
-| `pyfory.field(dynamic=True)` | Force type info to be written |
-| `pyfory.field(dynamic=False)` | Skip type info (use declared type) |
-| `Optional[T]` | Type hint for nullable fields |
-| `pyfory.int32`, `pyfory.int64` | Signed integers (varint encoding) |
-| `pyfory.uint32`, `pyfory.uint64` | Unsigned integers (varint encoding) |
-| `pyfory.fixed_uint32`, `pyfory.fixed_uint64` | Fixed-size unsigned |
-| `pyfory.tagged_uint64` | Tagged encoding for uint64 |
-
-## Related Topics
-
-- [Basic Serialization](basic_serialization) - Getting started with Fory serialization
-- [Schema Evolution](schema_evolution) - Compatible mode and schema evolution
-- [Cross-Language](cross_language) - Interoperability with Java, Rust, C++, Go
+### 默认值汇总
+
+| 选项 | Native 模式默认值 | Xlang 模式默认值 |
+| ---------- | ------------------------------------------ | ------------------- |
+| `nullable` | `str`/数值类型为 `False`，其余对象通常可空 | `False` |
+| `ref` | `True`（`str` 和数值类型除外） | `False` |
+| `dynamic` | `True`（数值/str/time 类型除外） | `False`（具体类型） |
+
+## 最佳实践
+
+1. **配置字段 ID**：兼容模式下建议配置，降低序列化成本
+2. **`Optional[T]` 配合 `nullable=True`**：xlang 下可空字段需要显式声明
+3. **共享对象启用 ref**：共享或循环关系使用 `ref=True`
+4. **敏感字段使用 `ignore=True`**：例如密码、令牌、内部状态
+5. **选择合适编码**：小值用 `varint`，全范围值用 `fixed`
+6. **保持 ID 稳定**：分配后不要更改字段 ID
+
+## 选项速查
+
+| 配置 | 说明 |
+| -------------------------------------------- | ------------------------------ |
+| `pyfory.field(id=N)` | 字段 tag ID，减少元信息开销 |
+| `pyfory.field(nullable=True)` | 标记字段可空 |
+| `pyfory.field(ref=True)` | 启用引用跟踪 |
+| `pyfory.field(ignore=True)` | 将字段排除在序列化之外 |
+| `pyfory.field(dynamic=True)` | 强制写入类型信息 |
+| `pyfory.field(dynamic=False)` | 跳过类型信息（按声明类型处理） |
+| `Optional[T]` | 可空字段类型提示 |
+| `pyfory.int32`, `pyfory.int64` | 有符号整数（varint 编码） |
+| `pyfory.uint32`, `pyfory.uint64` | 无符号整数（varint 编码） |
+| `pyfory.fixed_uint32`, `pyfory.fixed_uint64` | 定长无符号整数 |
+| `pyfory.tagged_uint64` | uint64 的 tagged 编码 |
+
+## 相关主题
+
+- [基础序列化](basic_serialization) - 快速上手 Fory 序列化
+- [Schema 演进](schema_evolution) - 兼容模式与 schema 演进
+- [跨语言](cross_language) - 与 Java、Rust、C++、Go 互操作
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.13/introduction/overview.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.13/introduction/overview.md
index 7a5a2a685c..28831ecb10 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.13/introduction/overview.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.13/introduction/overview.md
@@ -55,12 +55,12 @@ Apache Fory™ 通过先进的优化技术提供卓越性能：
Apache Fory™ 实现了针对不同场景优化的多个二进制协议：
-| 协议 | 使用场景 | 核心特性 |
-| ------------------------------------------------------------------------- | ---------------------- | -------------------------------------------- |
-| **[跨语言序列化](../specification/xlang_serialization_spec.md)** | 跨语言对象交换 | 自动序列化、引用、多态 |
-| **[Java 序列化](../specification/java_serialization_spec.md)** | 高性能 Java 专用 | JDK 序列化的直接替代，快 100 倍 |
-| **[行格式](../specification/row_format_spec.md)** | 分析和数据处理 | 零拷贝随机访问、Arrow 兼容 |
-| **Python 原生** | Python 专用序列化 | Pickle/cloudpickle 替代，性能更好 |
+| 协议 | 使用场景 | 核心特性 |
+| ---------------------------------------------------------------- | ----------------- | --------------------------------- |
+| **[跨语言序列化](../specification/xlang_serialization_spec.md)** | 跨语言对象交换 | 自动序列化、引用、多态 |
+| **[Java 序列化](../specification/java_serialization_spec.md)** | 高性能 Java 专用 | JDK 序列化的直接替代，快 100 倍 |
+| **[行格式](../specification/row_format_spec.md)** | 分析和数据处理 | 零拷贝随机访问、Arrow 兼容 |
+| **Python 原生** | Python 专用序列化 | Pickle/cloudpickle 替代，性能更好 |
所有协议共享相同的优化代码库，一个协议的改进可以惠及其他协议。
@@ -68,25 +68,25 @@ Apache Fory™ 实现了针对不同场景优化的多个二进制协议：
### 用户指南
-| 指南 | 描述 | 源文件 | 网站 |
-| ---------------------- | --------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| **Java 序列化** | Java 序列化综合指南 | [java_serialization_guide.md](../guide/java_serialization_guide.md) | [📖 查看](https://fory.apache.org/docs/guide/java_serialization) |
-| **跨语言序列化** | 多语言对象交换 | [xlang_serialization_guide.md](../guide/xlang_serialization_guide.md) | [📖 查看](https://fory.apache.org/docs/specification/fory_xlang_serialization_spec) |
-| **行格式** | 零拷贝随机访问格式 | [row_format_guide.md](../guide/row_format_guide.md) | [📖 查看](https://fory.apache.org/docs/specification/fory_row_format_spec) |
-| **Python** | Python 特定功能和用法 | [python_guide.md](../guide/python_guide.md) | [📖 查看](https://fory.apache.org/docs/guide/python_serialization) |
-| **Rust** | Rust 实现和模式 | [rust_guide.md](../guide/rust_guide.md) | [📖 查看](https://fory.apache.org/docs/guide/rust_serialization) |
-| **Scala** | Scala 集成和最佳实践 | [scala_guide.md](../guide/scala_guide.md) | [📖 查看](https://fory.apache.org/docs/guide/scala_serialization) |
-| **GraalVM** | 原生镜像支持和 AOT 编译 | [graalvm_guide.md](../guide/graalvm_guide.md) | [📖 查看](https://fory.apache.org/docs/guide/graalvm_serialization) |
-| **开发** | 构建和贡献 Fory | [DEVELOPMENT.md](../guide/DEVELOPMENT.md) | [📖 查看](https://fory.apache.org/docs/guide/development) |
+| 指南 | 描述 | 源文件 | 网站 |
+| ---------------- | ----------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **Java 序列化** | Java 序列化综合指南 | [java_serialization_guide.md](../guide/java_serialization_guide.md) | [📖 查看](https://fory.apache.org/docs/guide/java_serialization) |
+| **跨语言序列化** | 多语言对象交换 | [xlang_serialization_guide.md](../guide/xlang_serialization_guide.md) | [📖 查看](https://fory.apache.org/docs/specification/fory_xlang_serialization_spec) |
+| **行格式** | 零拷贝随机访问格式 | [row_format_guide.md](../guide/row_format_guide.md) | [📖 查看](https://fory.apache.org/docs/specification/fory_row_format_spec) |
+| **Python** | Python 特定功能和用法 | [python_guide.md](../guide/python_guide.md) | [📖 查看](https://fory.apache.org/docs/guide/python_serialization) |
+| **Rust** | Rust 实现和模式 | [rust_guide.md](../guide/rust_guide.md) | [📖 查看](https://fory.apache.org/docs/guide/rust_serialization) |
+| **Scala** | Scala 集成和最佳实践 | [scala_guide.md](../guide/scala_guide.md) | [📖 查看](https://fory.apache.org/docs/guide/scala_serialization) |
+| **GraalVM** | 原生镜像支持和 AOT 编译 | [graalvm_guide.md](../guide/graalvm_guide.md) | [📖 查看](https://fory.apache.org/docs/guide/graalvm_serialization) |
+| **开发** | 构建和贡献 Fory | [DEVELOPMENT.md](../guide/DEVELOPMENT.md) | [📖 查看](https://fory.apache.org/docs/guide/development) |
### 协议规范
-| 规范 | 描述 | 源文件 | 网站 |
-| ---------------------- | ------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| **跨语言序列化** | 跨语言二进制协议 | [xlang_serialization_spec.md](../specification/xlang_serialization_spec.md) | [📖 查看](https://fory.apache.org/docs/specification/fory_xlang_serialization_spec) |
-| **Java 序列化** | Java 优化协议 | [java_serialization_spec.md](../specification/java_serialization_spec.md) | [📖 查看](https://fory.apache.org/docs/specification/fory_java_serialization_spec) |
-| **行格式** | 基于行的二进制格式 | [row_format_spec.md](../specification/row_format_spec.md) | [📖 查看](https://fory.apache.org/docs/specification/fory_row_format_spec) |
-| **类型映射** | 跨语言类型转换 | [xlang_type_mapping.md](../specification/xlang_type_mapping.md) | [📖 查看](https://fory.apache.org/docs/specification/fory_xlang_serialization_spec) |
+| 规范 | 描述 | 源文件 | 网站 |
+| ---------------- | ------------------ | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **跨语言序列化** | 跨语言二进制协议 | [xlang_serialization_spec.md](../specification/xlang_serialization_spec.md) | [📖 查看](https://fory.apache.org/docs/specification/fory_xlang_serialization_spec) |
+| **Java 序列化** | Java 优化协议 | [java_serialization_spec.md](../specification/java_serialization_spec.md) | [📖 查看](https://fory.apache.org/docs/specification/fory_java_serialization_spec) |
+| **行格式** | 基于行的二进制格式 | [row_format_spec.md](../specification/row_format_spec.md) | [📖 查看](https://fory.apache.org/docs/specification/fory_row_format_spec) |
+| **类型映射** | 跨语言类型转换 | [xlang_type_mapping.md](../specification/xlang_type_mapping.md) | [📖 查看](https://fory.apache.org/docs/specification/fory_xlang_serialization_spec) |
## 兼容性
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/guide/cpp/schema-evolution.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/guide/cpp/schema-evolution.md
index 3f89d97aad..fd8c7bfcad 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/guide/cpp/schema-evolution.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/guide/cpp/schema-evolution.md
@@ -85,7 +85,7 @@ Compatible 模式支持以下 schema 变更：
| 添加新字段 | ✅ | 缺失字段使用默认值 |
| 删除字段 | ✅ | 额外字段被跳过 |
| 重排字段顺序 | ✅ | 按名称匹配字段，而非位置 |
-| 更改可空性 | ✅ | `T` ↔ `std::optional<T>` |
+| 更改可空性 | ✅ | `T` ↔ `std::optional<T>` |
| 更改字段类型 | ❌ | 类型必须兼容 |
| 重命名字段 | ❌ | 字段名必须匹配（区分大小写） |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15.json
new file mode 100644
index 0000000000..5134c6519e
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15.json
@@ -0,0 +1,22 @@
+{
+ "version.label": {
+ "message": "0.15",
+ "description": "The label for version 0.15"
+ },
+ "sidebar.docsSidebar.category.Introduction": {
+ "message": "Apache Fory 介绍",
+ "description": "The label for category Introduction in sidebar docsSidebar"
+ },
+ "sidebar.docsSidebar.category.Start": {
+ "message": "快速开始",
+ "description": "The label for category Start in sidebar docsSidebar"
+ },
+ "sidebar.docsSidebar.category.Schema IDL & Compiler": {
+ "message": "Schema IDL 与编译器",
+ "description": "The label for category Schema IDL & Compiler in sidebar docsSidebar"
+ },
+ "sidebar.docsSidebar.category.Guide": {
+ "message": "用户指南",
+ "description": "The label for category Guide in sidebar docsSidebar"
+ }
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/benchmarks/go/benchmark_report.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/benchmarks/go/benchmark_report.md
index a1c3d635f2..f73aacf0a2 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/benchmarks/go/benchmark_report.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/benchmarks/go/benchmark_report.md
@@ -10,48 +10,48 @@
## 性能摘要
-| 数据类型 | 操作 | Fory (ops/s) | Protobuf (ops/s) | Msgpack (ops/s) | Fory vs PB | Fory vs MP |
-|---------|------|--------------|------------------|-----------------|------------|------------|
-| Struct | 序列化 | 15.16M | 10.23M | 5.41M | 1.48x | 2.80x |
-| Struct | 反序列化 | 12.10M | 11.01M | 3.23M | 1.10x | 3.75x |
-| Structlist | 序列化 | 1.58M | 561K | 299K | 2.82x | 5.28x |
-| Structlist | 反序列化 | 1.10M | 529K | 175K | 2.09x | 6.30x |
-| Sample | 序列化 | 7.28M | 2.72M | 670K | 2.68x | 10.87x |
-| Sample | 反序列化 | 3.79M | 2.37M | 376K | 1.60x | 10.09x |
-| Samplelist | 序列化 | 510K | 141K | 38K | 3.61x | 13.34x |
-| Samplelist | 反序列化 | 236K | 107K | 19K | 2.20x | 12.66x |
-| Mediacontent | 序列化 | 3.72M | 2.12M | 1.29M | 1.75x | 2.88x |
-| Mediacontent | 反序列化 | 2.34M | 1.81M | 698K | 1.30x | 3.35x |
-| Mediacontentlist | 序列化 | 268K | 110K | 72K | 2.44x | 3.72x |
-| Mediacontentlist | 反序列化 | 138K | 87K | 36K | 1.58x | 3.86x |
+| 数据类型 | 操作 | Fory (ops/s) | Protobuf (ops/s) | Msgpack (ops/s) | Fory vs PB | Fory vs MP |
+| ---------------- | -------- | ------------ | ---------------- | --------------- | ---------- | ---------- |
+| Struct | 序列化 | 15.16M | 10.23M | 5.41M | 1.48x | 2.80x |
+| Struct | 反序列化 | 12.10M | 11.01M | 3.23M | 1.10x | 3.75x |
+| Structlist | 序列化 | 1.58M | 561K | 299K | 2.82x | 5.28x |
+| Structlist | 反序列化 | 1.10M | 529K | 175K | 2.09x | 6.30x |
+| Sample | 序列化 | 7.28M | 2.72M | 670K | 2.68x | 10.87x |
+| Sample | 反序列化 | 3.79M | 2.37M | 376K | 1.60x | 10.09x |
+| Samplelist | 序列化 | 510K | 141K | 38K | 3.61x | 13.34x |
+| Samplelist | 反序列化 | 236K | 107K | 19K | 2.20x | 12.66x |
+| Mediacontent | 序列化 | 3.72M | 2.12M | 1.29M | 1.75x | 2.88x |
+| Mediacontent | 反序列化 | 2.34M | 1.81M | 698K | 1.30x | 3.35x |
+| Mediacontentlist | 序列化 | 268K | 110K | 72K | 2.44x | 3.72x |
+| Mediacontentlist | 反序列化 | 138K | 87K | 36K | 1.58x | 3.86x |
## 详细耗时（ns/op）
-| 数据类型 | 操作 | Fory | Protobuf | Msgpack |
-|---------|------|------|----------|---------|
-| Struct | 序列化 | 66.0 | 97.8 | 184.9 |
-| Struct | 反序列化 | 82.7 | 90.9 | 309.6 |
-| Structlist | 序列化 | 632.8 | 1783.0 | 3340.0 |
-| Structlist | 反序列化 | 906.4 | 1891.0 | 5709.0 |
-| Sample | 序列化 | 137.3 | 367.3 | 1492.0 |
-| Sample | 反序列化 | 263.6 | 422.2 | 2661.0 |
-| Samplelist | 序列化 | 1962.0 | 7087.0 | 26169.0 |
-| Samplelist | 反序列化 | 4234.0 | 9321.0 | 53615.0 |
-| Mediacontent | 序列化 | 268.8 | 471.1 | 773.7 |
-| Mediacontent | 反序列化 | 426.9 | 553.1 | 1432.0 |
-| Mediacontentlist | 序列化 | 3736.0 | 9107.0 | 13911.0 |
-| Mediacontentlist | 反序列化 | 7247.0 | 11435.0 | 27975.0 |
+| 数据类型 | 操作 | Fory | Protobuf | Msgpack |
+| ---------------- | -------- | ------ | -------- | ------- |
+| Struct | 序列化 | 66.0 | 97.8 | 184.9 |
+| Struct | 反序列化 | 82.7 | 90.9 | 309.6 |
+| Structlist | 序列化 | 632.8 | 1783.0 | 3340.0 |
+| Structlist | 反序列化 | 906.4 | 1891.0 | 5709.0 |
+| Sample | 序列化 | 137.3 | 367.3 | 1492.0 |
+| Sample | 反序列化 | 263.6 | 422.2 | 2661.0 |
+| Samplelist | 序列化 | 1962.0 | 7087.0 | 26169.0 |
+| Samplelist | 反序列化 | 4234.0 | 9321.0 | 53615.0 |
+| Mediacontent | 序列化 | 268.8 | 471.1 | 773.7 |
+| Mediacontent | 反序列化 | 426.9 | 553.1 | 1432.0 |
+| Mediacontentlist | 序列化 | 3736.0 | 9107.0 | 13911.0 |
+| Mediacontentlist | 反序列化 | 7247.0 | 11435.0 | 27975.0 |
### 序列化后数据大小（字节）
-| 数据类型 | Fory | Protobuf | Msgpack |
-|---------|------|----------|---------|
-| Struct | 58 | 61 | 57 |
-| Sample | 446 | 375 | 524 |
-| MediaContent | 342 | 301 | 400 |
-| StructList | 560 | 1260 | 1146 |
-| SampleList | 7600 | 7560 | 10486 |
-| MediaContentList | 5776 | 6080 | 8006 |
+| 数据类型 | Fory | Protobuf | Msgpack |
+| ---------------- | ---- | -------- | ------- |
+| Struct | 58 | 61 | 57 |
+| Sample | 446 | 375 | 524 |
+| MediaContent | 342 | 301 | 400 |
+| StructList | 560 | 1260 | 1146 |
+| SampleList | 7600 | 7560 | 10486 |
+| MediaContentList | 5776 | 6080 | 8006 |
## 性能图表
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/_category_.json
new file mode 100644
index 0000000000..abf19e9fcb
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/_category_.json
@@ -0,0 +1,6 @@
+{
+ "position": 3,
+ "label": "Schema IDL 与编译器",
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/compiler-guide.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/compiler-guide.md
index 1c8184bfda..0046cbcd3b 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/compiler-guide.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/compiler-guide.md
@@ -19,9 +19,7 @@ license: |
limitations under the License.
---
-> 中文导读：本文档为 Fory 编译器/协议规范文档的中文译稿。为避免改变规范语义，代码片段、类型名、协议字段名保持英文，说明性文字优先翻译为中文。
-
-本指南介绍 Fory IDL 编译器的安装、使用与集成。
+本指南介绍 Fory IDL 编译器的安装、命令行使用方式以及构建系统集成方案。
## 安装
@@ -52,155 +50,153 @@ foryc --scan-generated [OPTIONS]
### 选项
-Compile options:
-
-| Option | Description | Default |
-| ------------------------------------- | ----------------------------------------------------- | ------------------- |
-| `--lang` | Comma-separated target languages | `all` |
-| `--output`, `-o` | Output directory | `./generated` |
-| `--package` | Override package name from Fory IDL file | (from file) |
-| `-I`, `--proto_path`, `--import_path` | Add directory to import search path (can be repeated) | (none) |
-| `--java_out=DST_DIR` | Generate Java code in DST_DIR | (none) |
-| `--python_out=DST_DIR` | Generate Python code in DST_DIR | (none) |
-| `--cpp_out=DST_DIR` | Generate C++ code in DST_DIR | (none) |
-| `--go_out=DST_DIR` | Generate Go code in DST_DIR | (none) |
-| `--rust_out=DST_DIR` | Generate Rust code in DST_DIR | (none) |
-| `--go_nested_type_style` | Go nested type naming: `camelcase` or `underscore` | from schema/default |
-| `--emit-fdl` | Print translated Fory IDL for non-`.fdl` inputs | `false` |
-| `--emit-fdl-path` | Write translated Fory IDL to a file or directory | (stdout) |
-
-Scan options (with `--scan-generated`):
-
-| Option | Description | Default |
-| ------------ | ------------------------------ | ------- |
-| `--root` | Root directory to scan | `.` |
-| `--relative` | Print paths relative to root | `false` |
-| `--delete` | Delete matched generated files | `false` |
-| `--dry-run` | Scan/print only, do not delete | `false` |
-
-### Scan Generated Files
-
-Use `--scan-generated` to find files produced by `foryc`. The scanner walks
-the tree recursively, skips `build/`, `target/`, and hidden directories, and prints
-each generated file as it is found.
+编译选项：
+
+| 选项 | 说明 | 默认值 |
+| ------------------------------------- | ------------------------------------------------ | ------------- |
+| `--lang` | 目标语言列表（逗号分隔） | `all` |
+| `--output`, `-o` | 输出目录 | `./generated` |
+| `--package` | 覆盖 Fory IDL 文件中的 package | （来自文件） |
+| `-I`, `--proto_path`, `--import_path` | 添加 import 搜索路径（可重复） | （无） |
+| `--java_out=DST_DIR` | 将 Java 代码输出到 `DST_DIR` | （无） |
+| `--python_out=DST_DIR` | 将 Python 代码输出到 `DST_DIR` | （无） |
+| `--cpp_out=DST_DIR` | 将 C++ 代码输出到 `DST_DIR` | （无） |
+| `--go_out=DST_DIR` | 将 Go 代码输出到 `DST_DIR` | （无） |
+| `--rust_out=DST_DIR` | 将 Rust 代码输出到 `DST_DIR` | （无） |
+| `--go_nested_type_style` | Go 嵌套类型命名风格：`camelcase` 或 `underscore` | schema/默认值 |
+| `--emit-fdl` | 对非 `.fdl` 输入打印转换后的 Fory IDL | `false` |
+| `--emit-fdl-path` | 将转换后的 Fory IDL 写入文件或目录 | （stdout） |
+
+扫描选项（配合 `--scan-generated`）：
+
+| 选项 | 说明 | 默认值 |
+| ------------ | ---------------------- | ------- |
+| `--root` | 扫描根目录 | `.` |
+| `--relative` | 以相对路径输出 | `false` |
+| `--delete` | 删除匹配到的生成文件 | `false` |
+| `--dry-run` | 仅扫描输出，不执行删除 | `false` |
+
+### 扫描生成文件
+
+使用 `--scan-generated` 可以定位 `foryc` 生成的文件。扫描器会递归遍历目录树，跳过 `build/`、`target/` 和隐藏目录，并输出找到的每个生成文件。
```bash
-# Scan current directory
+# 扫描当前目录
foryc --scan-generated
-# Scan a specific root
+# 扫描指定根目录
foryc --scan-generated --root ./src
-# Print paths relative to the scan root
+# 输出相对路径
foryc --scan-generated --root ./src --relative
-# Delete scanned generated files
+# 删除扫描到的生成文件
foryc --scan-generated --root ./src --delete
-# Dry-run (scan and print only)
+# Dry-run（仅扫描与输出）
foryc --scan-generated --root ./src --dry-run
```
-### Examples
+### 示例
-**Compile for all languages:**
+**为所有语言编译：**
```bash
foryc schema.fdl
```
-**Compile for specific languages:**
+**为指定语言编译：**
```bash
foryc schema.fdl --lang java,python
```
-**Specify output directory:**
+**指定输出目录：**
```bash
foryc schema.fdl --output ./src/generated
```
-**Override package name:**
+**覆盖 package：**
```bash
foryc schema.fdl --package com.myapp.models
```
-**Compile multiple files:**
+**编译多个文件：**
```bash
foryc user.fdl order.fdl product.fdl --output ./generated
```
-**Use import search paths:**
+**使用 import 搜索路径：**
```bash
-# Add a single import path
+# 单个路径
foryc src/main.fdl -I libs/common
-# Add multiple import paths (repeated option)
+# 多个路径（重复参数）
foryc src/main.fdl -I libs/common -I libs/types
-# Add multiple import paths (comma-separated)
+# 多个路径（逗号分隔）
foryc src/main.fdl -I libs/common,libs/types,third_party/
-# Using --proto_path (protoc-compatible alias)
+# --proto_path（protoc 兼容别名）
foryc src/main.fdl --proto_path=libs/common
-# Mix all styles
+# 混合写法
foryc src/main.fdl -I libs/common,libs/types --proto_path third_party/
```
-**Language-specific output directories (protoc-style):**
+**语言定向输出目录（protoc 风格）：**
```bash
-# Generate only Java code to a specific directory
+# 仅生成 Java
foryc schema.fdl --java_out=./src/main/java
-# Generate multiple languages to different directories
+# 多语言分别输出到不同目录
foryc schema.fdl --java_out=./java/gen --python_out=./python/src --go_out=./go/gen
-# Combine with import paths
+# 结合 import 路径
foryc schema.fdl --java_out=./gen/java -I proto/ -I common/
```
-When using `--{lang}_out` options:
+使用 `--{lang}_out` 时：
-- Only the specified languages are generated (not all languages)
-- The compiler writes under the specified directory (language-specific generators may still create package/module subdirectories)
-- This is compatible with protoc-style workflows
+- 只生成显式指定的语言（不会生成全部语言）
+- 输出写入指定目录（语言生成器可能继续按包/模块分层）
+- 兼容 protoc 风格工作流
-**Inspect translated Fory IDL from proto/fbs input:**
+**查看 proto/fbs 输入转换后的 Fory IDL：**
```bash
-# Print translated Fory IDL to stdout
+# 输出到 stdout
foryc schema.proto --emit-fdl
-# Write translated Fory IDL to a directory
+# 输出到目录
foryc schema.fbs --emit-fdl --emit-fdl-path ./translated
```
-## Import Path Resolution
+## Import 路径解析
-When compiling Fory IDL files with imports, the compiler searches for imported files in this order:
+编译含 import 的 Fory IDL 文件时，导入文件按以下顺序查找：
-1. **Relative to the importing file (default)** - The directory containing the file with the import statement is always searched first, automatically. No `-I` flag needed for same-directory imports.
-2. **Each `-I` path in order** - Additional search paths specified on the command line
+1. **相对于导入者文件目录（默认）**：始终优先查找，无需 `-I`
+2. **按顺序遍历每个 `-I` 路径**
-**Same-directory imports work automatically:**
+**同目录 import 可直接生效：**
```protobuf
// main.fdl
-import "common.fdl"; // Found if common.fdl is in the same directory
+import "common.fdl"; // 若 common.fdl 在同目录，将自动找到
```
```bash
-# No -I needed for same-directory imports
+# 同目录导入无需 -I
foryc main.fdl
```
-**Example project structure:**
+**示例目录结构：**
```
project/
@@ -210,7 +206,7 @@ project/
└── common.fdl
```
-**Without `-I` (fails):**
+**不加 `-I`（失败）：**
```bash
$ foryc src/main.fdl
@@ -218,7 +214,7 @@ Import error: Import not found: common.fdl
Searched in: /project/src
```
-**With `-I` (succeeds):**
+**加 `-I`（成功）：**
```bash
$ foryc src/main.fdl -I libs/
@@ -226,17 +222,17 @@ Compiling src/main.fdl...
Resolved 1 import(s)
```
-## Supported Languages
+## 支持语言
-| Language | Flag | Output Extension | Description |
-| -------- | -------- | ---------------- | --------------------------- |
-| Java | `java` | `.java` | POJOs with Fory annotations |
-| Python | `python` | `.py` | Dataclasses with type hints |
-| Go | `go` | `.go` | Structs with struct tags |
-| Rust | `rust` | `.rs` | Structs with derive macros |
-| C++ | `cpp` | `.h` | Structs with FORY macros |
+| 语言 | 标记 | 输出后缀 | 说明 |
+| ------ | -------- | -------- | ---------------------- |
+| Java | `java` | `.java` | 带 Fory 注解的 POJO |
+| Python | `python` | `.py` | 带类型提示的 dataclass |
+| Go | `go` | `.go` | 带 struct tag 的结构体 |
+| Rust | `rust` | `.rs` | 带 derive 宏的结构体 |
+| C++ | `cpp` | `.h` | 带 FORY 宏的结构体 |
-## Output Structure
+## 输出结构
### Java
@@ -251,9 +247,9 @@ generated/
└── ExampleForyRegistration.java
```
-- One file per type (enum or message)
-- Package structure matches Fory IDL package
-- Registration helper class generated
+- 每个类型（enum/message）单独一个文件
+- 包路径与 Fory IDL package 一致
+- 会生成注册辅助类
### Python
@@ -263,9 +259,9 @@ generated/
└── example.py
```
-- Single module with all types
-- Module name derived from package
-- Registration function included
+- 所有类型位于单模块
+- 模块名由 package 派生
+- 包含注册函数
### Go
@@ -276,9 +272,9 @@ generated/
└── example.go
```
-- Single file with all types
-- Directory and package name are derived from `go_package` or the Fory IDL package
-- Registration function included
+- 所有类型在单文件中
+- 目录名与包名来自 `go_package` 或 Fory IDL package
+- 包含注册函数
### Rust
@@ -288,9 +284,9 @@ generated/
└── example.rs
```
-- Single module with all types
-- Module name derived from package
-- Registration function included
+- 所有类型位于单模块
+- 模块名由 package 派生
+- 包含注册函数
### C++
@@ -300,15 +296,15 @@ generated/
└── example.h
```
-- Single header file
-- Namespace matches package (dots to `::`)
-- Header guards and forward declarations
+- 单头文件输出
+- 命名空间与 package 对齐（点号转换为 `::`）
+- 自动包含 header guard 与前向声明
-## Build Integration
+## 构建系统集成
### Maven (Java)
-Add to your `pom.xml`:
+在 `pom.xml` 中添加：
```xml
<build>
@@ -339,7 +335,7 @@ Add to your `pom.xml`:
</build>
```
-Add generated sources:
+添加生成源码目录：
```xml
<build>
@@ -368,7 +364,7 @@ Add generated sources:
### Gradle (Java/Kotlin)
-Add to `build.gradle`:
+在 `build.gradle` 中添加：
```groovy
task generateForyTypes(type: Exec) {
@@ -390,7 +386,7 @@ sourceSets {
### Python (setuptools)
-Add to `setup.py` or `pyproject.toml`:
+在 `setup.py` 或 `pyproject.toml` 中加入生成步骤：
```python
# setup.py
@@ -413,24 +409,24 @@ setup(
)
```
-### Go (go generate)
+### Go (`go generate`)
-Add to your Go file:
+在 Go 文件中添加：
```go
//go:generate foryc ../schema.fdl --lang go --output .
package models
```
-Run:
+执行：
```bash
go generate ./...
```
-### Rust (build.rs)
+### Rust (`build.rs`)
-Add to `build.rs`:
+在 `build.rs` 中添加：
```rust
use std::process::Command;
@@ -451,7 +447,7 @@ fn main() {
### CMake (C++)
-Add to `CMakeLists.txt`:
+在 `CMakeLists.txt` 中添加：
```cmake
find_program(FORY_COMPILER foryc)
@@ -474,7 +470,7 @@ target_include_directories(mylib PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/generated)
### Bazel
-Create a rule in `BUILD`:
+在 `BUILD` 中添加规则：
```python
genrule(
@@ -492,51 +488,51 @@ cc_library(
)
```
-## Error Handling
+## 错误处理
-### Syntax Errors
+### 语法错误
```
Error: Line 5, Column 12: Expected ';' after field declaration
```
-Fix: Check the indicated line for missing semicolons or syntax issues.
+修复方式：检查对应行是否缺少分号或存在语法问题。
-### Duplicate Type Names
+### 类型名重复
```
Error: Duplicate type name: User
```
-Fix: Ensure each enum and message has a unique name within the file.
+修复方式：确保同一文件内每个 enum/message 名称唯一。
-### Duplicate Type IDs
+### 类型 ID 重复
```
Error: Duplicate type ID 100: User and Order
```
-Fix: Assign unique type IDs to each type.
+修复方式：为每个类型分配唯一 ID。
-### Unknown Type References
+### 未知类型引用
```
Error: Unknown type 'Address' in Customer.address
```
-Fix: Define the referenced type before using it, or check for typos.
+修复方式：先定义被引用类型，或检查类型名拼写。
-### Duplicate Field Numbers
+### 字段号重复
```
Error: Duplicate field number 1 in User: name and id
```
-Fix: Assign unique field numbers within each message.
+修复方式：确保同一 message 内字段号唯一。
-## Best Practices
+## 最佳实践
-### Project Structure
+### 项目结构
```
project/
@@ -549,12 +545,12 @@ project/
└── build.gradle
```
-### Version Control
+### 版本控制
-- **Track**: Fory IDL schema files
-- **Ignore**: Generated code (can be regenerated)
+- **纳入版本控制**：Fory IDL schema 文件
+- **忽略生成代码**：可在构建时再生成
-Add to `.gitignore`:
+在 `.gitignore` 中加入：
```
# Generated Fory IDL code
@@ -562,12 +558,12 @@ src/generated/
generated/
```
-### CI/CD Integration
+### CI/CD 集成
-Always regenerate during builds:
+在构建流程中始终重新生成代码：
```yaml
-# GitHub Actions example
+# GitHub Actions 示例
steps:
- name: Install Fory IDL Compiler
run: pip install ./compiler
@@ -579,14 +575,14 @@ steps:
run: ./gradlew build
```
-### Schema Evolution
+### Schema 演进
-When modifying schemas:
+修改 schema 时建议遵循：
-1. **Never reuse field numbers** - Mark as reserved instead
-2. **Never change type IDs** - They're part of the binary format
-3. **Add new fields** - Use new field numbers
-4. **Use `optional`** - For backward compatibility
+1. **不要复用字段号**：删除字段后应保留/预留
+2. **不要改动类型 ID**：类型 ID 属于二进制协议的一部分
+3. **新增字段使用新字段号**
+4. **优先使用 `optional`**：保持向后兼容
```protobuf
message User [id=100] {
@@ -597,7 +593,7 @@ message User [id=100] {
}
```
-## Troubleshooting
+## 故障排查
### Command Not Found
@@ -605,7 +601,7 @@ message User [id=100] {
foryc: command not found
```
-**Solution:** Ensure the compiler is installed and in your PATH:
+**解决：** 确认编译器已安装且在 PATH 中：
```bash
pip install -e ./compiler
@@ -619,15 +615,15 @@ export PATH=$PATH:~/.local/bin
Permission denied: ./generated
```
-**Solution:** Ensure write permissions on the output directory:
+**解决：** 确保输出目录具备写权限：
```bash
chmod -R u+w ./generated
```
-### Import Errors in Generated Code
+### 生成代码 import 错误
-**Java:** Ensure Fory dependency is in your project:
+**Java：** 确保项目包含 Fory 依赖：
```xml
<dependency>
@@ -637,23 +633,23 @@ chmod -R u+w ./generated
</dependency>
```
-**Python:** Ensure pyfory is installed:
+**Python：** 确保安装 `pyfory`：
```bash
pip install pyfory
```
-**Go:** Ensure fory module is available:
+**Go：** 确保可获取 fory 模块：
```bash
go get github.com/apache/fory/go/fory
```
-**Rust:** Ensure fory crate is in `Cargo.toml`:
+**Rust：** 确保 `Cargo.toml` 中包含 fory crate：
```toml
[dependencies]
fory = "x.y.z"
```
-**C++:** Ensure Fory headers are in include path.
+**C++：** 确保编译器 include 路径可找到 Fory 头文件。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/flatbuffers-idl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/flatbuffers-idl.md
index 579ac6c3fc..6a2bfd2885 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/flatbuffers-idl.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/flatbuffers-idl.md
@@ -19,59 +19,49 @@ license: |
limitations under the License.
---
-> 中文导读：本文档为 Fory 编译器/协议规范文档的中文译稿。为避免改变规范语义，代码片段、类型名、协议字段名保持英文，说明性文字优先翻译为中文。
-
本页说明 Apache Fory 如何读取 FlatBuffers schema（`.fbs`）并将其转换为 Fory IR 以生成代码。
## 本页内容
-- When to use FlatBuffers input with Fory
-- Exact FlatBuffers to Fory mapping behavior
-- Supported Fory-specific attributes in `.fbs`
-- Migration notes and generated-code differences
+- 何时应在 Fory 中使用 FlatBuffers 输入
+- FlatBuffers 到 Fory 的精确映射行为
+- `.fbs` 中支持的 Fory 扩展属性
+- 迁移注意事项与生成代码差异
## 为什么使用 Apache Fory
-- Idiomatic generated code: Fory generates language-idiomatic classes/structs
- that can be used directly as domain objects.
-- Java performance: In Java object-serialization workloads, Fory is faster than
- FlatBuffers in Fory benchmarks.
-- Other languages: serialization performance is generally in a similar range.
-- Deserialization in practice: FlatBuffers does not perform native-object deserialization and is
- faster by default, but if your application needs native objects, it requires
- conversion and that conversion step can dominate read cost. In those cases,
- Fory deserialization is often faster end-to-end.
-- Easier APIs: Fory uses direct native objects, so you do not need to
- reverse-build tables or manually manage offsets.
-- Better graph modeling: Shared and circular references are first-class features
- in Fory.
+- **生成代码更符合语言习惯**：Fory 会生成各语言常用风格的类/结构体，可直接作为领域对象使用。
+- **Java 性能更优**：在 Fory 的 Java 对象序列化基准中，Fory 通常快于 FlatBuffers。
+- **其他语言性能相近**：序列化性能通常处于同一量级。
+- **实际反序列化链路更高效**：FlatBuffers 默认并不做原生对象反序列化，因此看起来更快；但当业务需要原生对象时，还需额外转换，这一步往往成为主要开销。在这种场景下，Fory 端到端反序列化通常更快。
+- **API 更简单**：Fory 直接操作原生对象，无需反向构建 table 或手动管理 offset。
+- **对象图建模能力更强**：Fory 原生支持共享引用和循环引用。
## 快速决策指南
-| Situation | Recommended Path |
-| ------------------------------------------------------------------ | ---------------------- |
-| You already have `.fbs` schemas and want Fory runtime/codegen | Use FlatBuffers input |
-| You are starting new schema work and want full Fory syntax control | Use native Fory IDL |
-| You need FlatBuffers wire compatibility at runtime | Keep FlatBuffers stack |
-| You need Fory object-graph semantics (`ref`, weak refs, etc.) | Use Fory |
+| 场景 | 建议路径 |
+| ----------------------------------------------- | ----------------------- |
+| 已有 `.fbs` schema，想接入 Fory 运行时/代码生成 | 使用 FlatBuffers 输入 |
+| 新建 schema，希望完整使用 Fory 语法能力 | 使用原生 Fory IDL |
+| 运行时必须保持 FlatBuffers 线格式兼容 | 继续使用 FlatBuffers 栈 |
+| 需要 Fory 对象图语义（`ref`、弱引用等） | 使用 Fory |
## FlatBuffers 到 Fory 的映射
-### Schema-Level Rules
+### Schema 级规则
-- `namespace` maps to Fory package namespace.
-- `include` entries map to Fory imports.
-- `table` is translated as `evolving=true`.
-- `struct` is translated as `evolving=false`.
-- `root_type` is parsed but ignored by Fory runtime/codegen.
-- `file_identifier` and `file_extension` are parsed but not used by Fory codegen.
+- `namespace` 映射为 Fory package 命名空间。
+- `include` 映射为 Fory import。
+- `table` 会被翻译为 `evolving=true`。
+- `struct` 会被翻译为 `evolving=false`。
+- `root_type` 会被解析，但 Fory 运行时/代码生成不会使用。
+- `file_identifier` 与 `file_extension` 会被解析，但 Fory 代码生成不会使用。
-### Field Numbering
+### 字段编号
-FlatBuffers fields do not have explicit field IDs. Fory assigns field numbers by
-source declaration order, starting at `1`.
+FlatBuffers 字段没有显式 field ID。Fory 会按源码声明顺序分配字段号，从 `1` 开始。
-### Scalar Type Mapping
+### 标量类型映射
| FlatBuffers | Fory Type |
| ----------- | --------- |
@@ -88,14 +78,14 @@ source declaration order, starting at `1`.
| `bool` | `bool` |
| `string` | `string` |
-Vectors (`[T]`) map to Fory lists.
+向量（`[T]`）映射为 Fory 列表类型。
-### Unions
+### 联合类型
-FlatBuffers unions map to Fory unions.
+FlatBuffers union 映射为 Fory union。
-- Case IDs are assigned by declaration order, starting at `1`.
-- Case names are derived from type names using snake_case field naming.
+- case ID 按声明顺序分配，从 `1` 开始。
+- case 名称由类型名转换为 snake_case 字段名。
**FlatBuffers**
@@ -110,7 +100,7 @@ table Container {
}
```
-**Fory shape after translation**
+**转换后的 Fory 结构**
```protobuf
union Payload {
@@ -123,33 +113,31 @@ message Container {
}
```
-### Defaults and Metadata
+### 默认值与元数据
-- FlatBuffers default values are parsed but not applied as Fory runtime defaults.
-- Non-Fory metadata attributes are preserved as generic options in IR and may be
- consumed by downstream tooling.
+- FlatBuffers 默认值会被解析，但不会作为 Fory 运行时默认值生效。
+- 非 Fory 的 metadata 属性会作为通用 option 保留在 IR 中，供下游工具按需消费。
-## Fory-Specific Attributes in FlatBuffers
+## FlatBuffers 中的 Fory 扩展属性
-FlatBuffers metadata attributes use `key:value`. For Fory-specific options, use
-`fory_` (or `fory.`) prefix in `.fbs`; the prefix is removed during parsing.
+FlatBuffers metadata 属性写法为 `key:value`。对于 Fory 扩展选项，在 `.fbs` 中使用 `fory_`（或 `fory.`）前缀；解析时会去掉该前缀。
-### Supported Field Attributes
+### 支持的字段属性
-| FlatBuffers Attribute | Effect in Fory |
-| -------------------------------- | ----------------------------------------------------- |
-| `fory_ref:true` | Enable reference tracking for the field |
-| `fory_nullable:true` | Mark field optional/nullable |
-| `fory_weak_ref:true` | Enable weak reference semantics and implies `ref` |
-| `fory_thread_safe_pointer:false` | For ref fields, select non-thread-safe pointer flavor |
+| FlatBuffers Attribute | 在 Fory 中的效果 |
+| -------------------------------- | --------------------------------- |
+| `fory_ref:true` | 为字段启用引用跟踪 |
+| `fory_nullable:true` | 将字段标记为 optional/nullable |
+| `fory_weak_ref:true` | 启用弱引用语义，并隐含开启 `ref` |
+| `fory_thread_safe_pointer:false` | 对 ref 字段选择非线程安全指针类型 |
-Semantics:
+语义说明：
-- `fory_weak_ref:true` implies `ref`.
-- `fory_thread_safe_pointer` only takes effect when the field is ref-tracked.
-- For list fields, `fory_ref:true` applies to list elements.
+- `fory_weak_ref:true` 隐含 `ref`。
+- `fory_thread_safe_pointer` 仅在字段启用 ref 跟踪时生效。
+- 对列表字段，`fory_ref:true` 作用于列表元素。
-Example:
+示例：
```fbs
table Node {
@@ -159,42 +147,37 @@ table Node {
}
```
-## Generated Code Differences
+## 生成代码差异
-Using `.fbs` as input to Fory still produces normal Fory-generated code, not
-FlatBuffers `ByteBuffer`-style APIs.
+即使用 `.fbs` 作为 Fory 输入，生成的依然是标准 Fory 代码，而不是 FlatBuffers 的 `ByteBuffer` 风格 API。
-- Java: POJOs/records with Fory metadata
-- Python: dataclasses plus registration helpers
-- Go/Rust/C++: native structs and Fory metadata
+- Java：带 Fory 元数据的 POJO/record
+- Python：dataclass 与注册辅助代码
+- Go/Rust/C++：原生结构体与 Fory 元数据
-The serialization format is Fory binary protocol, not FlatBuffers wire format.
+最终序列化格式是 Fory 二进制协议，而不是 FlatBuffers 线格式。
-## Usage
+## 用法
-Compile a FlatBuffers schema directly:
+直接编译 FlatBuffers schema：
```bash
foryc schema.fbs --lang java,python --output ./generated
```
-Inspect translated schema syntax for debugging:
+输出转换后的 Fory schema 语法以便调试：
```bash
foryc schema.fbs --emit-fdl --emit-fdl-path ./translated
```
-## Migration Notes
+## 迁移注意事项
-1. Keep existing `namespace` values stable to keep type registration stable.
-2. Review fields that relied on FlatBuffers default literals and set explicit
- defaults in application code if needed.
-3. Add `fory_ref`/`fory_weak_ref` where object-graph semantics are required.
-4. Validate generated model behavior with roundtrip tests before replacing
- existing serialization paths.
+1. 保持现有 `namespace` 稳定，以保证类型注册稳定。
+2. 检查依赖 FlatBuffers 字面量默认值的字段，并在业务代码中补充显式默认值。
+3. 在需要对象图语义的字段上添加 `fory_ref`/`fory_weak_ref`。
+4. 替换现有序列化路径前，先用 roundtrip 测试验证生成模型行为。
-## Summary
+## 总结
-FlatBuffers input lets you reuse existing `.fbs` schemas while moving to Fory's
-runtime and code generation model. This is useful for incremental migration,
-while preserving schema investment and adopting Fory-native object APIs.
+FlatBuffers 输入模式可让你复用现有 `.fbs` schema，同时迁移到 Fory 运行时与代码生成模型。它适合渐进式迁移场景：既保留既有 schema 投入，又能采用 Fory 原生对象 API。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/generated-code.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/generated-code.md
index ce33bac1e9..cadf241ab8 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/generated-code.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/generated-code.md
@@ -19,20 +19,18 @@ license: |
limitations under the License.
---
-> 中文导读：本文档为 Fory 编译器/协议规范文档的中文译稿。为避免改变规范语义，代码片段、类型名、协议字段名保持英文，说明性文字优先翻译为中文。
+本文档说明各目标语言的代码生成结果与结构。
-本文档说明各目标语言的生成代码结构。
+Fory IDL 生成的类型遵循宿主语言习惯，可直接作为领域对象使用。生成代码同时包含 `to/from bytes` 辅助方法和类型注册辅助逻辑。
-Fory IDL generated types are idiomatic in host languages and can be used directly as domain objects. Generated types also include `to/from bytes` helpers and registration helpers.
+## 参考 Schema
-## Reference Schemas
+下面示例基于两个真实 schema：
-The examples below use two real schemas:
+1. `addressbook.fdl`（显式类型 ID）
+2. `auto_id.fdl`（未显式声明类型 ID）
-1. `addressbook.fdl` (explicit type IDs)
-2. `auto_id.fdl` (no explicit type IDs)
-
-### `addressbook.fdl` (excerpt)
+### `addressbook.fdl`（节选）
```protobuf
package addressbook;
@@ -79,7 +77,7 @@ message AddressBook [id=103] {
}
```
-### `auto_id.fdl` (excerpt)
+### `auto_id.fdl`（节选）
```protobuf
package auto_id;
@@ -114,17 +112,17 @@ union Wrapper {
## Java
-### Output Layout
+### 输出布局
-For `package addressbook`, Java output is generated under:
+对于 `package addressbook`，Java 输出通常位于：
- `<java_out>/addressbook/`
-- Type files: `AddressBook.java`, `Person.java`, `Dog.java`, `Cat.java`, `Animal.java`
-- Registration helper: `AddressbookForyRegistration.java`
+- 类型文件：`AddressBook.java`、`Person.java`、`Dog.java`、`Cat.java`、`Animal.java`
+- 注册辅助类：`AddressbookForyRegistration.java`
-### Type Generation
+### 类型生成
-Messages generate Java classes with `@ForyField`, default constructors, getters/setters, and byte helpers:
+message 会生成带 `@ForyField`、默认构造器、getter/setter 以及字节辅助方法的 Java 类：
```java
public class Person {
@@ -156,7 +154,7 @@ public class Person {
}
```
-Unions generate classes extending `org.apache.fory.type.union.Union`:
+union 会生成继承 `org.apache.fory.type.union.Union` 的类：
```java
public final class Animal extends Union {
@@ -177,9 +175,9 @@ public final class Animal extends Union {
}
```
-### Registration
+### 注册
-Generated registration helper:
+生成的注册辅助方法：
```java
public static void register(Fory fory) {
@@ -194,7 +192,7 @@ public static void register(Fory fory) {
}
```
-For schemas without explicit `[id=...]`, generated registration uses computed numeric IDs (for example from `auto_id.fdl`):
+对于未显式 `[id=...]` 的 schema，注册代码会使用计算得到的数值 ID（例如 `auto_id.fdl`）：
```java
resolver.register(Status.class, 1124725126L);
@@ -204,7 +202,7 @@ resolver.registerUnion(Envelope.Detail.class, 1609214087L, new org.apache.fory.s
resolver.register(Envelope.Payload.class, 2862577837L);
```
-If `option enable_auto_type_id = false;` is set, registration uses namespace and type name:
+若设置 `option enable_auto_type_id = false;`，则按命名空间与类型名注册：
```java
resolver.register(Config.class, "myapp.models", "Config");
@@ -215,7 +213,7 @@ resolver.registerUnion(
new org.apache.fory.serializer.UnionSerializer(fory, Holder.class));
```
-### Usage
+### 使用示例
```java
Person person = new Person();
@@ -228,15 +226,15 @@ Person restored = Person.fromBytes(data);
## Python
-### Output Layout
+### 输出布局
-Python output is one module per schema file, for example:
+Python 每个 schema 文件生成一个模块，例如：
- `<python_out>/addressbook.py`
-### Type Generation
+### 类型生成
-Unions generate a case enum plus a `Union` subclass with typed helpers:
+union 生成 case 枚举与 `Union` 子类，并提供类型化辅助方法：
```python
class AnimalCase(Enum):
@@ -255,7 +253,7 @@ class Animal(Union):
def set_dog(self, v: Dog) -> None: ...
```
-Messages generate `@pyfory.dataclass` types, and nested types stay nested:
+message 生成 `@pyfory.dataclass` 类型，嵌套类型保持嵌套：
```python
@pyfory.dataclass
@@ -279,9 +277,9 @@ class Person:
def from_bytes(cls, data: bytes) -> "Person": ...
```
-### Registration
+### 注册
-Generated registration function:
+生成注册函数：
```python
def register_addressbook_types(fory: pyfory.Fory):
@@ -294,7 +292,7 @@ def register_addressbook_types(fory: pyfory.Fory):
fory.register_type(AddressBook, type_id=103)
```
-For schemas without explicit `[id=...]`, generated registration uses computed numeric IDs:
+未显式 `[id=...]` 时，注册代码使用计算得到的数值 ID：
```python
fory.register_type(Status, type_id=1124725126)
@@ -304,7 +302,7 @@ fory.register_union(Envelope.Detail, type_id=1609214087, serializer=Envelope.Det
fory.register_type(Envelope.Payload, type_id=2862577837)
```
-If `option enable_auto_type_id = false;` is set:
+若设置 `option enable_auto_type_id = false;`：
```python
fory.register_type(Config, namespace="myapp.models", typename="Config")
@@ -316,7 +314,7 @@ fory.register_union(
)
```
-### Usage
+### 使用示例
```python
person = Person(name="Alice", pet=Animal.dog(Dog(name="Rex", bark_volume=10)))
@@ -327,15 +325,15 @@ restored = Person.from_bytes(data)
## Rust
-### Output Layout
+### 输出布局
-Rust output is one module file per schema, for example:
+Rust 每个 schema 生成一个模块文件，例如：
- `<rust_out>/addressbook.rs`
-### Type Generation
+### 类型生成
-Unions map to Rust enums with `#[fory(id = ...)]` case attributes:
+union 映射为 Rust enum，并用 `#[fory(id = ...)]` 声明 case ID：
```rust
#[derive(ForyObject, Debug, Clone, PartialEq)]
@@ -347,7 +345,7 @@ pub enum Animal {
}
```
-Nested types generate nested modules:
+嵌套类型生成嵌套 module：
```rust
pub mod person {
@@ -370,7 +368,7 @@ pub mod person {
}
```
-Messages derive `ForyObject` and include `to_bytes`/`from_bytes` helpers:
+message 会 `derive(ForyObject)` 并生成 `to_bytes`/`from_bytes`：
```rust
#[derive(ForyObject, Debug, Clone, PartialEq, Default)]
@@ -384,9 +382,9 @@ pub struct Person {
}
```
-### Registration
+### 注册
-Generated registration function:
+生成注册函数：
```rust
pub fn register_types(fory: &mut Fory) -> Result<(), fory::Error> {
@@ -401,7 +399,7 @@ pub fn register_types(fory: &mut Fory) -> Result<(), fory::Error> {
}
```
-For schemas without explicit `[id=...]`, generated registration uses computed numeric IDs:
+未显式 `[id=...]` 时，注册代码使用计算得到的数值 ID：
```rust
fory.register::<Status>(1124725126)?;
@@ -411,14 +409,14 @@ fory.register_union::<envelope::Detail>(1609214087)?;
fory.register::<envelope::Payload>(2862577837)?;
```
-If `option enable_auto_type_id = false;` is set:
+若设置 `option enable_auto_type_id = false;`：
```rust
fory.register_by_namespace::<Config>("myapp.models", "Config")?;
fory.register_union_by_namespace::<Holder>("myapp.models", "Holder")?;
```
-### Usage
+### 使用示例
```rust
let person = Person {
@@ -433,15 +431,15 @@ let restored = Person::from_bytes(&bytes)?;
## C++
-### Output Layout
+### 输出布局
-C++ output is one header per schema file, for example:
+C++ 每个 schema 文件生成一个头文件，例如：
- `<cpp_out>/addressbook.h`
-### Type Generation
+### 类型生成
-Messages generate `final` classes with typed accessors and byte helpers:
+message 会生成 `final` 类，并包含类型化访问器与字节辅助方法：
```cpp
class Person final {
@@ -467,7 +465,7 @@ class Person final {
};
```
-Optional message fields generate `has_xxx`, `mutable_xxx`, and `clear_xxx` APIs:
+可选 message 字段会生成 `has_xxx`、`mutable_xxx`、`clear_xxx` API：
```cpp
class Envelope final {
@@ -487,7 +485,7 @@ class Envelope final {
};
```
-Unions generate `std::variant` wrappers:
+union 会生成基于 `std::variant` 的封装：
```cpp
class Animal final {
@@ -517,11 +515,11 @@ class Animal final {
};
```
-Generated headers also include `FORY_UNION`, `FORY_FIELD_CONFIG`, `FORY_ENUM`, and `FORY_STRUCT` macros for serialization metadata.
+生成头文件还会包含 `FORY_UNION`、`FORY_FIELD_CONFIG`、`FORY_ENUM`、`FORY_STRUCT` 等序列化元信息宏。
-### Registration
+### 注册
-Generated registration function:
+生成注册函数：
```cpp
inline void register_types(fory::serialization::BaseFory& fory) {
@@ -535,7 +533,7 @@ inline void register_types(fory::serialization::BaseFory& fory) {
}
```
-For schemas without explicit `[id=...]`, generated registration uses computed numeric IDs:
+未显式 `[id=...]` 时，注册代码使用计算得到的数值 ID：
```cpp
fory.register_enum<Status>(1124725126);
@@ -545,14 +543,14 @@ fory.register_union<Envelope::Detail>(1609214087);
fory.register_struct<Envelope::Payload>(2862577837);
```
-If `option enable_auto_type_id = false;` is set:
+若设置 `option enable_auto_type_id = false;`：
```cpp
fory.register_struct<Config>("myapp.models", "Config");
fory.register_union<Holder>("myapp.models", "Holder");
```
-### Usage
+### 使用示例
```cpp
addressbook::Person person;
@@ -565,17 +563,17 @@ auto restored = addressbook::Person::from_bytes(bytes.value());
## Go
-### Output Layout
+### 输出布局
-Go output path depends on schema options and `--go_out`.
+Go 输出路径受 schema 选项与 `--go_out` 共同影响。
-For `addressbook.fdl`, `go_package` is configured and generated output follows the configured import path/package (for example under your `--go_out` root).
+对于 `addressbook.fdl`，若配置了 `go_package`，生成结果会遵循对应 import path/package（位于 `--go_out` 根目录下）。
-Without `go_package`, output uses the requested `--go_out` directory and package-derived file naming.
+若未配置 `go_package`，则使用 `--go_out` 指定目录，并按 package 规则生成文件名与包名。
-### Type Generation
+### 类型生成
-Nested types use underscore naming by default (`Person_PhoneType`, `Person_PhoneNumber`):
+嵌套类型默认使用下划线命名（`Person_PhoneType`、`Person_PhoneNumber`）：
```go
type Person_PhoneType int32
@@ -592,7 +590,7 @@ type Person_PhoneNumber struct {
}
```
-Messages generate structs with `fory` tags and byte helpers:
+message 会生成带 `fory` tag 的 struct 与字节辅助方法：
```go
type Person struct {
@@ -606,7 +604,7 @@ func (m *Person) ToBytes() ([]byte, error) { ... }
func (m *Person) FromBytes(data []byte) error { ... }
```
-Unions generate typed case structs with constructors/accessors/visitor APIs:
+union 会生成 case struct，并提供构造器/访问器/visitor API：
```go
type AnimalCase uint32
@@ -624,9 +622,9 @@ func (u Animal) AsDog() (*Dog, bool) { ... }
func (u Animal) Visit(visitor AnimalVisitor) error { ... }
```
-### Registration
+### 注册
-Generated registration function:
+生成注册函数：
```go
func RegisterTypes(f *fory.Fory) error {
@@ -646,7 +644,7 @@ func RegisterTypes(f *fory.Fory) error {
}
```
-For schemas without explicit `[id=...]`, generated registration uses computed numeric IDs:
+未显式 `[id=...]` 时，注册代码使用计算得到的数值 ID：
```go
if err := f.RegisterEnum(Status(0), 1124725126); err != nil { ... }
@@ -656,20 +654,20 @@ if err := f.RegisterUnion(Envelope_Detail{}, 1609214087, fory.NewUnionSerializer
if err := f.RegisterStruct(Envelope_Payload{}, 2862577837); err != nil { ... }
```
-If `option enable_auto_type_id = false;` is set:
+若设置 `option enable_auto_type_id = false;`：
```go
if err := f.RegisterNamedStruct(Config{}, "myapp.models.Config"); err != nil { ... }
if err := f.RegisterNamedUnion(Holder{}, "myapp.models.Holder", fory.NewUnionSerializer(...)); err != nil { ... }
```
-`go_nested_type_style` controls nested type naming:
+`go_nested_type_style` 可控制嵌套类型命名风格：
```protobuf
option go_nested_type_style = "camelcase";
```
-### Usage
+### 使用示例
```go
person := &Person{
@@ -687,30 +685,30 @@ if err := restored.FromBytes(data); err != nil {
}
```
-## Cross-Language Notes
+## 跨语言说明
-### Type ID Behavior
+### 类型 ID 行为
-- Explicit `[id=...]` values are used directly in generated registration.
-- When type IDs are omitted, generated code uses computed numeric IDs (see `auto_id.*` outputs).
-- If `option enable_auto_type_id = false;` is set, generated registration uses namespace/type-name APIs instead of numeric IDs.
+- 显式 `[id=...]` 会直接用于生成注册代码。
+- 未声明类型 ID 时，生成代码会使用计算得到的数值 ID（参见 `auto_id.*` 输出）。
+- 若设置 `option enable_auto_type_id = false;`，则生成代码改为使用 namespace/type-name 注册 API，而非数值 ID。
-### Nested Type Shape
+### 嵌套类型形态
-| Language | Nested type form |
-| -------- | ------------------------------ |
-| Java | `Person.PhoneNumber` |
-| Python | `Person.PhoneNumber` |
-| Rust | `person::PhoneNumber` |
-| C++ | `Person::PhoneNumber` |
-| Go | `Person_PhoneNumber` (default) |
+| 语言 | 嵌套类型形式 |
+| ------ | ---------------------------- |
+| Java | `Person.PhoneNumber` |
+| Python | `Person.PhoneNumber` |
+| Rust | `person::PhoneNumber` |
+| C++ | `Person::PhoneNumber` |
+| Go | `Person_PhoneNumber`（默认） |
-### Byte Helper Naming
+### 字节辅助方法命名
-| Language | Helpers |
-| -------- | ------------------------- |
-| Java | `toBytes` / `fromBytes` |
-| Python | `to_bytes` / `from_bytes` |
-| Rust | `to_bytes` / `from_bytes` |
-| C++ | `to_bytes` / `from_bytes` |
-| Go | `ToBytes` / `FromBytes` |
+| 语言 | 辅助方法名称 |
+| ------ | ------------------------- |
+| Java | `toBytes` / `fromBytes` |
+| Python | `to_bytes` / `from_bytes` |
+| Rust | `to_bytes` / `from_bytes` |
+| C++ | `to_bytes` / `from_bytes` |
+| Go | `ToBytes` / `FromBytes` |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/index.md
index 58a4817492..8e26cdd387 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/index.md
@@ -19,15 +19,12 @@ license: |
limitations under the License.
---
-> 中文导读：本文档为 Fory 编译器/协议规范文档的中文译稿。为避免改变规范语义，代码片段、类型名、协议字段名保持英文，说明性文字优先翻译为中文。
-
-Fory IDL is a schema definition language for Apache Fory that enables type-safe
-cross-language serialization. Define your data structures once and generate
-native data structure code for Java, Python, Go, Rust, and C++.
+Fory IDL 是 Apache Fory 的 Schema 定义语言，可实现类型安全的跨语言序列化。
+你只需定义一次数据结构，即可为 Java、Python、Go、Rust 和 C++ 生成原生数据结构代码。
## 示例 Schema
-Fory IDL provides a simple, intuitive syntax for defining cross-language data structures:
+Fory IDL 提供了简单直观的语法来定义跨语言数据结构：
```protobuf
package example;
@@ -73,54 +70,54 @@ union Animal [id=106] {
}
```
-## Why Fory IDL?
+## 为什么选择 Fory IDL？
-### Schema-First Development
+### Schema 优先开发
-Define your data model once in Fory IDL and generate consistent, type-safe code across all languages. This ensures:
+在 Fory IDL 中一次定义数据模型，即可在所有语言中生成一致且类型安全的代码。这样可以确保：
-- **Type Safety**: Catch type errors at compile time, not runtime
-- **Consistency**: All languages use the same field names, types, and structures
-- **Documentation**: Schema serves as living documentation
-- **Evolution**: Managed schema changes across all implementations
+- **类型安全**：在编译期而不是运行期发现类型错误
+- **一致性**：各语言使用相同字段名、类型和结构
+- **文档性**：Schema 本身就是可持续演进的文档
+- **可演进性**：可在所有实现中受控地进行 Schema 变更
-### Fory-Native Features
+### Fory 原生能力
-Unlike generic IDLs, Fory IDL is designed specifically for Fory serialization:
+与通用 IDL 不同，Fory IDL 专门为 Fory 序列化设计：
-- **Reference Tracking**: First-class support for shared and circular references via `ref`
-- **Nullable Fields**: Explicit `optional` modifier for nullable types
-- **Type Registration**: Built-in support for both numeric IDs and namespace-based registration
-- **Native Code Generation**: Generates idiomatic code with Fory annotations/macros
+- **引用跟踪**：通过 `ref` 一等支持共享引用和循环引用
+- **可空字段**：通过 `optional` 显式声明可空类型
+- **类型注册**：内置支持数值 ID 与基于命名空间的注册
+- **原生代码生成**：生成带 Fory 注解/宏的语言惯用代码
-### Low Integration Overhead
+### 集成开销低
-Generated code uses native language constructs:
+生成代码直接使用各语言原生构造：
-- Java: Plain POJOs with `@ForyField` annotations
-- Python: Dataclasses with type hints
-- Go: Structs with struct tags
-- Rust: Structs with `#[derive(ForyObject)]`
-- C++: Structs with `FORY_STRUCT` macros
+- Java：带 `@ForyField` 注解的普通 POJO
+- Python：带类型提示的 dataclass
+- Go：带 struct tag 的结构体
+- Rust：带 `#[derive(ForyObject)]` 的结构体
+- C++：带 `FORY_STRUCT` 宏的结构体
-## Quick Start
+## 快速开始
-### 1. Install the Compiler
+### 1. 安装编译器
```bash
pip install fory-compiler
```
-Or install from source:
+或从源码安装：
```bash
cd compiler
pip install -e .
```
-### 2. Write Your Schema
+### 2. 编写 Schema
-Create `example.fdl`:
+创建 `example.fdl`：
```protobuf
package example;
@@ -132,19 +129,19 @@ message Person {
}
```
-### 3. Generate Code
+### 3. 生成代码
```bash
-# Generate for all languages
+# 为所有语言生成
foryc example.fdl --output ./generated
-# Generate for specific languages
+# 为指定语言生成
foryc example.fdl --lang java,python --output ./generated
```
-### 4. Use Generated Code
+### 4. 使用生成代码
-**Java:**
+**Java：**
```java
Person person = new Person();
@@ -153,34 +150,34 @@ person.setAge(30);
byte[] data = person.toBytes();
```
-**Python:**
+**Python：**
```python
import pyfory
from example import Person
person = Person(name="Alice", age=30)
-data = bytes(person) # or `person.to_bytes()`
+data = bytes(person) # 或 `person.to_bytes()`
```
-## Documentation
+## 文档导航
-| Document | Description |
-| ----------------------------------------------- | ------------------------------------------------- |
-| [Fory IDL Syntax](schema-idl.md) | Complete language syntax and grammar |
-| [Type System](schema-idl.md#type-system) | Primitive types, collections, and type rules |
-| [Compiler Guide](compiler-guide.md) | CLI options and build integration |
-| [Generated Code](generated-code.md) | Output format for each target language |
-| [Protocol Buffers IDL Support](protobuf-idl.md) | Comparison with protobuf and migration guide |
-| [FlatBuffers IDL Support](flatbuffers-idl.md) | FlatBuffers mapping rules and codegen differences |
+| 文档 | 说明 |
+| -------------------------------------------- | ---------------------------------- |
+| [Fory IDL 语法](schema-idl.md) | 完整语言语法与文法 |
+| [类型系统](schema-idl.md#type-system) | 基础类型、集合类型与类型规则 |
+| [编译器指南](compiler-guide.md) | CLI 选项与构建集成 |
+| [生成代码](generated-code.md) | 各目标语言的输出格式 |
+| [Protocol Buffers IDL 支持](protobuf-idl.md) | 与 protobuf 的对比及迁移指南 |
+| [FlatBuffers IDL 支持](flatbuffers-idl.md) | FlatBuffers 映射规则与代码生成差异 |
-## Key Concepts
+## 核心概念
-### Field Modifiers
+### 字段修饰符
-- **`optional`**: Field can be null/None
-- **`ref`**: Enable reference tracking for shared/circular references
-- **`list`**: Field is a list/array (alias: `repeated`)
+- **`optional`**：字段可为 null/None
+- **`ref`**：为共享/循环引用启用引用跟踪
+- **`list`**：字段为列表/数组（别名：`repeated`）
```protobuf
message Example {
@@ -190,26 +187,26 @@ message Example {
}
```
-### Cross-Language Compatibility
+### 跨语言兼容
-Fory IDL types map to native types in each language:
+Fory IDL 类型会映射为各语言原生类型：
-| Fory IDL Type | Java | Python | Go | Rust | C++ |
+| Fory IDL 类型 | Java | Python | Go | Rust | C++ |
| ------------- | --------- | -------------- | -------- | -------- | ------------- |
| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` |
| `string` | `String` | `str` | `string` | `String` | `std::string` |
| `bool` | `boolean` | `bool` | `bool` | `bool` | `bool` |
-See [Type System](schema-idl.md#type-system) for complete mappings.
+完整映射请参见 [类型系统](schema-idl.md#type-system)。
-## Best Practices
+## 最佳实践
-1. **Use meaningful package names**: Group related types together
-2. **Assign type IDs for performance**: Numeric IDs are faster than name-based registration
-3. **Reserve ID ranges**: Leave gaps for future additions (e.g., 100-199 for users, 200-299 for orders)
-4. **Use `optional` explicitly**: Make nullability clear in the schema
-5. **Use `ref` for shared objects**: Enable reference tracking when objects are shared
+1. **使用有意义的 package 名称**：将相关类型分组管理
+2. **为性能分配类型 ID**：数值 ID 比基于名称的注册更高效
+3. **预留 ID 范围**：为后续扩展保留空隙（例如用户 100-199，订单 200-299）
+4. **显式使用 `optional`**：清晰表达可空语义
+5. **共享对象使用 `ref`**：对象可能被多处引用时开启引用跟踪
-## Examples
+## 示例
-See the [examples](https://github.com/apache/fory/tree/main/compiler/examples) directory for complete working examples.
+完整可运行示例见 [examples](https://github.com/apache/fory/tree/main/compiler/examples) 目录。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/protobuf-idl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/protobuf-idl.md
index 2a6865d1e2..d5bb1d8791 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/protobuf-idl.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/protobuf-idl.md
@@ -19,56 +19,50 @@ license: |
limitations under the License.
---
-> 中文导读：本文档为 Fory 编译器/协议规范文档的中文译稿。为避免改变规范语义，代码片段、类型名、协议字段名保持英文，说明性文字优先翻译为中文。
-
本页说明 Apache Fory 如何处理 Protocol Buffers（`.proto`）schema、protobuf 概念如何映射到 Fory，以及 protobuf 专用 Fory 扩展选项的使用方式。
## 本页内容
-- Choosing protobuf vs Fory for your use case
-- Syntax and semantic differences that matter during migration
-- Supported Fory extension options in protobuf files
-- Practical migration patterns from protobuf to Fory
+- 如何在具体场景下选择 protobuf 或 Fory
+- 迁移时需要关注的语法与语义差异
+- `.proto` 文件中支持的 Fory 扩展选项
+- 从 protobuf 迁移到 Fory 的实践路径
## 快速决策指南
-| Situation | Recommended Format |
-| ------------------------------------------------------------- | ------------------ |
-| You are building gRPC APIs and rely on protobuf tooling | Protocol Buffers |
-| You need maximum object-graph performance and ref tracking | Fory |
-| You need circular/shared references in serialized data | Fory |
-| You need strong unknown-field behavior for wire compatibility | Protocol Buffers |
-| You need native structs/classes instead of protobuf wrappers | Fory |
+| 场景 | 建议格式 |
+| ----------------------------------------------------- | ---------------- |
+| 主要构建 gRPC API，依赖 protobuf 工具链 | Protocol Buffers |
+| 需要极致对象图性能与引用跟踪 | Fory |
+| 需要在序列化数据中表达循环/共享引用 | Fory |
+| 需要强 unknown-field 语义保证线格式兼容 | Protocol Buffers |
+| 希望直接使用原生 struct/class，而非 protobuf 包装类型 | Fory |
## Protobuf 与 Fory 对比
-| Aspect | Protocol Buffers | Fory |
-| ------------------ | ----------------------------- | ------------------------------------- |
-| Primary purpose | RPC/message contracts | High-performance object serialization |
-| Encoding model | Tag-length-value | Fory binary protocol |
-| Reference tracking | Not built-in | First-class (`ref`) |
-| Circular refs | Not supported | Supported |
-| Unknown fields | Preserved | Not preserved |
-| Generated types | Protobuf-specific model types | Native language constructs |
-| gRPC ecosystem | Native | In progress (active development) |
+| 维度 | Protocol Buffers | Fory |
+| --------- | --------------------- | ---------------------- |
+| 主要目标 | RPC/消息契约 | 高性能对象序列化 |
+| 编码模型 | Tag-Length-Value | Fory 二进制协议 |
+| 引用跟踪 | 非内建 | 一等支持（`ref`） |
+| 循环引用 | 不支持 | 支持 |
+| 未知字段 | 保留 | 不保留 |
+| 生成类型 | protobuf 专用模型类型 | 语言原生构造 |
+| gRPC 生态 | 原生成熟 | 持续建设中（活跃开发） |
-Fory gRPC support is under active development. For production gRPC
-workflows today, protobuf remains the mature/default choice.
+Fory 的 gRPC 支持仍在持续开发中。当前生产级 gRPC 工作流里，protobuf 仍是更成熟的默认选择。
## 为什么使用 Apache Fory
-- Idiomatic generated code: Fory IDL generates language-idiomatic classes and
- structs that can be used directly as domain objects.
-- Faster serialization: In Fory benchmarks, Fory can be around 10x faster than
- protobuf for object serialization workloads.
-- Better graph modeling: Shared and circular references are first-class features
- instead of application-level ID-link workarounds.
+- **代码更贴近语言习惯**：Fory IDL 生成的类和结构体可直接作为业务领域对象使用。
+- **序列化性能更高**：在 Fory 基准中，Fory 在对象序列化场景中可显著快于 protobuf。
+- **对象图表达更自然**：共享引用和循环引用是内建能力，无需通过业务层 ID 关联绕过。
-See benchmark details under [Performance References](#performance-references).
+性能细节请参见 [性能参考](#性能参考)。
-## Syntax and Semantic Mapping
+## 语法与语义映射
-### Package and File Options
+### Package 与文件级选项
**Protocol Buffers**
@@ -85,10 +79,9 @@ option go_package = "example.com/models";
package example.models;
```
-Fory uses one package namespace for cross-language registration. Language-specific
-package placement is still configurable in code generation.
+Fory 使用统一 package 命名空间做跨语言注册。语言特定的包路径仍可在代码生成阶段单独配置。
-### Message and Enum Definitions
+### Message 与 Enum 定义
**Protocol Buffers**
@@ -126,16 +119,15 @@ enum Status [id=102] {
}
```
-Key differences:
+关键差异：
-- Fory can assign stable type IDs directly (`[id=...]`).
-- Fory uses `list<T>` (with `repeated T` as alias).
-- Enum naming conventions are language-driven instead of protobuf prefix style.
+- Fory 可直接分配稳定类型 ID（`[id=...]`）。
+- Fory 使用 `list<T>`（`repeated T` 为兼容别名）。
+- 枚举命名更偏向语言习惯，而非 protobuf 前缀风格。
-### `oneof` to `union`
+### `oneof` 到 `union`
-Protobuf `oneof` is translated to a nested Fory `union` plus an optional field
-referencing that union.
+protobuf 的 `oneof` 会被翻译为嵌套 Fory `union`，并增加一个可选字段指向该 union。
**Protocol Buffers**
@@ -148,7 +140,7 @@ message Event {
}
```
-**Fory-style shape after translation**
+**转换后的 Fory 结构**
```protobuf
message Event {
@@ -160,42 +152,42 @@ message Event {
}
```
-Notes:
+说明：
-- Union case IDs are derived from the original `oneof` field numbers.
-- The synthetic union field uses the smallest `oneof` case number.
+- union case ID 来自原 `oneof` 字段号。
+- 自动生成的 union 引用字段使用 `oneof` 中最小字段号。
-### Imports and Well-Known Types
+### Import 与 Well-Known Types
-Protobuf imports are supported. Common well-known types map directly:
+支持 protobuf import。常见 well-known types 会直接映射：
- `google.protobuf.Timestamp` -> `timestamp`
- `google.protobuf.Duration` -> `duration`
- `google.protobuf.Any` -> `any`
-## 类型映射 Highlights
-
-| Protobuf Type | Fory Mapping |
-| ---------------------------------------- | ---------------------------------------- |
-| `bool` | `bool` |
-| `int32`, `uint32` | variable-length 32-bit integer kinds |
-| `sint32` | zigzag 32-bit integer |
-| `int64`, `uint64` | variable-length 64-bit integer kinds |
-| `sint64` | zigzag 64-bit integer |
-| `fixed32`, `fixed64` | fixed-width unsigned integer kinds |
-| `sfixed32`, `sfixed64` | fixed-width signed integer kinds |
-| `float`, `double` | `float32`, `float64` |
-| `string`, `bytes` | `string`, `bytes` |
-| `repeated T` | `list<T>` |
-| `map<K, V>` | `map<K, V>` |
-| `optional T` | `optional T` |
-| `oneof` | `union` + optional union reference field |
-| `int64 [(fory).type = "tagged_int64"]` | `tagged_int64` encoding |
-| `uint64 [(fory).type = "tagged_uint64"]` | `tagged_uint64` encoding |
-
-## Fory Extension Options (Protobuf)
-
-Fory-specific options in `.proto` use the `(fory).` prefix.
+## 类型映射要点
+
+| Protobuf Type | Fory 映射 |
+| ---------------------------------------- | ----------------------------- |
+| `bool` | `bool` |
+| `int32`, `uint32` | 可变长 32 位整型家族 |
+| `sint32` | zigzag 32 位整型 |
+| `int64`, `uint64` | 可变长 64 位整型家族 |
+| `sint64` | zigzag 64 位整型 |
+| `fixed32`, `fixed64` | 定长无符号整型家族 |
+| `sfixed32`, `sfixed64` | 定长有符号整型家族 |
+| `float`, `double` | `float32`, `float64` |
+| `string`, `bytes` | `string`, `bytes` |
+| `repeated T` | `list<T>` |
+| `map<K, V>` | `map<K, V>` |
+| `optional T` | `optional T` |
+| `oneof` | `union` + 可选 union 引用字段 |
+| `int64 [(fory).type = "tagged_int64"]` | `tagged_int64` 编码 |
+| `uint64 [(fory).type = "tagged_uint64"]` | `tagged_uint64` 编码 |
+
+## Fory 扩展选项（Protobuf）
+
+`.proto` 文件中的 Fory 专用选项使用 `(fory).` 前缀。
```protobuf
option (fory).enable_auto_type_id = true;
@@ -206,46 +198,46 @@ message TreeNode {
}
```
-### File-Level Options
+### 文件级选项
-| Option | Type | Description |
-| ------------------------------------ | ------ | -------------------------------------------------------------- |
-| `(fory).use_record_for_java_message` | bool | Generate Java records for all messages in this file |
-| `(fory).polymorphism` | bool | Enable polymorphic serialization metadata by default |
-| `(fory).enable_auto_type_id` | bool | Auto-generate type IDs when omitted (compiler default is true) |
-| `(fory).evolving` | bool | Default schema-evolution behavior for messages |
-| `(fory).go_nested_type_style` | string | Go nested naming style: `underscore` (default) or `camelcase` |
+| 选项 | 类型 | 说明 |
+| ------------------------------------ | ------ | --------------------------------------------------- |
+| `(fory).use_record_for_java_message` | bool | 对该文件所有 message 生成 Java record |
+| `(fory).polymorphism` | bool | 默认开启多态序列化元信息 |
+| `(fory).enable_auto_type_id` | bool | 缺失时自动生成类型 ID（编译器默认 true） |
+| `(fory).evolving` | bool | message 的默认 schema 演进行为 |
+| `(fory).go_nested_type_style` | string | Go 嵌套命名风格：`underscore`（默认）或 `camelcase` |
-### Message and Enum Options
+### Message 与 Enum 级选项
-| Option | Applies To | Type | Description |
-| ---------------------------- | ------------- | ------ | ---------------------------------------- |
-| `(fory).id` | message, enum | int | Explicit type ID for registration |
-| `(fory).alias` | message, enum | string | Alternate name used for auto-ID hashing |
-| `(fory).evolving` | message | bool | Override file-level evolution setting |
-| `(fory).use_record_for_java` | message | bool | Generate Java record for this message |
-| `(fory).deprecated` | message, enum | bool | Mark type as deprecated |
-| `(fory).namespace` | message | string | Override default package-based namespace |
+| 选项 | 作用对象 | 类型 | 说明 |
+| ---------------------------- | ------------- | ------ | ----------------------------- |
+| `(fory).id` | message, enum | int | 显式类型 ID（用于注册） |
+| `(fory).alias` | message, enum | string | 自动 ID 哈希使用的别名 |
+| `(fory).evolving` | message | bool | 覆盖文件级演进设置 |
+| `(fory).use_record_for_java` | message | bool | 为该 message 生成 Java record |
+| `(fory).deprecated` | message, enum | bool | 标记类型为弃用 |
+| `(fory).namespace` | message | string | 覆盖默认 package 命名空间 |
-### Field-Level Options
+### 字段级选项
-| Option | Type | Description |
-| ---------------------------- | ------ | ------------------------------------------------------------ |
-| `(fory).ref` | bool | Enable reference tracking for this field |
-| `(fory).nullable` | bool | Treat field as nullable (`optional`) |
-| `(fory).weak_ref` | bool | Generate weak pointer semantics (C++/Rust codegen) |
-| `(fory).thread_safe_pointer` | bool | Rust pointer flavor for ref fields (`Arc` vs `Rc`) |
-| `(fory).deprecated` | bool | Mark field as deprecated |
-| `(fory).type` | string | Primitive override, currently `tagged_int64`/`tagged_uint64` |
+| 选项 | 类型 | 说明 |
+| ---------------------------- | ------ | ----------------------------------------------------- |
+| `(fory).ref` | bool | 为该字段启用引用跟踪 |
+| `(fory).nullable` | bool | 将字段视为可空（`optional`） |
+| `(fory).weak_ref` | bool | 生成弱指针语义（C++/Rust 代码生成） |
+| `(fory).thread_safe_pointer` | bool | ref 字段在 Rust 中的指针类型（`Arc` vs `Rc`） |
+| `(fory).deprecated` | bool | 标记字段为弃用 |
+| `(fory).type` | string | 基础类型覆盖，目前支持 `tagged_int64`/`tagged_uint64` |
-Reference option behavior:
+引用相关行为：
-- `weak_ref = true` implies ref tracking.
-- For `repeated` fields, `(fory).ref = true` applies to list elements.
-- For `map<K, V>` fields, `(fory).ref = true` applies to map values.
-- `weak_ref` and `thread_safe_pointer` are codegen hints for C++/Rust.
+- `weak_ref = true` 隐含开启 ref 跟踪。
+- 对 `repeated` 字段，`(fory).ref = true` 作用于列表元素。
+- 对 `map<K, V>` 字段，`(fory).ref = true` 作用于 map value。
+- `weak_ref` 与 `thread_safe_pointer` 是 C++/Rust 代码生成提示。
-### Option Examples by Shape
+### 典型选项组合示例
```protobuf
message Graph {
@@ -256,12 +248,11 @@ message Graph {
}
```
-## Reference Tracking vs Protobuf IDs
+## 引用跟踪 vs Protobuf ID 关联
-Protobuf itself does not preserve shared/cyclic object graphs. With Fory
-protobuf extensions, you can opt into graph semantics.
+protobuf 本身不保留共享/循环对象图。借助 Fory protobuf 扩展，可以显式启用对象图语义。
-**Without Fory ref options (protobuf-style IDs):**
+**不使用 Fory ref 选项（protobuf 风格 ID 关联）：**
```protobuf
message TreeNode {
@@ -271,7 +262,7 @@ message TreeNode {
}
```
-**With Fory ref options (object graph):**
+**使用 Fory ref 选项（对象图语义）：**
```protobuf
message TreeNode {
@@ -280,37 +271,34 @@ message TreeNode {
}
```
-## Migration Guide: Protobuf to Fory
+## 迁移指南：Protobuf 到 Fory
-### Step 1: Translate Schema Syntax
+### 第 1 步：转换 schema 语法
-- Keep package names stable.
-- Replace `repeated T` with `list<T>` (or keep `repeated` alias).
-- Add explicit `[id=...]` where you need stable numeric registration.
+- 保持 package 名称稳定。
+- 将 `repeated T` 改为 `list<T>`（或保留 `repeated` 别名）。
+- 在需要稳定数值注册的位置添加显式 `[id=...]`。
-### Step 2: Convert `oneof` and Special Types
+### 第 2 步：处理 `oneof` 与特殊类型
-- `oneof` -> `union` + optional union field.
-- Map protobuf well-known types to Fory primitives (`timestamp`, `duration`, `any`).
+- `oneof` -> `union` + 可选 union 字段。
+- 将 protobuf well-known types 映射到 Fory 基础类型（`timestamp`、`duration`、`any`）。
-### Step 3: Replace Protobuf Workarounds with `ref`
+### 第 3 步：用 `ref` 替换 protobuf 的对象图绕过方案
-Where protobuf used manual ID links for object graphs, switch to Fory `ref`
-modifiers (and optional `ref(weak=true)` where needed).
+若 protobuf 里通过手工 ID 关联表达对象图，迁移到 Fory 后应改用 `ref` 修饰符（必要时使用 `ref(weak=true)`）。
-### Step 4: Update Build/Codegen
+### 第 4 步：更新构建与代码生成
-Replace protobuf generation steps with the Fory compiler invocation for target
-languages.
+将 protobuf 代码生成步骤替换为 Fory 编译器针对目标语言的生成命令。
-### Step 5: Run Compatibility Checks
+### 第 5 步：执行兼容性验证
-For staged migrations, keep both formats in parallel and verify payload-level
-parity with integration tests.
+分阶段迁移时，可并行保留两种格式，并通过集成测试验证 payload 级一致性。
-## Coexistence Strategy
+## 共存策略
-You can run protobuf and Fory in parallel during migration:
+迁移期间可以并行运行 protobuf 与 Fory：
```java
public byte[] serialize(Object obj, Format format) {
@@ -321,16 +309,13 @@ public byte[] serialize(Object obj, Format format) {
}
```
-Use translators at service boundaries while internal object-graph heavy paths
-migrate first.
+可在服务边界设置转换层，并优先迁移内部对象图较重的链路。
-## Performance References
+## 性能参考
- Benchmarks: https://fory.apache.org/docs/introduction/benchmark
- Benchmark code: https://github.com/apache/fory/tree/main/benchmarks
-## Summary
+## 总结
-Use protobuf when your primary concern is API contracts and gRPC ecosystem
-integration. Use Fory when object-graph performance, native models, and
-reference semantics are the primary concern.
+当主要关注 API 契约与 gRPC 生态时，建议使用 protobuf。若主要关注对象图性能、原生数据模型与引用语义，建议使用 Fory。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/schema-idl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/schema-idl.md
index ee420bd790..be6d5c6b2a 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/schema-idl.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/compiler/schema-idl.md
@@ -19,37 +19,19 @@ license: |
limitations under the License.
---
-## 中文章节导读
+本文档给出 Fory IDL 的语法与语义参考，覆盖文件结构、类型系统、字段规则、选项与类型注册策略。
-本文描述 Fory IDL 的语法与语义规则，覆盖文件结构、声明、类型定义、字段约束、注解与扩展选项。它是编译器前端解析与代码生成的基础约束文档。
-
-阅读时可重点关注：
-
-1. **文件级结构**：package、option、import 与类型声明顺序。
-2. **类型系统语法**：enum/message/union 及字段声明规则。
-3. **字段标签与属性**：字段 ID、可空、引用、默认值与兼容性约束。
-4. **命名与作用域**：类型可见性、嵌套声明与名称解析。
-5. **与 protobuf/flatbuffers 的映射关系**：迁移与互操作规则。
-
-为保证编译行为一致，语法关键字、示例 schema 与标识符保持英文；说明性段落使用中文。
-
-> 中文导读：本文档为 Fory 编译器/协议规范文档的中文译稿。为避免改变规范语义，代码片段、类型名、协议字段名保持英文，说明性文字优先翻译为中文。
-
-本文档提供 Fory IDL 的语法与语义参考。
-
-For compiler usage and build integration, see
-[Compiler Guide](compiler-guide.md). For protobuf/FlatBuffers frontend mapping
-rules, see [Protocol Buffers IDL Support](protobuf-idl.md) and
-[FlatBuffers IDL Support](flatbuffers-idl.md).
+编译器使用方式与构建集成请参见 [Compiler Guide](compiler-guide.md)。
+protobuf/FlatBuffers 前端映射请参见 [Protocol Buffers IDL Support](protobuf-idl.md) 与 [FlatBuffers IDL Support](flatbuffers-idl.md)。
## 文件结构
-An Fory IDL file typically consists of:
+一个 Fory IDL 文件通常包含：
-1. Optional package declaration
-2. Optional file-level options
-3. Optional import statements
-4. Type definitions (enums, messages, and unions)
+1. 可选 `package` 声明
+2. 可选文件级 `option`
+3. 可选 `import` 语句
+4. 类型定义（`enum`、`message`、`union`）
```protobuf
// Optional package declaration
@@ -70,7 +52,7 @@ union Event [id=103] { ... }
## 注释
-Fory IDL supports both single-line and block comments:
+支持单行注释与块注释：
```protobuf
// This is a single-line comment
@@ -85,51 +67,51 @@ message Example {
}
```
-## Package Declaration
+## Package 声明
-The package declaration defines the namespace for all types in the file.
+`package` 定义文件中所有类型的命名空间。
```protobuf
package com.example.models;
```
-You can optionally specify a package alias used for auto-generated type IDs:
+也可以配置 alias（用于自动类型 ID 计算）：
```protobuf
package com.example.models alias models_v1;
```
-**Rules:**
+规则：
-- Optional but recommended
-- Must appear before any type definitions
-- Only one package declaration per file
-- Used for namespace-based type registration
-- Package alias is used for auto-ID hashing
+- 可选但推荐
+- 必须位于任何类型定义之前
+- 每个文件最多一个 `package`
+- 用于命名空间注册
+- `alias` 会参与 auto-ID 哈希
-**Language Mapping:**
+语言映射：
-| Language | Package Usage |
-| -------- | --------------------------------- |
-| Java | Java package |
-| Python | Module name (dots to underscores) |
-| Go | Package name (last component) |
-| Rust | Module name (dots to underscores) |
-| C++ | Namespace (dots to `::`) |
+| 语言 | package 用法 |
+| ------ | ----------------------- |
+| Java | Java package |
+| Python | 模块名（`.` 转 `_`） |
+| Go | 包名（通常取最后一段） |
+| Rust | 模块名（`.` 转 `_`） |
+| C++ | 命名空间（`.` 转 `::`） |
-## File-Level Options
+## 文件级选项
-Options can be specified at file level to control language-specific code generation.
+文件级选项用于控制语言定制代码生成。
-### Syntax
+### 语法
```protobuf
option option_name = value;
```
-### Java Package Option
+### Java Package 选项
-Override the Java package for generated code:
+通过 `java_package` 覆盖 Java 输出包名：
```protobuf
package payment;
@@ -140,15 +122,15 @@ message Payment {
}
```
-**Effect:**
+效果：
-- Generated Java files will be in `com/mycorp/payment/v1/` directory
-- Java package declaration will be `package com.mycorp.payment.v1;`
-- Type registration still uses the Fory IDL package (`payment`) for cross-language compatibility
+- Java 文件输出到 `com/mycorp/payment/v1/`
+- Java `package` 声明使用该值
+- 跨语言类型注册仍以 Fory package（如 `payment`）为准
-### Go Package Option
+### Go Package 选项
-Specify the Go import path and package name:
+通过 `go_package` 指定 Go import path 与包名：
```protobuf
package payment;
@@ -159,17 +141,11 @@ message Payment {
}
```
-**Format:** `"import/path;package_name"` or just `"import/path"` (last segment used as package name)
-
-**Effect:**
-
-- Generated Go files will have `package paymentv1`
-- The import path can be used in other Go code
-- Type registration still uses the Fory IDL package (`payment`) for cross-language compatibility
+格式：`"import/path;package_name"` 或仅 `"import/path"`（包名取最后一段）。
-### Java Outer Classname Option
+### Java Outer Classname 选项
-Generate all types as inner classes of a single outer wrapper class:
+将多个类型包装到一个外层类：
```protobuf
package payment;
@@ -186,49 +162,11 @@ message Payment {
}
```
-**Effect:**
-
-- Generates a single file `DescriptorProtos.java` instead of separate files
-- All enums and messages become `public static` inner classes
-- The outer class is `public final` with a private constructor
-- Useful for grouping related types together
-
-**Generated structure:**
-
-```java
-public final class DescriptorProtos {
- private DescriptorProtos() {}
-
- public static enum Status {
- UNKNOWN,
- ACTIVE;
- }
-
- public static class Payment {
- private String id;
- private Status status;
- // ...
- }
-}
-```
-
-**Combined with java_package:**
+默认会生成单文件，枚举与消息作为静态内部类型。
-```protobuf
-package payment;
-option java_package = "com.example.proto";
-option java_outer_classname = "PaymentProtos";
+### Java Multiple Files 选项
-message Payment {
- string id = 1;
-}
-```
-
-This generates `com/example/proto/PaymentProtos.java` with all types as inner classes.
-
-### Java Multiple Files Option
-
-Control whether types are generated in separate files or as inner classes:
+控制 Java 是否拆分多文件：
```protobuf
package payment;
@@ -244,1171 +182,556 @@ message Receipt {
}
```
-**Behavior:**
-
-| `java_outer_classname` | `java_multiple_files` | Result |
-| ---------------------- | --------------------- | ------------------------------------------- |
-| Not set | Any | Separate files (one per type) |
-| Set | `false` (default) | Single file with all types as inner classes |
-| Set | `true` | Separate files (overrides outer class) |
+行为：
-**Effect of `java_multiple_files = true`:**
+| `java_outer_classname` | `java_multiple_files` | 结果 |
+| ---------------------- | --------------------- | ---------------- |
+| 未设置 | 任意 | 每个类型一个文件 |
+| 已设置 | `false`（默认） | 单文件 + 内部类 |
+| 已设置 | `true` | 强制拆分为多文件 |
-- Each top-level enum and message gets its own `.java` file
-- Overrides `java_outer_classname` behavior
-- Useful when you want separate files but still specify an outer class name for other purposes
-
-**Example without java_multiple_files (default):**
-
-```protobuf
-option java_outer_classname = "PaymentProtos";
-// Generates: PaymentProtos.java containing Payment and Receipt as inner classes
-```
-
-**Example with java_multiple_files = true:**
-
-```protobuf
-option java_outer_classname = "PaymentProtos";
-option java_multiple_files = true;
-// Generates: Payment.java, Receipt.java (separate files)
-```
-
-### Multiple Options
-
-Multiple options can be specified:
+### 多个选项组合
```protobuf
package payment;
option java_package = "com.mycorp.payment.v1";
option go_package = "github.com/mycorp/apis/gen/payment/v1;paymentv1";
option deprecated = true;
-
-message Payment {
- string id = 1;
-}
```
-### Protobuf Extension Syntax
+### Protobuf 扩展语法说明
-In `.fdl` files, use native Fory IDL syntax only (for example, `[id=100]`, `ref`,
-`optional`, `nullable=true`).
+在 `.fdl` 中请使用 Fory 原生语法（如 `[id=100]`、`ref`、`optional`、`nullable=true`）。
+`(fory).xxx` 形式仅用于 `.proto`（protobuf 前端）。
-Protobuf extension syntax with `(fory).` is for `.proto` files and the protobuf
-frontend only.
+### 选项优先级
-For protobuf extension options, see
-[Protocol Buffers IDL Support](protobuf-idl.md#fory-extension-options-protobuf).
+语言包路径优先级：
-### Option Priority
+1. 命令行覆盖（最高）
+2. 语言选项（`java_package`、`go_package`）
+3. Fory IDL `package`（兜底）
-For language-specific packages:
+### 跨语言类型注册
-1. Command-line package override (highest priority)
-2. Language-specific option (`java_package`, `go_package`)
-3. Fory IDL package declaration (fallback)
-
-**Example:**
-
-```protobuf
-package myapp.models;
-option java_package = "com.example.generated";
-```
+默认情况下，注册名由 `package + type name`（或类型 ID）确定。建议长期保持 `package` 稳定，以避免跨版本注册不一致。
-| Scenario | Java Package Used |
-| ------------------------- | ------------------------- |
-| No override | `com.example.generated` |
-| CLI: `--package=override` | `override` |
-| No java_package option | `myapp.models` (fallback) |
+## Import 语句
-### Cross-Language Type Registration
-
-Language-specific options only affect where code is generated, not the type namespace used for serialization. This ensures cross-language compatibility:
-
-```protobuf
-package myapp.models;
-option java_package = "com.mycorp.generated";
-option go_package = "github.com/mycorp/gen;genmodels";
-
-message User {
- string name = 1;
-}
-```
-
-All languages will register `User` with namespace `myapp.models`, enabling:
-
-- Java serialized data → Go deserialization
-- Go serialized data → Java deserialization
-- Any language combination works seamlessly
-
-## Import Statement
-
-Import statements allow you to use types defined in other Fory IDL files.
-
-### Basic Syntax
+### 基本语法
```protobuf
-import "path/to/file.fdl";
+import "common/types.fdl";
```
-### Multiple Imports
+### 多个导入
```protobuf
import "common/types.fdl";
-import "common/enums.fdl";
-import "models/address.fdl";
+import "domain/user.fdl";
+import "domain/order.fdl";
```
-### Path Resolution
+### 路径解析
-Import paths are resolved relative to the importing file:
+导入解析顺序：
-```
-project/
-├── common/
-│ └── types.fdl
-├── models/
-│ ├── user.fdl # import "../common/types.fdl"
-│ └── order.fdl # import "../common/types.fdl"
-└── main.fdl # import "common/types.fdl"
-```
+1. 导入者文件所在目录
+2. 命令行 `-I/--proto_path/--import_path` 指定目录（按给定顺序）
-**Rules:**
-
-- Import paths are quoted strings (double or single quotes)
-- Paths are resolved relative to the importing file's directory
-- Imported types become available as if defined in the current file
-- Circular imports are detected and reported as errors
-- Transitive imports work (if A imports B and B imports C, A has access to C's types)
-
-### Complete Example
-
-**common/types.fdl:**
+### 完整示例
```protobuf
-package common;
+// src/main.fdl
+package app;
-enum Status [id=100] {
- PENDING = 0;
- ACTIVE = 1;
- COMPLETED = 2;
-}
+import "common.fdl";
+import "models/user.fdl";
-message Address [id=101] {
- string street = 1;
- string city = 2;
- string country = 3;
+message Main {
+ common.Meta meta = 1;
+ models.User user = 2;
}
```
-**models/user.fdl:**
-
-```protobuf
-package models;
-import "../common/types.fdl";
-
-message User [id=200] {
- string id = 1;
- string name = 2;
- Address home_address = 3; // Uses imported type
- Status status = 4; // Uses imported enum
-}
-```
-
-### Unsupported Import Syntax
-
-The following protobuf import modifiers are **not supported**:
-
-```protobuf
-// NOT SUPPORTED - will produce an error
-import public "other.fdl";
-import weak "other.fdl";
-```
+### 不支持的 import 写法
-**`import public`**: Fory IDL uses a simpler import model. All imported types are available to the importing file only. Re-exporting is not supported. Import each file directly where needed.
+- URL 形式（如 `https://...`）
+- 绝对路径依赖（不推荐，会破坏可移植性）
-**`import weak`**: Fory IDL requires all imports to be present at compile time. Optional dependencies are not supported.
+### import 错误
-### Import Errors
+典型错误：
-The compiler reports errors for:
+- 文件不存在
+- 搜索路径未包含依赖目录
+- 同名文件冲突导致解析到错误版本
-- **File not found**: The imported file doesn't exist
-- **Circular import**: A imports B which imports A (directly or indirectly)
-- **Parse errors**: Syntax errors in imported files
-- **Unsupported syntax**: `import public` or `import weak`
+## Enum 定义
-## Enum Definition
-
-Enums define a set of named integer constants.
-
-### Basic Syntax
+### 基本语法
```protobuf
enum Status {
- PENDING = 0;
+ UNKNOWN = 0;
ACTIVE = 1;
- COMPLETED = 2;
+ DISABLED = 2;
}
```
-### With Explicit Type ID
+### 显式类型 ID
```protobuf
-enum Status [id=100] {
- PENDING = 0;
+enum Status [id=101] {
+ UNKNOWN = 0;
ACTIVE = 1;
- COMPLETED = 2;
+ DISABLED = 2;
}
```
-### Reserved Values
-
-Reserve field numbers or names to prevent reuse:
+### 预留值
```protobuf
enum Status {
- reserved 2, 15, 9 to 11, 40 to max; // Reserved numbers
- reserved "OLD_STATUS", "DEPRECATED"; // Reserved names
- PENDING = 0;
- ACTIVE = 1;
- COMPLETED = 3;
-}
-```
-
-### Enum Type Options
-
-Enum-level options are declared inline in `[]` after the enum name:
-
-```protobuf
-enum Status [deprecated=true] {
- PENDING = 0;
+ UNKNOWN = 0;
ACTIVE = 1;
+ reserved 2, 3;
+ reserved 10 to 20;
}
```
-FDL does not support `option ...;` statements inside enum bodies.
-
-**Unsupported:**
-
-- `allow_alias` is **not supported**. Each enum value must have a unique integer.
-
-### Language Mapping
-
-| Language | Implementation |
-| -------- | -------------------------------------- |
-| Java | `enum Status { UNKNOWN, ACTIVE, ... }` |
-| Python | `class Status(IntEnum): UNKNOWN = 0` |
-| Go | `type Status int32` with constants |
-| Rust | `#[repr(i32)] enum Status { Unknown }` |
-| C++ | `enum class Status : int32_t { ... }` |
-
-### Enum Prefix Stripping
-
-When enum values use a protobuf-style prefix (enum name in UPPER_SNAKE_CASE), the compiler automatically strips the prefix for languages with scoped enums:
-
-```protobuf
-// Input with prefix
-enum DeviceTier {
- DEVICE_TIER_UNKNOWN = 0;
- DEVICE_TIER_TIER1 = 1;
- DEVICE_TIER_TIER2 = 2;
-}
-```
-
-**Generated code:**
+### enum 类型选项
-| Language | Output | Style |
-| -------- | ----------------------------------------- | -------------- |
-| Java | `UNKNOWN, TIER1, TIER2` | Scoped enum |
-| Rust | `Unknown, Tier1, Tier2` | Scoped enum |
-| C++ | `UNKNOWN, TIER1, TIER2` | Scoped enum |
-| Python | `UNKNOWN, TIER1, TIER2` | Scoped IntEnum |
-| Go | `DeviceTierUnknown, DeviceTierTier1, ...` | Unscoped const |
+常见：`id`、`alias`、`deprecated`。
-**Note:** The prefix is only stripped if the remainder is a valid identifier. For example, `DEVICE_TIER_1` is kept unchanged because `1` is not a valid identifier name.
+### 语言映射
-**Grammar:**
+- Java：`enum`
+- Python：`IntEnum`
+- Go：`type + const`
+- Rust：`repr(i32)` 枚举
+- C++：`enum class`
-```
-enum_def := 'enum' IDENTIFIER [type_options] '{' enum_body '}'
-type_options := '[' type_option (',' type_option)* ']'
-type_option := IDENTIFIER '=' option_value
-enum_body := (reserved_stmt | enum_value)*
-reserved_stmt := 'reserved' reserved_items ';'
-enum_value := IDENTIFIER '=' INTEGER ';'
-```
-
-**Rules:**
-
-- Enum names must be unique within the file
-- Enum values must have explicit integer assignments
-- Value integers must be unique within the enum (no aliases)
-- Type ID (`[id=100]`) is optional for enums but recommended for cross-language use
-
-**Example with All Features:**
-
-```protobuf
-// HTTP status code categories
-enum HttpCategory [id=200] {
- reserved 10 to 20; // Reserved for future use
- reserved "UNKNOWN"; // Reserved name
- INFORMATIONAL = 1;
- SUCCESS = 2;
- REDIRECTION = 3;
- CLIENT_ERROR = 4;
- SERVER_ERROR = 5;
-}
-```
+### 枚举前缀处理
-## Message Definition
+针对 protobuf 风格 `TYPE_NAME_VALUE`，生成器通常会按语言习惯去除冗余前缀，使 API 更自然。
-Messages define structured data types with typed fields.
+## Message 定义
-### Basic Syntax
+### 基本语法
```protobuf
-message Person {
- string name = 1;
- int32 age = 2;
-}
-```
-
-### With Explicit Type ID
-
-```protobuf
-message Person [id=101] {
+message User {
string name = 1;
int32 age = 2;
}
```
-### Without Explicit Type ID
+### 显式类型 ID
```protobuf
-message Person { // Auto-generated when enable_auto_type_id = true
+message User [id=100] {
string name = 1;
int32 age = 2;
}
```
-### Language Mapping
+### 无显式类型 ID
-| Language | Implementation |
-| -------- | ----------------------------------- |
-| Java | POJO class with getters/setters |
-| Python | `@dataclass` class |
-| Go | Struct with exported fields |
-| Rust | Struct with `#[derive(ForyObject)]` |
-| C++ | Struct with `FORY_STRUCT` macro |
+未声明 `[id=...]` 时，编译器可按配置自动生成类型 ID，或使用 namespace/name 注册。
-Type IDs control cross-language registration for messages, unions, and enums. See
-[Type IDs](#type-ids) for auto-generation, aliases, and collision handling.
+### 语言映射
-### Reserved Fields
+- Java：类 / record（按选项）
+- Python：dataclass
+- Go：struct
+- Rust：struct
+- C++：class/struct + 宏元信息
-Reserve field numbers or names to prevent reuse after removing fields:
+### 预留字段
```protobuf
message User {
- reserved 2, 15, 9 to 11; // Reserved field numbers
- reserved "old_field", "temp"; // Reserved field names
- string id = 1;
- string name = 3;
-}
-```
-
-### Message Type Options
-
-Message-level options are declared inline in `[]` after the message name:
-
-```protobuf
-message User [deprecated=true] {
- string id = 1;
- string name = 2;
+ string name = 1;
+ reserved 2, 3;
+ reserved 10 to 20;
}
```
-FDL does not support `option ...;` statements inside message or enum bodies.
-
-**Grammar:**
-
-```
-message_def := 'message' IDENTIFIER [type_options] '{' message_body '}'
-type_options := '[' type_option (',' type_option)* ']'
-type_option := IDENTIFIER '=' option_value
-message_body := (reserved_stmt | nested_type | field_def)*
-nested_type := enum_def | message_def | union_def
-```
-
-**Rules:**
-
-- Type IDs follow the rules in [Type IDs](#type-ids).
+### message 类型选项
-## Nested Types
+常见选项：`id`、`alias`、`evolving`、`deprecated`、`namespace`、`use_record_for_java`。
-Messages can contain nested message, enum, and union definitions. This is useful for defining types that are closely related to their parent message.
+## 嵌套类型
-### Nested Messages
+### 嵌套 message
```protobuf
-message SearchResponse {
- message Result {
- string url = 1;
- string title = 2;
- list<string> snippets = 3;
- }
- list<Result> results = 1;
-}
-```
-
-### Nested Enums
-
-```protobuf
-message Container {
- enum Status {
- STATUS_UNKNOWN = 0;
- STATUS_ACTIVE = 1;
- STATUS_INACTIVE = 2;
+message Person {
+ message PhoneNumber {
+ string number = 1;
}
- Status status = 1;
+ PhoneNumber phone = 1;
}
```
-### Qualified Type Names
-
-Nested types can be referenced from other messages using qualified names (Parent.Child):
+### 嵌套 enum
```protobuf
-message SearchResponse {
- message Result {
- string url = 1;
- string title = 2;
+message Person {
+ enum PhoneType {
+ MOBILE = 0;
+ HOME = 1;
}
-}
-
-message SearchResultCache {
- // Reference nested type with qualified name
- SearchResponse.Result cached_result = 1;
- list<SearchResponse.Result> all_results = 2;
+ PhoneType type = 1;
}
```
-### Deeply Nested Types
+### 限定类型名
-Nesting can be multiple levels deep:
+可使用完整限定名引用嵌套类型，例如 `Person.PhoneNumber`。
-```protobuf
-message Outer {
- message Middle {
- message Inner {
- string value = 1;
- }
- Inner inner = 1;
- }
- Middle middle = 1;
-}
-
-message OtherMessage {
- // Reference deeply nested type
- Outer.Middle.Inner deep_ref = 1;
-}
-```
+### 深层嵌套类型
-### Language-Specific Generation
+支持多层嵌套，但建议控制层级，避免可读性下降。
-| Language | Nested Type Generation |
-| -------- | --------------------------------------------------------------------------------- |
-| Java | Static inner classes (`SearchResponse.Result`) |
-| Python | Nested classes within dataclass |
-| Go | Flat structs with underscore (`SearchResponse_Result`, configurable to camelcase) |
-| Rust | Nested modules (`search_response::Result`) |
-| C++ | Nested classes (`SearchResponse::Result`) |
+### 各语言生成形态
-**Note:** Go defaults to underscore-separated nested names; set `option go_nested_type_style = "camelcase";` to use concatenated names. Rust emits nested modules for nested types.
+| 语言 | 嵌套类型形态 |
+| ------ | --------------------- |
+| Java | `Outer.Inner` |
+| Python | `Outer.Inner` |
+| Rust | `outer::Inner` |
+| C++ | `Outer::Inner` |
+| Go | `Outer_Inner`（默认） |
-### Nested Type Rules
+### 嵌套规则
-- Nested type names must be unique within their parent message
-- Nested types can have their own type IDs
-- Numeric type IDs must be globally unique (including nested types); see [Type IDs](#type-ids)
- for auto-generation and collision handling
-- Within a message, you can reference nested types by simple name
-- From outside, use the qualified name (Parent.Child)
+- 嵌套类型名在其父作用域内必须唯一
+- 可被同文件后续类型引用
+- 可通过 import + 限定名跨文件引用
-## Union Definition
+## Union 定义
-Unions define a value that can hold exactly one of several case types.
-
-### Basic Syntax
+### 基本语法
```protobuf
-union Animal [id=106] {
+union Animal {
Dog dog = 1;
Cat cat = 2;
}
```
-### Using a Union in a Message
+### 在 message 中使用 union
```protobuf
-message Person [id=100] {
+message Person {
Animal pet = 1;
- optional Animal favorite_pet = 2;
}
```
-### Rules
-
-- Case IDs must be unique within the union
-- Cases cannot be `optional` or `ref`
-- Union cases do not support field options
-- Case types can be primitives, enums, messages, or other named types
-- Union type IDs follow the rules in [Type IDs](#type-ids).
-
-**Grammar:**
+### 规则
-```
-union_def := 'union' IDENTIFIER [type_options] '{' union_field* '}'
-union_field := field_type IDENTIFIER '=' INTEGER ';'
-```
+- case 字段号必须唯一
+- case 类型通常为消息类型或可序列化复合类型
+- 各语言会生成带 case 判别和访问器的 union 表达
-## Field Definition
+## 字段定义
-Fields define the properties of a message.
-
-### Basic Syntax
+### 基本语法
```protobuf
-field_type field_name = field_number;
+string name = 1;
```
-### With Modifiers
+### 带修饰符语法
```protobuf
-optional list<string> tags = 1; // Nullable list
-list<optional string> tags = 2; // Elements may be null
-ref list<Node> nodes = 3; // Collection tracked as a reference
-list<ref Node> nodes = 4; // Elements tracked as references
+optional string nickname = 2;
+ref Node parent = 3;
+list<int32> scores = 4;
```
-**Grammar:**
-
-```
-field_def := [modifiers] field_type IDENTIFIER '=' INTEGER ';'
-modifiers := { 'optional' | 'ref' }
-field_type := primitive_type | named_type | list_type | map_type
-list_type := 'list' '<' { 'optional' | 'ref' } field_type '>'
-```
-
-Modifiers apply to the field/collection. Use `list<...>` to describe element
-modifiers. `repeated` is accepted as an alias for `list`.
-
-### Field Modifiers
+### 字段修饰符
#### `optional`
-Marks the field as nullable:
+声明字段可为空（null/None）：
```protobuf
message User {
- string name = 1; // Required, non-null
- optional string email = 2; // Nullable
+ optional string email = 1;
}
```
-**Generated Code:**
-
-| Language | Non-optional | Optional |
-| -------- | ------------------ | ----------------------------------------------- |
-| Java | `String name` | `String email` with `@ForyField(nullable=true)` |
-| Python | `name: str` | `name: Optional[str]` |
-| Go | `Name string` | `Name *string` |
-| Rust | `name: String` | `name: Option<String>` |
-| C++ | `std::string name` | `std::optional<std::string> name` |
-
-**Default Values:**
-
-| Type | Default Value |
-| ------------------ | ------------------- |
-| Non-optional types | Language default |
-| Optional types | `null`/`None`/`nil` |
+建议在跨语言场景显式使用，以避免默认值差异。
#### `ref`
-Enables reference tracking for shared/circular references:
+开启引用跟踪，用于共享对象与循环结构：
```protobuf
message Node {
- string value = 1;
- ref Node parent = 2; // Can point to shared object
+ string name = 1;
+ ref Node parent = 2;
list<ref Node> children = 3;
}
```
-**Use Cases:**
-
-- Shared objects (same object referenced multiple times)
-- Circular references (object graphs with cycles)
-- Tree structures with parent pointers
-
-**Generated Code:**
-
-| Language | Without `ref` | With `ref` |
-| -------- | -------------- | ----------------------------------------- |
-| Java | `Node parent` | `Node parent` with `@ForyField(ref=true)` |
-| Python | `parent: Node` | `parent: Node = pyfory.field(ref=True)` |
-| Go | `Parent Node` | `Parent *Node` with `fory:"ref"` |
-| Rust | `parent: Node` | `parent: Arc<Node>` |
-| C++ | `Node parent` | `std::shared_ptr<Node> parent` |
-
-Rust uses `Arc` by default; use `ref(thread_safe=false)` or `ref(weak=true)`
-to customize pointer types. For protobuf option syntax, see
-[Protocol Buffers IDL Support](protobuf-idl.md#field-level-options).
+当运行时全局 ref tracking 开启时，字段级 `ref` 才会生效。
#### `list`
-Marks the field as a list/array:
+列表字段（`repeated` 为等价别名）：
```protobuf
-message Document {
+message Group {
list<string> tags = 1;
- list<User> authors = 2;
}
```
-**Generated Code:**
-
-| Language | Type |
-| -------- | -------------------------- |
-| Java | `List<String>` |
-| Python | `List[str]` |
-| Go | `[]string` |
-| Rust | `Vec<String>` |
-| C++ | `std::vector<std::string>` |
+### 组合修饰符
-### Combining Modifiers
-
-Modifiers can be combined:
-
-```fdl
-message Example {
- optional list<string> tags = 1; // Nullable list
- list<optional string> aliases = 2; // Elements may be null
- ref list<Node> nodes = 3; // Collection tracked as a reference
- list<ref Node> children = 4; // Elements tracked as references
- optional ref User owner = 5; // Nullable tracked reference
-}
-```
-
-Modifiers before `list` apply to the field/collection. Modifiers after `list`
-apply to elements. `repeated` is accepted as an alias for `list`.
-
-**List modifier mapping:**
-
-| Fory IDL | Java | Python | Go | Rust | C++ |
-| ----------------------- | ---------------------------------------------- | --------------------------------------- | ----------------------- | --------------------- | ----------------------------------------- |
-| `optional list<string>` | `List<String>` + `@ForyField(nullable = true)` | `Optional[List[str]]` | `[]string` + `nullable` | `Option<Vec<String>>` | `std::optional<std::vector<std::string>>` |
-| `list<optional string>` | `List<String>` (nullable elements) | `List[Optional[str]]` | `[]*string` | `Vec<Option<String>>` | `std::vector<std::optional<std::string>>` |
-| `ref list<User>` | `List<User>` + `@ForyField(ref = true)` | `List[User]` + `pyfory.field(ref=True)` | `[]User` + `ref` | `Arc<Vec<User>>` | `std::shared_ptr<std::vector<User>>` |
-| `list<ref User>` | `List<User>` | `List[User]` | `[]*User` + `ref=false` | `Vec<Arc<User>>` | `std::vector<std::shared_ptr<User>>` |
-
-Use `ref(thread_safe=false)` in Fory IDL (or `[(fory).thread_safe_pointer = false]` in protobuf)
-to generate `Rc` instead of `Arc` in Rust.
-
-## Field Numbers
-
-Each field must have a unique positive integer identifier:
+可组合使用：
```protobuf
-message Example {
- string first = 1;
- string second = 2;
- string third = 3;
+message Graph {
+ optional ref Node root = 1;
+ list<ref Node> nodes = 2;
}
```
-**Rules and best practices:**
+## 字段号
-- Numbers must be unique within a message.
-- Numbers must be positive integers.
-- Gaps are allowed and are useful when fields are removed.
-- Prefer sequential numbering from `1`.
-- Never reuse a removed field number for a different field.
+字段号规则：
-## Type System
+- 同一 message 内必须唯一
+- 必须为正整数
+- 不应复用已删除字段号（建议使用 `reserved`）
+- 建议预留编号区间以便演进
-Fory IDL provides a cross-language type system for primitives, named types, and
-collections. Field modifiers (`optional`, `list`, `ref`) control nullability,
-collection behavior, and reference tracking (see
-[Field Modifiers](#field-modifiers)).
+## Type System {#type-system}
+
+Fory IDL 类型系统包括基础类型、命名类型和集合类型。
### Primitive Types
-| Type | Description | Size |
-| --------------- | ----------------------------------------- | -------- |
-| `bool` | Boolean value | 1 byte |
-| `int8` | Signed 8-bit integer | 1 byte |
-| `int16` | Signed 16-bit integer | 2 bytes |
-| `int32` | Signed 32-bit integer (varint encoding) | 4 bytes |
-| `int64` | Signed 64-bit integer (varint encoding) | 8 bytes |
-| `uint8` | Unsigned 8-bit integer | 1 byte |
-| `uint16` | Unsigned 16-bit integer | 2 bytes |
-| `uint32` | Unsigned 32-bit integer (varint encoding) | 4 bytes |
-| `uint64` | Unsigned 64-bit integer (varint encoding) | 8 bytes |
-| `fixed_int32` | Signed 32-bit integer (fixed encoding) | 4 bytes |
-| `fixed_int64` | Signed 64-bit integer (fixed encoding) | 8 bytes |
-| `fixed_uint32` | Unsigned 32-bit integer (fixed encoding) | 4 bytes |
-| `fixed_uint64` | Unsigned 64-bit integer (fixed encoding) | 8 bytes |
-| `tagged_int64` | Signed 64-bit integer (tagged encoding) | 8 bytes |
-| `tagged_uint64` | Unsigned 64-bit integer (tagged encoding) | 8 bytes |
-| `float32` | 32-bit floating point | 4 bytes |
-| `float64` | 64-bit floating point | 8 bytes |
-| `string` | UTF-8 string | Variable |
-| `bytes` | Binary data | Variable |
-| `date` | Calendar date | Variable |
-| `timestamp` | Date and time with timezone | Variable |
-| `duration` | Duration | Variable |
-| `decimal` | Decimal value | Variable |
-| `any` | Dynamic value (runtime type) | Variable |
+| 类型族 | 示例 |
+| -------- | --------------------------------- |
+| 布尔 | `bool` |
+| 整数 | `int8/int16/int32/int64`、`uint*` |
+| 浮点 | `float32`、`float64` |
+| 字符串 | `string` |
+| 字节数组 | `bytes` |
+| 时间 | `date`、`timestamp`、`duration` |
+| 动态类型 | `any` |
#### Boolean
-| Language | Type | Notes |
-| -------- | --------------------- | ------------------ |
-| Java | `boolean` / `Boolean` | Primitive or boxed |
-| Python | `bool` | |
-| Go | `bool` | |
-| Rust | `bool` | |
-| C++ | `bool` | |
+`bool` 表示布尔值。
#### Integer Types
-Fory IDL provides fixed-width signed integers (varint encoding for 32/64-bit by default):
-
-| Fory IDL Type | Size | Range |
-| ------------- | ------ | ----------------- |
-| `int8` | 8-bit | -128 to 127 |
-| `int16` | 16-bit | -32,768 to 32,767 |
-| `int32` | 32-bit | -2^31 to 2^31 - 1 |
-| `int64` | 64-bit | -2^63 to 2^63 - 1 |
-
-**Language Mapping (Signed):**
-
-| Fory IDL | Java | Python | Go | Rust | C++ |
-| -------- | ------- | -------------- | ------- | ----- | --------- |
-| `int8` | `byte` | `pyfory.int8` | `int8` | `i8` | `int8_t` |
-| `int16` | `short` | `pyfory.int16` | `int16` | `i16` | `int16_t` |
-| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` |
-| `int64` | `long` | `pyfory.int64` | `int64` | `i64` | `int64_t` |
-
-Fory IDL provides fixed-width unsigned integers (varint encoding for 32/64-bit by default):
-
-| Fory IDL | Size | Range |
-| -------- | ------ | ------------- |
-| `uint8` | 8-bit | 0 to 255 |
-| `uint16` | 16-bit | 0 to 65,535 |
-| `uint32` | 32-bit | 0 to 2^32 - 1 |
-| `uint64` | 64-bit | 0 to 2^64 - 1 |
-
-**Language Mapping (Unsigned):**
-
-| Fory IDL | Java | Python | Go | Rust | C++ |
-| -------- | ------- | --------------- | -------- | ----- | ---------- |
-| `uint8` | `short` | `pyfory.uint8` | `uint8` | `u8` | `uint8_t` |
-| `uint16` | `int` | `pyfory.uint16` | `uint16` | `u16` | `uint16_t` |
-| `uint32` | `long` | `pyfory.uint32` | `uint32` | `u32` | `uint32_t` |
-| `uint64` | `long` | `pyfory.uint64` | `uint64` | `u64` | `uint64_t` |
+支持有符号/无符号与不同位宽。跨语言场景建议明确编码策略并保持字段语义稳定。
#### Integer Encoding Variants
-For 32/64-bit integers, Fory IDL uses varint encoding by default. Use explicit types when
-you need fixed-width or tagged encoding:
+常见编码：
-| Fory IDL Type | Encoding | Notes |
-| --------------- | -------- | ------------------------ |
-| `fixed_int32` | fixed | Signed 32-bit |
-| `fixed_int64` | fixed | Signed 64-bit |
-| `fixed_uint32` | fixed | Unsigned 32-bit |
-| `fixed_uint64` | fixed | Unsigned 64-bit |
-| `tagged_int64` | tagged | Signed 64-bit (hybrid) |
-| `tagged_uint64` | tagged | Unsigned 64-bit (hybrid) |
+- `varint`：小值更省空间
+- `fixed`：固定长度，性能稳定
+- `tagged`：混合编码（特定类型可用）
#### Floating-Point Types
-| Fory IDL Type | Size | Precision |
-| ------------- | ------ | ------------- |
-| `float32` | 32-bit | ~7 digits |
-| `float64` | 64-bit | ~15-16 digits |
-
-**Language Mapping:**
-
-| Fory IDL | Java | Python | Go | Rust | C++ |
-| --------- | -------- | ---------------- | --------- | ----- | -------- |
-| `float32` | `float` | `pyfory.float32` | `float32` | `f32` | `float` |
-| `float64` | `double` | `pyfory.float64` | `float64` | `f64` | `double` |
+- `float32`
+- `float64`
#### String Type
-| Language | Type | Notes |
-| -------- | ------------- | --------------------- |
-| Java | `String` | Immutable |
-| Python | `str` | |
-| Go | `string` | Immutable |
-| Rust | `String` | Owned, heap-allocated |
-| C++ | `std::string` | |
+`string` 使用 UTF-8 文本语义。
#### Bytes Type
-| Language | Type | Notes |
-| -------- | ---------------------- | --------- |
-| Java | `byte[]` | |
-| Python | `bytes` | Immutable |
-| Go | `[]byte` | |
-| Rust | `Vec<u8>` | |
-| C++ | `std::vector<uint8_t>` | |
+`bytes` 用于原始二进制载荷。
#### Temporal Types
##### Date
-| Language | Type | Notes |
-| -------- | --------------------------- | ----------------------- |
-| Java | `java.time.LocalDate` | |
-| Python | `datetime.date` | |
-| Go | `time.Time` | Time portion ignored |
-| Rust | `chrono::NaiveDate` | Requires `chrono` crate |
-| C++ | `fory::serialization::Date` | |
+`date` 表示日期（不含时区时间部分）。
##### Timestamp
-| Language | Type | Notes |
-| -------- | -------------------------------- | ----------------------- |
-| Java | `java.time.Instant` | UTC-based |
-| Python | `datetime.datetime` | |
-| Go | `time.Time` | |
-| Rust | `chrono::NaiveDateTime` | Requires `chrono` crate |
-| C++ | `fory::serialization::Timestamp` | |
+`timestamp` 表示时间点（跨语言应统一时间语义与精度预期）。
#### Any
-| Language | Type | Notes |
-| -------- | -------------- | -------------------- |
-| Java | `Object` | Runtime type written |
-| Python | `Any` | Runtime type written |
-| Go | `any` | Runtime type written |
-| Rust | `Box<dyn Any>` | Runtime type written |
-| C++ | `std::any` | Runtime type written |
-
-**Example:**
-
-```protobuf
-enum EventType [id=120] {
- CREATED = 0;
- DELETED = 1;
-}
-
-message UserCreated [id=121] {
- string user_id = 1;
-}
-
-message Envelope [id=122] {
- EventType type = 1;
- any payload = 2;
-}
-```
-
-**Generated Code (`Envelope.payload`):**
-
-| Language | Generated Field Type |
-| -------- | ----------------------- |
-| Java | `Object payload` |
-| Python | `payload: Any` |
-| Go | `Payload any` |
-| Rust | `payload: Box<dyn Any>` |
-| C++ | `std::any payload` |
-
-**Notes:**
-
-- `any` always writes a null flag (same as `nullable`) because values may be empty.
-- Allowed runtime values are limited to `bool`, `string`, `enum`, `message`, and `union`.
- Other primitives (numeric, bytes, date/time) and list/map are not supported; wrap them in a
- message or use explicit fields instead.
-- `ref` is not allowed on `any` fields (including list/map values). Wrap `any` in a message
- if you need reference tracking.
-- The runtime type must be registered in the target language schema/IDL registration; unknown
- types fail to deserialize.
+`any` 允许存储动态类型值。使用 `any` 时建议配合清晰的业务约束，避免滥用导致模型不稳定。
### Named Types
-Reference other messages, enums, or unions by name:
+命名类型包括：
-```protobuf
-enum Status { ... }
-message User { ... }
+- `enum`
+- `message`
+- `union`
-message Order {
- User customer = 1; // Reference to User message
- Status status = 2; // Reference to Status enum
-}
-```
+支持跨文件 import 和限定名引用。
### Collection Types
#### List (`list`)
-Use the `list<...>` type for list fields. `repeated` is accepted as an alias. See [Field Modifiers](#field-modifiers) for
-modifier combinations and language mapping.
+```protobuf
+list<T>
+```
-Nested collection types are not supported. Use a message wrapper if you need
-`list<list<...>>`, `list<map<...>>`, or `map<..., list<...>>`.
+等价别名：`repeated T`。
#### Map
-Maps with typed keys and values:
-
```protobuf
-message Config {
- map<string, string> properties = 1;
- map<string, int32> counts = 2;
- map<int32, User> users = 3;
-}
+map<K, V>
```
-**Language Mapping:**
-
-| Fory IDL | Java | Python | Go | Rust | C++ |
-| -------------------- | ---------------------- | ----------------- | ------------------ | ----------------------- | -------------------------------- |
-| `map<string, int32>` | `Map<String, Integer>` | `Dict[str, int]` | `map[string]int32` | `HashMap<String, i32>` | `std::map<std::string, int32_t>` |
-| `map<string, User>` | `Map<String, User>` | `Dict[str, User]` | `map[string]User` | `HashMap<String, User>` | `std::map<std::string, User>` |
-
-**Key Type Restrictions:**
+约束：
-- `string` (most common)
-- Integer types (`int8`, `int16`, `int32`, `int64`)
-- `bool`
-
-Avoid using messages or complex types as keys.
+- `K` 一般应为可稳定比较的标量类型
+- `V` 可为任意支持类型
### Type Compatibility Matrix
-This matrix shows which type conversions are safe across languages:
-
-| From -> To | bool | int8 | int16 | int32 | int64 | float32 | float64 | string |
-| ---------- | ---- | ---- | ----- | ----- | ----- | ------- | ------- | ------ |
-| bool | Y | Y | Y | Y | Y | - | - | - |
-| int8 | - | Y | Y | Y | Y | Y | Y | - |
-| int16 | - | - | Y | Y | Y | Y | Y | - |
-| int32 | - | - | - | Y | Y | - | Y | - |
-| int64 | - | - | - | - | Y | - | - | - |
-| float32 | - | - | - | - | - | Y | Y | - |
-| float64 | - | - | - | - | - | - | Y | - |
-| string | - | - | - | - | - | - | - | Y |
+跨语言建议：
-Y = Safe conversion, - = Not recommended
+- 使用各语言都稳定支持的公共子集
+- 尽量避免平台相关宽度/语义差异
+- 对整数编码与可空语义显式声明
### Best Practices
-- Use `int32` as the default for most integers; use `int64` for large values.
-- Use `string` for text data (UTF-8) and `bytes` for binary data.
-- Use `optional` only when the field may legitimately be absent.
-- Use `ref` only when needed for shared or circular references.
-- Prefer `list` for ordered sequences and `map` for key-value lookups.
+1. 优先使用显式字段号与稳定命名
+2. 需要可空就显式 `optional`
+3. 存在共享/循环关系时使用 `ref`
+4. 降低 `any` 使用范围，优先强类型建模
+5. 预留字段号与枚举值区间
## Type IDs
-Type IDs enable efficient cross-language serialization and are used for
-messages, unions, and enums. When `enable_auto_type_id = true` (default) and
-`id` is omitted, the compiler auto-generates one using
-`MurmurHash3(utf8(package.type_name))` (32-bit) and annotates it in generated
-code. When `enable_auto_type_id = false`, types without explicit IDs are
-registered by namespace and name instead. Collisions are detected at
-compile-time across the current file and all imports; when a collision occurs,
-the compiler raises an error and asks for an explicit `id` or an `alias`.
-
-```protobuf
-enum Color [id=100] { ... }
-message User [id=101] { ... }
-union Event [id=102] { ... }
-```
-
-Enum type IDs remain optional; if omitted they are auto-generated using the same
-hash when `enable_auto_type_id = true`.
+类型 ID 用于跨语言快速注册与解码匹配。
-### With Explicit Type ID
+### 显式类型 ID
```protobuf
-message User [id=101] { ... }
-message User [id=101, deprecated=true] { ... } // Multiple options
+message User [id=100] {
+ string name = 1;
+}
```
-### Without Explicit Type ID
+### 无显式类型 ID
-```protobuf
-message Config { ... } // Auto-generated when enable_auto_type_id = true
-```
+未显式声明时可：
-You can set `[alias="..."]` to change the hash source without renaming the type.
+- 自动生成数值 ID（默认配置）
+- 禁用自动 ID，改用 namespace/type-name 注册
-### Practical Notes
+### 实践说明
-- If a type omits `id` and `enable_auto_type_id = true`, Fory generates an ID
- with `MurmurHash3(utf8(package.type_name))` (32-bit).
-- Package alias and type alias change the hash input and can be used to resolve
- hash collisions without renaming public types.
-- Manual IDs in the small varint range (`0-127`) are compact on the wire; auto
- IDs are typically larger and usually consume 4-5 bytes.
+- 类型 ID 在协议层面应视为稳定标识
+- 一经发布，不建议更改
+- 建议按域规划 ID 段（如 100-199 用户域）
-### ID Assignment Strategy
+### ID 分配策略
-```protobuf
-// Enums: 100-199
-enum Status [id=100] { ... }
-enum Priority [id=101] { ... }
+- 核心高频模型优先分配固定 ID
+- 团队统一管理 ID 区间与分配规范
+- 在 CI 中增加 ID 冲突检查
-// User domain: 200-299
-message User [id=200] { ... }
-message UserProfile [id=201] { ... }
+## 完整示例
-// Order domain: 300-399
-message Order [id=300] { ... }
-message OrderItem [id=301] { ... }
-```
+```protobuf
+package demo.order;
-## Complete Example
+option java_package = "com.example.demo.order";
+option go_package = "github.com/example/demo/gen/order;order";
-```protobuf
-// E-commerce domain model
-package com.shop.models;
-
-// Enums with type IDs
-enum OrderStatus [id=100] {
- PENDING = 0;
- CONFIRMED = 1;
- SHIPPED = 2;
- DELIVERED = 3;
- CANCELLED = 4;
-}
+import "demo/common.fdl";
-enum PaymentMethod [id=101] {
- CREDIT_CARD = 0;
- DEBIT_CARD = 1;
- PAYPAL = 2;
- BANK_TRANSFER = 3;
+enum Status [id=200] {
+ UNKNOWN = 0;
+ CREATED = 1;
+ PAID = 2;
+ SHIPPED = 3;
}
-// Messages with type IDs
-message Address [id=200] {
- string street = 1;
- string city = 2;
- string state = 3;
- string country = 4;
- string postal_code = 5;
+message Item [id=201] {
+ string sku = 1;
+ int32 quantity = 2;
}
-message Customer [id=201] {
+message User [id=202] {
string id = 1;
string name = 2;
optional string email = 3;
- optional string phone = 4;
- optional Address billing_address = 5;
- optional Address shipping_address = 6;
}
-message Product [id=202] {
- string sku = 1;
- string name = 2;
- string description = 3;
- float64 price = 4;
- int32 stock = 5;
- list<string> categories = 6;
- map<string, string> attributes = 7;
+union Animal [id=203] {
+ Dog dog = 1;
+ Cat cat = 2;
}
-message OrderItem [id=203] {
- ref Product product = 1; // Track reference to avoid duplication
- int32 quantity = 2;
- float64 unit_price = 3;
+message Dog [id=204] {
+ string name = 1;
}
-message Order [id=204] {
- string id = 1;
- ref Customer customer = 2;
- list<OrderItem> items = 3;
- OrderStatus status = 4;
- PaymentMethod payment_method = 5;
- float64 total = 6;
- optional string notes = 7;
- timestamp created_at = 8;
- optional timestamp shipped_at = 9;
+message Cat [id=205] {
+ string name = 1;
}
-// Config without explicit type ID (auto-generated when enable_auto_type_id = true)
-message ShopConfig {
- string store_name = 1;
- string currency = 2;
- float64 tax_rate = 3;
- list<string> supported_countries = 4;
+message Order [id=206] {
+ string id = 1;
+ ref User buyer = 2;
+ list<Item> items = 3;
+ Status status = 4;
+ map<string, string> metadata = 5;
+ optional Animal pet = 6;
}
```
-For protobuf-specific extension options and `(fory).` syntax, see
-[Protocol Buffers IDL Support](protobuf-idl.md#fory-extension-options-protobuf).
+## 语法摘要
-## Grammar Summary
+以下为简化文法（便于快速查阅，具体以编译器实现为准）：
+```ebnf
+file = [packageDecl] {optionDecl} {importDecl} {typeDecl} ;
+
+packageDecl = "package" qualifiedName ["alias" identifier] ";" ;
+optionDecl = "option" identifier "=" optionValue ";" ;
+importDecl = "import" stringLiteral ";" ;
+
+typeDecl = enumDecl | messageDecl | unionDecl ;
+
+enumDecl = "enum" identifier [typeOptions] "{" {enumField | reservedDecl} "}" ;
+enumField = identifier "=" intLiteral ";" ;
+
+messageDecl = "message" identifier [typeOptions] "{" {fieldDecl | nestedTypeDecl | reservedDecl} "}" ;
+unionDecl = "union" identifier [typeOptions] "{" {unionCaseDecl} "}" ;
+
+fieldDecl = [fieldModifier] typeRef identifier "=" intLiteral [fieldOptions] ";" ;
+unionCaseDecl = typeRef identifier "=" intLiteral [fieldOptions] ";" ;
+
+fieldModifier = "optional" | "ref" | "list" ;
+
+typeRef = primitiveType | qualifiedName | listType | mapType ;
+listType = "list" "<" typeRef ">" ;
+mapType = "map" "<" typeRef "," typeRef ">" ;
+
+typeOptions = "[" optionPair {"," optionPair} "]" ;
+fieldOptions = "[" optionPair {"," optionPair} "]" ;
+optionPair = identifier "=" optionValue ;
+
+reservedDecl = "reserved" reservedItem {"," reservedItem} ";" ;
+reservedItem = intLiteral | intLiteral "to" intLiteral | stringLiteral ;
```
-file := [package_decl] file_option* import_decl* type_def*
-
-package_decl := 'package' package_name ['alias' package_name] ';'
-package_name := IDENTIFIER ('.' IDENTIFIER)*
-
-file_option := 'option' option_name '=' option_value ';'
-option_name := IDENTIFIER
-
-import_decl := 'import' STRING ';'
-
-type_def := enum_def | message_def | union_def
-
-enum_def := 'enum' IDENTIFIER [type_options] '{' enum_body '}'
-enum_body := (reserved_stmt | enum_value)*
-enum_value := IDENTIFIER '=' INTEGER ';'
-
-message_def := 'message' IDENTIFIER [type_options] '{' message_body '}'
-message_body := (reserved_stmt | nested_type | field_def)*
-nested_type := enum_def | message_def | union_def
-field_def := [modifiers] field_type IDENTIFIER '=' INTEGER [field_options] ';'
-
-union_def := 'union' IDENTIFIER [type_options] '{' union_field* '}'
-union_field := ['repeated'] field_type IDENTIFIER '=' INTEGER [field_options] ';'
-option_value := 'true' | 'false' | IDENTIFIER | INTEGER | STRING
-
-reserved_stmt := 'reserved' reserved_items ';'
-reserved_items := reserved_item (',' reserved_item)*
-reserved_item := INTEGER | INTEGER 'to' INTEGER | INTEGER 'to' 'max' | STRING
-
-modifiers := { 'optional' | 'ref' | 'repeated' }
-
-field_type := primitive_type | named_type | list_type | map_type
-primitive_type := 'bool'
- | 'int8' | 'int16' | 'int32' | 'int64'
- | 'uint8' | 'uint16' | 'uint32' | 'uint64'
- | 'fixed_int32' | 'fixed_int64' | 'fixed_uint32' | 'fixed_uint64'
- | 'tagged_int64' | 'tagged_uint64'
- | 'float32' | 'float64'
- | 'string' | 'bytes'
- | 'date' | 'timestamp' | 'duration' | 'decimal'
- | 'any'
-named_type := qualified_name
-qualified_name := IDENTIFIER ('.' IDENTIFIER)* // e.g., Parent.Child
-list_type := 'list' '<' { 'optional' | 'ref' } field_type '>'
-map_type := 'map' '<' field_type ',' field_type '>'
-
-type_options := '[' type_option (',' type_option)* ']'
-type_option := IDENTIFIER '=' option_value // e.g., id=100, deprecated=true
-field_options := '[' field_option (',' field_option)* ']'
-field_option := IDENTIFIER '=' option_value // e.g., deprecated=true, ref=true
-
-STRING := '"' [^"\n]* '"' | "'" [^'\n]* "'"
-IDENTIFIER := [a-zA-Z_][a-zA-Z0-9_]*
-INTEGER := '-'? [0-9]+
-```
+
+实现建议：如需严谨验证，请以编译器语法解析器和测试用例为准。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/guide/cpp/field-configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/guide/cpp/field-configuration.md
index 0c18e125ce..4dd404c290 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/guide/cpp/field-configuration.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.15/guide/cpp/field-configuration.md
@@ -19,25 +19,22 @@ license: |
limitations under the License.
---
-> 中文导读：本页介绍字段级序列化配置，包括字段 ID、可空控制、引用跟踪、忽略字段与动态类型控制等。
-> 建议在跨语言和兼容模式场景中优先显式配置字段 ID，并在需要时开启 ref/nullable 以保证行为一致。
-
-本页说明如何配置序列化的字段级元信息。
+本页说明如何在 C++ 中配置序列化字段级元信息。
## 概述
-Apache Fory™ provides two ways to specify field-level metadata at compile time:
+Apache Fory™ 在编译期提供两种字段元信息配置方式：
-1. **`fory::field<>` template** - Inline metadata in struct definition
-2. **`FORY_FIELD_TAGS` macro** - Non-invasive metadata added separately
+1. **`fory::field<>` 模板**：在 struct 定义中内联声明元信息
+2. **`FORY_FIELD_TAGS` 宏**：在 struct 外部附加元信息（非侵入）
-These enable:
+这些机制可用于：
-- **Tag IDs**: Assign compact numeric IDs for schema evolution
-- **Nullability**: Mark pointer fields as nullable
-- **Reference Tracking**: Enable reference tracking for shared pointers
+- **Tag ID**：为 schema 演进分配紧凑数值 ID
+- **可空控制**：将指针字段标记为可空
+- **引用跟踪**：为共享指针启用引用跟踪
-## fory::field 模板
+## `fory::field` 模板
```cpp
template <typename T, int16_t Id, typename... Options>
@@ -46,11 +43,11 @@ class field;
### 模板参数
-| Parameter | Description |
-| --------- | ------------------------------------------------ |
-| `T` | The underlying field type |
-| `Id` | Field tag ID (int16_t) for compact serialization |
-| `Options` | Optional tags: `fory::nullable`, `fory::ref` |
+| 参数 | 说明 |
+| --------- | ------------------------------------------ |
+| `T` | 底层字段类型 |
+| `Id` | 字段 tag ID（`int16_t`），用于紧凑序列化 |
+| `Options` | 可选标签：`fory::nullable`、`fory::ref` 等 |
### 基本用法
@@ -67,7 +64,7 @@ struct Person {
FORY_STRUCT(Person, name, age, nickname);
```
-The `fory::field<>` wrapper is transparent - you can use it like the underlying type:
+`fory::field<>` 是透明包装，可像底层类型一样使用：
```cpp
Person person;
@@ -79,9 +76,9 @@ int a = person.age.get(); // Explicit get()
## 标签类型
-### fory::nullable
+### `fory::nullable`
-Marks a smart pointer field as nullable (can be `nullptr`):
+将智能指针字段标记为可空（可为 `nullptr`）：
```cpp
struct Node {
@@ -91,9 +88,9 @@ struct Node {
FORY_STRUCT(Node, name, next);
```
-**Valid for:** `std::shared_ptr<T>`, `std::unique_ptr<T>`
+**适用类型：** `std::shared_ptr<T>`、`std::unique_ptr<T>`
-**Note:** For nullable primitives or strings, use `std::optional<T>` instead:
+**说明：** 对原生值类型或字符串的可空语义，请使用 `std::optional<T>`：
```cpp
// Correct: use std::optional for nullable primitives
@@ -103,19 +100,19 @@ fory::field<std::optional<int32_t>, 0> optional_value;
// fory::field<int32_t, 0, fory::nullable> value; // Compile error!
```
-### fory::not_null
+### `fory::not_null`
-Explicitly marks a pointer field as non-nullable. This is the default for smart pointers, but can be used for documentation:
+显式声明指针字段不可空。虽然这是智能指针的默认行为，但可用于增强可读性：
```cpp
fory::field<std::shared_ptr<Data>, 0, fory::not_null> data; // Must not be nullptr
```
-**Valid for:** `std::shared_ptr<T>`, `std::unique_ptr<T>`
+**适用类型：** `std::shared_ptr<T>`、`std::unique_ptr<T>`
-### fory::ref
+### `fory::ref`
-Enables reference tracking for shared pointer fields. When multiple fields reference the same object, it will be serialized once and shared:
+为共享指针字段启用引用跟踪。多个字段引用同一对象时，仅序列化一次并保持共享关系：
```cpp
struct Graph {
@@ -126,27 +123,27 @@ struct Graph {
FORY_STRUCT(Graph, name, left, right);
```
-**Valid for:** `std::shared_ptr<T>` only (requires shared ownership)
+**适用类型：** 仅 `std::shared_ptr<T>`（需要共享所有权）
-### Combining Tags
+### 组合标签
-Multiple tags can be combined for shared pointers:
+共享指针可组合多个标签：
```cpp
// Nullable + ref tracking
fory::field<std::shared_ptr<Node>, 0, fory::nullable, fory::ref> link;
```
-## Type Rules
+## 类型规则
-| Type | Allowed Options | Nullability |
-| -------------------- | ----------------- | ---------------------------------- |
-| Primitives, strings | None | Use `std::optional<T>` if nullable |
-| `std::optional<T>` | None | Inherently nullable |
-| `std::shared_ptr<T>` | `nullable`, `ref` | Non-null by default |
-| `std::unique_ptr<T>` | `nullable` | Non-null by default |
+| 类型 | 可用选项 | 可空语义 |
+| -------------------- | ----------------- | --------------------------------- |
+| 原生类型、字符串 | 无 | 若需可空请使用 `std::optional<T>` |
+| `std::optional<T>` | 无 | 天然可空 |
+| `std::shared_ptr<T>` | `nullable`、`ref` | 默认不可空 |
+| `std::unique_ptr<T>` | `nullable` | 默认不可空 |
-## Complete Example
+## 完整示例
```cpp
#include "fory/serialization/fory.h"
@@ -191,9 +188,9 @@ int main() {
}
```
-## Compile-Time Validation
+## 编译期校验
-Invalid configurations are caught at compile time:
+非法配置会在编译期报错：
```cpp
// Error: nullable and not_null are mutually exclusive
@@ -209,9 +206,9 @@ fory::field<std::unique_ptr<int>, 0, fory::ref> bad3;
fory::field<std::optional<int>, 0, fory::nullable> bad4;
```
-## Backwards Compatibility
+## 向后兼容
-Existing structs without `fory::field<>` wrappers continue to work:
+未使用 `fory::field<>` 包装的旧 struct 仍可正常工作：
```cpp
// Old style - still works
@@ -229,15 +226,15 @@ struct ModernPerson {
FORY_STRUCT(ModernPerson, name, age);
```
-## FORY_FIELD_TAGS Macro
+## `FORY_FIELD_TAGS` 宏
-The `FORY_FIELD_TAGS` macro provides a non-invasive way to add field metadata without modifying struct definitions. This is useful for:
+`FORY_FIELD_TAGS` 提供了一种非侵入式方案：无需修改 struct 定义即可附加字段元信息。适用场景：
-- **Third-party types**: Add metadata to types you don't own
-- **Clean structs**: Keep struct definitions as pure C++
-- **Isolated dependencies**: Confine Fory headers to serialization config files
+- **第三方类型**：为非自有类型添加元信息
+- **纯净结构定义**：保持 struct 仅包含标准 C++ 类型
+- **依赖隔离**：将 Fory 头文件限制在序列化配置文件中
-### Usage
+### 用法
```cpp
// user_types.h - NO fory headers needed!
@@ -268,33 +265,33 @@ FORY_FIELD_TAGS(Document,
)
```
-### FORY_FIELD_TAGS Options
+### `FORY_FIELD_TAGS` 选项
-| Field Type | Valid Combinations |
+| 字段类型 | 合法组合 |
| -------------------- | ---------------------------------------------------------------------------------------- |
-| Primitives, strings | `(field, id)` only |
-| `std::optional<T>` | `(field, id)` only |
-| `std::shared_ptr<T>` | `(field, id)`, `(field, id, nullable)`, `(field, id, ref)`, `(field, id, nullable, ref)` |
-| `std::unique_ptr<T>` | `(field, id)`, `(field, id, nullable)` |
+| 原生类型、字符串 | 仅 `(field, id)` |
+| `std::optional<T>` | 仅 `(field, id)` |
+| `std::shared_ptr<T>` | `(field, id)`、`(field, id, nullable)`、`(field, id, ref)`、`(field, id, nullable, ref)` |
+| `std::unique_ptr<T>` | `(field, id)`、`(field, id, nullable)` |
-### API Comparison
+### API 对比
-| Aspect | `fory::field<>` Wrapper | `FORY_FIELD_TAGS` Macro |
-| ----------------------- | ------------------------ | ----------------------- |
-| **Struct definition** | Modified (wrapped types) | Unchanged (pure C++) |
-| **IDE support** | Template noise | Excellent (clean types) |
-| **Third-party classes** | Not supported | Supported |
-| **Header dependencies** | Required everywhere | Isolated to config |
-| **Migration effort** | High (change all fields) | Low (add one macro) |
+| 维度 | `fory::field<>` 包装 | `FORY_FIELD_TAGS` 宏 |
+| -------------- | ------------------------ | ---------------------- |
+| **结构定义** | 需要改动（包装字段类型） | 无需改动（保持纯 C++） |
+| **IDE 体验** | 有模板噪音 | 更清晰（原生字段类型） |
+| **第三方类型** | 不支持 | 支持 |
+| **头文件依赖** | 各处都需要 | 可集中在配置文件 |
+| **迁移成本** | 高（修改全部字段） | 低（新增一个宏） |
-## FORY_FIELD_CONFIG Macro
+## `FORY_FIELD_CONFIG` 宏
-The `FORY_FIELD_CONFIG` macro is the most powerful and flexible way to configure field-level serialization. It provides:
+`FORY_FIELD_CONFIG` 是更强、更灵活的字段配置方式，提供：
-- **Builder pattern API**: Fluent, chainable configuration with `F(id).option1().option2()`
-- **Encoding control**: Specify how unsigned integers are encoded (varint, fixed, tagged)
-- **Compile-time verification**: Field names are verified against member pointers
-- **Cross-language compatibility**: Configure encoding to match other languages (Java, Rust, etc.)
+- **Builder 风格 API**：链式配置 `F(id).option1().option2()`
+- **编码控制**：指定无符号整数编码（varint、fixed、tagged）
+- **编译期校验**：通过成员指针校验字段名
+- **跨语言兼容**：按 Java、Rust 等语言期望配置编码
### 基本语法
@@ -308,9 +305,9 @@ FORY_FIELD_CONFIG(StructType,
);
```
-### The F() Builder
+### `F()` Builder
-The `fory::F(id)` factory creates a `FieldMeta` object that supports method chaining:
+`fory::F(id)` 工厂函数会创建支持链式调用的 `FieldMeta` 对象：
```cpp
fory::F(0) // Create with field ID 0
@@ -323,7 +320,7 @@ fory::F(0) // Create with field ID 0
.compress(false) // Disable compression
```
-**Tip:** To use `F()` without the `fory::` prefix, add a using declaration:
+**提示：** 若希望省略 `fory::` 前缀，可添加 `using` 声明：
```cpp
using fory::F;
@@ -334,19 +331,19 @@ FORY_FIELD_CONFIG(MyStruct,
);
```
-### Encoding Options for Unsigned Integers
+### 无符号整数编码选项
-For `uint32_t` and `uint64_t` fields, you can specify the wire encoding:
+对于 `uint32_t` 与 `uint64_t` 字段，可显式指定线格式编码：
-| Method | Type ID | Description | Use Case |
-| ----------- | ------------- | ---------------------------------------------- | ------------------------------------- |
-| `.varint()` | VAR_UINT32/64 | Variable-length encoding (1-5 or 1-10 bytes) | Values typically small |
-| `.fixed()` | UINT32/64 | Fixed-size encoding (always 4 or 8 bytes) | Values uniformly distributed |
-| `.tagged()` | TAGGED_UINT64 | Tagged hybrid encoding with size hint (uint64) | Mixed small and large values (uint64) |
+| 方法 | Type ID | 说明 | 适用场景 |
+| ----------- | ------------- | --------------------------------- | ------------------------ |
+| `.varint()` | VAR_UINT32/64 | 变长编码（1-5 或 1-10 字节） | 数值通常较小 |
+| `.fixed()` | UINT32/64 | 定长编码（固定 4 或 8 字节） | 数值分布较均匀 |
... 1983 lines suppressed ...
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org