From 92f09a42906828057ec5a0b66a3d951ac9866923 Mon Sep 17 00:00:00 2001
From: Harvey Zhao <laozhaochaguan@gmail.com>
Date: Sun, 8 Mar 2026 13:15:13 +0800
Subject: [PATCH] Refactor documentation for clarity and consistency

- Updated descriptions and terminology across various component documentation files for improved clarity.
- Changed headings and section titles for better readability and consistency.
- Enhanced the language and structure of the documentation to provide clearer guidance on usage and configuration.
- Removed the `fix-docs.js` script as its functionality has been integrated into the translation process.
- Improved the translation script to handle Markdown code block issues and added retry logic for API calls.
---
 .../docs/en/advanced/built-in.md              |  26 +--
 .../docs/en/advanced/class.md                 |  12 +-
 .../docs/en/advanced/event.md                 | 134 ++++++-------
 .../docs/en/advanced/global.md                |  48 ++---
 .../docs/en/advanced/plugin.md                |   8 +-
 .../docs/en/advanced/property.md              |  70 +++----
 .../docs/en/component/contextmenu.md          |   6 +-
 .../docs/en/component/controls.md             |  26 +--
 .../docs/en/component/layers.md               |   2 +-
 .../docs/en/component/setting.md              |  72 +++----
 packages/artplayer-vitepress/docs/en/index.md |  26 +--
 .../artplayer-vitepress/docs/en/start/i18n.md |  10 +-
 .../docs/en/start/option.md                   |  92 ++++-----
 scripts/fix-docs.js                           |  73 -------
 scripts/trans-docs.js                         | 180 ++++++++++++++----
 15 files changed, 413 insertions(+), 372 deletions(-)
 delete mode 100644 scripts/fix-docs.js

