@aigne/doc-smith 0.8.3 → 0.8.5

package/docs/configuration-interactive-setup.md

@@ -1,82 +1,135 @@
----
-labels: ["Reference"]
----
-
 # Interactive Setup
 
-Setting up a new documentation project is straightforward with the interactive setup wizard. By running a single command, `aigne doc init`, you can generate a comprehensive `config.yaml` file tailored to your project's needs. The wizard guides you through a series of questions, provides intelligent defaults, and helps prevent configuration mistakes.
+To simplify project configuration, AIGNE DocSmith provides an interactive setup wizard launched with the `aigne doc init` command. This guided process asks a series of questions about your documentation goals and generates a `config.yaml` file based on your answers. It is the recommended way to start a new documentation project, as it helps prevent configuration errors and provides specific recommendations.
+
+## Running the Wizard
+
+To begin, run the following command in your project's root directory:
+
+```bash aigne doc init icon=lucide:sparkles
+npx aigne doc init
+```
+
+The wizard will then guide you through an 8-step process to configure your documentation.
 
-This is the recommended way to start a new DocSmith project, as it ensures all necessary settings are considered from the beginning.
+## The Guided Process
 
-## The Setup Process
+The wizard covers the following key areas:
 
-The `init` command launches a guided, 8-step process to understand your documentation goals. At each step, it asks a question and often suggests a default based on your previous answers.
+1.  **Primary Goal**: Defines the main outcome for your readers (e.g., getting started quickly, finding answers fast).
+2.  **Target Audience**: Specifies who will be reading the documentation (e.g., non-technical end-users, developers).
+3.  **Reader Knowledge Level**: Assesses the typical starting knowledge of your audience.
+4.  **Documentation Depth**: Determines how comprehensive the content should be.
+5.  **Primary Language**: Sets the main language for the documentation.
+6.  **Translation Languages**: Selects additional languages for translation.
+7.  **Output Directory**: Specifies where to save the generated documentation files.
+8.  **Source Code Paths**: Defines which files and directories to analyze, with support for glob patterns.
+
+## Assisted Configuration
+
+The wizard includes built-in logic to help you create a more effective and coherent configuration.
 
 ```d2
 direction: down
 
-start: "Start: `aigne doc init`" {
-  shape: hexagon
+User-Selections: {
+  label: "1. User provides input\n(Purpose, Audience, etc.)"
+  shape: rectangle
 }
 
-step1: "[1/8] Define Primary Goal"
-step2: "[2/8] Select Target Audience"
-step3: "[3/8] Set Reader Knowledge Level"
-step4: "[4/8] Choose Documentation Depth"
-step5: "[5/8] Select Primary Language"
-step6: "[6/8] Add Translation Languages"
-step7: "[7/8] Specify Output Directory"
-step8: "[8/8] Configure Source Paths"
-
-finish: "config.yaml is generated!" {
-  shape: hexagon
+Wizard-Engine: {
+  label: "2. Wizard's Logic Engine"
+  shape: rectangle
+  grid-columns: 2
+
+  Filtering: {
+    label: "Option Filtering\n(Prevents invalid combos)"
+  }
+
+  Conflict-Detection: {
+    label: "Conflict Detection\n(Identifies complex needs)"
+  }
 }
 
-start -> step1 -> step2 -> step3 -> step4 -> step5 -> step6 -> step7 -> step8 -> finish
+Guided-Experience: {
+  label: "3. Guided Experience"
+  shape: rectangle
+  content: "User sees simplified, relevant options"
+}
 
-subsystem: "Throughout the process, DocSmith provides intelligent defaults and detects potential configuration conflicts to ensure a coherent setup." {
-    shape: callout
+Final-Config: {
+  label: "4. Final Configuration"
+  content: "config.yaml is generated with\nconflict resolution strategies"
 }
 
-subsystem -- step3
-subsystem -- step4
+User-Selections -> Wizard-Engine
+Wizard-Engine.Filtering -> Guided-Experience
+Wizard-Engine.Conflict-Detection -> Final-Config
+Guided-Experience -> User-Selections: "Refines"
 ```
 
