feat: adjust i18n config + documentation

vuejs · Apr 18, 2018 · bccddbf · bccddbf
1 parent f0a1a00
commit bccddbf
Show file tree

Hide file tree

Showing 13 changed files with 260 additions and 72 deletions.
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -3,15 +3,11 @@ module.exports = {
   locales: {
     '/': {
       lang: 'en-US',
-      label: 'English',
-      selectText: 'Languages',
       title: 'VuePress',
       description: 'Vue-powered Static Site Generator'
     },
     '/zh/': {
       lang: 'zh-CN',
-      label: '简体中文',
-      selectText: '选择语言',
       title: 'VuePress',
       description: 'Vue 驱动的静态网站生成器'
     }
@@ -32,42 +28,51 @@ module.exports = {
     repo: 'vuejs/vuepress',
     editLinks: true,
     docsDir: 'docs',
-    nav: {
-      '/': [
-        {
-          text: 'Guide',
-          link: '/guide/',
-        },
-        {
-          text: 'Config Reference',
-          link: '/config/'
-        },
-        {
-          text: 'Default Theme Config',
-          link: '/default-theme-config/'
+    locales: {
+      '/': {
+        label: 'English',
+        selectText: 'Languages',
+        editLinkText: 'Edit this page on GitHub',
+        nav: [
+          {
+            text: 'Guide',
+            link: '/guide/',
+          },
+          {
+            text: 'Config Reference',
+            link: '/config/'
+          },
+          {
+            text: 'Default Theme Config',
+            link: '/default-theme-config/'
+          }
+        ],
+        sidebar: {
+          '/guide/': genSidebarConfig('Guide')
         }
-      ],
-      '/zh/': [
-        {
-          text: '指南',
-          link: '/zh/guide/',
-        },
-        {
-          text: '配置',
-          link: '/zh/config/'
-        },
-        {
-          text: '默认主题',
-          link: '/zh/default-theme-config/'
+      },
+      '/zh/': {
+        label: '简体中文',
+        selectText: '选择语言',
+        editLinkText: '在 GitHub 上编辑此页',
+        nav: [
+          {
+            text: '指南',
+            link: '/zh/guide/',
+          },
+          {
+            text: '配置',
+            link: '/zh/config/'
+          },
+          {
+            text: '默认主题',
+            link: '/zh/default-theme-config/'
+          }
+        ],
+        sidebar: {
+          '/zh/guide/': genSidebarConfig('指南')
         }
-      ]
-    },
-    sidebar: {
-      '/guide/': genSidebarConfig('Guide'),
-      '/zh/guide/': genSidebarConfig('指南')
-    },
-    editLinkText: {
-      '/zh/': '在 GitHub 上编辑此页'
+      }
     }
   }
 }

diff --git a/docs/config/README.md b/docs/config/README.md
@@ -98,6 +98,13 @@ The `serviceWorker` option only handles the service worker. To make your site fu
 Also, only enable this if you are able to deploy your site with SSL, since service worker can only be registered under HTTPs URLs.
 :::
 
+### locales
+
+- Type: `{ [path: string]: Object }`
+- Default: `undefined`
+
+Specify locales for i18n support. For more details, see the guide on [Internationalization](../guide/i18n.md).
+
 ## Theming
 
 ### theme

diff --git a/docs/default-theme-config/README.md b/docs/default-theme-config/README.md
@@ -231,7 +231,9 @@ module.exports = {
     // optional, defaults to master
     docsBranch: 'master',
     // defaults to true, set to false to disable
-    editLinks: true
+    editLinks: true,
+    // custom text for edit link. Defaults to "Edit this page"
+    editLinkText: 'Help us improve this page!'
   }
 }
 ```

diff --git a/docs/guide/i18n.md b/docs/guide/i18n.md
@@ -0,0 +1,82 @@
+# Internationalization
+
+## Site Level i18n Config
+
+To leverage multi-language support in VuePress, you first need to use the following file structure:
+
+```
+/
+├─ README.md
+├─ foo.md
+├─ /nested/
+│  └─ README.md
+└─ /zh/
+   ├─ README.md
+   ├─ foo.md
+   └─ /zh/nested/
+      └─ README.md
+```
+
+Then, specify the `locales` option in `.vuepress/config.js`:
+
+``` js
+module.exports = {
+  locales: {
+    // The key is the path for the locale to be nested under.
+    // As a special case, the default locale can use '/' as its path.
+    '/': {
+      lang: 'en-US', // this will be set as the lang attribute on <html>
+      title: 'VuePress',
+      description: 'Vue-powered Static Site Generator'
+    },
+    '/zh/': {
+      lang: 'zh-CN',
+      title: 'VuePress',
+      description: 'Vue 驱动的静态网站生成器'
+    }
+  }
+}
+```
+
+If a locale does not have `title` or `description` VuePress will fallback to the root level values. You can omit the root level `title` and `description` as long as they are provided in each locale.
+
+## Default Theme i18n Config
+
+The default theme also has built-in i18n support via `themeConfig.locales`, using the same `{ path: config }` format. Each locale can have its own [nav](../default-theme-config/#navbar-links) and [sidebar](../default-theme-config/#sidebar) config, in addition to a few other text values used across the site:
+
+``` js
+module.exports = {
+  locales: { /* ... */ },
+  themeConfig: {
+    locales: {
+      '/': {
+        // text for the language dropdown
+        selectText: 'Languages',
+        // label for this locale in the language dropdown
+        label: 'English',
+        // text for the edit-on-github link
+        editLinkText: 'Edit this page on GitHub',
+        nav: [
+          { text: 'Nested', link: '/nested/' }
+        ],
+        sidebar: {
+          '/': [/* ... */],
+          '/nested/': [/* ... */]
+        }
+      },
+      '/zh/': {
+        selectText: '选择语言',
+        label: '简体中文',
+        editLinkText: '在 GitHub 上编辑此页',
+        nav: [
+          { text: '嵌套', link: '/zh/nested/' }
+        ],
+        sidebar: {
+          '/zh/': [/* ... */],
+          '/zh/nested/': [/* ... */]
+        }
+      }
+    }
+  }
+}
+```
diff --git a/docs/zh/config/README.md b/docs/zh/config/README.md
@@ -97,6 +97,13 @@ module.exports = {
 当然，仅仅只在你的网站部署后能用 SSL 的时候开启它，因为 service worker 只能在 HTTPs 的链接下注册。
 :::
 
+### locales
+
+- 类型: `{ [path: string]: Object }`
+- 默认值: `undefined`
+
+提供多语言支持的语言配置。具体细节请查看 [多语言支持](../guide/i18n.md)。
+
 ## 主题
 
 ### theme

diff --git a/docs/zh/default-theme-config/README.md b/docs/zh/default-theme-config/README.md
@@ -4,8 +4,8 @@ sidebar: auto
 
 # 默认主题
 
-::: tip
-所有列在这一页的选项仅对默认的主题生效。如果你在使用一个自定义主题，选项可能会有不同。
+::: tip 提示
+本页所列的选项仅对默认主题生效。如果你在使用一个自定义主题，选项可能会有不同。
 :::
 
 ## 首页
@@ -226,7 +226,9 @@ module.exports = {
     // 可选的, 默认是  master
     docsBranch: 'master',
     // 默认是 true, 设置为 false 来禁用
-    editLinks: true
+    editLinks: true,
+    // 默认为 "Edit this page"
+    editLinkText: '帮助我们改善此页面！'
   }
 }
 ```

diff --git a/docs/zh/guide/assets.md b/docs/zh/guide/assets.md
@@ -17,7 +17,7 @@
 ![Image from dependency](~some-dependency/image.png)
 ```
 
-Webpack 的别名可以通过 `.vuepress/config.js` 中 [configureWebpack](/zh/config/#configurewebpack) 来配置，如：
+Webpack 的别名可以通过 `.vuepress/config.js` 中 [configureWebpack](../config/#configurewebpack) 来配置，如：
 
 ``` js
 module.exports = {

diff --git a/docs/zh/guide/i18n.md b/docs/zh/guide/i18n.md
@@ -0,0 +1,82 @@
+# 多语言支持
+
+## 站点多语言配置
+
+要启用 VuePress 的多语言支持，首先需要使用如下的文件结构：
+
+```
+/
+├─ README.md
+├─ foo.md
+├─ /nested/
+│  └─ README.md
+└─ /zh/
+   ├─ README.md
+   ├─ foo.md
+   └─ /zh/nested/
+      └─ README.md
+```
+
+然后，在 `.vuepress/config.js` 中提供 `locales` 选项：
+
+``` js
+module.exports = {
+  locales: {
+    // 键名是该语言所属的子路径
+    // 作为特例，默认语言可以使用 '/' 作为其路径。
+    '/': {
+      lang: 'en-US', // 将会被设置为 <html> 的 lang 属性
+      title: 'VuePress',
+      description: 'Vue-powered Static Site Generator'
+    },
+    '/zh/': {
+      lang: 'zh-CN',
+      title: 'VuePress',
+      description: 'Vue 驱动的静态网站生成器'
+    }
+  }
+}
+```
+
+如果一个语言没有声明 `title` 或者 `description`，VuePress 将会尝试使用配置顶层的对应值。如果每个语言都声明了 `title` 和 `description`，则顶层的这两个值可以被省略。
+
+## 默认主题多语言配置
+
+默认主题也内置了多语言支持，可以通过 `themeConfig.locales` 来配置。该选项接受同样的 `{ path: config }` 格式的值。每个语言除了可以配置一些站点中用到的文字之外，还可以拥有自己的 [导航栏](../default-theme-config/#导航栏) 和 [侧边栏](../default-theme-config/#侧边栏) 配置：
+
+``` js
+module.exports = {
+  locales: { /* ... */ },
+  themeConfig: {
+    locales: {
+      '/': {
+        selectText: 'Languages',
+        label: 'English',
+        editLinkText: 'Edit this page on GitHub',
+        nav: [
+          { text: 'Nested', link: '/nested/' }
+        ],
+        sidebar: {
+          '/': [/* ... */],
+          '/nested/': [/* ... */]
+        }
+      },
+      '/zh/': {
+        // 多语言下拉菜单的标题
+        selectText: '选择语言',
+        // 该语言在下拉菜单中的标签
+        label: '简体中文',
+        // 编辑链接文字
+        editLinkText: '在 GitHub 上编辑此页',
+        nav: [
+          { text: '嵌套', link: '/zh/nested/' }
+        ],
+        sidebar: {
+          '/zh/': [/* ... */],
+          '/zh/nested/': [/* ... */]
+        }
+      }
+    }
+  }
+}
+```
diff --git a/lib/app/dataMixin.js b/lib/app/dataMixin.js
@@ -58,6 +58,9 @@ export default {
     $localePath () {
       return this.$localeConfig.path || '/'
     },
+    $themeLocaleConfig () {
+      return (this.$site.themeConfig.locales || {})[this.$localePath] || {}
+    },
     $page () {
       return findPageForPath(
         this.$site.pages,

diff --git a/lib/default-theme/Layout.vue b/lib/default-theme/Layout.vue
@@ -48,17 +48,16 @@ export default {
       return (
         !frontmatter.layout &&
         !frontmatter.home &&
-        frontmatter.sidebar !== false && (
-          frontmatter.sidebar === 'auto' ||
-          themeConfig.sidebar
-        )
+        frontmatter.sidebar !== false &&
+        this.sidebarItems.length
       )
     },
     sidebarItems () {
       return resolveSidebarItems(
         this.$page,
         this.$route,
-        this.$site
+        this.$site,
+        this.$localePath
       )
     },
     pageClasses() {

diff --git a/lib/default-theme/NavLinks.vue b/lib/default-theme/NavLinks.vue
@@ -30,21 +30,19 @@ export default {
   components: { OutboundLink, NavLink, DropdownLink },
   computed: {
     userNav () {
-      const { nav } = this.$site.themeConfig
-      if (Array.isArray(nav)) return nav
-      if (typeof nav === 'object') return nav[this.$localePath]
-      return []
+      return this.$themeLocaleConfig.nav || this.$site.themeConfig.nav || []
     },
     nav () {
       const { locales } = this.$site
       if (locales) {
         let currentLink = this.$page.path
         const routes = this.$router.options.routes
+        const themeLocales = this.$site.themeConfig.locales || {}
         const languageDropdown = {
-          text: this.$localeConfig.selectText,
+          text: this.$themeLocaleConfig.selectText || 'Languages',
           items: Object.keys(locales).map(path => {
             const locale = locales[path]
-            const text = locale.label
+            const text = themeLocales[path] && themeLocales[path].label || locale.lang
             let link
             // Stay on the current page
             if (locale.lang === this.$lang) {