From 896c7e22df6fe27cdc869cb8c71015509390f909 Mon Sep 17 00:00:00 2001
From: pengzhanbo <volodymyr@foxmail.com>
Date: Sun, 8 Mar 2026 16:59:50 +0800
Subject: [PATCH] chore: improve theme code comments

---
 theme/src/client/composables/collections.ts  | 60 +++++++++++++
 theme/src/client/composables/flyout.ts       | 46 ++++++++++
 theme/src/client/composables/icons.ts        | 66 +++++++++++++-
 theme/src/client/composables/sidebar-data.ts | 93 ++++++++++++++++++--
 theme/src/node/enhance.ts                    | 32 +++++--
 theme/src/node/utils/createMatcher.ts        | 23 +++++
 theme/src/node/utils/pinyin.ts               | 21 ++++-
 theme/src/node/utils/resolveContent.ts       | 24 +++++
 theme/src/node/utils/translate.ts            | 34 ++++++-
 theme/src/node/utils/writeTemp.ts            | 34 ++++++-
 10 files changed, 413 insertions(+), 20 deletions(-)

diff --git a/theme/src/client/composables/collections.ts b/theme/src/client/composables/collections.ts
index f65e0667..7b5f6f34 100644
--- a/theme/src/client/composables/collections.ts
+++ b/theme/src/client/composables/collections.ts
@@ -12,10 +12,34 @@ import { removeLeadingSlash } from 'vuepress/shared'
 import { normalizeLink } from '../utils/index.js'
 import { useData } from './data.js'
 
+/**
+ * Reference type for collections data.
+ * Maps locale paths to arrays of collection items.
+ *
+ * 集合数据的引用类型。
+ * 将语言环境路径映射到集合项数组。
+ */
 export type CollectionsRef = Ref<Record<string, ThemeCollectionItem[]>>
+
+/**
+ * Reference type for a single collection item.
+ *
+ * 单个集合项的引用类型。
+ */
 export type CollectionItemRef<T extends ThemeBaseCollection> = Ref<T | undefined>
 
+/**
+ * Global reference to all collections data.
+ *
+ * 所有集合数据的全局引用。
+ */
 export const collectionsRef: CollectionsRef = ref(collectionsRaw)
+
+/**
+ * Global reference to the current collection item.
+ *
+ * 当前集合项的全局引用。
+ */
 export const collectionItemRef: CollectionItemRef<ThemeBaseCollection> = ref()
 
 const forceCollection = ref<string | true>()
@@ -26,13 +50,49 @@ if (__VUEPRESS_DEV__ && (import.meta.webpackHot || import.meta.hot)) {
   }
 }
 
+/**
+ * Use collections data.
+ * Returns the global collections reference.
+ *
+ * 获取集合数据。
+ * 返回全局集合引用。
+ *
+ * @returns Collections data reference / 集合数据引用
+ */
 export const useCollections = (): CollectionsRef => collectionsRef
+
+/**
+ * Use current collection item.
+ * Returns the current collection based on the page context.
+ *
+ * 获取当前集合项。
+ * 根据页面上下文返回当前集合。
+ *
+ * @template T - Collection type / 集合类型
+ * @returns Current collection item reference / 当前集合项引用
+ */
 export const useCollection = <T extends ThemeBaseCollection = ThemeDocCollection>(): CollectionItemRef<T> => collectionItemRef as CollectionItemRef<T>
 
+/**
+ * Force update the current collection.
+ * Used to programmatically switch the active collection.
+ *
+ * 强制更新当前集合。
+ * 用于以编程方式切换活动集合。
+ *
+ * @param dir - Collection directory or true for first posts collection / 集合目录或 true 表示第一个文章集合
+ */
 export function forceUpdateCollection(dir?: string | true): void {
   forceCollection.value = dir
 }
 