-Here is a breakdown of each step:
+### Default Suggestions and Option Filtering
 
-1.  **Primary Goal**: Define the main purpose of your documentation. This choice heavily influences the style and structure of the generated content.
-2.  **Target Audience**: Specify who will be reading the documentation. This helps tailor the tone, language, and examples to the right audience.
-3.  **Reader Knowledge Level**: Indicate the typical starting knowledge of your readers. The wizard filters this list to show only options compatible with your previous selections.
-4.  **Documentation Depth**: Decide how comprehensive the documentation should be. A recommended default is provided based on your goal and audience.
-5.  **Primary Language**: Choose the main language for your documentation. It defaults to your detected system language.
-6.  **Translation Languages**: Select any additional languages you want to translate the documentation into.
-7.  **Documentation Directory**: Set the output folder for the generated documentation files.
-8.  **Source Code Paths**: Specify which files and folders DocSmith should analyze to generate documentation. You can use both direct paths (e.g., `./src`) and glob patterns (e.g., `src/**/*.js`).
+As you answer questions, the wizard provides defaults and filters subsequent options to guide you toward a logical configuration. For instance:
 
-## Intelligent Conflict Prevention
+-   **Default Suggestions**: If you select "Get started quickly" as your primary goal, the wizard will recommend "Is a total beginner" as the reader's knowledge level.
+-   **Real-time Filtering**: If your target audience is "End users (non-technical)," the wizard will hide technically advanced knowledge levels like "Is an expert trying to do something specific" to prevent incompatible selections.
 
-A key feature of the interactive setup is its ability to prevent conflicting configurations. As you make selections, the wizard intelligently filters the options in subsequent steps to ensure your final configuration is logical and effective.
+### Conflict Detection and Resolution
 
-For example, if you select **"Get started quickly"** as your primary goal, the wizard will prevent you from choosing **"Is an expert trying to do something specific"** as the reader's knowledge level. A quick-start guide is fundamentally incompatible with the needs of an expert who requires advanced, in-depth reference material. This mechanism guides you toward creating a coherent documentation strategy without requiring you to memorize every possible combination of settings.
+Sometimes, you may have multiple goals or audiences that seem to conflict, such as creating documentation for both non-technical **End Users** and expert **Developers**. The wizard identifies these as "resolvable conflicts."
 
-## Handling Complex Scenarios
+It then formulates a strategy to address these diverse needs within the documentation's structure. For the End User vs. Developer example, the resolution strategy is to create separate user paths:
 
-Sometimes, you may want to target multiple, distinct audiences. For instance, you might need documentation for both non-technical **End Users** and expert **Developers**. While these audiences have conflicting needs, the setup wizard allows you to select both.
+-   **User Guide Path**: Uses plain language, focuses on UI interactions, and is oriented toward business outcomes.
+-   **Developer Guide Path**: Is code-first, technically precise, and includes SDK examples and configuration snippets.
 
-Instead of treating this as an error, DocSmith uses this information as a guideline for the documentation's structure. It will resolve the conflict by planning separate user paths:
+This approach ensures that the final documentation is structured to serve multiple audiences effectively, rather than creating a confusing mix of content.
 
-*   **A User Guide**: Written in plain language, focusing on UI and business outcomes.
-*   **A Developer Guide**: Featuring code snippets, API references, and technical details.
+## Generated Output
 
-This approach ensures that the final documentation can serve diverse needs effectively through intelligent structural design rather than simple concatenation.
+Upon completion, the wizard saves a `config.yaml` file in your project. This file is fully commented, explaining each option and listing all available choices, making it easy to review and modify manually later.
 
