From 5b356dc36101a595f4e362ae4ac95cd4e8dd5c75 Mon Sep 17 00:00:00 2001
From: waynzh <zhanghaowei19W@gmail.com>
Date: Sat, 5 Nov 2022 01:06:44 +0800
Subject: [PATCH] translation: add the Chinese translation link and categorize
 files

---
 .vitepress/config.js                          | 154 +--------------
 .vitepress/locales/en.js                      | 175 ++++++++++++++++++
 .vitepress/locales/index.js                   |  13 ++
 .vitepress/locales/zh.js                      | 175 ++++++++++++++++++
 src/zh/{ => archive}/array-refs.md            |   0
 src/zh/{ => archive}/introduction.md          |   0
 src/zh/{ => archive}/suspense.md              |   0
 .../async-components.md                       |   0
 .../attribute-coercion.md                     |   0
 .../attrs-includes-class-style.md             |   0
 src/zh/{ => breaking-changes}/children.md     |   0
 .../custom-directives.md                      |   0
 .../custom-elements-interop.md                |   0
 src/zh/{ => breaking-changes}/data-option.md  |   0
 src/zh/{ => breaking-changes}/emits-option.md |   0
 src/zh/{ => breaking-changes}/events-api.md   |   0
 src/zh/{ => breaking-changes}/filters.md      |   0
 .../functional-components.md                  |   0
 .../global-api-treeshaking.md                 |   0
 src/zh/{ => breaking-changes}/global-api.md   |   0
 src/zh/breaking-changes/index.md              |  66 +++++++
 .../inline-template-attribute.md              |   0
 .../{ => breaking-changes}/key-attribute.md   |   0
 .../keycode-modifiers.md                      |   0
 .../listeners-removed.md                      |   0
 .../{ => breaking-changes}/mount-changes.md   |   0
 src/zh/{ => breaking-changes}/props-data.md   |   0
 .../props-default-this.md                     |   0
 .../render-function-api.md                    |   0
 .../slots-unification.md                      |   0
 .../transition-as-root.md                     |   0
 .../transition-group.md                       |   0
 src/zh/{ => breaking-changes}/transition.md   |   0
 src/zh/{ => breaking-changes}/v-bind.md       |   0
 src/zh/{ => breaking-changes}/v-if-v-for.md   |   0
 src/zh/{ => breaking-changes}/v-model.md      |   0
 .../v-on-native-modifier-removed.md           |   0
 .../vnode-lifecycle-events.md                 |   0
 src/zh/{ => breaking-changes}/watch.md        |   0
 src/zh/index.md                               | 119 ++++++++++++
 src/zh/{ => new}/fragments.md                 |   0
 src/zh/recommendations.md                     |  75 ++++++++
 42 files changed, 627 insertions(+), 150 deletions(-)
 create mode 100644 .vitepress/locales/en.js
 create mode 100644 .vitepress/locales/index.js
 create mode 100644 .vitepress/locales/zh.js
 rename src/zh/{ => archive}/array-refs.md (100%)
 rename src/zh/{ => archive}/introduction.md (100%)
 rename src/zh/{ => archive}/suspense.md (100%)
 rename src/zh/{ => breaking-changes}/async-components.md (100%)
 rename src/zh/{ => breaking-changes}/attribute-coercion.md (100%)
 rename src/zh/{ => breaking-changes}/attrs-includes-class-style.md (100%)
 rename src/zh/{ => breaking-changes}/children.md (100%)
 rename src/zh/{ => breaking-changes}/custom-directives.md (100%)
 rename src/zh/{ => breaking-changes}/custom-elements-interop.md (100%)
 rename src/zh/{ => breaking-changes}/data-option.md (100%)
 rename src/zh/{ => breaking-changes}/emits-option.md (100%)
 rename src/zh/{ => breaking-changes}/events-api.md (100%)
 rename src/zh/{ => breaking-changes}/filters.md (100%)
 rename src/zh/{ => breaking-changes}/functional-components.md (100%)
 rename src/zh/{ => breaking-changes}/global-api-treeshaking.md (100%)
 rename src/zh/{ => breaking-changes}/global-api.md (100%)
 create mode 100644 src/zh/breaking-changes/index.md
 rename src/zh/{ => breaking-changes}/inline-template-attribute.md (100%)
 rename src/zh/{ => breaking-changes}/key-attribute.md (100%)
 rename src/zh/{ => breaking-changes}/keycode-modifiers.md (100%)
 rename src/zh/{ => breaking-changes}/listeners-removed.md (100%)
 rename src/zh/{ => breaking-changes}/mount-changes.md (100%)
 rename src/zh/{ => breaking-changes}/props-data.md (100%)
 rename src/zh/{ => breaking-changes}/props-default-this.md (100%)
 rename src/zh/{ => breaking-changes}/render-function-api.md (100%)
 rename src/zh/{ => breaking-changes}/slots-unification.md (100%)
 rename src/zh/{ => breaking-changes}/transition-as-root.md (100%)
 rename src/zh/{ => breaking-changes}/transition-group.md (100%)
 rename src/zh/{ => breaking-changes}/transition.md (100%)
 rename src/zh/{ => breaking-changes}/v-bind.md (100%)
 rename src/zh/{ => breaking-changes}/v-if-v-for.md (100%)
 rename src/zh/{ => breaking-changes}/v-model.md (100%)
 rename src/zh/{ => breaking-changes}/v-on-native-modifier-removed.md (100%)
 rename src/zh/{ => breaking-changes}/vnode-lifecycle-events.md (100%)
 rename src/zh/{ => breaking-changes}/watch.md (100%)
 create mode 100644 src/zh/index.md
 rename src/zh/{ => new}/fragments.md (100%)
 create mode 100644 src/zh/recommendations.md