+/**
+ * Setup collection tracking.
+ * Automatically determines the current collection based on route and page path.
+ *
+ * 设置集合跟踪。
+ * 根据路由和页面路径自动确定当前集合。
+ */
 export function setupCollection(): void {
   const routeLocale = useRouteLocale()
   const { page } = useData()
diff --git a/theme/src/client/composables/flyout.ts b/theme/src/client/composables/flyout.ts
index 8ee7f95e..d518a563 100644
--- a/theme/src/client/composables/flyout.ts
+++ b/theme/src/client/composables/flyout.ts
@@ -2,17 +2,42 @@ import type { Ref } from 'vue'
 import { onUnmounted, readonly, ref, watch } from 'vue'
 import { inBrowser } from '../utils/index.js'
 
+/**
+ * Options for useFlyout composable.
+ *
+ * useFlyout 组合式函数的选项。
+ */
 interface UseFlyoutOptions {
+  /** Element to track focus for / 要跟踪焦点的元素 */
   el: Ref<HTMLElement | undefined>
+  /** Callback when element gains focus / 元素获得焦点时的回调 */
   onFocus?: () => void
+  /** Callback when element loses focus / 元素失去焦点时的回调 */
   onBlur?: () => void
 }
 
+/**
+ * Currently focused element reference.
+ * Shared across all flyout instances.
+ *
+ * 当前聚焦元素的引用。
+ * 在所有弹出框实例之间共享。
+ */
 export const focusedElement: Ref<HTMLElement | undefined> = ref()
 
 let active = false
 let listeners = 0
 
+/**
+ * Use flyout focus tracking.
+ * Tracks focus state for dropdown menus and flyout components.
+ *
+ * 弹出框焦点跟踪。
+ * 跟踪下拉菜单和弹出框组件的焦点状态。
+ *
+ * @param options - Flyout options / 弹出框选项
+ * @returns Readonly reference to focus state / 焦点状态的只读引用
+ */
 export function useFlyout(options: UseFlyoutOptions): Readonly<Ref<boolean>> {
   const focus = ref(false)
 
@@ -47,16 +72,37 @@ export function useFlyout(options: UseFlyoutOptions): Readonly<Ref<boolean>> {
   return readonly(focus)
 }
 
+/**
+ * Activate global focus tracking.
+ * Adds focusin event listener to document.
+ *
+ * 激活全局焦点跟踪。
+ * 向文档添加 focusin 事件监听器。
+ */
 function activateFocusTracking() {
   document.addEventListener('focusin', handleFocusIn)
   active = true
   focusedElement.value = document.activeElement as HTMLElement
 }
 
+/**
+ * Deactivate global focus tracking.
+ * Removes focusin event listener from document.
+ *
+ * 停用全局焦点跟踪。
+ * 从文档移除 focusin 事件监听器。
+ */
 function deactivateFocusTracking() {
   document.removeEventListener('focusin', handleFocusIn)
 }
 
+/**
+ * Handle focusin event.
+ * Updates the focused element reference.
+ *
+ * 处理 focusin 事件。
+ * 更新聚焦元素引用。
+ */
 function handleFocusIn() {
   focusedElement.value = document.activeElement as HTMLElement
 }
diff --git a/theme/src/client/composables/icons.ts b/theme/src/client/composables/icons.ts
index d8a43243..a541e568 100644
--- a/theme/src/client/composables/icons.ts
+++ b/theme/src/client/composables/icons.ts
@@ -2,14 +2,29 @@ import type { Ref } from 'vue'
 import { icons } from '@internal/iconify'
 import { ref } from 'vue'
 
+/**
+ * Raw icons data structure from internal data.
+ *
+ * 来自内部数据的原始图标数据结构。
+ */
 interface IconsRawData {
+  /** Collection names / 集合名称 */
   co: string[]
+  /** Background icons by collection index / 按集合索引的背景图标 */
   bg: Record<number, string[]>
+  /** Mask icons by collection index / 按集合索引的遮罩图标 */
   mask: Record<number, string[]>
 }
 
+/**
+ * Processed icons data structure.
+ *
+ * 处理后的图标数据结构。
+ */
 interface IconsData {
+  /** List of background icons / 背景图标列表 */
   bg: string[]
+  /** List of mask icons / 遮罩图标列表 */
   mask: string[]
 }
 
@@ -17,6 +32,15 @@ type IconsDataRef = Ref<IconsData>
 
 const iconsData: IconsDataRef = ref(resolveIconsData(icons))
 
+/**
+ * Use icons data.
+ * Returns the processed icons data reference.
+ *
+ * 获取图标数据。
+ * 返回处理后的图标数据引用。
+ *
+ * @returns Icons data reference / 图标数据引用
+ */
 export const useIconsData = (): IconsDataRef => iconsData
 
 if (__VUEPRESS_DEV__ && (import.meta.webpackHot || import.meta.hot)) {
@@ -25,12 +49,31 @@ if (__VUEPRESS_DEV__ && (import.meta.webpackHot || import.meta.hot)) {
   }
 }
 
-// 旧版本内置图标别名，映射回 simple-icons 集合中的名称
+/**
+ * Fallback mappings for old icon aliases.
+ * Maps legacy icon names to their current equivalents.
+ *
+ * 旧版本内置图标别名的后备映射。
+ * 将旧图标名称映射到当前等效名称。
+ */
 export const socialFallbacks: Record<string, string> = {
   twitter: 'x',
   weibo: 'sinaweibo',
 }
 
+/**
+ * Resolve raw icons data to processed format.
+ * Converts indexed data to flat icon lists.
+ *
+ * 将原始图标数据解析为处理后的格式。
+ * 将索引数据转换为平面图标列表。
+ *
+ * @param data - Raw icons data / 原始图标数据
+ * @param data.co - Collection names / 集合名称
+ * @param data.bg - Background icons by collection index / 按集合索引的背景图标
+ * @param data.mask - Mask icons by collection index / 按集合索引的遮罩图标
+ * @returns Processed icons data / 处理后的图标数据
+ */
 export function resolveIconsData({ co, bg, mask }: IconsRawData): IconsData {
   return {
     bg: processIcons(co, bg),
@@ -38,6 +81,16 @@ export function resolveIconsData({ co, bg, mask }: IconsRawData): IconsData {
   }
 }
 
+/**
+ * Normalize icon to CSS class name.
+ * Returns the appropriate class name based on icon type.
+ *
+ * 将图标规范化为 CSS 类名。
+ * 根据图标类型返回适当的类名。
+ *
+ * @param icon - Icon name in format "collection:name" / 格式为 "collection:name" 的图标名称
+ * @returns CSS class name or empty string if not found / CSS 类名，如果未找到则返回空字符串
+ */
 export function normalizeIconClassname(icon: string): string {
   const [collect, name] = icon.split(':')
   const iconName = `vpi-${collect}-${name}`
@@ -48,6 +101,17 @@ export function normalizeIconClassname(icon: string): string {
   return ''
 }
 
+/**
+ * Process indexed icons into flat list.
+ * Converts collection-indexed data to "collection:icon" format.
+ *
+ * 将索引图标处理为平面列表。
+ * 将集合索引数据转换为 "collection:icon" 格式。
+ *
+ * @param collects - Array of collection names / 集合名称数组
+ * @param raw - Indexed icon data / 索引图标数据
+ * @returns Flat array of icon identifiers / 图标标识符的平面数组
+ */
 function processIcons(collects: string[], raw: Record<number, string[]>): string[] {
   const data: string[] = []
   for (const [key, list] of Object.entries(raw)) {
diff --git a/theme/src/client/composables/sidebar-data.ts b/theme/src/client/composables/sidebar-data.ts
index 6b2b556b..95b084f6 100644
--- a/theme/src/client/composables/sidebar-data.ts
+++ b/theme/src/client/composables/sidebar-data.ts
@@ -12,18 +12,51 @@ import { useRouteLocale } from 'vuepress/client'
 import { normalizeLink, normalizePrefix, resolveNavLink } from '../utils/index.js'
 import { useData } from './data.js'
 
+/**
+ * Sidebar data type - maps locale paths to sidebar configurations.
+ *
+ * 侧边栏数据类型 - 将语言环境路径映射到侧边栏配置。
+ */
 export type SidebarData = Record<string, ThemeSidebar>
 
+/**
+ * Reference type for sidebar data.
+ *
+ * 侧边栏数据的引用类型。
+ */
 export type SidebarDataRef = Ref<SidebarData>
+
+/**
+ * Reference type for auto-generated directory sidebar.
+ *
+ * 自动生成目录侧边栏的引用类型。
+ */
 export type AutoDirSidebarRef = Ref<ThemeSidebarItem[] | {
   link: string
   items: ThemeSidebarItem[]
 }>
+
+/**
+ * Reference type for auto-generated home data.
+ *
+ * 自动生成首页数据的引用类型。
+ */
 export type AutoHomeDataRef = Ref<Record<string, string>>
 
 const { __auto__, __home__, ...items } = sidebarRaw
 
+/**
+ * Global sidebar data reference.
+ *
+ * 全局侧边栏数据引用。
+ */
 export const sidebarData: SidebarDataRef = ref(items)
+
+/**
+ * Auto-generated directory sidebar reference.
+ *
+ * 自动生成目录侧边栏引用。
+ */
 export const autoDirSidebar: AutoDirSidebarRef = ref(__auto__)
 const autoHomeData: AutoHomeDataRef = ref(__home__)
 
@@ -38,6 +71,13 @@ if (__VUEPRESS_DEV__ && (import.meta.webpackHot || import.meta.hot)) {
 
 const sidebar: Ref<ResolvedSidebarItem[]> = ref([])
 
+/**
+ * Setup sidebar tracking.
+ * Automatically updates sidebar based on route and frontmatter changes.
+ *
+ * 设置侧边栏跟踪。
+ * 根据路由和 frontmatter 变化自动更新侧边栏。
+ */
 export function setupSidebar(): void {
   const { page, frontmatter } = useData()
 
@@ -67,19 +107,30 @@ export function setupSidebar(): void {
 }
 
 /**
- * Use sidebar data
+ * Use sidebar data.
+ * Returns the resolved sidebar items for the current page.
  *
- * 获取侧边栏数据
+ * 获取侧边栏数据。
+ * 返回当前页面的解析侧边栏项目。
+ *
+ * @returns Resolved sidebar items reference / 解析侧边栏项目引用
  */
 export function useSidebarData(): Ref<ResolvedSidebarItem[]> {
   return sidebar
 }
 
 /**
- * Get the `Sidebar` from sidebar option. This method will ensure to get correct
- * sidebar config from `MultiSideBarConfig` with various path combinations such
- * as matching `guide/` and `/guide/`. If no matching config was found, it will
- * return empty array.
+ * Get the sidebar configuration from sidebar options.
+ * Ensures correct sidebar config from MultiSideBarConfig with various path combinations.
+ * Returns empty array if no matching config is found.
+ *
+ * 从侧边栏选项获取侧边栏配置。
+ * 确保从 MultiSideBarConfig 获取正确的侧边栏配置，支持各种路径组合。
+ * 如果未找到匹配的配置，则返回空数组。
+ *
+ * @param routePath - Current route path / 当前路由路径
+ * @param routeLocal - Current route locale / 当前路由语言环境
+ * @returns Resolved sidebar items / 解析的侧边栏项目
  */
 export function getSidebar(routePath: string, routeLocal: string): ResolvedSidebarItem[] {
   const _sidebar = sidebarData.value[routeLocal]
@@ -123,6 +174,17 @@ export function getSidebar(routePath: string, routeLocal: string): ResolvedSideb
   return []
 }
 
+/**
+ * Resolve sidebar items from raw configuration.
+ * Converts string items and nested structures to resolved format.
+ *
+ * 从原始配置解析侧边栏项目。
+ * 将字符串项目和嵌套结构转换为解析格式。
+ *
+ * @param sidebarItems - Raw sidebar items / 原始侧边栏项目
+ * @param _prefix - URL prefix for nested items / 嵌套项目的 URL 前缀
+ * @returns Resolved sidebar items / 解析的侧边栏项目
+ */
 function resolveSidebarItems(
   sidebarItems: (string | ThemeSidebarItem)[],
   _prefix = '',
@@ -163,7 +225,14 @@ function resolveSidebarItems(
 }
 
 /**
- * Get or generate sidebar group from the given sidebar items.
+ * Get or generate sidebar groups from the given sidebar items.
+ * Groups consecutive items without children into a single group.
+ *
+ * 从给定的侧边栏项目获取或生成侧边栏分组。
+ * 将没有子项目的连续项目分组到单个组中。
+ *
+ * @param sidebar - Flat array of sidebar items / 平面侧边栏项目数组
+ * @returns Grouped sidebar items / 分组的侧边栏项目
  */
 export function getSidebarGroups(sidebar: ResolvedSidebarItem[]): ResolvedSidebarItem[] {
   const groups: ResolvedSidebarItem[] = []
@@ -188,6 +257,16 @@ export function getSidebarGroups(sidebar: ResolvedSidebarItem[]): ResolvedSideba
   return groups
 }
 
+/**
+ * Get the first link from sidebar items.
+ * Recursively searches through nested items to find the first link.
+ *
+ * 从侧边栏项目获取第一个链接。
+ * 递归搜索嵌套项目以找到第一个链接。
+ *
+ * @param sidebar - Sidebar items to search / 要搜索的侧边栏项目
+ * @returns First link found or empty string / 找到的第一个链接或空字符串
+ */
 export function getSidebarFirstLink(sidebar: ResolvedSidebarItem[]): string {
   for (const item of sidebar) {
     if (item.link)
diff --git a/theme/src/node/enhance.ts b/theme/src/node/enhance.ts
index 62dce38e..1a95af98 100644
--- a/theme/src/node/enhance.ts
+++ b/theme/src/node/enhance.ts
@@ -1,17 +1,39 @@
 /**
- * 此增强为临时性措施，vuepress/core 将会在下个版本中实现
- * 在 vuepress/core 下个版本是，应该删除此增强
+ * Temporary enhancement for VuePress app.
+ * This enhancement will be removed in the next version of vuepress/core.
+ *
+ * VuePress 应用的临时增强。
+ * 此增强将在 vuepress/core 的下一个版本中被移除。
  */
 
 import type { App } from 'vuepress'
 import { fs, hash } from 'vuepress/utils'
 
+/**
+ * Cache structure for writeTemp operations.
+ * Tracks content hash and writing promises for optimization.
+ *
+ * writeTemp 操作的缓存结构。
+ * 跟踪内容哈希和写入承诺以进行优化。
+ */
 interface WriteTempCache {
-  hash?: string // content hash
-  current?: Promise<void> // the current writing promise
-  next?: () => Promise<void> // the next writing promise
+  /** Content hash for change detection / 用于变更检测的内容哈希 */
+  hash?: string
+  /** Current writing promise / 当前写入承诺 */
+  current?: Promise<void>
+  /** Next writing promise to chain / 要链接的下一个写入承诺 */
+  next?: () => Promise<void>
 }
 
+/**
+ * Enhance the VuePress app with optimized writeTemp method.
+ * Implements caching and promise chaining for better performance.
+ *
+ * 使用优化的 writeTemp 方法增强 VuePress 应用。
+ * 实现缓存和承诺链接以获得更好的性能。
+ *
+ * @param app - VuePress application instance / VuePress 应用实例
+ */
 export function enhanceApp(app: App): void {
   // rewrite writeTemp to cache the writing promise
   const cache = new Map<string, WriteTempCache>()
diff --git a/theme/src/node/utils/createMatcher.ts b/theme/src/node/utils/createMatcher.ts
index d5a789d3..f514e482 100644
--- a/theme/src/node/utils/createMatcher.ts
+++ b/theme/src/node/utils/createMatcher.ts
@@ -2,6 +2,17 @@ import type { Matcher } from 'picomatch'
 import { toArray, uniq } from '@pengzhanbo/utils'
 import picomatch from 'picomatch'
 
+/**
+ * Resolve include and exclude patterns into pattern and ignore arrays.
+ * Converts various pattern formats into a standardized format for matching.
+ *
+ * 将 include 和 exclude 模式解析为 pattern 和 ignore 数组。
+ * 将各种模式格式转换为用于匹配的标准化格式。
+ *
+ * @param include - Patterns to include, can be string or array / 要包含的模式，可以是字符串或数组
+ * @param exclude - Patterns to exclude, can be string or array / 要排除的模式，可以是字符串或数组
+ * @returns Object containing pattern and ignore arrays / 包含 pattern 和 ignore 数组的对象
+ */
 export function resolveMatcherPattern(include?: string | string[], exclude?: string | string[]): {
   pattern: string[]
   ignore: string[]
@@ -26,6 +37,18 @@ export function resolveMatcherPattern(include?: string | string[], exclude?: str
   return { pattern, ignore }
 }
 
+/**
+ * Create a file matcher function using picomatch.
+ * Returns a function that tests if a file path matches the given patterns.
+ *
+ * 使用 picomatch 创建文件匹配器函数。
+ * 返回一个测试文件路径是否匹配给定模式的函数。
+ *
+ * @param include - Patterns to include / 要包含的模式
+ * @param exclude - Patterns to exclude / 要排除的模式
+ * @param cwd - Current working directory for relative path matching / 用于相对路径匹配的当前工作目录
+ * @returns Matcher function that tests file paths / 测试文件路径的匹配器函数
+ */
 export function createMatcher(include?: string | string[], exclude?: string | string[], cwd?: string): Matcher {
   exclude = ['**/node_modules/**', '**/.vuepress/**', ...toArray(exclude)]
   const { pattern, ignore } = resolveMatcherPattern(include, exclude)
diff --git a/theme/src/node/utils/pinyin.ts b/theme/src/node/utils/pinyin.ts
index 586f21b4..393baba7 100644
--- a/theme/src/node/utils/pinyin.ts
+++ b/theme/src/node/utils/pinyin.ts
@@ -4,17 +4,30 @@ import { interopDefault } from './interopDefault'
 let _pinyin: typeof import('pinyin-pro').pinyin | null = null
 
 /**
- * Check if pinyin-pro package is installed
+ * Check if pinyin-pro package is installed.
+ * Used for Chinese character to pinyin conversion.
  *
- * 检查是否安装了 pinyin-pro 包
+ * 检查是否安装了 pinyin-pro 包。
+ * 用于中文字符转拼音功能。
  */
 export const hasPinyin = isPackageExists('pinyin-pro')
 const hasPinyinData = isPackageExists('@pinyin-pro/data')
 
 /**
- * Get pinyin function
+ * Get the pinyin conversion function.
+ * Dynamically imports pinyin-pro and its data if available.
+ * Caches the result for subsequent calls.
  *
- * 获取拼音函数
+ * 获取拼音转换函数。
+ * 动态导入 pinyin-pro 及其数据（如果可用）。
+ * 缓存结果以供后续调用使用。
+ *
+ * @returns Pinyin function or null if not installed / 拼音函数，如果未安装则返回 null
+ * @example
+ * const pinyin = await getPinyin()
+ * if (pinyin) {
+ *   const result = pinyin('中文') // 'zhōng wén'
+ * }
  */
 export async function getPinyin() {
   if (hasPinyin && !_pinyin) {
diff --git a/theme/src/node/utils/resolveContent.ts b/theme/src/node/utils/resolveContent.ts
index 9036b1f7..d2a11c29 100644
--- a/theme/src/node/utils/resolveContent.ts
+++ b/theme/src/node/utils/resolveContent.ts
@@ -1,12 +1,36 @@
 import type { App } from 'vuepress'
 
+/**
+ * Options for resolving content to be written to a temporary file.
+ *
+ * 解析要写入临时文件的内容的选项。
+ */
 export interface ResolveContentOptions {
+  /** Variable name for the exported content / 导出内容的变量名 */
   name: string
+  /** Content to be serialized / 要序列化的内容 */
   content: any
+  /** Content to prepend before the export / 在导出之前添加的内容 */
   before?: string
+  /** Content to append after the export / 在导出之后添加的内容 */
   after?: string
 }
 
+/**
+ * Resolve content string for writing to temporary files.
+ * Generates JavaScript module content with HMR support in development mode.
+ *
+ * 解析用于写入临时文件的内容字符串。
+ * 在开发模式下生成带有 HMR 支持的 JavaScript 模块内容。
+ *
+ * @param app - VuePress application instance / VuePress 应用实例
+ * @param options - Content resolution options / 内容解析选项
+ * @param options.name - Variable name for the exported content / 导出内容的变量名
+ * @param options.content - Content to be serialized / 要序列化的内容
+ * @param options.before - Content to prepend before the export / 在导出之前添加的内容
+ * @param options.after - Content to append after the export / 在导出之后添加的内容
+ * @returns Resolved content string / 解析后的内容字符串
+ */
 export function resolveContent(app: App, { name, content, before, after }: ResolveContentOptions): string {
   content = `${before ? `${before}\n` : ''}export const ${name} = ${JSON.stringify(content)}${after ? `\n${after}` : ''}`
 
diff --git a/theme/src/node/utils/translate.ts b/theme/src/node/utils/translate.ts
index 56f14cbe..1db1ceb9 100644
--- a/theme/src/node/utils/translate.ts
+++ b/theme/src/node/utils/translate.ts
@@ -1,6 +1,9 @@
 /**
- * 简单的内置 中 / 英 翻译转换工具，
- * 用于在需要 Log 的场景，根据 app.lang 设置输出语言
+ * Simple built-in Chinese/English translation utility.
+ * Used for log output based on app.lang settings.
+ *
+ * 简单的内置中/英翻译转换工具。
+ * 用于在需要日志输出的场景，根据 app.lang 设置输出语言。
  */
 
 import { isEmptyObject } from '@pengzhanbo/utils'
@@ -11,6 +14,15 @@ type TranslateData = Record<string, string>
 
 let lang: TranslateLang = 'en'
 
+/**
+ * Set the translation language based on the current locale.
+ * Supports Chinese variants (zh-CN, zh, zh-Hans, zh-Hant) and defaults to English.
+ *
+ * 根据当前区域设置翻译语言。
+ * 支持中文变体（zh-CN、zh、zh-Hans、zh-Hant），默认为英文。
+ *
+ * @param current - Current locale string / 当前区域设置字符串
+ */
 export function setTranslateLang(current: string): void {
   if (['zh-CN', 'zh', 'zh-Hans', 'zh-Hant'].includes(current)) {
     lang = 'zh'
@@ -20,6 +32,24 @@ export function setTranslateLang(current: string): void {
   }
 }
 
+/**
+ * Create a translation function with locale support.
+ * Returns a function that translates keys to localized strings with optional interpolation.
+ *
+ * 创建支持本地化的翻译函数。
+ * 返回一个将键翻译为本地化字符串的函数，支持可选的插值。
+ *
+ * @template Data - Data type for interpolation / 插值数据类型
+ * @template Locale - Locale type for translations / 翻译区域类型
+ * @param locales - Locale data for each language / 每种语言的区域数据
+ * @returns Translation function / 翻译函数
+ * @example
+ * const t = createTranslate({
+ *   zh: { hello: '你好，{{name}}！' },
+ *   en: { hello: 'Hello, {{name}}!' }
+ * })
+ * t('hello', { name: 'World' }) // '你好，World！' or 'Hello, World!'
+ */
 export function createTranslate<
   Data extends TranslateData = TranslateData,
   Locale extends TranslateLocale = TranslateLocale,
diff --git a/theme/src/node/utils/writeTemp.ts b/theme/src/node/utils/writeTemp.ts
index 722cc19a..81d61f1a 100644
--- a/theme/src/node/utils/writeTemp.ts
+++ b/theme/src/node/utils/writeTemp.ts
@@ -1,11 +1,33 @@
 /**
- * 仅内容发生变更时，才写入临时文件
+ * Write to temporary file only when content changes.
+ * Optimizes file I/O by caching content hashes.
+ *
+ * 仅内容发生变更时，才写入临时文件。
+ * 通过缓存内容哈希优化文件 I/O。
  */
 import type { App } from 'vuepress'
 import { hash } from './hash.js'
 
+/**
+ * Cache for content hashes to detect changes.
+ * Maps file paths to their content hashes.
+ *
+ * 内容哈希缓存，用于检测变更。
+ * 将文件路径映射到其内容哈希。
+ */
 export const contentHash: Map<string, string> = new Map()
 
+/**
+ * Write content to a temporary file if it has changed.
+ * Uses hash comparison to avoid unnecessary writes.
+ *
+ * 如果内容已更改，则写入临时文件。
+ * 使用哈希比较避免不必要的写入。
+ *
+ * @param app - VuePress application instance / VuePress 应用实例
+ * @param filepath - Relative path to the temporary file / 临时文件的相对路径
+ * @param content - Content to write / 要写入的内容
+ */
 export async function writeTemp(
   app: App,
   filepath: string,
@@ -18,6 +40,16 @@ export async function writeTemp(
   }
 }
 
+/**
+ * Set or clear the content hash for a file.
+ * Used to manually manage the hash cache.
+ *
+ * 设置或清除文件的内容哈希。
+ * 用于手动管理哈希缓存。
+ *
+ * @param filepath - File path to manage / 要管理的文件路径
+ * @param content - Content to hash, or empty to clear / 要哈希的内容，或为空以清除
+ */
 export function setContentHash(filepath: string, content: string): void {
   if (content) {
     const currentHash = hash(content)