-After completing the wizard, your configuration will be saved, and you'll be ready to generate your first set of documents.
+Here is a snippet of what the generated file looks like:
+
+```yaml config.yaml icon=logos:yaml
+# Project information for documentation publishing
+projectName: your-project-name
+projectDesc: Your project description.
+projectLogo: ""
+
+# =============================================================================
+# Documentation Configuration
+# =============================================================================
+
+# Purpose: What's the main outcome you want readers to achieve?
+# Available options (uncomment and modify as needed):
+#   getStarted       - Get started quickly: Help new users go from zero to working in <30 minutes
+#   completeTasks    - Complete specific tasks: Guide users through common workflows and use cases
+documentPurpose:
+  - completeTasks
+  - findAnswers
+
+# Target Audience: Who will be reading this most often?
+# Available options (uncomment and modify as needed):
+#   endUsers         - End users (non-technical): People who use the product but don't code
+#   developers       - Developers integrating your product/API: Engineers adding this to their projects
+targetAudienceTypes:
+  - endUsers
+  - developers
+
+# ... other settings
+```
+
+## Next Steps
+
+With your configuration file in place, you are ready to generate, translate, or publish your documentation.
 
 <x-cards>
-  <x-card data-title="Configuration Guide" data-icon="lucide:file-cog" data-href="/configuration">
-    Learn how to manually edit the `config.yaml` file for advanced customization.
-  </x-card>
   <x-card data-title="Generate Documentation" data-icon="lucide:play-circle" data-href="/features/generate-documentation">
-    Run the command to generate your first set of documents based on your new configuration.
+    Learn how to use a single command to automatically create a complete set of documentation from your source code.
+  </x-card>
+  <x-card data-title="Configuration Guide" data-icon="lucide:settings" data-href="/configuration">
+    Dive deeper into all available settings and learn how to fine-tune the config.yaml file manually.
   </x-card>
 </x-cards>

package/docs/configuration-interactive-setup.zh.md

@@ -1,82 +1,135 @@
----
-labels: ["Reference"]
----
-
 # 交互式设置
 
-使用交互式设置向导可以轻松地设置新的文档项目。只需运行 `aigne doc init` 命令，即可根据项目需求生成一个全面的 `config.yaml` 文件。该向导将引导你完成一系列问题，提供智能的默认值，并帮助你避免配置错误。
+为简化项目配置，AIGNE DocSmith 提供了一个交互式设置向导，可通过 `aigne doc init` 命令启动。该引导式流程会询问一系列关于文档目标的问题，并根据您的回答生成一个 `config.yaml` 文件。这是开始新文档项目的推荐方式，因为它有助于防止配置错误并提供具体建议。
+
+## 运行向导
+
+首先，在您项目的根目录中运行以下命令：
+
+```bash aigne doc init icon=lucide:sparkles
+npx aigne doc init
+```
+
+然后，向导将引导您完成一个 8 步流程来配置您的文档。
 
-这是启动新 DocSmith 项目的推荐方法，因为它能确保从一开始就考虑到所有必要的设置。
+## 引导式流程
 
-## 设置过程
+向导涵盖以下关键领域：
 