diff --git a/.vitepress/config.js b/.vitepress/config.js
index 5f8ca76..17824ce 100644
--- a/.vitepress/config.js
+++ b/.vitepress/config.js
@@ -1,156 +1,10 @@
+import locales from './locales'
+
 export default {
-  title: 'Vue 3 Migration Guide',
-  description: 'Guide on migrating from Vue 2 to Vue 3',
   srcDir: 'src',
+  locales: locales.vitepressConfig,
 
   themeConfig: {
-    nav: [{ text: 'Vue 3 Docs', link: 'https://vuejs.org' }],
-
-    sidebar: [
-      {
-        text: 'Guide',
-        items: [
-          { text: 'Overview', link: '/' },
-          { text: 'New Recommendations', link: '/recommendations' },
-          { text: 'Migration Build', link: '/migration-build' },
-          {
-            text: 'Breaking Changes',
-            link: '/breaking-changes/'
-          }
-        ]
-      },
-      {
-        text: 'Global API',
-        items: [
-          {
-            text: 'Global API Application Instance',
-            link: '/breaking-changes/global-api'
-          },
-          {
-            text: 'Global API Treeshaking',
-            link: '/breaking-changes/global-api-treeshaking'
-          }
-        ]
-      },
-      {
-        text: 'Template Directives',
-        items: [
-          { text: 'v-model', link: '/breaking-changes/v-model' },
-          {
-            text: 'key Usage Change',
-            link: '/breaking-changes/key-attribute'
-          },
-          {
-            text: 'v-if vs. v-for Precedence',
-            link: '/breaking-changes/v-if-v-for'
-          },
-          { text: 'v-bind Merge Behavior', link: '/breaking-changes/v-bind' },
-          {
-            text: 'v-on.native modifier removed',
-            link: '/breaking-changes/v-on-native-modifier-removed'
-          }
-        ]
-      },
-      {
-        text: 'Components',
-        items: [
-          {
-            text: 'Functional Components',
-            link: '/breaking-changes/functional-components'
-          },
-          {
-            text: 'Async Components',
-            link: '/breaking-changes/async-components'
-          },
-          { text: 'emits Option', link: '/breaking-changes/emits-option' }
-        ]
-      },
-      {
-        text: 'Render Function',
-        items: [
-          {
-            text: 'Render Function API',
-            link: '/breaking-changes/render-function-api'
-          },
-          {
-            text: 'Slots Unification',
-            link: '/breaking-changes/slots-unification'
-          },
-          {
-            text: '$listeners merged into $attrs',
-            link: '/breaking-changes/listeners-removed'
-          },
-          {
-            text: '$attrs includes class & style',
-            link: '/breaking-changes/attrs-includes-class-style'
-          }
-        ]
-      },
-      {
-        text: 'Custom Elements',
-        items: [
-          {
-            text: 'Custom Elements Interop Changes',
-            link: '/breaking-changes/custom-elements-interop'
-          }
-        ]
-      },
-      {
-        text: 'Removed APIs',
-        items: [
-          {
-            text: 'v-on keyCode Modifiers',
-            link: '/breaking-changes/keycode-modifiers'
-          },
-          { text: 'Events API', link: '/breaking-changes/events-api' },
-          { text: 'Filters', link: '/breaking-changes/filters' },
-          {
-            text: 'inline-template',
-            link: '/breaking-changes/inline-template-attribute'
-          },
-          { text: '$children', link: '/breaking-changes/children' },
-          { text: 'propsData option', link: '/breaking-changes/props-data' }
-        ]
-      },
-      {
-        text: 'Other Minor Changes',
-        items: [
-          {
-            text: 'Attribute Coercion Behavior',
-            link: '/breaking-changes/attribute-coercion'
-          },
-          {
-            text: 'Custom Directives',
-            link: '/breaking-changes/custom-directives'
-          },
-          { text: 'Data Option', link: '/breaking-changes/data-option' },
-          {
-            text: 'Mount API changes',
-            link: '/breaking-changes/mount-changes'
-          },
-          {
-            text: 'Props Default Function this Access',
-            link: '/breaking-changes/props-default-this'
-          },
-          {
-            text: 'Transition Class Change',
-            link: '/breaking-changes/transition'
-          },
-          {
-            text: 'Transition as Root',
-            link: '/breaking-changes/transition-as-root'
-          },
-          {
-            text: 'Transition Group Root Element',
-            link: '/breaking-changes/transition-group'
-          },
-          {
-            text: 'VNode lifecycle events',
-            link: '/breaking-changes/vnode-lifecycle-events'
-          },
-          { text: 'Watch on Arrays', link: '/breaking-changes/watch' }
-        ]
-      }
-    ]
+    locales: locales.themeConfig
   }
 }