diff --git a/packages/artplayer-vitepress/docs/en/advanced/built-in.md b/packages/artplayer-vitepress/docs/en/advanced/built-in.md
index 91e7bc5de..891023e78 100644
--- a/packages/artplayer-vitepress/docs/en/advanced/built-in.md
+++ b/packages/artplayer-vitepress/docs/en/advanced/built-in.md
@@ -49,7 +49,7 @@ This is the definition of all `DOM` elements: [artplayer/types/template.d.ts](ht
 
 ## `events`
 
-Manages all `DOM` events for the player. It essentially proxies `addEventListener` and `removeEventListener`. When using the following methods to handle events, the event will be automatically destroyed when the player is destroyed.
+Manages all `DOM` events for the player. It essentially proxies `addEventListener` and `removeEventListener`. When using the following methods to handle events, the events will also be automatically destroyed when the player is destroyed.
 
 - The `proxy` method is used to proxy `DOM` events.
 - The `hover` method is used to proxy custom `hover` events.
@@ -77,7 +77,7 @@ art.events.hover(container, (event) => {
 
 :::warning Note
 
-If you need `DOM` events that only exist during the player's lifecycle, it is strongly recommended to use these functions to avoid memory leaks.
+If you need `DOM` events that should only exist during the player's lifecycle, it is strongly recommended to use these functions to avoid memory leaks.
 
 :::
 
@@ -86,10 +86,10 @@ If you need `DOM` events that only exist during the player's lifecycle, it is st
 Manages the player's local storage.
 
 - The `name` property is used to set the cache `key`.
-- The `set` method is used to set a cache value.
-- The `get` method is used to get a cache value.
-- The `del` method is used to delete a cache value.
-- The `clear` method is used to clear all cache.
+- The `set` method is used to set a cache.
+- The `get` method is used to retrieve a cache.
+- The `del` method is used to delete a cache.
+- The `clear` method is used to clear all caches.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -151,7 +151,7 @@ console.info(art.icons.loading);
 
 Manages the player's `i18n`.
 
-- The `get` method is used to get an `i18n` value.
+- The `get` method is used to retrieve an `i18n` value.
 - The `update` method is used to update the `i18n` object.
 
 <div className="run-code">▶ Run Code</div>
@@ -173,7 +173,7 @@ art.i18n.update({
 
 :::warning
 
-Using `art.i18n.update` can only update the `i18n` after instantiation. If you want to update the `i18n` before instantiation, please use the `i18n` option in the basic options.
+Using `art.i18n.update` can only update the `i18n` after instantiation. If you want to update `i18n` before instantiation, please use the `i18n` option in the basic settings.
 
 :::
 
@@ -207,8 +207,8 @@ Manages the player's layers.
 - The `add` method is used to dynamically add a layer.
 - The `remove` method is used to dynamically remove a layer.
 - The `update` method is used to dynamically update a layer.
-- The `show` property is used to set whether all layers are visible.
-- The `toggle` method is used to toggle the visibility of all layers.
+- The `show` property is used to set whether all layers are displayed.
+- The `toggle` method is used to toggle the display of all layers.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -229,7 +229,7 @@ art.on('ready', () => {
 });
 ```
 
-:::warning Refer to the following address for `Component Configuration`:
+:::warning For `Component Configuration`, please refer to:
 
 [/component/layers.html](/component/layers.html)
 
@@ -469,7 +469,7 @@ art.on('ready', () => {
 });
 ```
 
-:::warning For the `Settings Panel`, please refer to:
+:::warning For `Settings Panel`, please refer to
 
 [/component/setting.html](/component/setting.html)
 
@@ -477,7 +477,7 @@ art.on('ready', () => {
 
 ## `plugins`
 
-Manages the player's plugin functionality, with only the `add` method for dynamically adding plugins
+Manages the player's plugin functionality, with only one method `add` for dynamically adding plugins
 
 <div className="run-code">▶ Run Code</div>
 
diff --git a/packages/artplayer-vitepress/docs/en/advanced/class.md b/packages/artplayer-vitepress/docs/en/advanced/class.md
index 77d5e3f51..d3c9b807c 100644
--- a/packages/artplayer-vitepress/docs/en/advanced/class.md
+++ b/packages/artplayer-vitepress/docs/en/advanced/class.md
@@ -1,10 +1,10 @@
 # Static Properties
 
-Here, `Static Properties` refer to the `top-level properties` mounted on the `constructor function`, which are very rarely used.
+Here, `static properties` refer to the `first-level properties` attached to the `constructor`, which are rarely used.
 
 ## `instances`
 
-Returns an array of all player instances. This property can be useful when you need to manage multiple player instances simultaneously.
+Returns an array of all player instances. This property can be useful when you need to manage multiple players simultaneously.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -41,7 +41,7 @@ console.info(Artplayer.env);
 
 ## `build`
 
-Returns the build time of the player.
+Returns the build timestamp of the player.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -87,7 +87,7 @@ console.info(Artplayer.scheme);
 
 ## `Emitter`
 
-Returns the constructor function for the event emitter.
+Returns the constructor of the event emitter.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -107,7 +107,7 @@ console.info(Artplayer.validator);
 
 ## `kindOf`
 
-Returns the utility function for type detection.
+Returns the type detection utility function.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -127,7 +127,7 @@ console.info(Artplayer.html);
 
 ## `option`
 
-Returns the default options for the player.
+Returns the default options of the player.
 
 <div className="run-code">▶ Run Code</div>
 
diff --git a/packages/artplayer-vitepress/docs/en/advanced/event.md b/packages/artplayer-vitepress/docs/en/advanced/event.md
index bf52cc523..70a2e6033 100644
--- a/packages/artplayer-vitepress/docs/en/advanced/event.md
+++ b/packages/artplayer-vitepress/docs/en/advanced/event.md
@@ -1,8 +1,8 @@
 # Instance Events
 
-Player events are divided into two types: `native events` (prefixed with `video:`) and `custom events`.
+Player events are divided into two types: `native events` of the video (prefixed with `video:`), and `custom events`.
 
-Listen to an event:
+Listening to events:
 
 <div className="run-code">▶ Run Code</div>
 
@@ -17,7 +17,7 @@ art.on('video:canplay', () => {
 });
 ```
 
-Listen to an event only once:
+Listening to an event only once:
 
 <div className="run-code">▶ Run Code</div>
 
@@ -32,7 +32,7 @@ art.once('video:canplay', () => {
 });
 ```
 
-Manually trigger an event:
+Manually triggering an event:
 
 <div className="run-code">▶ Run Code</div>
 
@@ -45,7 +45,7 @@ var art = new Artplayer({
 art.emit('focus');
 ```
 
-Remove an event listener:
+Removing an event:
 
 <div className="run-code">▶ Run Code</div>
 
@@ -71,7 +71,7 @@ art.on('ready', onReady);
 
 ## `ready`
 
-Triggered when the player is ready for the first time
+Triggered when the player is ready for the first time.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -88,7 +88,7 @@ art.on('ready', () => {
 
 ## `restart`
 
-Triggered when the player switches URL and becomes playable
+Triggered when the player switches URLs and becomes ready to play.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -109,7 +109,7 @@ art.on('restart', (url) => {
 
 ## `pause`
 
-Triggered when the player is paused
+Triggered when the player is paused.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -126,7 +126,7 @@ art.on('pause', () => {
 
 ## `play`
 
-Triggered when the player starts playing
+Triggered when the player starts playing.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -143,7 +143,7 @@ art.on('play', () => {
 
 ## `hotkey`
 
-Triggered when a hotkey is pressed on the player
+Triggered when a player hotkey is pressed.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -160,7 +160,7 @@ art.on('hotkey', (event) => {
 
 ## `destroy`
 
-Triggered when the player is destroyed
+Triggered when the player is destroyed.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -181,7 +181,7 @@ art.on('destroy', () => {
 
 ## `focus`
 
-Triggered when the player gains focus
+Triggered when the player gains focus.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -198,7 +198,7 @@ art.on('focus', (event) => {
 
 ## `blur`
 
-Triggered when the player loses focus
+Triggered when the player loses focus.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -215,7 +215,7 @@ art.on('blur', (event) => {
 
 ## `dblclick`
 
-Triggered when the player is double-clicked
+Triggered when the player is double-clicked.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -232,7 +232,7 @@ art.on('dblclick', (event) => {
 
 ## `click`
 
-Triggered when the player is clicked
+Triggered when the player is clicked.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -249,7 +249,7 @@ art.on('click', (event) => {
 
 ## `error`
 
-Triggered when an error occurs while loading the video
+Triggered when an error occurs while the player is loading a video.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -267,7 +267,7 @@ art.on('error', (error, reconnectTime) => {
 
 ## `hover`
 
-Triggered when the mouse enters or leaves the player
+Triggered when the mouse enters or leaves the player.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -284,7 +284,7 @@ art.on('hover', (state, event) => {
 
 ## `mousemove`
 
-Triggered when the mouse moves over the player
+Triggered when the mouse moves over the player.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -301,7 +301,7 @@ art.on('mousemove', (event) => {
 
 ## `resize`
 
-Triggered when the player's dimensions change
+Triggered when the player's dimensions change.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -318,7 +318,7 @@ art.on('resize', () => {
 
 ## `view`
 
-Triggered when the player enters or leaves the viewport
+Triggered when the player enters the viewport.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -335,7 +335,7 @@ art.on('view', (state) => {
 
 ## `lock`
 
-Triggered when the lock state changes on mobile devices
+Triggered when the lock state changes on mobile devices.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -353,7 +353,7 @@ art.on('lock', (state) => {
 
 ## `aspectRatio`
 
-Triggered when the player's aspect ratio changes
+Triggered when the player's aspect ratio changes.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -372,7 +372,7 @@ art.on('aspectRatio', (aspectRatio) => {
 
 ## `autoHeight`
 
-Triggered when the player automatically adjusts its height
+Triggered when the player's height is automatically set.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -393,7 +393,7 @@ art.on('autoHeight', (height) => {
 
 ## `autoSize`
 
-Triggered when the player automatically adjusts its size
+Triggered when the player's size is automatically set.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -411,7 +411,7 @@ art.on('autoSize', () => {
 
 ## `flip`
 
-Triggered when the player is flipped
+Triggered when the player is flipped.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -430,7 +430,7 @@ art.on('flip', (flip) => {
 
 ## `fullscreen`
 
-Triggered when the player enters or exits window fullscreen mode
+Triggered when the player enters or exits windowed fullscreen mode.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -448,7 +448,7 @@ art.on('fullscreen', (state) => {
 
 ## `fullscreenError`
 
-Triggered when a window fullscreen error occurs
+Triggered when a windowed fullscreen error occurs.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -469,7 +469,7 @@ art.on('fullscreenError', (event) => {
 
 ## `fullscreenWeb`
 
-Triggered when the player enters or exits web fullscreen mode
+Triggered when the player enters or exits web fullscreen mode.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -487,7 +487,7 @@ art.on('fullscreenWeb', (state) => {
 
 ## `mini`
 
-Triggered when the player enters or exits mini mode
+Triggered when the player enters or exits mini mode.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -508,7 +508,7 @@ art.on('mini', (state) => {
 
 ## `pip`
 
-Triggered when the player enters or exits picture-in-picture mode
+Triggered when the player enters or exits Picture-in-Picture mode.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -527,7 +527,7 @@ art.on('pip', (state) => {
 
 ## `screenshot`
 
-Triggered when the player captures a screenshot
+Triggered when the player takes a screenshot.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -545,7 +545,7 @@ art.on('screenshot', (dataUri) => {
 
 ## `seek`
 
-Triggered when the player performs a time seek
+Triggered when the player performs a time seek.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -562,7 +562,7 @@ art.on('seek', (currentTime) => {
 
 ## `subtitleOffset`
 
-Triggered when subtitle offset changes in the player
+Triggered when the subtitle offset changes in the player.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -584,7 +584,7 @@ art.on('subtitleOffset', (offset) => {
 
 ## `subtitleBeforeUpdate`
 
-Triggered before subtitles are updated
+Triggered before subtitles are updated.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -604,7 +604,7 @@ art.on('subtitleBeforeUpdate', (cues) => {
 
 ## `subtitleAfterUpdate`
 
-Triggered after subtitles are updated
+Triggered after subtitles are updated.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -624,7 +624,7 @@ art.on('subtitleAfterUpdate', (cues) => {
 
 ## `subtitleLoad`
 
-Triggered when subtitles are loaded
+Triggered when subtitles are loaded.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -644,7 +644,7 @@ art.on('subtitleLoad', (option, cues) => {
 
 ## `info`
 
-Triggered when the info panel is shown or hidden
+Triggered when the info panel is shown or hidden.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -661,7 +661,7 @@ art.on('info', (state) => {
 
 ## `layer`
 
-Triggered when custom layers are shown or hidden
+Triggered when a custom layer is shown or hidden.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -678,7 +678,7 @@ art.on('layer', (state) => {
 
 ## `loading`
 
-Triggered when the loader is shown or hidden
+Triggered when the loader is shown or hidden.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -695,7 +695,7 @@ art.on('loading', (state) => {
 
 ## `mask`
 
-Triggered when the mask layer is shown or hidden
+Triggered when the mask layer is shown or hidden.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -712,7 +712,7 @@ art.on('mask', (state) => {
 
 ## `subtitle`
 
-Triggered when the subtitle layer is shown or hidden
+Triggered when the subtitle layer is shown or hidden.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -729,7 +729,7 @@ art.on('subtitle', (state) => {
 
 ## `contextmenu`
 
-Triggered when the context menu is shown or hidden
+Triggered when the context menu is shown or hidden.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -746,7 +746,7 @@ art.on('contextmenu', (state) => {
 
 ## `control`
 
-Triggered when the controls are shown or hidden
+Triggered when the control bar is shown or hidden.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -763,7 +763,7 @@ art.on('control', (state) => {
 
 ## `setting`
 
-Triggered when the settings panel is shown or hidden
+Triggered when the settings panel is shown or hidden.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -782,7 +782,7 @@ art.on('setting', (state) => {
 
 ## `muted`
 
-Triggered when the mute state changes
+Triggered when the muted state changes.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -799,7 +799,7 @@ art.on('muted', (state) => {
 
 ## `keydown`
 
-Listens for `keydown` events from the `document`
+Listens for the `keydown` event from the `document`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -816,84 +816,84 @@ art.on('keydown', (event) => {
 
 ## `video:canplay`
 
-The browser can start playing the media, but estimates there isn't enough data to play through to the end without having to stop for further buffering
+The browser can start playing the media, but estimates there is not enough data to play through to the end without stopping for further buffering.
 
 ## `video:canplaythrough`
 
-The browser estimates it can play the media through to the end without stopping to buffer content
+The browser estimates it can play the media through to the end without stopping for buffering.
 
 ## `video:complete`
 
-OfflineAudioContext rendering is complete
+The OfflineAudioContext rendering is complete.
 
 ## `video:durationchange`
 
-Triggered when the value of the duration property changes
+Triggered when the value of the `duration` property changes.
 
 ## `video:emptied`
 
-The media has become empty; for example, this event is sent when the media has already been loaded (or partially loaded), and the load() method is called to reload it
+The media has become empty; for example, this event is sent when the media has already been loaded (or partially loaded), and the `load()` method is called to reload it.
 
 ## `video:ended`
 
-Playback has stopped because the media has reached its end point
+Playback has stopped because the media has reached its end.
 
 ## `video:error`
 
-An error occurred while fetching media data, or the resource type is not a supported media format
+An error occurred while fetching the media data, or the resource type is not a supported media format.
 
 ## `video:loadeddata`
 
-The first frame of the media has finished loading
+The first frame of the media has finished loading.
 
 ## `video:loadedmetadata`
 
-Metadata has been loaded
+Metadata has been loaded.
 
 ## `video:pause`
 
-Playback has been paused
+Playback has been paused.
 
 ## `video:play`
 
-Playback has begun
+Playback has begun.
 
 ## `video:playing`
 
-Playback is ready to start after having been paused or delayed due to lack of data
+Playback is ready to start after having been paused or delayed due to lack of data.
 
 ## `video:progress`
 
-Periodically triggered while the browser is loading the resource
+Fired periodically as the browser loads the resource.
 
 ## `video:ratechange`
 
-The playback rate has changed
+The playback rate has changed.
 
 ## `video:seeked`
 
-A seek operation has completed
+A seek operation has completed.
 
 ## `video:seeking`
 
-A seek operation has begun
+A seek operation has begun.
 
 ## `video:stalled`
 
-The user agent is trying to fetch media data, but data is unexpectedly not forthcoming
+The user agent is trying to fetch media data, but data is unexpectedly not forthcoming.
 
 ## `video:suspend`
 
-Media data loading has been suspended
+Media data loading has been suspended.
 
 ## `video:timeupdate`
 
-The time indicated by the currentTime attribute has been updated
+The time indicated by the `currentTime` property has changed.
 
 ## `video:volumechange`
 
-The volume has changed
+The volume has changed.
 
 ## `video:waiting`
 
-Playback has stopped due to temporary lack of data
\ No newline at end of file
+Playback has stopped because of a temporary lack of data.
\ No newline at end of file
diff --git a/packages/artplayer-vitepress/docs/en/advanced/global.md b/packages/artplayer-vitepress/docs/en/advanced/global.md
index d44801738..c3049c870 100644
--- a/packages/artplayer-vitepress/docs/en/advanced/global.md
+++ b/packages/artplayer-vitepress/docs/en/advanced/global.md
@@ -1,10 +1,10 @@
 # Global Properties
 
-These `global properties` refer to the `top-level properties` mounted on the `constructor`. The property names are all in uppercase. They are subject to change in the future and are generally not used.
+The `global properties` here refer to the `top-level properties` mounted on the `constructor`. All property names are in uppercase. These are subject to change in the future and are rarely used.
 
 ## DEBUG
 
-Whether to enable `debug` mode, which can print all built-in events of the video. Default is off.
+Whether to enable `debug` mode, which can print all built-in video events. Default is off.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -44,7 +44,7 @@ var art = new Artplayer({
 
 ## NOTICE_TIME
 
-The display duration for notification messages, in milliseconds. Default is `2000`.
+The display duration of notification messages, in milliseconds. Default is `2000`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -79,7 +79,7 @@ var art = new Artplayer({
 
 ## SETTING_ITEM_WIDTH
 
-The default width of settings items in the settings panel, in pixels. Default is `200`.
+The default width of a setting item in the settings panel, in pixels. Default is `200`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -99,7 +99,7 @@ var art = new Artplayer({
 
 ## SETTING_ITEM_HEIGHT
 
-The default height of settings items in the settings panel, in pixels. Default is `35`.
+The default height of a setting item in the settings panel, in pixels. Default is `35`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -255,7 +255,7 @@ var art = new Artplayer({
 
 ## CONTROL_HIDE_TIME
 
-The delay time in milliseconds for auto-hiding the bottom control bar. Default is `3000`.
+The auto-hide delay time for the bottom control bar, in milliseconds. Default is `3000`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -270,7 +270,7 @@ var art = new Artplayer({
 
 ## DBCLICK_TIME
 
-The delay time in milliseconds for double-click events. Default is `300`.
+The delay time for the double-click event, in milliseconds. Default is `300`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -289,7 +289,7 @@ art.on('dblclick', () => {
 
 ## DBCLICK_FULLSCREEN
 
-On desktop, whether double-click toggles fullscreen mode. Default is `true`.
+On desktop, whether double-click toggles fullscreen. Default is `true`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -304,7 +304,7 @@ var art = new Artplayer({
 
 ## MOBILE_DBCLICK_PLAY
 
-On mobile devices, whether double-click toggles play/pause. Default is `true`.
+On mobile, whether double-click toggles play/pause. Default is `true`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -319,7 +319,7 @@ var art = new Artplayer({
 
 ## MOBILE_CLICK_PLAY
 
-On mobile devices, whether single-click toggles play/pause. Default is `false`.
+On mobile, whether single-click toggles play/pause. Default is `false`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -334,7 +334,7 @@ var art = new Artplayer({
 
 ## AUTO_ORIENTATION_TIME
 
-On mobile devices, the delay time in milliseconds for automatic screen rotation. Default is `200`.
+On mobile, the delay time for auto-rotation, in milliseconds. Default is `200`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -350,7 +350,7 @@ var art = new Artplayer({
 
 ## INFO_LOOP_TIME
 
-The refresh interval in milliseconds for the information panel. Default is `1000`.
+The refresh interval for the info panel, in milliseconds. Default is `1000`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -367,7 +367,7 @@ art.info.show = true;
 
 ## FAST_FORWARD_VALUE
 
-On mobile devices, the speed multiplier for fast-forward during long-press. Default is `3`.
+On mobile, the speed multiplier for long-press fast-forward. Default is `3`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -383,7 +383,7 @@ var art = new Artplayer({
 
 ## FAST_FORWARD_TIME
 
-On mobile devices, the delay time in milliseconds for activating fast-forward during long-press. Default is `1000`.
+On mobile, the delay time for long-press fast-forward, in milliseconds. Default is `1000`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -399,7 +399,7 @@ var art = new Artplayer({
 
 ## TOUCH_MOVE_RATIO
 
-On mobile devices, the speed multiplier for seeking when swiping left/right. Default is `0.5`.
+On mobile, the speed multiplier for left/right swipe to seek. Default is `0.5`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -414,7 +414,7 @@ var art = new Artplayer({
 
 ## VOLUME_STEP
 
-The volume adjustment step for keyboard shortcuts. Default is `0.1`.
+The step size for volume adjustment via keyboard shortcuts. Default is `0.1`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -429,7 +429,7 @@ var art = new Artplayer({
 
 ## SEEK_STEP
 
-The seeking step in seconds for keyboard shortcuts. Default is `5`.
+The step size for seeking via keyboard shortcuts, in seconds. Default is `5`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -484,7 +484,7 @@ art.setting.show = true;
 
 ## FLIP
 
-The built-in list of video flip modes. Default is `['normal', 'horizontal', 'vertical']`.
+The built-in list of video flip options. Default is `['normal', 'horizontal', 'vertical']`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -505,7 +505,7 @@ art.setting.show = true;
 
 ## FULLSCREEN_WEB_IN_BODY
 
-Determines whether to mount the player under the `body` element during web fullscreen mode. Defaults to `true`.
+Whether to mount the player under the `body` element during web fullscreen mode. Default is `true`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -521,7 +521,7 @@ var art = new Artplayer({
 
 ## LOG_VERSION
 
-Sets whether to print the player version. Defaults to `true`.
+Sets whether to print the player version. Default is `true`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -536,7 +536,7 @@ var art = new Artplayer({
 
 ## USE_RAF
 
-Sets whether to use `requestAnimationFrame`. Defaults to `false`. Currently mainly used for smooth progress bar effects.
+Sets whether to use `requestAnimationFrame`. Default is `false`. Currently, it is primarily used for smooth progress bar effects.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -552,9 +552,9 @@ var art = new Artplayer({
 
 ## REMOVE_SRC_WHEN_DESTROY
 
-Determines whether to remove the video's `src` attribute and call `load()` to actively release media resources when destroying the player. Defaults to `true`.
+Whether to remove the video's `src` attribute and call `load()` to actively release media resources when destroying the player. Default is `true`.
 
-When enabled, this can reduce video resource usage in single-page applications or scenarios where players are frequently created/destroyed. If you wish to preserve the video element's state and only remove the UI, set this to `false`.
+Enabling this can reduce video resource usage in single-page applications or scenarios where players are frequently created/destroyed. If you wish to preserve the state of the video element and only remove the UI, you can set this to `false`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -566,6 +566,6 @@ var art = new Artplayer({
     url: '/assets/sample/video.mp4',
 });
 
-// Only destroys the UI, does not actively clear src
+// Only destroy the UI, do not actively clear the src
 art.destroy();
 ```
\ No newline at end of file
diff --git a/packages/artplayer-vitepress/docs/en/advanced/plugin.md b/packages/artplayer-vitepress/docs/en/advanced/plugin.md
index d73326634..52ee8c732 100644
--- a/packages/artplayer-vitepress/docs/en/advanced/plugin.md
+++ b/packages/artplayer-vitepress/docs/en/advanced/plugin.md
@@ -1,8 +1,8 @@
 # Writing Plugins
 
-Once you are familiar with the player's `properties`, `methods`, and `events`, writing plugins becomes very straightforward.
+Once you are familiar with the player's `properties`, `methods`, and `events`, writing a plugin becomes a very straightforward task.
 
-You can load plugin functions during instantiation:
+You can load a plugin function during instantiation.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -29,7 +29,7 @@ art.on('ready', () => {
 });
 ```
 
-You can also load plugin functions after instantiation:
+You can also load a plugin function after instantiation.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -57,7 +57,7 @@ art.on('ready', () => {
 });
 ```
 
-For example, let's say I want to write a plugin that displays an image ad when the video is paused:
+For example, let's say I want to write a plugin that displays an image ad when the video is paused.
 
 <div className="run-code">▶ Run Code</div>
 
diff --git a/packages/artplayer-vitepress/docs/en/advanced/property.md b/packages/artplayer-vitepress/docs/en/advanced/property.md
index 29ee47b64..fada1b7f9 100644
--- a/packages/artplayer-vitepress/docs/en/advanced/property.md
+++ b/packages/artplayer-vitepress/docs/en/advanced/property.md
@@ -50,7 +50,7 @@ art.on('ready', () => {
 
 -   Type: `Function`
 
-Toggle video playback and pause.
+Toggle video play and pause.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -75,7 +75,7 @@ art.on('ready', () => {
 -   Type: `Function`
 -   Parameter: `Boolean`
 
-Destroy the player. Accepts a parameter indicating whether to remove the player's `html` after destruction. Defaults to `true`.
+Destroy the player. Accepts a parameter indicating whether to also remove the player's `html` after destruction. Defaults to `true`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -137,7 +137,7 @@ art.on('ready', () => {
 -   Type: `Setter`
 -   Parameter: `Number`
 
-Fast forward the video time, in seconds.
+Fast-forward the video time, in seconds.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -299,7 +299,7 @@ art.on('ready', () => {
 -   Type: `Setter/Getter`
 -   Parameter: `Boolean`
 
-Sets and gets whether the video is muted.
+Sets or gets whether the video is muted.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -321,7 +321,7 @@ art.on('ready', () => {
 -   Type: `Setter/Getter`
 -   Parameter: `Number`
 
-Sets and gets the current playback time of the video. Setting the time is similar to `seek`, but it does not trigger additional events.
+Sets or gets the current playback time of the video. Setting the time is similar to `seek`, but it does not trigger additional events.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -359,7 +359,7 @@ art.on('ready', () => {
 
 :::warning Note
 
-Some videos may not have a duration, such as live streams or videos that have not been fully decoded. In these cases, the obtained duration will be `0`.
+Some videos may not have a duration, such as live streams or videos that have not been fully decoded. In such cases, the obtained duration will be `0`.
 
 :::
 
@@ -427,7 +427,7 @@ art.on('ready', async () => {
 -   Type: `Setter/Getter`
 -   Parameter: `Boolean`
 
-Sets and gets the player's window fullscreen state.
+Sets or gets the player's window fullscreen state.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -449,7 +449,7 @@ var art = new Artplayer({
 
 :::warning Note
 
-Due to browser security mechanisms, the page must have prior user interaction (e.g., the user has clicked on the page) before triggering window fullscreen.
+Due to browser security mechanisms, a user interaction (e.g., a click on the page) must occur before triggering window fullscreen.
 
 :::
 
@@ -458,7 +458,7 @@ Due to browser security mechanisms, the page must have prior user interaction (e
 -   Type: `Setter/Getter`
 -   Parameter: `Boolean`
 
-Sets and gets the player's web page fullscreen state.
+Sets or gets the player's web page fullscreen state.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -483,7 +483,7 @@ art.on('ready', () => {
 -   Type: `Setter/Getter`
 -   Parameter: `Boolean`
 
-Sets and gets the player's Picture-in-Picture mode.
+Sets or gets the player's Picture-in-Picture (PIP) mode.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -505,7 +505,7 @@ var art = new Artplayer({
 
 :::warning Note
 
-Due to browser security mechanisms, the page must have prior user interaction (e.g., the user has clicked on the page) before triggering Picture-in-Picture.
+Due to browser security mechanisms, a user interaction (e.g., a click on the page) must occur before triggering Picture-in-Picture.
 
 :::
 
@@ -514,7 +514,7 @@ Due to browser security mechanisms, the page must have prior user interaction (e
 -   Type: `Setter/Getter`
 -   Parameter: `String`
 
-Sets and gets the video poster. The poster effect is only visible before video playback starts.
+Sets and gets the video poster. The poster effect is only visible before the video starts playing.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -578,7 +578,7 @@ art.on('ready', () => {
 -   Type: `Setter/Getter`
 -   Parameter: `String`
 
-Gets or sets the player's current state. Supported values: `standard` (normal), `mini` (mini window), `pip` (picture-in-picture), `fullscreen` (fullscreen window), `fullscreenWeb` (webpage fullscreen).
+Gets or sets the player's current state. Supported values: `standard` (normal), `mini` (mini window), `pip` (picture-in-picture), `fullscreen` (window fullscreen), `fullscreenWeb` (webpage fullscreen).
 
 <div className="run-code">▶ Run Code</div>
 
@@ -589,7 +589,7 @@ var art = new Artplayer({
 });
 
 art.on('ready', () => {
-    console.info(art.state); // Default: standard
+    console.info(art.state); // Default is 'standard'
     art.state = 'mini';
 });
 ```
@@ -642,10 +642,10 @@ The dimension and coordinate information is obtained via `getBoundingClientRect`
 
 -   Type: `Getter`
 
-These properties provide shortcut access to `rect`:
+These properties provide quick access to `rect`:
 
-- `bottom`, `top`, `left`, `right`, `x`, `y`: Correspond to the fields of the same name in `DOMRect`
-- `width`, `height`: The player's current visible width and height
+- `bottom`, `top`, `left`, `right`, `x`, `y`: Correspond to the fields of the same name in `DOMRect`.
+- `width`, `height`: The player's current visible width and height.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -665,7 +665,7 @@ art.on('ready', () => {
 -   Type: `Setter/Getter`
 -   Parameter: `String`
 
-Sets and gets the player flip state. Supported values: `normal`, `horizontal`, `vertical`.
+Sets and gets the player's flip state. Supported values: `normal`, `horizontal`, `vertical`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -687,7 +687,7 @@ art.on('ready', () => {
 -   Type: `Setter/Getter`
 -   Parameter: `Number`
 
-Sets and gets the player's playback rate.
+Sets and gets the player's playback speed.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -730,7 +730,7 @@ art.on('ready', () => {
 
 -   Type: `Function`
 
-When the container only has a defined width, this property can automatically calculate and set the video height.
+When the container only has a defined width, this property can automatically calculate and set the video's height.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -751,7 +751,7 @@ art.on('resize', () => {
 
 :::warning Note
 
-This property is useful when your container has only a defined width but an unknown height. It automatically calculates the video height, but you need to determine the appropriate timing to set this property.
+This property is useful when your container has only a width but the exact height is unknown. It can automatically calculate the video height, but you need to determine the timing for setting this property.
 
 :::
 
@@ -760,7 +760,7 @@ This property is useful when your container has only a defined width but an unkn
 -   Type: `Function`
 -   Parameter: `String`
 
-Dynamically gets and sets attributes of the video element.
+Dynamically get and set attributes of the video element.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -782,7 +782,7 @@ art.on('ready', () => {
 -   Type: `Setter/Getter`
 -   Parameter: `String`
 
-Dynamically gets and sets the video type.
+Dynamically get and set the video type.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -804,7 +804,7 @@ art.on('ready', () => {
 -   Type: `Setter/Getter`
 -   Parameter: `String`
 
-Dynamically gets and sets the player's theme color.
+Dynamically get and set the player's theme color.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -825,7 +825,7 @@ art.on('ready', () => {
 
 -   Type: `Function`
 
-Initiates AirPlay.
+Initiate AirPlay.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -849,7 +849,7 @@ var art = new Artplayer({
 
 -   Type: `Getter`
 
-The proportion of the video that has been buffered, ranging from `[0, 1]`. Often used with the `video:timeupdate` event.
+The proportion of video buffered, ranging from `[0, 1]`. Often used with the `video:timeupdate` event.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -868,7 +868,7 @@ art.on('video:timeupdate', () => {
 
 -   Type: `Getter`
 
-The amount of media that has been buffered, in seconds. Typically used alongside `loaded` to display detailed buffering progress.
+The buffered media duration in seconds. Typically used alongside `loaded` to display detailed buffering progress.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -887,7 +887,7 @@ art.on('video:timeupdate', () => {
 
 -   Type: `Getter`
 
-The proportion of the video that has been played, ranging from `[0, 1]`. Often used with the `video:timeupdate` event.
+The proportion of video played, ranging from `[0, 1]`. Often used with the `video:timeupdate` event.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -906,7 +906,7 @@ art.on('video:timeupdate', () => {
 
 -   Type: `Function`
 
-A proxy function for `DOM` events, essentially proxying `addEventListener` and `removeEventListener`. When using `proxy` to handle events, the event is automatically removed when the player is destroyed.
+A proxy function for `DOM` events, essentially proxying `addEventListener` and `removeEventListener`. When using `proxy` to handle events, the event is automatically cleaned up when the player is destroyed.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -925,7 +925,7 @@ art.proxy(container, 'click', event => {
 
 :::warning Note
 
-If you need `DOM` events to exist only for the duration of the player's lifecycle, it is strongly recommended to use this function to avoid memory leaks.
+If you need certain `DOM` events to exist only for the player's lifecycle, it is strongly recommended to use this function to avoid memory leaks.
 
 :::
 
@@ -933,7 +933,7 @@ If you need `DOM` events to exist only for the duration of the player's lifecycl
 
 -   Type: `Function`
 
-A `DOM` query function, similar to `document.querySelector`, but the search is scoped to the current player instance, preventing errors from duplicate class names.
+A `DOM` query function, similar to `document.querySelector`, but the search is scoped to the current player, preventing errors with duplicate class names.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -967,7 +967,7 @@ console.info(art.video);
 
 -   Type: `Function`
 
-Dynamically gets or sets CSS variables.
+Dynamically get or set `CSS` variables.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -989,7 +989,7 @@ art.on('ready', () => {
 -   Type: `Setter`
 -   Parameter: `Array`
 
-Dynamically sets the list of available quality levels.
+Dynamically set the quality list.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -1033,7 +1033,7 @@ art.on('ready', () => {
 -   Type: `Setter/Getter`
 -   Parameter: `Object`
 
-Dynamically set thumbnails
+Dynamically set thumbnails.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -1057,7 +1057,7 @@ art.on('ready', () => {
 -   Type: `Setter/Getter`
 -   Parameter: `Number`
 
-Dynamically set subtitle offset
+Dynamically set subtitle offset.
 
 <div className="run-code">▶ Run Code</div>
 
diff --git a/packages/artplayer-vitepress/docs/en/component/contextmenu.md b/packages/artplayer-vitepress/docs/en/component/contextmenu.md
index 76d80ac6f..1a67dcaaa 100644
--- a/packages/artplayer-vitepress/docs/en/component/contextmenu.md
+++ b/packages/artplayer-vitepress/docs/en/component/contextmenu.md
@@ -7,11 +7,11 @@
 | `disable` | `Boolean`           | Whether to disable the component     |
 | `name`    | `String`            | Unique component name for CSS class  |
 | `index`   | `Number`            | Component index for display priority |
-| `html`    | `String`, `Element` | Component DOM element                |
+| `html`    | `String`, `Element` | DOM element of the component         |
 | `style`   | `Object`            | Component style object               |
 | `click`   | `Function`          | Component click event                |
 | `mounted` | `Function`          | Triggered after component mount      |
-| `tooltip` | `String`            | Component tooltip text               |
+| `tooltip` | `String`            | Tooltip text for the component       |
 
 ## Creation
 
@@ -64,7 +64,7 @@ art.contextmenu.show = true;
 console.info(art.contextmenu['your-menu']);
 ```
 
-## Removal
+## Deletion
 
 <div className="run-code">▶ Run Code</div>
 
diff --git a/packages/artplayer-vitepress/docs/en/component/controls.md b/packages/artplayer-vitepress/docs/en/component/controls.md
index c62903504..1ea1e5840 100644
--- a/packages/artplayer-vitepress/docs/en/component/controls.md
+++ b/packages/artplayer-vitepress/docs/en/component/controls.md
@@ -2,19 +2,19 @@
 
 ## Configuration
 
-| Property    | Type                | Description                                      |
-| ----------- | ------------------- | ------------------------------------------------ |
-| `disable`   | `Boolean`           | Whether to disable the control                   |
-| `name`      | `String`            | Unique control name for CSS class identification |
-| `index`     | `Number`            | Control index for display priority               |
-| `html`      | `String`, `Element` | Control's DOM element                            |
-| `style`     | `Object`            | Control style object                             |
-| `click`     | `Function`          | Control click event handler                      |
-| `mounted`   | `Function`          | Triggered after control is mounted               |
-| `tooltip`   | `String`            | Control tooltip text                             |
-| `position`  | `String`            | `left` or `right` - controls display position    |
-| `selector`  | `Array`             | Array of selector list objects                   |
-| `onSelect`  | `Function`          | Function triggered when selector item is clicked |
+| Property   | Type                | Description                                      |
+| ---------- | ------------------- | ------------------------------------------------ |
+| `disable`  | `Boolean`           | Whether to disable the control                   |
+| `name`     | `String`            | Unique name of the control, used for class marking |
+| `index`    | `Number`            | Control index, determines display priority       |
+| `html`     | `String`, `Element` | DOM element of the control                       |
+| `style`    | `Object`            | Style object for the control                     |
+| `click`    | `Function`          | Click event handler for the control              |
+| `mounted`  | `Function`          | Triggered after the control is mounted           |
+| `tooltip`  | `String`            | Tooltip text for the control                     |
+| `position` | `String`            | `left` or `right` - controls which side the control appears on |
+| `selector` | `Array`             | Array of objects for selection list              |
+| `onSelect` | `Function`          | Function triggered when a selection list item is clicked |
 
 ## Creation
 
diff --git a/packages/artplayer-vitepress/docs/en/component/layers.md b/packages/artplayer-vitepress/docs/en/component/layers.md
index fbeac9aa3..8f476f938 100644
--- a/packages/artplayer-vitepress/docs/en/component/layers.md
+++ b/packages/artplayer-vitepress/docs/en/component/layers.md
@@ -1,4 +1,4 @@
-# Layer
+# Layers
 
 ## Configuration
 
diff --git a/packages/artplayer-vitepress/docs/en/component/setting.md b/packages/artplayer-vitepress/docs/en/component/setting.md
index d67bc62b8..0f26bbc48 100644
--- a/packages/artplayer-vitepress/docs/en/component/setting.md
+++ b/packages/artplayer-vitepress/docs/en/component/setting.md
@@ -2,7 +2,7 @@
 
 ## Built-in
 
-First, you need to open the settings panel. It comes with four built-in items: `flip`, `playbackRate`, `aspectRatio`, `subtitleOffset`
+First, you need to open the settings panel. It comes with four built-in items: `flip`, `playbackRate`, `aspectRatio`, `subtitleOffset`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -10,7 +10,7 @@ First, you need to open the settings panel. It comes with four built-in items: `
 var art = new Artplayer({
     container: '.artplayer-app',
     url: '/assets/sample/video.mp4',
-	setting: true,
+    setting: true,
     flip: true,
     playbackRate: true,
     aspectRatio: true,
@@ -18,15 +18,15 @@ var art = new Artplayer({
 });
 ```
 
-## Creating - Buttons
+## Create - Button
 
-| Property  | Type                | Description          |
-| --------- | ------------------- | -------------------- |
-| `html`    | `String`, `Element` | Element DOM          |
-| `icon`    | `String`, `Element` | Element icon         |
-| `onClick` | `Function`          | Element click event  |
-| `width`   | `Number`            | List width           |
-| `tooltip` | `String`            | Tooltip text         |
+| Property   | Type                | Description          |
+| ---------- | ------------------- | -------------------- |
+| `html`     | `String`, `Element` | The DOM element      |
+| `icon`     | `String`, `Element` | The icon element     |
+| `onClick`  | `Function`          | The click event      |
+| `width`    | `Number`            | The list width       |
+| `tooltip`  | `String`            | The tooltip text     |
 
 <div className="run-code">▶ Run Code</div>
 
@@ -40,25 +40,25 @@ var art = new Artplayer({
             html: 'Button',
             icon: '<img width="22" height="22" src="/assets/img/state.svg">',
             tooltip: 'tooltip',
-			onClick(item, $dom, event) {
+            onClick(item, $dom, event) {
                 console.info(item, $dom, event);
-				return 'new tooltip'
-			}
+                return 'new tooltip';
+            },
         },
     ],
 });
 ```
 
-## Creating - Selection Lists
+## Create - Selection List
 
-| Property  | Type                | Description          |
-| --------- | ------------------- | -------------------- |
-| `html`    | `String`, `Element` | Element DOM          |
-| `icon`    | `String`, `Element` | Element icon         |
-| `selector`| `Array`             | Element list         |
-| `onSelect`| `Function`          | Element click event  |
-| `width`   | `Number`            | List width           |
-| `tooltip` | `String`            | Tooltip text         |
+| Property   | Type                | Description          |
+| ---------- | ------------------- | -------------------- |
+| `html`     | `String`, `Element` | The DOM element      |
+| `icon`     | `String`, `Element` | The icon element     |
+| `selector` | `Array`             | The list of elements |
+| `onSelect` | `Function`          | The click event      |
+| `width`    | `Number`            | The list width       |
+| `tooltip`  | `String`            | The tooltip text     |
 
 <div className="run-code">▶ Run Code</div>
 
@@ -118,7 +118,7 @@ var art = new Artplayer({
 });
 ```
 
-## Creating - Nested Lists
+## Create - Nested List
 
 <div className="run-code">▶ Run Code</div>
 
@@ -172,13 +172,13 @@ var art = new Artplayer({
 
 ## Create - Toggle Button
 
-| Property   | Type                | Description               |
-| ---------- | ------------------- | ------------------------- |
-| `html`     | `String`, `Element` | DOM element of the item   |
-| `icon`     | `String`, `Element` | Icon of the item          |
+| Property   | Type                | Description                |
+| ---------- | ------------------- | -------------------------- |
+| `html`     | `String`, `Element` | DOM element for the item   |
+| `icon`     | `String`, `Element` | Icon for the item          |
 | `switch`   | `Boolean`           | Default state of the button |
-| `onSwitch` | `Function`          | Button toggle event       |
-| `tooltip`  | `String`            | Tooltip text              |
+| `onSwitch` | `Function`          | Button toggle event        |
+| `tooltip`  | `String`            | Tooltip text               |
 
 <div className="run-code">▶ Run Code</div>
 
@@ -207,14 +207,14 @@ var art = new Artplayer({
 
 ## Create - Range Slider
 
-| Property   | Type                | Description               |
-| ---------- | ------------------- | ------------------------- |
-| `html`     | `String`, `Element` | DOM element of the item   |
-| `icon`     | `String`, `Element` | Icon of the item          |
-| `range`    | `Array`             | Default state array       |
+| Property   | Type                | Description                |
+| ---------- | ------------------- | -------------------------- |
+| `html`     | `String`, `Element` | DOM element for the item   |
+| `icon`     | `String`, `Element` | Icon for the item          |
+| `range`    | `Array`             | Default state array        |
 | `onRange`  | `Function`          | Event triggered on completion |
-| `onChange` | `Function`          | Event triggered on change |
-| `tooltip`  | `String`            | Tooltip text              |
+| `onChange` | `Function`          | Event triggered on change  |
+| `tooltip`  | `String`            | Tooltip text               |
 
 ```js
 const range = [5, 1, 10, 1];
diff --git a/packages/artplayer-vitepress/docs/en/index.md b/packages/artplayer-vitepress/docs/en/index.md
index 7a0c2c72e..a624feff5 100644
--- a/packages/artplayer-vitepress/docs/en/index.md
+++ b/packages/artplayer-vitepress/docs/en/index.md
@@ -1,4 +1,4 @@
-# Installation & Usage
+# Installation and Usage
 
 ## Installation
 
@@ -69,11 +69,11 @@ https://unpkg.com/artplayer/dist/artplayer.js
 
 ::: warning Note
 
-The player's dimensions depend on the size of its container `container`, so your container must have defined dimensions.
+The player's dimensions depend on the dimensions of its `container`. Therefore, your `container` must have defined dimensions.
 
 :::
 
-::: tip See more usage examples at the following link:
+::: tip See more usage examples at the following link
 
 [/example](https://github.com/zhw2590582/ArtPlayer/tree/master/example)
 
@@ -147,7 +147,7 @@ function getInstance(art) {
 
 ::: warning Artplayer is not reactive:
 
-Directly modifying `option` in `Vue.js` will not update the player.
+Directly modifying the `option` in `Vue.js` will not update the player.
 
 :::
 
@@ -207,13 +207,13 @@ export default App
 
 ::: warning Artplayer is not reactive:
 
-Directly modifying `option` in `React.js` will not update the player.
+Directly modifying the `option` in `React.js` will not update the player.
 
 :::
 
 ## TypeScript
 
-`artplayer.d.ts` is automatically imported when importing `Artplayer`.
+The `artplayer.d.ts` file is automatically imported when you import `Artplayer`.
 
 ### Vue.js
 
@@ -235,7 +235,7 @@ art.current = new Artplayer();
 
 ### Option
 
-You can also use the option type.
+You can also use the type for the options.
 
 ```ts{3}
 import Artplayer, { type Option } from 'artplayer';
@@ -250,7 +250,7 @@ option.volume = 0.5;
 const art = new Artplayer(option);
 ```
 
-::: tip Full TypeScript definitions
+::: tip Full TypeScript Definitions
 
 [packages/artplayer/types](https://github.com/zhw2590582/ArtPlayer/tree/master/packages/artplayer/types)
 
@@ -258,7 +258,7 @@ const art = new Artplayer(option);
 
 ## JavaScript
 
-Sometimes your `js` files may lose TypeScript type hints. In such cases, you can manually import the types.
+Sometimes your `js` files may lose `TypeScript` type hints. In such cases, you can manually import the types.
 
 Variable:
 
@@ -314,9 +314,9 @@ const art8 = new Artplayer(option);
 
 ## Legacy Browsers
 
-The production build `artplayer.js` only supports the latest major version of `Chrome`: `last 1 Chrome version`
+The production build `artplayer.js` only supports the latest major version of `Chrome`: `last 1 Chrome version`.
 
-For legacy browsers, you can use the `artplayer.legacy.js` file, which supports compatibility down to: `IE 11`
+For legacy browsers, you can use the `artplayer.legacy.js` file, which is compatible down to: `IE 11`.
 
 ```js
 import Artplayer from 'artplayer/legacy'
@@ -350,7 +350,7 @@ Reference documentation: [browserslist](https://github.com/browserslist/browsers
 
 :::
 
-Starting from `5.2.6`, `artplayer` and all plugins also provide an `ESM` version `mjs`, such as:
+Starting from version `5.2.6`, `artplayer` and all plugins also provide an `ESM` version in `mjs` format, such as:
 
 - `artplayer/dist/artplayer.mjs`
 - `artplayer-plugin-danmuku/dist/artplayer-plugin-danmuku.mjs`
@@ -396,7 +396,7 @@ Starting from `5.2.6`, `artplayer` and all plugins also provide an `ESM` version
 
 ## Custom userAgent
 
-Currently, the detection for whether a device is mobile is not entirely accurate. Sometimes you may want to adjust the player's UI by changing the `userAgent`. Therefore, starting from `5.2.4`, a new global variable `globalThis.CUSTOM_USER_AGENT` has been added.
+Currently, the detection of whether a device is mobile is not always accurate. Sometimes you may want to adjust the player's UI by changing the `userAgent`. Therefore, starting from version `5.2.4`, a global variable `globalThis.CUSTOM_USER_AGENT` has been added.
 
 ```html
 <html>
diff --git a/packages/artplayer-vitepress/docs/en/start/i18n.md b/packages/artplayer-vitepress/docs/en/start/i18n.md
index 5216eb02d..db1fe5c28 100644
--- a/packages/artplayer-vitepress/docs/en/start/i18n.md
+++ b/packages/artplayer-vitepress/docs/en/start/i18n.md
@@ -2,13 +2,13 @@
 
 ::: danger
 
-Due to the increasing number of bundled multilingual resources, starting from version `5.1.0`, the core `artplayer.js` code will only include `Simplified Chinese` and `English`. Other languages are no longer bundled by default and must be imported manually as needed.
+Due to the increasing number of bundled multilingual resources, starting from version `5.1.0`, the core `artplayer.js` code will no longer bundle any languages other than `Simplified Chinese` and `English`. You will need to manually import any other languages you require.
 
 :::
 
 :::warning 
 
-When a language cannot be matched, English will be displayed by default. For i18n implementation reference, see: [artplayer/types/i18n.d.ts](https://github.com/zhw2590582/ArtPlayer/blob/master/packages/artplayer/types/i18n.d.ts)
+When a language cannot be matched, English will be displayed by default. For i18n syntax reference, see: [artplayer/types/i18n.d.ts](https://github.com/zhw2590582/ArtPlayer/blob/master/packages/artplayer/types/i18n.d.ts)
 
 :::
 
@@ -26,9 +26,9 @@ var art = new Artplayer({
 
 ## Importing Languages
 
-Language files before bundling are located at: `artplayer/src/i18n/*.js`. Contributions to add your language are welcome.
+Language files before bundling are located at: `artplayer/src/i18n/*.js`. Contributions for new languages are welcome.
 
-Language files after bundling are located at: `artplayer/dist/i18n/*.js`
+Bundled language files are located at: `artplayer/dist/i18n/*.js`
 
 ::: code-group
 
@@ -79,7 +79,7 @@ var art = new Artplayer({
 });
 ```
 
-## Modifying Languages
+## Modifying a Language
 
 ```js
 import zhTw from 'artplayer/i18n/zh-tw';
diff --git a/packages/artplayer-vitepress/docs/en/start/option.md b/packages/artplayer-vitepress/docs/en/start/option.md
index bb20aa355..f77a030af 100644
--- a/packages/artplayer-vitepress/docs/en/start/option.md
+++ b/packages/artplayer-vitepress/docs/en/start/option.md
@@ -11,13 +11,13 @@ The `DOM` container where the player is mounted.
 
 ```js{2}
 var art = new Artplayer({
-    container: '.artplayer-app', 
+    container: '.artplayer-app',
     // container: document.querySelector('.artplayer-app'),
     url: '/assets/sample/video.mp4',
 });
 ```
 
-You may need to initialize the size of the container element, for example:
+You may need to set the size of the container element, for example:
 
 ```css{2-3}
 .artplayer-app {
@@ -56,7 +56,7 @@ var art = new Artplayer({
 });
 ```
 
-Sometimes the `url` is not known immediately; in such cases, you can set the `url` asynchronously.
+Sometimes the `url` is not known immediately. In such cases, you can set the `url` asynchronously.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -83,7 +83,7 @@ To play other formats like `.m3u8` or `.flv`, please refer to the `Third-party L
 -   Type: `String`
 -   Default: `''`
 
-The unique identifier for the player, currently only used for playback resumption `autoplayback`.
+The unique identifier for the player. Currently used only for playback memory `autoplayback`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -100,7 +100,7 @@ var art = new Artplayer({
 -   Type: `Function`
 -   Default: `undefined`
 
-The constructor accepts a function as the second parameter, which is triggered when the player is successfully initialized and the video is ready to play, similar to the `ready` event.
+The constructor accepts a function as the second parameter. This function is triggered when the player is successfully initialized and the video is ready to play, similar to the `ready` event.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -176,7 +176,7 @@ var art = new Artplayer({
 -   Type: `Number`
 -   Default: `0.7`
 
-The default volume of the player.
+The player's default volume.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -190,7 +190,7 @@ var art = new Artplayer({
 
 :::warning Note
 
-The player caches the last volume level; upon next initialization (e.g., page refresh), the player will read this cached value.
+The player caches the last volume setting. Upon the next initialization (e.g., page refresh), the player will read this cached value.
 
 :::
 
@@ -199,7 +199,7 @@ The player caches the last volume level; upon next initialization (e.g., page re
 -   Type: `Boolean`
 -   Default: `false`
 
-Enable live streaming mode, which hides the progress bar and playback time.
+Enable live streaming mode. This will hide the progress bar and playback time.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -216,7 +216,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `false`
 
-Whether to mute by default.
+Whether to start muted by default.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -257,7 +257,7 @@ If you want the video to autoplay immediately upon page load, `muted` must be se
 -   Type: `Boolean`
 -   Default: `false`
 
-By default, the player's dimensions fill the entire `container` size, often resulting in black bars. This option automatically adjusts the player size to hide the black bars, similar to `object-fit: cover;` in CSS.
+By default, the player's dimensions fill the entire `container`, often resulting in black bars. This option automatically adjusts the player size to hide black bars, similar to `css`'s `object-fit: cover;`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -275,7 +275,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `false`
 
-Automatically enters `mini player` mode when the player scrolls out of the browser viewport.
+Automatically enters `Mini Player` mode when the player scrolls out of the browser viewport.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -292,7 +292,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `false`
 
-Whether to enable video looping.
+Whether to loop playback.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -309,7 +309,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `false`
 
-Whether to display the video flip functionality. Currently appears in the `Settings Panel` and `Context Menu`.
+Whether to display the video flip function. Currently only appears in the `Settings Panel` and `Context Menu`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -327,7 +327,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `false`
 
-Whether to display the video playback rate functionality. Appears in the `Settings Panel` and `Context Menu`.
+Whether to display the video playback speed function. It will appear in the `Settings Panel` and `Context Menu`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -345,7 +345,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `false`
 
-Whether to display the video aspect ratio functionality. Appears in the `Settings Panel` and `Context Menu`.
+Whether to display the video aspect ratio function. It will appear in the `Settings Panel` and `Context Menu`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -363,7 +363,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `false`
 
-Whether to display the `Video Screenshot` functionality in the bottom control bar.
+Whether to display the `Screenshot` function in the bottom control bar.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -377,7 +377,7 @@ var art = new Artplayer({
 
 :::warning Note
 
-Due to browser security mechanisms, screenshot capture may fail if the video source URL is cross-origin with the website.
+Due to browser security mechanisms, screenshotting may fail if the video source URL is cross-origin with the website.
 
 :::
 
@@ -403,7 +403,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `true`
 
-Whether to enable hotkeys.
+Whether to use hotkeys.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -425,7 +425,7 @@ var art = new Artplayer({
 
 :::warning Note
 
-These hotkeys only take effect after the player gains focus (e.g., by clicking on the player).
+These hotkeys only take effect after the player gains focus (e.g., after clicking on the player).
 
 :::
 
@@ -451,7 +451,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `true`
 
-If multiple players exist simultaneously on the page, whether only one player is allowed to play at a time.
+If multiple players exist on the page simultaneously, whether only one player is allowed to play at a time.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -468,7 +468,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `true`
 
-Whether to enable the backdrop blur effect for the player UI. When enabled, overlays such as the settings panel, context menu, and volume bar will apply a `backdrop-filter` frosted glass effect for a more transparent appearance. However, this may cause performance or compatibility issues on some low-performance devices or older browsers.
+Whether to enable the backdrop blur effect for the player UI. When enabled, overlays such as the settings panel, context menu, and volume bar will apply a `backdrop-filter` frosted glass effect for a more transparent look. However, this may cause performance or compatibility issues on some low-performance devices or older browsers.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -502,7 +502,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `false`
 
-Whether to display the player `Webpage Fullscreen` button in the bottom control bar.
+Whether to display the player `Web Fullscreen` button in the bottom control bar.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -519,7 +519,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `false`
 
-Subtitle timing offset, range within `[-5s, 5s]`. Appears in the `Settings Panel`.
+Subtitle time offset, ranging from `[-5s, 5s]`. Appears in the `Settings Panel`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -541,7 +541,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `false`
 
-Mini progress bar that appears only when the player loses focus and is playing.
+A mini progress bar that only appears when the player loses focus and is playing.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -558,7 +558,7 @@ var art = new Artplayer({
 -   Type: `Boolean`
 -   Default: `false`
 
-Whether to use SSR mount mode. Useful if you want to pre-render the player's required HTML before mounting.
+Whether to use SSR (Server-Side Rendering) mount mode. Useful if you want to pre-render the player's required HTML before the player is mounted.
 
 You can access the player's required HTML via `Artplayer.html`.
 
@@ -639,7 +639,7 @@ var art = new Artplayer({
 -   Type: `Array`
 -   Default: `[]`
 
-Initialize custom settings panel.
+Initialize custom settings panels.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -692,7 +692,7 @@ var art = new Artplayer({
 -   Type: `Array`
 -   Default: `[]`
 
-Initialize custom context menu.
+Initialize custom context menus.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -748,7 +748,7 @@ var art = new Artplayer({
 
 ```
 
-:::warning For `Component Configuration`, please refer to:
+:::warning For `Component Configuration`, please refer to the following address:
 
 [/component/controls.html](/component/controls.html)
 
@@ -794,10 +794,10 @@ var art = new Artplayer({
 
 Display `Highlight Information` on the progress bar.
 
-| Property | Type     | Description                    |
-| -------- | -------- | ------------------------------ |
-| `time`   | `Number` | Highlight time (in seconds)    |
-| `text`   | `String` | Highlight text                 |
+| Property | Type     | Description                     |
+| -------- | -------- | ------------------------------- |
+| `time`   | `Number` | Highlight time (in seconds)     |
+| `text`   | `String` | Highlight text                  |
 
 <div className="run-code">▶ Run Code</div>
 
@@ -899,7 +899,7 @@ var art = new Artplayer({
 -   Type: `Object`
 -   Default: `{}`
 
-Set the video subtitle. Supported subtitle formats: `vtt`, `srt`, `ass`.
+Set video subtitles. Supported subtitle formats: `vtt`, `srt`, `ass`.
 
 | Property    | Type       | Description                                      |
 | ----------- | ---------- | ------------------------------------------------ |
@@ -907,8 +907,8 @@ Set the video subtitle. Supported subtitle formats: `vtt`, `srt`, `ass`.
 | `url`       | `String`   | Subtitle URL                                     |
 | `type`      | `String`   | Subtitle type, options: `vtt`, `srt`, `ass`      |
 | `style`     | `Object`   | Subtitle style                                   |
-| `encoding`  | `String`   | Subtitle encoding, default: `utf-8`              |
-| `escape`    | `Boolean`  | Whether to escape `html` tags, default: `true`   |
+| `encoding`  | `String`   | Subtitle encoding, default `utf-8`               |
+| `escape`    | `Boolean`  | Whether to escape `html` tags, default `true`    |
 | `onVttLoad` | `Function` | Function for modifying `vtt` text                |
 
 <div className="run-code">▶ Run Code</div>
@@ -933,9 +933,9 @@ var art = new Artplayer({
 ## `moreVideoAttr`
 
 -   Type: `Object`
--   Default: `{'controls': false, 'preload': 'metadata'}` (In Safari, it automatically adjusts to `preload: 'auto'` for better loading experience).
+-   Default: `{'controls': false, 'preload': 'metadata'}` (In Safari, it will automatically adjust to `preload: 'auto'` for better loading experience.)
 
-More video attributes. These attributes will be directly written into the video element.
+More video attributes. These attributes will be written directly into the video element.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -956,7 +956,7 @@ var art = new Artplayer({
 -   Type: `Object`
 -   Default: `{}`
 
-Used to replace default icons, supports both `Html` strings and `HTMLElement`.
+Used to replace default icons. Supports `Html` strings and `HTMLElement`.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -982,7 +982,7 @@ var art = new Artplayer({
 -   Type: `String`
 -   Default: `''`
 
-Used to specify the video format. It needs to be used in conjunction with `customType`. By default, the video format is determined by the suffix of the video URL (e.g., `.m3u8`, `.mkv`, `.ts`). However, sometimes the video URL lacks the correct suffix, so explicit specification is necessary.
+Used to specify the video format. It needs to be used together with `customType`. By default, the video format is determined by the suffix of the video URL (e.g., `.m3u8`, `.mkv`, `.ts`). However, sometimes the video URL may not have the correct suffix, so it needs to be explicitly specified.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -1000,7 +1000,7 @@ The player can only parse suffixes like this: `/assets/sample/video.m3u8`
 
 But cannot parse suffixes like this: `/assets/sample/video?type=m3u8`
 
-Therefore, if you use `customType`, it is best to also specify the `type`.
+Therefore, if you use `customType`, it's best to also specify the `type`.
 
 :::
 
@@ -1009,7 +1009,7 @@ Therefore, if you use `customType`, it is best to also specify the `type`.
 -   Type: `Object`
 -   Default: `{}`
 
-Matches based on the video's `type` and delegates video decoding to third-party programs. The handler function receives three parameters:
+Matches based on the video's `type` and delegates video decoding to third-party programs for processing. The processing function can receive three parameters:
 
 - `video`: The video `DOM` element
 - `url`: The video URL
@@ -1172,9 +1172,9 @@ var art = new Artplayer({
 
 :::warning Note
 
-By default, the player uses the `url` as the `key` to cache the playback progress.
+Because the player uses the `url` as the `key` to cache playback progress by default.
 
-However, if the same video has different `url`s, you need to use the `id` to identify the unique `key` for the video.
+However, if the `url` for the same video is different, then you need to use `id` to identify the unique `key` for the video.
 
 :::
 
@@ -1183,7 +1183,7 @@ However, if the same video has different `url`s, you need to use the `id` to ide
 -   Type: `Boolean`
 -   Default: `false`
 
-Whether to rotate the player during fullscreen mode on mobile web, based on the video dimensions and viewport size.
+Whether to rotate the player in fullscreen mode on mobile web, based on the video dimensions and viewport dimensions.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -1217,7 +1217,7 @@ var art = new Artplayer({
 -   Type: `Object`
 -   Default: `{}`
 
-Used to modify built-in CSS variables.
+Used to modify the built-in CSS variables.
 
 <div className="run-code">▶ Run Code</div>
 
@@ -1231,7 +1231,7 @@ var art = new Artplayer({
 });
 ```
 
-:::warning CSS Variable Reference
+:::warning Reference for `cssVar` Syntax
 
 [artplayer/types/cssVar.d.ts](https://github.com/zhw2590582/ArtPlayer/blob/master/packages/artplayer/types/cssVar.d.ts)
 
diff --git a/scripts/fix-docs.js b/scripts/fix-docs.js
deleted file mode 100644
index 1a5b61662..000000000
--- a/scripts/fix-docs.js
+++ /dev/null
@@ -1,73 +0,0 @@
-import fs from 'node:fs'
-import path from 'node:path'
-import { glob } from 'glob'
-
-const docsDir = path.resolve('packages/artplayer-vitepress/docs')
-
-function fixMarkdownFile(filePath) {
-  const content = fs.readFileSync(filePath, 'utf-8')
-  const lines = content.split('\n')
-  const fixedLines = []
-  let inCodeBlock = false
-  let fixes = 0
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-
-    // Check if entering a code block
-    if (line.startsWith('```') && !inCodeBlock) {
-      inCodeBlock = true
-      fixedLines.push(line)
-      continue
-    }
-
-    // Check if properly exiting a code block
-    if (line.startsWith('```') && inCodeBlock) {
-      inCodeBlock = false
-      fixedLines.push(line)
-      continue
-    }
-
-    // Check if we hit a heading while still in a code block (missing ```)
-    if (inCodeBlock && line.startsWith('## ')) {
-      // Add the missing closing ```
-      fixedLines.push('```')
-      fixedLines.push('')
-      inCodeBlock = false
-      fixes++
-    }
-
-    // Check if we hit ::: (admonition) while still in a code block
-    if (inCodeBlock && line.startsWith(':::')) {
-      fixedLines.push('```')
-      fixedLines.push('')
-      inCodeBlock = false
-      fixes++
-    }
-
-    fixedLines.push(line)
-  }
-
-  // If file ended while still in code block
-  if (inCodeBlock) {
-    fixedLines.push('```')
-    fixes++
-  }
-
-  if (fixes > 0) {
-    fs.writeFileSync(filePath, fixedLines.join('\n'))
-    console.log(`✅ Fixed ${fixes} code blocks in ${path.relative(docsDir, filePath)}`)
-  }
-
-  return fixes
-}
-
-// Find all markdown files
-const files = glob.sync('**/*.md', { cwd: docsDir, absolute: true })
-
-let totalFixes = 0
-for (const file of files) {
-  totalFixes += fixMarkdownFile(file)
-}
-
-console.log(`\n✨ Total: Fixed ${totalFixes} code blocks in ${files.length} files`)
diff --git a/scripts/trans-docs.js b/scripts/trans-docs.js
index 40c13566c..406d8fe35 100644
--- a/scripts/trans-docs.js
+++ b/scripts/trans-docs.js
@@ -13,14 +13,81 @@ const srcDirs = ['docs/advanced', 'docs/component', 'docs/start']
 const indexFile = 'docs/index.md'
 const outputRoot = path.join(rootDir, 'docs/en')
 const API_URL = 'https://api.deepseek.com/v1/chat/completions'
-const API_KEY = process.env.DEEPL_API_KEY
+const API_KEY = process.env.DEEPSEEK_API_KEY
+
+// 配置常量
+const MAX_CONCURRENT_REQUESTS = 5 // 并发请求数
+const REQUEST_TIMEOUT = 60000 // 请求超时时间 60秒
+const MAX_RETRIES = 3 // 最大重试次数
+const CHUNK_SIZE = 4000 // 分块大小
 
 if (!API_KEY) {
-  console.error('❌ Missing DEEPL_API_KEY in .env file')
+  console.error('❌ Missing DEEPSEEK_API_KEY in .env file')
   process.exit(1)
 }
 
-function splitMarkdown(text, maxLen = 4000) {
+// ==================== Markdown 修复功能 ====================
+
+/**
+ * 修复 Markdown 代码块闭合问题
+ * - 遇到 ## 标题时补上遗漏的 ```
+ * - 遇到 ::: 时补上遗漏的 ```
+ * - 文件末尾检查是否需要补上
+ */
+function fixMarkdownCodeBlocks(content) {
+  const lines = content.split('\n')
+  const fixedLines = []
+  let inCodeBlock = false
+  let fixes = 0
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+
+    // 检查是否进入代码块
+    if (line.startsWith('```') && !inCodeBlock) {
+      inCodeBlock = true
+      fixedLines.push(line)
+      continue
+    }
+
+    // 检查是否正常退出代码块
+    if (line.startsWith('```') && inCodeBlock) {
+      inCodeBlock = false
+      fixedLines.push(line)
+      continue
+    }
+
+    // 在代码块中遇到标题（缺少 ```）
+    if (inCodeBlock && line.startsWith('## ')) {
+      fixedLines.push('```')
+      fixedLines.push('')
+      inCodeBlock = false
+      fixes++
+    }
+
+    // 在代码块中遇到 :::（admonition）
+    if (inCodeBlock && line.startsWith(':::')) {
+      fixedLines.push('```')
+      fixedLines.push('')
+      inCodeBlock = false
+      fixes++
+    }
+
+    fixedLines.push(line)
+  }
+
+  // 文件末尾仍在代码块中
+  if (inCodeBlock) {
+    fixedLines.push('```')
+    fixes++
+  }
+
+  return { content: fixedLines.join('\n'), fixes }
+}
+
+// ==================== 翻译功能 ====================
+
+function splitMarkdown(text, maxLen = CHUNK_SIZE) {
   const lines = text.split('\n')
   const chunks = []
   let buffer = ''
@@ -45,17 +112,72 @@ function cleanTranslation(text) {
   return text
     .replace(/^```(markdown|md)?/gi, '')
     .replace(/```$/g, '')
-    .replace(/^(Here('|’)s|Below is|Translation|The English version|Here is)[:：]?\s*/gi, '')
+    .replace(/^(Here('|')s|Below is|Translation|The English version|Here is)[:：]?\s*/gi, '')
     .replace(/(Translation completed\.?|End of translation\.?)$/gi, '')
     .trim()
 }
 
-async function translateText(text) {
-  const chunks = splitMarkdown(text, 4000)
+async function callDeepSeekAPI(prompt, tag, chunkId) {
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      console.log(`🔹 [${tag}] Translating chunk ${chunkId} (attempt ${attempt}/${MAX_RETRIES})`)
+      const controller = new AbortController()
+      const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT)
+
+      const res = await fetch(API_URL, {
+        method: 'POST',
+        signal: controller.signal,
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${API_KEY}`,
+        },
+        body: JSON.stringify({
+          model: 'deepseek-chat',
+          messages: [{ role: 'user', content: prompt }],
+          temperature: 0.2,
+        }),
+      })
+      clearTimeout(timeout)
+
+      // 处理限流情况
+      if (res.status === 429) {
+        const delay = Math.pow(2, attempt) * 1000
+        console.log(`⏳ [${tag}] Rate limited, waiting ${delay}ms...`)
+        await new Promise(r => setTimeout(r, delay))
+        continue
+      }
+
+      if (!res.ok) {
+        const error = await res.text()
+        console.error(`[${tag}] API Error:`, error)
+        throw new Error(`DeepSeek API error: ${res.status}`)
+      }
+
+      const data = await res.json()
+      if (!data.choices || !data.choices[0]) {
+        throw new Error('Invalid API response: missing choices')
+      }
+      return data.choices[0].message?.content?.trim() || ''
+    }
+    catch (err) {
+      if (err.name === 'AbortError') {
+        console.error(`[${tag}] Request timeout for chunk ${chunkId}`)
+      }
+      if (attempt === MAX_RETRIES) {
+        throw err
+      }
+      const delay = 1000 * attempt
+      console.log(`⚠️ [${tag}] Retry ${attempt}/${MAX_RETRIES} after ${delay}ms...`)
+      await new Promise(r => setTimeout(r, delay))
+    }
+  }
+}
+
+async function translateText(text, fileName) {
+  const chunks = splitMarkdown(text, CHUNK_SIZE)
   let result = ''
 
   for (let i = 0; i < chunks.length; i++) {
-    console.log(`🔹 Translating chunk ${i + 1}/${chunks.length}`)
     const prompt = `
 You are a professional English technical translator for documentation.
 Translate the following Markdown content from Simplified Chinese to fluent English.
@@ -64,29 +186,9 @@ Return ONLY the translated Markdown content — do NOT add any explanations, pre
 
 Text to translate:
 ${chunks[i]}
-        `.trim()
+    `.trim()
 
-    const res = await fetch(API_URL, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${API_KEY}`,
-      },
-      body: JSON.stringify({
-        model: 'deepseek-chat',
-        messages: [{ role: 'user', content: prompt }],
-        temperature: 0.2,
-      }),
-    })
-
-    if (!res.ok) {
-      const error = await res.text()
-      console.error('API Error:', error)
-      throw new Error(`DeepSeek API error: ${res.status}`)
-    }
-
-    const data = await res.json()
-    const raw = data.choices?.[0]?.message?.content?.trim() || ''
+    const raw = await callDeepSeekAPI(prompt, fileName, `${i + 1}/${chunks.length}`)
     const translated = cleanTranslation(raw)
     result += `\n\n${translated}`
   }
@@ -96,14 +198,26 @@ ${chunks[i]}
 
 async function processFile(inputPath, outputPath) {
   const content = fs.readFileSync(inputPath, 'utf8')
+  const fileName = path.basename(inputPath)
   console.log(`🌍 Translating: ${inputPath}`)
-  const translated = await translateText(content)
+
+  // 1. 翻译
+  let translated = await translateText(content, fileName)
+
+  // 2. 修复 Markdown 语法
+  const { content: fixed, fixes } = fixMarkdownCodeBlocks(translated)
+  if (fixes > 0) {
+    console.log(`🔧 [${fileName}] Fixed ${fixes} unclosed code blocks`)
+    translated = fixed
+  }
+
+  // 3. 保存
   fs.mkdirSync(path.dirname(outputPath), { recursive: true })
   fs.writeFileSync(outputPath, translated, 'utf8')
   console.log(`✅ Saved: ${outputPath}`)
 }
 
-async function runWithConcurrency(tasks, limit = 5) {
+async function runWithConcurrency(tasks, limit = MAX_CONCURRENT_REQUESTS) {
   const results = []
   const executing = new Set()
   for (const task of tasks) {
@@ -137,8 +251,8 @@ async function main() {
     }
   }
 
-  console.log(`🧠 Total files: ${tasks.length}, concurrency: 5`)
-  await runWithConcurrency(tasks, 5)
+  console.log(`🧠 Total files: ${tasks.length}, concurrency: ${MAX_CONCURRENT_REQUESTS}`)
+  await runWithConcurrency(tasks, MAX_CONCURRENT_REQUESTS)
   console.log('🎉 Translation complete!')
 }