-`init` 命令会启动一个包含 8 个步骤的引导式流程，以了解你的文档目标。在每一步中，它都会提出一个问题，并通常会根据你之前的回答建议一个默认值。
+1.  **主要目标**：定义读者的主要预期成果（例如，快速入门、快速找到答案）。
+2.  **目标受众**：明确文档的阅读对象（例如，非技术最终用户、开发者）。
+3.  **读者知识水平**：评估受众的典型初始知识水平。
+4.  **文档深度**：决定内容的详尽程度。
+5.  **主要语言**：设置文档的主要语言。
+6.  **翻译语言**：选择用于翻译的其他语言。
+7.  **输出目录**：指定保存生成的文档文件的位置。
+8.  **源代码路径**：定义要分析的文件和目录，支持 glob 模式。
+
+## 辅助配置
+
+该向导包含内置逻辑，可帮助您创建更有效、更一致的配置。
 
 ```d2
 direction: down
 
-start: "开始: `aigne doc init`" {
-  shape: hexagon
+User-Selections: {
+  label: "1. 用户提供输入\n（目的、受众等）"
+  shape: rectangle
 }
 
-step1: "[1/8] 定义主要目标"
-step2: "[2/8] 选择目标受众"
-step3: "[3/8] 设置读者知识水平"
-step4: "[4/8] 选择文档深度"
-step5: "[5/8] 选择主要语言"
-step6: "[6/8] 添加翻译语言"
-step7: "[7/8] 指定输出目录"
-step8: "[8/8] 配置源路径"
-
-finish: "config.yaml 已生成！" {
-  shape: hexagon
+Wizard-Engine: {
+  label: "2. 向导的逻辑引擎"
+  shape: rectangle
+  grid-columns: 2
+
+  Filtering: {
+    label: "选项过滤\n（防止无效组合）"
+  }
+
+  Conflict-Detection: {
+    label: "冲突检测\n（识别复杂需求）"
+  }
 }
 
-start -> step1 -> step2 -> step3 -> step4 -> step5 -> step6 -> step7 -> step8 -> finish
+Guided-Experience: {
+  label: "3. 引导式体验"
+  shape: rectangle
+  content: "用户看到简化、相关的选项"
+}
 
-subsystem: "在整个过程中，DocSmith 提供智能的默认值并检测潜在的配置冲突，以确保设置的一致性。" {
-    shape: callout
+Final-Config: {
+  label: "4. 最终配置"
+  content: "config.yaml 根据\n冲突解决策略生成"
 }
 
-subsystem -- step3
-subsystem -- step4
+User-Selections -> Wizard-Engine
+Wizard-Engine.Filtering -> Guided-Experience
+Wizard-Engine.Conflict-Detection -> Final-Config
+Guided-Experience -> User-Selections: "优化"
 ```
 
-以下是每个步骤的详细说明：
+### 默认建议和选项过滤
 
-1.  **主要目标**：定义文档的主要目的。这个选择会极大地影响生成内容的风格和结构。
-2.  **目标受众**：明确文档的读者。这有助于针对正确的受众调整语气、语言和示例。
-3.  **读者知识水平**：指明读者的典型初始知识水平。向导会筛选此列表，仅显示与你先前选择兼容的选项。
-4.  **文档深度**：决定文档的全面程度。系统会根据你的目标和受众提供一个推荐的默认值。
-5.  **主要语言**：选择文档的主要语言。它会默认为你检测到的系统语言。
-6.  **翻译语言**：选择你希望将文档翻译成的其他语言。
-7.  **文档目录**：为生成的文档文件设置输出文件夹。
-8.  **源代码路径**：指定 DocSmith 应分析以生成文档的文件和文件夹。你可以使用直接路径（例如 `./src`）和 glob 模式（例如 `src/**/*.js`）。
+在您回答问题时，向导会提供默认值并筛选后续选项，以引导您进行逻辑配置。例如：
 
-## 智能冲突预防
+-   **默认建议**：如果您选择“快速入门”作为主要目标，向导将推荐“完全是初学者”作为读者的知识水平。
+-   **实时过滤**：如果您的目标受众是“最终用户（非技术人员）”，向导将隐藏“试图做特定事情的专家”等技术高级知识水平，以防止不兼容的选择。
 
-交互式设置的一个关键特性是它能够防止配置冲突。在你进行选择时，向导会智能地筛选后续步骤中的选项，以确保你的最终配置是合乎逻辑且有效的。
+### 冲突检测与解决
 