diff --git a/.vitepress/locales/en.js b/.vitepress/locales/en.js
new file mode 100644
index 0000000..04e8c95
--- /dev/null
+++ b/.vitepress/locales/en.js
@@ -0,0 +1,175 @@
+export default {
+  vitepressConfig: {
+    title: 'Vue 3 Migration Guide',
+    lang: 'en-US',
+    description: 'Guide on migrating from Vue 2 to Vue 3',
+  },
+  themeConfig: {
+    localeLinks: {
+      text: 'English',
+      items: [
+        { text: '简体中文', link: '/zh/' },
+      ]
+    },
+
+    nav: [
+      { text: 'Docs', link: '/' },
+      {
+        text: 'Links',
+        items: [
+          {
+            text: 'Vue 3 Docs',
+            link: 'https://vuejs.org',
+          }
+        ]
+      }
+    ],
+
+    sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          { text: 'Overview', link: '/' },
+          { text: 'New Recommendations', link: '/recommendations' },
+          { text: 'Migration Build', link: '/migration-build' },
+          {
+            text: 'Breaking Changes',
+            link: '/breaking-changes/'
+          }
+        ]
+      },
+      {
+        text: 'Global API',
+        items: [
+          {
+            text: 'Global API Application Instance',
+            link: '/breaking-changes/global-api'
+          },
+          {
+            text: 'Global API Treeshaking',
+            link: '/breaking-changes/global-api-treeshaking'
+          }
+        ]
+      },
+      {
+        text: 'Template Directives',
+        items: [
+          { text: 'v-model', link: '/breaking-changes/v-model' },
+          {
+            text: 'key Usage Change',
+            link: '/breaking-changes/key-attribute'
+          },
+          {
+            text: 'v-if vs. v-for Precedence',
+            link: '/breaking-changes/v-if-v-for'
+          },
+          { text: 'v-bind Merge Behavior', link: '/breaking-changes/v-bind' },
+          {
+            text: 'v-on.native modifier removed',
+            link: '/breaking-changes/v-on-native-modifier-removed'
+          }
+        ]
+      },
+      {
+        text: 'Components',
+        items: [
+          {
+            text: 'Functional Components',
+            link: '/breaking-changes/functional-components'
+          },
+          {
+            text: 'Async Components',
+            link: '/breaking-changes/async-components'
+          },
+          { text: 'emits Option', link: '/breaking-changes/emits-option' }
+        ]
+      },
+      {
+        text: 'Render Function',
+        items: [
+          {
+            text: 'Render Function API',
+            link: '/breaking-changes/render-function-api'
+          },
+          {
+            text: 'Slots Unification',
+            link: '/breaking-changes/slots-unification'
+          },
+          {
+            text: '$listeners merged into $attrs',
+            link: '/breaking-changes/listeners-removed'
+          },
+          {
+            text: '$attrs includes class & style',
+            link: '/breaking-changes/attrs-includes-class-style'
+          }
+        ]
+      },
+      {
+        text: 'Custom Elements',
+        items: [
+          {
+            text: 'Custom Elements Interop Changes',
+            link: '/breaking-changes/custom-elements-interop'
+          }
+        ]
+      },
+      {
+        text: 'Removed APIs',
+        items: [
+          {
+            text: 'v-on keyCode Modifiers',
+            link: '/breaking-changes/keycode-modifiers'
+          },
+          { text: 'Events API', link: '/breaking-changes/events-api' },
+          { text: 'Filters', link: '/breaking-changes/filters' },
+          {
+            text: 'inline-template',
+            link: '/breaking-changes/inline-template-attribute'
+          },
+          { text: '$children', link: '/breaking-changes/children' },
+          { text: 'propsData option', link: '/breaking-changes/props-data' }
+        ]
+      },
+      {
+        text: 'Other Minor Changes',
+        items: [
+          {
+            text: 'Attribute Coercion Behavior',
+            link: '/breaking-changes/attribute-coercion'
+          },
+          {
+            text: 'Custom Directives',
+            link: '/breaking-changes/custom-directives'
+          },
+          { text: 'Data Option', link: '/breaking-changes/data-option' },
+          {
+            text: 'Mount API changes',
+            link: '/breaking-changes/mount-changes'
+          },
+          {
+            text: 'Props Default Function this Access',
+            link: '/breaking-changes/props-default-this'
+          },
+          {
+            text: 'Transition Class Change',
+            link: '/breaking-changes/transition'
+          },
+          {
+            text: 'Transition as Root',
+            link: '/breaking-changes/transition-as-root'
+          },
+          {
+            text: 'Transition Group Root Element',
+            link: '/breaking-changes/transition-group'
+          },
+          {
+            text: 'VNode lifecycle events',
+            link: '/breaking-changes/vnode-lifecycle-events'
+          },
+          { text: 'Watch on Arrays', link: '/breaking-changes/watch' }
+        ]
+      }
+    ]
+  },
+}
diff --git a/.vitepress/locales/index.js b/.vitepress/locales/index.js
new file mode 100644
index 0000000..b1c0ff4
--- /dev/null
+++ b/.vitepress/locales/index.js
@@ -0,0 +1,13 @@
+import en from './en.js'
+import zh from './zh.js'
+
+export default {
+  vitepressConfig: {
+    '/': en.vitepressConfig,
+    '/zh/': zh.vitepressConfig,
+  },
+  themeConfig: {
+    '/': en.themeConfig,
+    '/zh/': zh.themeConfig,
+  },
+}
diff --git a/.vitepress/locales/zh.js b/.vitepress/locales/zh.js
new file mode 100644
index 0000000..87aeeeb
--- /dev/null
+++ b/.vitepress/locales/zh.js
@@ -0,0 +1,175 @@
+export default {
+  vitepressConfig: {
+    title: 'Vue 3 迁移指南',
+    lang: 'zh-CN',
+    description: 'Guide on migrating from Vue 2 to Vue 3',
+  },
+  themeConfig: {
+    localeLinks: {
+      text: '简体中文',
+      items: [
+        { text: 'English', link: '/' },
+      ]
+    },
+
+    nav: [
+      { text: '指南', link: '/zh/' },
+      {
+        text: '相关链接',
+        items: [
+          {
+            text: 'Vue 3 文档',
+            link: 'https://vuejs.org',
+          }
+        ]
+      }
+    ],
+
+    sidebar: [
+      {
+        text: '指南',
+        items: [
+          { text: '概览', link: '/zh/' },
+          { text: '建议', link: '/zh/recommendations' },
+          { text: '用于迁移的构建版本', link: '/zh/migration-build' },
+          {
+            text: '非兼容的变更',
+            link: '/zh/breaking-changes/'
+          }
+        ]
+      },
+      {
+        text: '全局 API',
+        items: [
+          {
+            text: '全局 API',
+            link: '/zh/breaking-changes/global-api'
+          },
+          {
+            text: '全局 API Treeshaking',
+            link: '/zh/breaking-changes/global-api-treeshaking'
+          }
+        ]
+      },
+      {
+        text: '模板指令',
+        items: [
+          { text: 'v-model', link: '/zh/breaking-changes/v-model' },
+          {
+            text: 'key 用法改变',
+            link: '/zh/breaking-changes/key-attribute'
+          },
+          {
+            text: 'v-if 与 v-for 的优先级对比',
+            link: '/zh/breaking-changes/v-if-v-for'
+          },
+          { text: 'v-bind 合并行为', link: '/zh/breaking-changes/v-bind' },
+          {
+            text: '移除 v-on.native 修饰符',
+            link: '/zh/breaking-changes/v-on-native-modifier-removed'
+          }
+        ]
+      },
+      {
+        text: '组件',
+        items: [
+          {
+            text: '函数式组件',
+            link: '/zh/breaking-changes/functional-components'
+          },
+          {
+            text: '异步组件',
+            link: '/zh/breaking-changes/async-components'
+          },
+          { text: 'emits 选项', link: '/zh/breaking-changes/emits-option' }
+        ]
+      },
+      {
+        text: '渲染函数',
+        items: [
+          {
+            text: '渲染函数 API',
+            link: '/zh/breaking-changes/render-function-api'
+          },
+          {
+            text: '插槽统一',
+            link: '/zh/breaking-changes/slots-unification'
+          },
+          {
+            text: '$listeners 合并入 $attrs',
+            link: '/zh/breaking-changes/listeners-removed'
+          },
+          {
+            text: '$attrs 包含 class & style',
+            link: '/zh/breaking-changes/attrs-includes-class-style'
+          }
+        ]
+      },
+      {
+        text: '自定义元素',
+        items: [
+          {
+            text: '与自定义元素的互操作性',
+            link: '/zh/breaking-changes/custom-elements-interop'
+          }
+        ]
+      },
+      {
+        text: '移除的 API',
+        items: [
+          {
+            text: 'v-on 按键修饰符',
+            link: '/zh/breaking-changes/keycode-modifiers'
+          },
+          { text: '事件 API', link: '/zh/breaking-changes/events-api' },
+          { text: 'Filters', link: '/zh/breaking-changes/filters' },
+          {
+            text: '内联模板',
+            link: '/zh/breaking-changes/inline-template-attribute'
+          },
+          { text: '$children', link: '/zh/breaking-changes/children' },
+          { text: 'propsData 选项', link: '/zh/breaking-changes/props-data' }
+        ]
+      },
+      {
+        text: '其他细微改动',
+        items: [
+          {
+            text: 'Attribute 强制行为',
+            link: '/zh/breaking-changes/attribute-coercion'
+          },
+          {
+            text: '自定义指令',
+            link: '/zh/breaking-changes/custom-directives'
+          },
+          { text: 'Data 选项', link: '/zh/breaking-changes/data-option' },
+          {
+            text: '挂载 API 变化',
+            link: '/zh/breaking-changes/mount-changes'
+          },
+          {
+            text: '在 prop 的默认函数中访问 this',
+            link: '/zh/breaking-changes/props-default-this'
+          },
+          {
+            text: '过渡的 class 名更改',
+            link: '/zh/breaking-changes/transition'
+          },
+          {
+            text: 'Transition 作为根节点',
+            link: '/zh/breaking-changes/transition-as-root'
+          },
+          {
+            text: 'Transition Group 根元素',
+            link: '/zh/breaking-changes/transition-group'
+          },
+          {
+            text: 'VNode 生命周期事件',
+            link: '/zh/breaking-changes/vnode-lifecycle-events'
+          },
+          { text: '侦听数组', link: '/zh/breaking-changes/watch' }
+        ]
+      }
+    ]
+  }
+}
diff --git a/src/zh/array-refs.md b/src/zh/archive/array-refs.md
similarity index 100%
rename from src/zh/array-refs.md
rename to src/zh/archive/array-refs.md
diff --git a/src/zh/introduction.md b/src/zh/archive/introduction.md
similarity index 100%
rename from src/zh/introduction.md
rename to src/zh/archive/introduction.md
diff --git a/src/zh/suspense.md b/src/zh/archive/suspense.md
similarity index 100%
rename from src/zh/suspense.md
rename to src/zh/archive/suspense.md
diff --git a/src/zh/async-components.md b/src/zh/breaking-changes/async-components.md
similarity index 100%
rename from src/zh/async-components.md
rename to src/zh/breaking-changes/async-components.md
diff --git a/src/zh/attribute-coercion.md b/src/zh/breaking-changes/attribute-coercion.md
similarity index 100%
rename from src/zh/attribute-coercion.md
rename to src/zh/breaking-changes/attribute-coercion.md
diff --git a/src/zh/attrs-includes-class-style.md b/src/zh/breaking-changes/attrs-includes-class-style.md
similarity index 100%
rename from src/zh/attrs-includes-class-style.md
rename to src/zh/breaking-changes/attrs-includes-class-style.md
diff --git a/src/zh/children.md b/src/zh/breaking-changes/children.md
similarity index 100%
rename from src/zh/children.md
rename to src/zh/breaking-changes/children.md
diff --git a/src/zh/custom-directives.md b/src/zh/breaking-changes/custom-directives.md
similarity index 100%
rename from src/zh/custom-directives.md
rename to src/zh/breaking-changes/custom-directives.md
diff --git a/src/zh/custom-elements-interop.md b/src/zh/breaking-changes/custom-elements-interop.md
similarity index 100%
rename from src/zh/custom-elements-interop.md
rename to src/zh/breaking-changes/custom-elements-interop.md
diff --git a/src/zh/data-option.md b/src/zh/breaking-changes/data-option.md
similarity index 100%
rename from src/zh/data-option.md
rename to src/zh/breaking-changes/data-option.md
diff --git a/src/zh/emits-option.md b/src/zh/breaking-changes/emits-option.md
similarity index 100%
rename from src/zh/emits-option.md
rename to src/zh/breaking-changes/emits-option.md
diff --git a/src/zh/events-api.md b/src/zh/breaking-changes/events-api.md
similarity index 100%
rename from src/zh/events-api.md
rename to src/zh/breaking-changes/events-api.md
diff --git a/src/zh/filters.md b/src/zh/breaking-changes/filters.md
similarity index 100%
rename from src/zh/filters.md
rename to src/zh/breaking-changes/filters.md
diff --git a/src/zh/functional-components.md b/src/zh/breaking-changes/functional-components.md
similarity index 100%
rename from src/zh/functional-components.md
rename to src/zh/breaking-changes/functional-components.md
diff --git a/src/zh/global-api-treeshaking.md b/src/zh/breaking-changes/global-api-treeshaking.md
similarity index 100%
rename from src/zh/global-api-treeshaking.md
rename to src/zh/breaking-changes/global-api-treeshaking.md
diff --git a/src/zh/global-api.md b/src/zh/breaking-changes/global-api.md
similarity index 100%
rename from src/zh/global-api.md
rename to src/zh/breaking-changes/global-api.md
diff --git a/src/zh/breaking-changes/index.md b/src/zh/breaking-changes/index.md
new file mode 100644
index 0000000..d1f5aa6
--- /dev/null
+++ b/src/zh/breaking-changes/index.md
@@ -0,0 +1,66 @@
+# 非兼容的变更
+
+This page lists all Vue 3 breaking changes from Vue 2.
+
+While it looks like a lot has changed, a lot of what you know and love about Vue is still the same; but we wanted to be as thorough as possible and provide detailed explanations and examples for every documented change.
+
+## Details
+
+### Global API
+
+- [Global Vue API is changed to use an application instance](./global-api.html)
+- [Global and internal APIs have been restructured to be tree-shakable](./global-api-treeshaking.html)
+
+### Template Directives
+
+- [`v-model` usage on components has been reworked, replacing `v-bind.sync`](./v-model.html)
+- [`key` usage on `<template v-for>` and non-`v-for` nodes has changed](./key-attribute.html)
+- [`v-if` and `v-for` precedence when used on the same element has changed](./v-if-v-for.html)
+- [`v-bind="object"` is now order-sensitive](./v-bind.html)
+- [`v-on:event.native` modifier has been removed](./v-on-native-modifier-removed.md)
+
+### Components
+
+- [Functional components can only be created using a plain function](./functional-components.html)
+- [`functional` attribute on single-file component (SFC) `<template>` and `functional` component option are deprecated](./functional-components.html)
+- [Async components now require `defineAsyncComponent` method to be created](./async-components.html)
+- [Component events should now be declared with the `emits` option](./emits-option.md)
+
+### Render Function
+
+- [Render function API changed](./render-function-api.html)
+- [`$scopedSlots` property is removed and all slots are exposed via `$slots` as functions](./slots-unification.html)
+- [`$listeners` has been removed / merged into `$attrs`](./listeners-removed)
+- [`$attrs` now includes `class` and `style` attributes](./attrs-includes-class-style.md)
+
+### Custom Elements
+
+- [Custom element checks are now performed during template compilation](./custom-elements-interop.html)
+- [Special `is` attribute usage is restricted to the reserved `<component>` tag only](./custom-elements-interop.html#customized-built-in-elements)
+
+### Other Minor Changes
+
+- The `destroyed` lifecycle option has been renamed to `unmounted`
+- The `beforeDestroy` lifecycle option has been renamed to `beforeUnmount`
+- [Props `default` factory function no longer has access to `this` context](./props-default-this.html)
+- [Custom directive API changed to align with component lifecycle and `binding.expression` removed](./custom-directives.html)
+- [The `data` option should always be declared as a function](./data-option.html)
+- [The `data` option from mixins is now merged shallowly](./data-option.html#mixin-merge-behavior-change)
+- [Attributes coercion strategy changed](./attribute-coercion.html)
+- [Some transition classes got a rename](./transition.html)
+- [`<TransitionGroup>` now renders no wrapper element by default](./transition-group.html)
+- [When watching an array, the callback will only trigger when the array is replaced. If you need to trigger on mutation, the `deep` option must be specified.](./watch.html)
+- `<template>` tags with no special directives (`v-if/else-if/else`, `v-for`, or `v-slot`) are now treated as plain elements and will result in a native `<template>` element instead of rendering its inner content.
+- [Mounted application does not replace the element it's mounted to](./mount-changes.html)
+- [Lifecycle `hook:` events prefix changed to `vnode-`](./vnode-lifecycle-events.html)
+
+### Removed APIs
+
+- [`keyCode` support as `v-on` modifiers](./keycode-modifiers.html)
+- [$on, $off and \$once instance methods](./events-api.html)
+- [Filters](./filters.html)
+- [Inline templates attributes](./inline-template-attribute.html)
+- [`$children` instance property](./children.html)
+- [`propsData` option](./props-data.html)
+- `$destroy` instance method. Users should no longer manually manage the lifecycle of individual Vue components.
+- Global functions `set` and `delete`, and the instance methods `$set` and `$delete`. They are no longer required with proxy-based change detection.
diff --git a/src/zh/inline-template-attribute.md b/src/zh/breaking-changes/inline-template-attribute.md
similarity index 100%
rename from src/zh/inline-template-attribute.md
rename to src/zh/breaking-changes/inline-template-attribute.md
diff --git a/src/zh/key-attribute.md b/src/zh/breaking-changes/key-attribute.md
similarity index 100%
rename from src/zh/key-attribute.md
rename to src/zh/breaking-changes/key-attribute.md
diff --git a/src/zh/keycode-modifiers.md b/src/zh/breaking-changes/keycode-modifiers.md
similarity index 100%
rename from src/zh/keycode-modifiers.md
rename to src/zh/breaking-changes/keycode-modifiers.md
diff --git a/src/zh/listeners-removed.md b/src/zh/breaking-changes/listeners-removed.md
similarity index 100%
rename from src/zh/listeners-removed.md
rename to src/zh/breaking-changes/listeners-removed.md
diff --git a/src/zh/mount-changes.md b/src/zh/breaking-changes/mount-changes.md
similarity index 100%
rename from src/zh/mount-changes.md
rename to src/zh/breaking-changes/mount-changes.md
diff --git a/src/zh/props-data.md b/src/zh/breaking-changes/props-data.md
similarity index 100%
rename from src/zh/props-data.md
rename to src/zh/breaking-changes/props-data.md
diff --git a/src/zh/props-default-this.md b/src/zh/breaking-changes/props-default-this.md
similarity index 100%
rename from src/zh/props-default-this.md
rename to src/zh/breaking-changes/props-default-this.md
diff --git a/src/zh/render-function-api.md b/src/zh/breaking-changes/render-function-api.md
similarity index 100%
rename from src/zh/render-function-api.md
rename to src/zh/breaking-changes/render-function-api.md
diff --git a/src/zh/slots-unification.md b/src/zh/breaking-changes/slots-unification.md
similarity index 100%
rename from src/zh/slots-unification.md
rename to src/zh/breaking-changes/slots-unification.md
diff --git a/src/zh/transition-as-root.md b/src/zh/breaking-changes/transition-as-root.md
similarity index 100%
rename from src/zh/transition-as-root.md
rename to src/zh/breaking-changes/transition-as-root.md
diff --git a/src/zh/transition-group.md b/src/zh/breaking-changes/transition-group.md
similarity index 100%
rename from src/zh/transition-group.md
rename to src/zh/breaking-changes/transition-group.md
diff --git a/src/zh/transition.md b/src/zh/breaking-changes/transition.md
similarity index 100%
rename from src/zh/transition.md
rename to src/zh/breaking-changes/transition.md
diff --git a/src/zh/v-bind.md b/src/zh/breaking-changes/v-bind.md
similarity index 100%
rename from src/zh/v-bind.md
rename to src/zh/breaking-changes/v-bind.md
diff --git a/src/zh/v-if-v-for.md b/src/zh/breaking-changes/v-if-v-for.md
similarity index 100%
rename from src/zh/v-if-v-for.md
rename to src/zh/breaking-changes/v-if-v-for.md
diff --git a/src/zh/v-model.md b/src/zh/breaking-changes/v-model.md
similarity index 100%
rename from src/zh/v-model.md
rename to src/zh/breaking-changes/v-model.md
diff --git a/src/zh/v-on-native-modifier-removed.md b/src/zh/breaking-changes/v-on-native-modifier-removed.md
similarity index 100%
rename from src/zh/v-on-native-modifier-removed.md
rename to src/zh/breaking-changes/v-on-native-modifier-removed.md
diff --git a/src/zh/vnode-lifecycle-events.md b/src/zh/breaking-changes/vnode-lifecycle-events.md
similarity index 100%
rename from src/zh/vnode-lifecycle-events.md
rename to src/zh/breaking-changes/vnode-lifecycle-events.md
diff --git a/src/zh/watch.md b/src/zh/breaking-changes/watch.md
similarity index 100%
rename from src/zh/watch.md
rename to src/zh/breaking-changes/watch.md
diff --git a/src/zh/index.md b/src/zh/index.md
new file mode 100644
index 0000000..bd636a1
--- /dev/null
+++ b/src/zh/index.md
@@ -0,0 +1,119 @@
+# Vue 3 Migration Guide
+
+This guide is primarily for users with prior Vue 2 experience who want to learn about the changes between Vue 2 and Vue 3. **This is not something you have to read from top to bottom before trying out Vue 3.** The recommended way to learn Vue 3 is by reading the [new documentation](https://vuejs.org).
+
+<!-- VueMastery Start -->
+<style>
+.vue-mastery-link {
+  background-color: #f9f9f9;
+  border-radius: 8px;
+  padding: 8px 16px 8px 8px;
+}
+
+.vue-mastery-link a {
+  display: flex;
+  align-items: center;
+  text-decoration: none;
+}
+
+.vue-mastery-link .banner {
+  background-color: #f9f9f9;
+  border-radius: 4px;
+  width:96px;
+  height:56px;
+  object-fit: cover;
+}
+
+.vue-mastery-link .description {
+  flex: 1;
+  font-weight: 500;
+  font-size: 14px;
+  line-height: 20px;
+  color: #213547;
+  margin: 0 0 0 16px;
+}
+
+.vue-mastery-link .description span {
+  color: #42b883;
+}
+
+.vue-mastery-link .logo-wrapper {
+  position: relative;
+  width: 48px;
+  height: 48px;
+  border-radius: 50%;
+  background-color: #ffffff;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+}
+
+.vue-mastery-link .logo-wrapper img {
+  width: 25px;
+  object-fit: contain;
+}
+
+@media (max-width: 576px) {
+  .vue-mastery-link .banner {
+    width:56px;
+  }
+
+  .vue-mastery-link .description {
+    font-size: 12px;
+    line-height: 18px;
+  }
+  .vue-mastery-link .logo-wrapper {
+    position: relative;
+    width: 32px;
+    height: 32px;
+  }
+}
+</style>
+
+<div class="vue-mastery-link">
+  <a href="https://www.vuemastery.com/migration-guide-cheat-sheet/" target="_blank">
+    <div class="banner-wrapper">
+      <img class="banner" alt="Vue Mastery banner" width="96px" height="56px" src="https://storage.googleapis.com/vue-mastery.appspot.com/flamelink/media/vuemastery-graphical-link-96x56.png" />
+    </div>
+    <p class="description">Get the free Migration Guide Cheat Sheet at <span>VueMastery.com</span></p>
+    <div class="logo-wrapper">
+        <img alt="Vue Mastery Logo" width="25px" src="https://storage.googleapis.com/vue-mastery.appspot.com/flamelink/media/vue-mastery-logo.png" />
+    </div>
+  </a>
+</div>
+<!-- VueMastery End -->
+
+<style>
+.note {
+  color: #476582;
+}
+</style>
+
+## Notable New Features
+
+Some of the new features to keep an eye on in Vue 3 include:
+
+- [Composition API](https://vuejs.org/guide/extras/composition-api-faq.html)<span class="note">\*</span>
+- [SFC Composition API Syntax Sugar (`<script setup>`)](https://vuejs.org/api/sfc-script-setup.html)<span class="note">\*</span>
+- [Teleport](https://vuejs.org/guide/built-ins/teleport.html)
+- [Fragments](/new/fragments.html)
+- [Emits Component Option](https://vuejs.org/api/options-state.html#emits)<span class="note">\*\*</span>
+- [`createRenderer` API from `@vue/runtime-core`](https://vuejs.org/api/custom-renderer.html) to create custom renderers
+- [SFC State-driven CSS Variables (`v-bind` in `<style>`)](https://vuejs.org/api/sfc-css-features.html#v-bind-in-css)<span class="note">\*</span>
+- [SFC `<style scoped>` can now include global rules or rules that target only slotted content](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0023-scoped-styles-changes.md)
+- [Suspense](https://vuejs.org/guide/built-ins/suspense.html) <sup class="warning">experimental</sup>
+
+<sub class="note"><b>\*</b> Now also supported in <a href="https://blog.vuejs.org/posts/vue-2-7-naruto.html" target="_blank">Vue 2.7</a></sub><br>
+<sub class="note"><b>\*\*</b> Supported in Vue 2.7, but only for type inference</sub>
+
+## Breaking Changes
+
+Breaking changes between Vue 2 and Vue 3 are listed [here](/breaking-changes/).
+
+## New Framework-level Recommendations
+
+New framework-level recommendations are listed [here](/recommendations).
+
+## Migration Build
+
+If you have an existing Vue 2 project or library that you intend to upgrade to Vue 3, we provide a build of Vue 3 that offers Vue 2 compatible APIs. Check out the [Migration Build](./migration-build.html) page for more details.
diff --git a/src/zh/fragments.md b/src/zh/new/fragments.md
similarity index 100%
rename from src/zh/fragments.md
rename to src/zh/new/fragments.md
diff --git a/src/zh/recommendations.md b/src/zh/recommendations.md
new file mode 100644
index 0000000..4dde1fe
--- /dev/null
+++ b/src/zh/recommendations.md
@@ -0,0 +1,75 @@
+# New Framework-level Recommendations
+
+The supporting libraries for Vue 3 have undergone major updates. Here is a summary of the new default recommendations:
+
+- New versions of Router, Devtools & test utils w/ Vue 3 support
+- Build Toolchain: Vue CLI -> [Vite](https://vitejs.dev/)
+- State Management: Vuex -> [Pinia](https://pinia.vuejs.org/)
+- IDE Support: Vetur -> [Volar](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volar)
+- New command line TypeScript support: [vue-tsc](https://github.com/johnsoncodehk/volar/tree/master/packages/vue-tsc)
+- SSG: VuePress -> [VitePress](https://vitepress.vuejs.org/)
+- JSX: `@vue/babel-preset-jsx` -> [`@vue/babel-plugin-jsx`](https://github.com/vuejs/jsx-next)
+
+## Details
+
+### Build Toolchain
+
+We now recommend [Vite](https://vitejs.dev/) as the new build toolchain for Vue 3 projects. Vite is a new build tool that offers extremely fast server start and hot update performance. It was originally created by the Vue team but is now a cross-framework tool. Learn more about [why we are recommending Vite](https://vitejs.dev/guide/why.html).
+
+You can create a new Vite-powered Vue 3 project via [`create-vue`](https://github.com/vuejs/create-vue), our new scaffolding tool:
+
+```sh
+npm init vue@3
+```
+
+While Vue CLI has also been upgraded to support Vue 3, it is now in maintenance and no longer recommended for new projects. For information on migrating from Vue CLI to Vite:
+
+- [Vue CLI -> Vite Migration Guide from VueSchool.io](https://vueschool.io/articles/vuejs-tutorials/how-to-migrate-from-vue-cli-to-vite/)
+- [Tools / Plugins that help with auto migration](https://github.com/vitejs/awesome-vite#vue-cli)
+
+Also see [Tooling chapter in new docs](https://vuejs.org/guide/scaling-up/tooling.html).
+
+### Vue Router
+
+Vue Router 4.0 provides Vue 3 support and has a number of breaking changes of its own. Check out its [migration guide](https://router.vuejs.org/) for full details.
+
+- [Documentation](https://router.vuejs.org/)
+- [GitHub](https://github.com/vuejs/router)
+- [RFCs](https://github.com/vuejs/rfcs/pulls?q=is%3Apr+is%3Amerged+label%3Arouter)
+
+### State Management
+
+[Pinia](https://pinia.vuejs.org/) is the new recommended large-scale state management solution. Pinia was created as a prototype for Vuex 5, and has now evolved into the de facto implementation for what we had planned for Vuex 5. We decided to keep its original name in respect of the amount of work that went into it by core team member [Eduardo](https://github.com/posva).
+
+- [Documentation](https://pinia.vuejs.org/)
+- [GitHub](https://github.com/vuejs/pinia)
+- [State management chapter in new docs](https://vuejs.org/guide/scaling-up/state-management.html)
+
+Vuex 4.0 also provides Vue 3 support with largely the same API as 3.x, and can be used if you have existing Vuex stores that need to be migrated to Vue 3. The only breaking change is [how the plugin is installed](https://next.vuex.vuejs.org/guide/migrating-to-4-0-from-3-x.html#breaking-changes).
+
+### IDE Support
+
+[Volar](https://github.com/johnsoncodehk/volar) is now the new official VSCode extension, with greatly improved TypeScript support for Vue SFCs, including full type inference for template expressions.
+
+If you have previous installed Vetur, make sure to disable it to avoid conflict with Volar.
+
+### Devtools Extension
+
+The devtools extension has received major updates (released as v6) to support both Vue 2 and Vue 3. If you have previously installed v6 via the beta channel, you can remove it and install the extension from the stable channel now.
+
+- [Documentation](https://devtools.vuejs.org/guide/installation.html)
+- [GitHub](https://github.com/vuejs/devtools)
+
+### TypeScript Support
+
+You can now type-check and generate definition files for Vue SFCs from the command line using [vue-tsc](https://github.com/johnsoncodehk/volar/tree/master/packages/vue-tsc).
+
+Also see [TypeScript Guide in new docs](https://vuejs.org/guide/typescript/overview.html).
+
+### Static Site Generator
+
+[VitePress](https://vitepress.vuejs.org/) is the spiritual successor to VuePress, built on Vue 3 + Vite. It provides a far superior dev experience and also produces faster sites.
+
+### JSX
+
+JSX support for Vue 3 is now provided via [`@vue/babel-plugin-jsx`](https://github.com/vuejs/babel-plugin-jsx).