chore: translate English comments to Chinese

Author: jin-sir

src/checkBrowserSupport/compareVersions.ts

@@ -1,10 +1,10 @@
 /**
- * Compare two version numbers
+ * 比较两个版本号
  *
  * @private
- * @param version1 First version number
- * @param version2 Second version number
- * @returns {number} Returns 1 if version1 > version2, returns -1 if version1 < version2, returns 0 if equal
+ * @param version1 第一个版本号
+ * @param version2 第二个版本号
+ * @returns {number} 当 version1 > version2 时返回 1 ，当 version1 < version2 时返回 -1 ，相等时返回 0
  */
 function compareVersions(version1: string, version2: string): number {
     const v1Parts = version1.split('.').map(Number);

src/checkBrowserSupport/index.ts

@@ -10,36 +10,38 @@ export interface IBrowser {
 }
 
 /**
- * Checks if the current browser meets minimum version requirements
+ * 检查当前浏览器是否满足最低版本要求
  *
- * @category Environment Detection
+ * @category 环境检测
  * @description
- * A utility function that validates whether the current browser satisfies specified minimum version
- * requirements. The function accepts an array of browser specifications and performs version
- * comparison checks.
+ * 该函数会检查当前浏览器的版本是否大于或等于指定的最低版本要求。
+ * 如果当前浏览器不在指定的浏览器列表中，将返回 false。
  *
- * @param {IBrowser[]} browsers - An array of browser specifications, where each specification contains:
- * - `name`: Browser name (e.g., 'chrome', 'firefox', 'safari')
- * - `version`: Minimum required version number
- * @returns {boolean} Returns `true` if current browser meets version requirements, `false` otherwise
+ * @param {IBrowser[]} browsers - 浏览器最低版本配置数组
+ * - `name`: 浏览器名称，不区分大小写（如：'chrome'、'firefox'、'safari'等）
+ * - `version`: 最低版本号要求，支持字符串或数字格式（如：'80'、75、'13.0.1'等）
+ * @returns {boolean} 返回检查结果
+ * - 当前浏览器版本满足要求时，返回 `true`
+ * - 当前浏览器版本不满足要求或浏览器类型不匹配时，返回 `false`
+ * - 传入空数组时，返回 `false`
  *
  * @example
  * ```typescript
  * import { checkBrowserSupport } from 'dt-utils';
  *
- * // Single browser check
+ * // 检查单个浏览器版本要求
  * checkBrowserSupport([
  *   { name: 'chrome', version: '80' }
  * ]);
  *
- * // Multiple browser support
+ * // 检查多个浏览器版本要求（满足其中之一即可）
  * checkBrowserSupport([
  *   { name: 'chrome', version: '80' },
  *   { name: 'firefox', version: '75' },
  *   { name: 'safari', version: '13' }
  * ]);
  *
- * // Version can be string or number
+ * // 版本号支持字符串或数字格式
  * checkBrowserSupport([
  *   { name: 'chrome', version: 80 },
  *   { name: 'firefox', version: '75.0.1' }

src/copy/createFakeElement.ts

@@ -1,19 +1,17 @@
 /**
- * Creates a temporary textarea element for clipboard operations
- * This element is positioned off-screen and used as an intermediary for copying text
- * when the Clipboard API is not available
+ * 创建一个用于剪贴板操作的临时文本区域元素
  *
  * @private
- * @param {string} value - Text content to be copied to clipboard
- * @returns {HTMLTextAreaElement} A configured textarea element ready for clipboard operations
+ * @param {string} value - 要复制到剪贴板的文本内容
+ * @returns {HTMLTextAreaElement} 一个配置好的、可用于剪贴板操作的文本区域元素
  */
 function createFakeElement(value: string): HTMLTextAreaElement {
     const isRTL = document.documentElement.getAttribute('dir') === 'rtl';
     const fakeElement = document.createElement('textarea');
 
     /**
-     * Prevent zooming on iOS and reset box model
-     * Move element out of screen horizontally
+     * 防止在iOS上缩放并重置盒模型
+     * 将元素水平移出屏幕
      */
     Object.assign(fakeElement.style, {
         visibility: 'hidden',

src/copy/index.ts

@@ -1,27 +1,27 @@
 import createFakeElement from './createFakeElement';
 /**
- * A robust cross-browser clipboard utility function.
+ * 浏览器剪贴板复制工具函数。
  *
  * @category Utils
  * @description
- * This function provides a consistent and reliable way to copy text to the clipboard across different browsers.
- * It leverages the modern Clipboard API when available, falling back to the execCommand('copy') method for legacy browsers.
+ * 提供一个一致且可靠的方式来在不同浏览器中复制文本到剪贴板。
+ * 它优先使用现代的 Clipboard API，当不可用时会降级使用 execCommand('copy') 方法来支持旧版浏览器。
  *
- * @param {string} text - The text content to copy
- * @returns {Promise<boolean>} Copy operation result
- *   - Resolves to true if copy succeeds
- *   - Resolves to false if copy fails
+ * @param {string} text - 要复制的文本内容
+ * @returns {Promise<boolean>} 复制操作结果
+ *   - 复制成功时返回 true
+ *   - 复制失败时返回 false
  *
  * @example
  * ```typescript
  * import { copy } from 'dt-utils';
  *
- * // Simple copy
+ * // 简单复制
  * const text = "Hello, clipboard!";
  * const success = await copy(text);
  * console.log(success ? "Copied!" : "Copy failed");
  *
- * // Copy with error handling
+ * // 带错误处理的复制
  * try {
  *   const text = "Sensitive data";
  *   if (await copy(text)) {
@@ -33,7 +33,7 @@ import createFakeElement from './createFakeElement';
  *   handleError(error);
  * }
  *
- * // Copy in button click handler
+ * // 在按钮点击处理程序中复制
  * button.addEventListener('click', async () => {
  *   const success = await copy('Click to copy text');
  *   button.textContent = success ? 'Copied!' : 'Try again';

src/downloadFile/index.ts

@@ -5,36 +5,41 @@ export interface DownloadOptions extends Omit<RequestInit, 'body' | 'method'> {
 }
 
 /**
- * Downloads a file from the specified URL using a POST request
+ * 从指定 URL 下载文件
  *
  * @category Utils
  * @description
- * This function sends a POST request to the specified URL with the provided data.
- * The response is expected to be a file. If the response is successful, the file is downloaded
- * with the specified filename. If the response is not successful, an error is thrown.
+ * 通过向指定 URL 发送 HTTP 请求（默认为 POST 方法）来下载文件。
  *
- * Note: This function assumes that the server responds with a file. If the server responds
- * with a different content type, an error will be thrown.
+ * 主要功能：
+ * - 支持自定义请求数据和下载文件名
+ * - 自动从响应头获取文件名（如果未指定）
+ * - 处理下载失败的错误情况
  *
- * @param {string} url - The URL to download the file from
- * @param {RequestData} data - The data to be sent in the request body (optional)
- * @param {DownloadOptions} options - Request options including optional fileName
- * @returns {Promise<Response>} Promise that resolves with the fetch Response object
+ * 注意事项：
+ * - 服务端必须返回文件流，若返回 JSON 格式将抛出错误
+ * - 下载失败时会返回原始响应对象以便进一步处理
+ * - 仅支持浏览器环境，依赖 document API
+ *
+ * @param {string} url - 下载文件的目标 URL
+ * @param {RequestData} data - POST 请求携带的数据对象（可选）
+ * @param {DownloadOptions} options - 下载配置项，可包含自定义文件名和其他 fetch 选项
+ * @returns {Promise<Response>} 返回原始响应对象的 Promise
  *
  * @example
  * ```typescript
  * import { downloadFile } from 'dt-utils';
  *
- * // Basic usage
+ * // 基本用法
  * await downloadFile('https://api.example.com/download', { id: 123 });
  *
- * // With custom filename
+ * // 使用自定义文件名
  * await downloadFile('https://api.example.com/download',
  *   { id: 123 },
  *   { fileName: 'custom.pdf' }
  * );
  *
- * // With additional fetch options
+ * // 使用额外的 fetch 选项
  * await downloadFile('https://api.example.com/download',
  *   { id: 123 },
  *   {

src/formatBytes/index.ts

@@ -3,42 +3,48 @@ type ByteUnit = 'B' | 'KB' | 'MB' | 'GB' | 'TB' | 'PB' | 'EB' | 'ZB' | 'YB';
 type FormattedBytes = `${number} ${ByteUnit}` | 'Invalid value' | '0 B';
 
 /**
- * Formats a numeric byte value into a string with appropriate size units.
+ * 将字节数值格式化为带单位的字符串表示。
  *
- * @category Formatting
+ * @category 格式化
  * @description
- * Converts a byte value into a human-readable string representation with the most appropriate
- * size unit, ranging from Bytes (B) to Yottabytes (YB). The conversion uses 1024 as the base
- * unit multiplier (1 KB = 1024 B).
+ * 自动将字节数值转换为最适合的单位表示形式，支持从字节(B)到尧字节(YB)的单位范围。
+ * 转换采用二进制换算(1024进制)，即:
+ * - 1 KB = 1024 B
+ * - 1 MB = 1024 KB
+ * - 以此类推...
  *
- * @param {number} value - The numeric value in bytes to format
- * @param {number} [decimals=2] - The number of decimal places to round to (defaults to 2)
- * @returns {FormattedBytes} A formatted string in the format "value unit" (e.g. "1.5 MB") or error message
+ * 特殊情况处理:
+ * - 当输入为负数、NaN或Infinity时，返回"Invalid value"
+ * - 当输入为0时，返回"0 B"
+ *
+ * @param {number} value - 要格式化的字节数值
+ * @param {number} [decimals=2] - 结果保留的小数位数，默认为2位
+ * @returns {FormattedBytes} 格式化后的字符串，例如"1.5 MB"。若输入无效则返回"Invalid value"
  *
  * @example
  * ```typescript
  * import { formatBytes } from 'dt-utils';
  *
- * // Basic formatting
+ * // 基本格式化
  * formatBytes(1024)        // => "1 KB"
  * formatBytes(1536)        // => "1.5 KB"
  * formatBytes(1048576)     // => "1 MB"
  *
- * // Specifying decimal places
+ * // 指定小数位数
  * formatBytes(1234567, 1)  // => "1.2 MB"
  * formatBytes(1234567, 3)  // => "1.178 MB"
  *
- * // Large numbers
+ * // 大数值
  * formatBytes(1.5e12)      // => "1.36 TB"
  *
- * // Edge cases
+ * // 边界情况
  * formatBytes(0)           // => "0 B"
  * formatBytes(-1024)       // => "Invalid value"
  * formatBytes(Infinity)    // => "Invalid value"
  * formatBytes(NaN)         // => "Invalid value"
  * ```
  *
- * @see {@link https://en.wikipedia.org/wiki/Byte#Multiple-byte_units} for more information about byte units
+ * @see {@link https://en.wikipedia.org/wiki/Byte#Multiple-byte_units} 查看更多关于字节单位的信息
  */
 const formatBytes = (value: number, decimals = 2): FormattedBytes => {
     if (!Number.isFinite(value)) return 'Invalid value';