-例如，如果你选择 **“快速入门”** 作为主要目标，向导将阻止你选择 **“试图完成特定任务的专家”** 作为读者知识水平。快速入门指南与需要高级、深入参考资料的专家的需求在根本上是不兼容的。这种机制引导你制定一个连贯的文档策略，而无需你记住每一种可能的设置组合。
+有时，您可能有多个似乎相互冲突的目标或受众，例如同时为非技术的**最终用户**和专业的**开发者**创建文档。向导会将这些识别为“可解决的冲突”。
 
-## 处理复杂场景
+然后，它会制定一个策略，在文档结构中解决这些多样化的需求。对于最终用户与开发者的例子，解决方法是创建独立的用户路径：
 
-有时，你可能希望面向多个不同的受众。例如，你可能需要为非技术的 **最终用户** 和专业的 **开发者** 提供文档。虽然这些受众的需求存在冲突，但设置向导允许你同时选择两者。
+-   **用户指南路径**：使用通俗易懂的语言，侧重于 UI 交互，并面向业务成果。
+-   **开发者指南路径**：代码优先，技术上精确，并包含 SDK 示例和配置片段。
 
-DocSmith 不会将此视为错误，而是将此信息用作文档结构的指导。它将通过规划独立的用户路径来解决冲突：
+这种方法可确保最终的文档结构能够有效地服务于多个受众，而不是产生令人困惑的内容混合。
 
-*   **用户指南**：用通俗易懂的语言编写，侧重于用户界面和业务成果。
-*   **开发者指南**：包含代码片段、API 参考和技术细节。
+## 生成的输出
 
-这种方法通过智能的结构设计，而非简单的内容拼接，确保最终的文档能够有效地满足不同需求。
+完成后，向导会在您的项目中保存一个 `config.yaml` 文件。该文件带有完整的注释，解释了每个选项并列出了所有可用选择，方便日后手动审查和修改。
 
-完成向导后，你的配置将被保存，你就可以生成第一套文档了。
+以下是生成文件的片段示例：
+
+```yaml config.yaml icon=logos:yaml
+# 用于文档发布的项目信息
+projectName: your-project-name
+projectDesc: 您的项目描述。
+projectLogo: ""
+
+# =============================================================================
+# 文档配置
+# =============================================================================
+
+# 目的：您希望读者达到的主要成果是什么？
+# 可用选项（根据需要取消注释并修改）：
+#   getStarted       - 快速入门：帮助新用户在 30 分钟内从零开始上手
+#   completeTasks    - 完成特定任务：引导用户完成常见的工作流程和用例
+documentPurpose:
+  - completeTasks
+  - findAnswers
+
+# 目标受众：谁会最常阅读这份文档？
+# 可用选项（根据需要取消注释并修改）：
+#   endUsers         - 最终用户（非技术人员）：使用产品但不编写代码的人
+#   developers       - 开发者（集成您的产品/API）：将此添加到其项目中的工程师
+targetAudienceTypes:
+  - endUsers
+  - developers
+
+# ... 其他设置
+```
+
+## 后续步骤
+
+配置文件就绪后，您就可以生成、翻译或发布您的文档了。
 
 <x-cards>
-  <x-card data-title="配置指南" data-icon="lucide:file-cog" data-href="/configuration">
-    了解如何手动编辑 `config.yaml` 文件以进行高级定制。
-  </x-card>
   <x-card data-title="生成文档" data-icon="lucide:play-circle" data-href="/features/generate-documentation">
-    运行命令，根据你的新配置生成第一套文档。
+    了解如何使用单个命令从您的源代码自动创建一套完整的文档。
+  </x-card>
+  <x-card data-title="配置指南" data-icon="lucide:settings" data-href="/configuration">
+    深入了解所有可用设置，并学习如何手动微调 config.yaml 文件。
   </x-card>
 </x-cards>

package/docs/configuration-language-support.md

@@ -1,64 +1,94 @@
----
-labels: ["Reference"]
----
-
 # Language Support
 
-AIGNE DocSmith is designed for a global audience, offering automated translation capabilities for over a dozen languages. This allows you to generate and maintain documentation in multiple languages with minimal effort, ensuring your project is accessible to users worldwide. The translation feature is powered by the `aigne doc translate` command.
+AIGNE DocSmith provides automated translation for 12 languages, allowing you to generate and maintain documentation for a global audience. The entire process is handled by the `aigne doc translate` command, which uses an AI engine to process your source documents and create localized versions.
+
+The translation workflow processes your source documents through the AIGNE AI engine to generate localized versions in your selected target languages.
+
+```d2
+direction: down
+
+Source-Doc: {
+  label: "Source Document\n(e.g., English)"
+  shape: rectangle
+}
+
+AI-Engine: {
+  label: "AIGNE DocSmith\nAI Translation Engine"
+  shape: rectangle
+}
+
+Translated-Docs: {
+  label: "Translated Documents"
+  shape: rectangle
+  grid-columns: 3
+
+  zh: "简体中文"
+  ja: "日本語"
+  es: "Español"
+  fr: "Français"
+  de: "Deutsch"
+  more: "..."
+}
+
+Source-Doc -> AI-Engine: "`aigne doc translate`"
+AI-Engine -> Translated-Docs: "Generates"
+```
 
 ## Supported Languages
 
-DocSmith provides high-quality, AI-powered translations for the following languages. You can select your primary documentation language and any number of target languages for translation during the project setup.
+DocSmith offers AI-powered translations for the following languages. You can define your project's primary language during the initial setup and select any number of target languages for translation.
 
-| Language | Language Code |
-|---|---|
-| English (en) | `en` |
-| 简体中文 (zh) | `zh` |
-| 繁體中文 (zh-TW) | `zh-TW` |
-| 日本語 (ja) | `ja` |
-| 한국어 (ko) | `ko` |
-| Español (es) | `es` |
-| Français (fr) | `fr` |
-| Deutsch (de) | `de` |
-| Português (pt) | `pt` |
-| Русский (ru) | `ru` |
-| Italiano (it) | `it` |
-| العربية (ar) | `ar` |
-
-## How to Enable and Use Translation
-
-Translation languages are typically configured when you first initialize your project using `aigne doc init`. However, you can easily add new languages or translate documents at any time using the `aigne doc translate` command.
+| Language | Language Code | Sample Text |
+|---|---|---|
+| English | `en` | Hello |
+| 简体中文 | `zh` | 你好 |
+| 繁體中文 | `zh-TW` | 你好 |
+| 日本語 | `ja` | こんにちは |
+| 한국어 | `ko` | 안녕하세요 |
+| Español | `es` | Hola |
+| Français | `fr` | Bonjour |
+| Deutsch | `de` | Hallo |
+| Português | `pt` | Olá |
+| Русский | `ru` | Привет |
+| Italiano | `it` | Ciao |
+| العربية | `ar` | مرحبا |
+
+## How to Configure and Use Translation
+
+Translation languages are set when you initialize your project with `aigne doc init`. You can add new languages or translate documents at any time using the `aigne doc translate` command, which offers two modes of operation.
 
 ### Interactive Mode
 
-The simplest way to translate your documents is by running the command without any arguments. This will launch an interactive wizard.
+For a guided experience, run the command without any arguments. This is the recommended approach for most users.
 
-```bash
+```bash Interactive Translation icon=lucide:wand
 aigne doc translate
 ```
 
-The interactive mode will guide you through:
+The interactive mode will then prompt you to:
 
-- Selecting which existing documents you want to translate.
-- Choosing target languages from the supported list.
-- Adding new translation languages to your project's configuration.
+- Select which of your existing documents to translate.
+- Choose one or more target languages from the supported list.
+- Add new translation languages to your project's configuration if they are not already included.
 
-### Command-Line Mode
+### Command-Line Arguments
 
-For automation or more direct control, you can specify documents and languages as command-line arguments. This is ideal for use in scripts or CI/CD environments.
+For direct control or for use in automated scripts (like CI/CD pipelines), you can specify documents and languages directly as command-line arguments.
 
-```bash
+```bash Command Example icon=lucide:terminal
 # Translate overview.md and examples.md into Chinese and Japanese
 aigne doc translate --langs zh --langs ja --docs overview.md --docs examples.md
 ```
 
-Key parameters include:
+Key parameters for the command include:
 
-- `--langs`: Specify a target language code. You can use this flag multiple times for multiple languages.
-- `--docs`: Specify the path to a document you want to translate. This can also be used multiple times.
-- `--feedback`: Provide specific instructions to improve the quality of the translation.
-- `--glossary`: Use a custom glossary file to ensure consistent terminology.
+| Parameter | Description |
+|---|---|
+| `--langs` | Specify a target language code. This flag can be used multiple times to select several languages. |
+| `--docs` | Specify the path to a document to translate (e.g., `overview.md`). This can also be used multiple times. |
+| `--feedback` | Provide specific instructions to guide the translation model (e.g., `"Use a formal tone"`). |
+| `--glossary` | Use a custom glossary file (e.g., `@path/to/glossary.md`) to ensure consistent translation of project-specific terms. |
 
 ---
 
-Now that you know which languages are supported and how to enable them, you can start reaching a broader audience. For a more detailed walkthrough of the translation workflow and its advanced features, see the [Translate Documentation](./features-translate-documentation.md) guide.
+This section covers the available languages and how to enable them. For a complete guide on the translation workflow, including advanced options and best practices, see the [Translate Documentation](./features-translate-documentation.md) guide.

package/docs/configuration-language-support.zh.md

@@ -1,64 +1,94 @@
----
-labels: ["Reference"]
----
-
 # 语言支持
 
-AIGNE DocSmith 面向全球用户设计，提供十几种语言的自动翻译功能。这使你能够以最少的工作量生成和维护多语言文档，确保你的项目能够被世界各地的用户访问。该翻译功能由 `aigne doc translate` 命令提供支持。
+AIGNE DocSmith 提供 12 种语言的自动翻译功能，让你能够为全球用户生成和维护文档。整个过程由 `aigne doc translate` 命令处理，该命令使用 AI 引擎处理你的源文档并创建本地化版本。
+
+翻译工作流通过 AIGNE AI 引擎处理你的源文档，以在你选择的目标语言中生成本地化版本。
+
+```d2
+direction: down
+
+Source-Doc: {
+  label: "源文档\n（例如，英语）"
+  shape: rectangle
+}
+
+AI-Engine: {
+  label: "AIGNE DocSmith\nAI 翻译引擎"
+  shape: rectangle
+}
+
+Translated-Docs: {
+  label: "翻译后文档"
+  shape: rectangle
+  grid-columns: 3
+
+  zh: "简体中文"
+  ja: "日本語"
+  es: "Español"
+  fr: "Français"
+  de: "Deutsch"
+  more: "..."
+}
+
+Source-Doc -> AI-Engine: "`aigne doc translate`"
+AI-Engine -> Translated-Docs: "生成"
+```
 
 ## 支持的语言
 
-DocSmith 为以下语言提供高质量的 AI 翻译。你可以在项目设置期间选择你的主要文档语言和任意数量的目标翻译语言。
+DocSmith 为以下语言提供 AI 翻译功能。你可以在初始设置期间定义项目的主要语言，并选择任意数量的目标语言进行翻译。
 
-| 语言 | 语言代码 |
-|---|---|
-| 英语 (en) | `en` |
-| 简体中文 (zh) | `zh` |
-| 繁體中文 (zh-TW) | `zh-TW` |
-| 日语 (ja) | `ja` |
-| 韩语 (ko) | `ko` |
-| 西班牙语 (es) | `es` |
-| 法语 (fr) | `fr` |
-| 德语 (de) | `de` |
-| 葡萄牙语 (pt) | `pt` |
-| 俄语 (ru) | `ru` |
-| 意大利语 (it) | `it` |
-| 阿拉伯语 (ar) | `ar` |
-
-## 如何启用和使用翻译
-
-翻译语言通常在首次使用 `aigne doc init` 初始化项目时进行配置。但是，你可以随时使用 `aigne doc translate` 命令轻松添加新语言或翻译文档。
+| 语言 | 语言代码 | 示例文本 |
+|---|---|---|
+| 英语 | `en` | Hello |
+| 简体中文 | `zh` | 你好 |
+| 繁體中文 | `zh-TW` | 你好 |
+| 日本語 | `ja` | こんにちは |
+| 한국어 | `ko` | 안녕하세요 |
+| Español | `es` | Hola |
+| Français | `fr` | Bonjour |
+| Deutsch | `de` | Hallo |
+| Português | `pt` | Olá |
+| Русский | `ru` | Привет |
+| Italiano | `it` | Ciao |
+| العربية | `ar` | مرحبا |
+
+## 如何配置和使用翻译功能
+
+翻译语言在你使用 `aigne doc init` 初始化项目时设置。你可以随时使用 `aigne doc translate` 命令添加新语言或翻译文档，该命令提供两种操作模式。
 
 ### 交互模式
 
-翻译文档最简单的方法是直接运行该命令，不带任何参数。这将启动一个交互式向导。
+如需引导式体验，请在不带任何参数的情况下运行该命令。这是为大多数用户推荐的方法。
 
-```bash
+```bash Interactive Translation icon=lucide:wand
 aigne doc translate
 ```
 
-交互模式将引导你完成以下操作：
+交互模式将提示你：
 
 - 选择要翻译的现有文档。
-- 从支持的语言列表中选择目标语言。
-- 将新的翻译语言添加到你的项目配置中。
+- 从支持的语言列表中选择一个或多个目标语言。
+- 如果项目中尚未包含新的翻译语言，则将其添加到项目配置中。
 
-### 命令行模式
+### 命令行参数
 
-为了实现自动化或更直接的控制，你可以将文档和语言指定为命令行参数。这非常适合在脚本或 CI/CD 环境中使用。
+为了直接控制或在自动化脚本（如 CI/CD 流水线）中使用，你可以直接将文档和语言指定为命令行参数。
 
-```bash
+```bash Command Example icon=lucide:terminal
 # 将 overview.md 和 examples.md 翻译成中文和日文
 aigne doc translate --langs zh --langs ja --docs overview.md --docs examples.md
 ```
 
-关键参数包括：
+该命令的关键参数包括：
 
-- `--langs`: 指定目标语言代码。你可以多次使用此标志以指定多种语言。
-- `--docs`: 指定要翻译的文档的路径。此标志也可以多次使用。
-- `--feedback`: 提供具体说明以提高翻译质量。
-- `--glossary`: 使用自定义术语表文件以确保术语的一致性。
+| 参数 | 描述 |
+|---|---|
+| `--langs` | 指定目标语言代码。该标志可以多次使用以选择多种语言。 |
+| `--docs` | 指定要翻译的文档路径（例如 `overview.md`）。该标志也可以多次使用。 |
+| `--feedback` | 提供具体指令以指导翻译模型（例如，`"Use a formal tone"`）。 |
+| `--glossary` | 使用自定义术语表文件（例如 `@path/to/glossary.md`）以确保项目特定术语的翻译一致性。 |
 
 ---
 
-现在你已经了解了支持哪些语言以及如何启用它们，可以开始覆盖更广泛的受众了。有关翻译工作流程及其高级功能的更详细演练，请参阅 [翻译文档](./features-translate-documentation.md) 指南。
+本节介绍了可用语言以及如何启用它们。有关翻译工作流的完整指南，包括高级选项和最佳实践，请参阅[翻译文档](./features-translate-documentation.md)指南。