From 1407baf9b98c343edbc5c2efa31cbc1545ecec2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=83=BD=E5=AE=81?= Date: Tue, 2 Jan 2024 20:22:05 +0800 Subject: [PATCH] docs: improve chinese translation (#3402) --- docs/zh/guide/cms.md | 6 +-- docs/zh/guide/custom-theme.md | 28 +++++----- docs/zh/guide/data-loading.md | 54 ++++++++++---------- docs/zh/guide/deploy.md | 32 ++++++------ docs/zh/guide/extending-default-theme.md | 9 ++-- docs/zh/guide/getting-started.md | 4 +- docs/zh/guide/i18n.md | 12 ++--- docs/zh/guide/markdown.md | 43 ++++++++-------- docs/zh/guide/routing.md | 18 +++---- docs/zh/guide/sitemap-generation.md | 2 +- docs/zh/guide/ssr-compat.md | 4 +- docs/zh/reference/cli.md | 4 +- docs/zh/reference/default-theme-badge.md | 4 +- docs/zh/reference/default-theme-config.md | 44 ++++++++-------- docs/zh/reference/default-theme-footer.md | 4 +- docs/zh/reference/default-theme-home-page.md | 40 +++++++-------- docs/zh/reference/default-theme-nav.md | 3 +- docs/zh/reference/default-theme-search.md | 2 +- docs/zh/reference/default-theme-sidebar.md | 8 ++- docs/zh/reference/default-theme-team-page.md | 27 +++++----- docs/zh/reference/frontmatter-config.md | 2 +- docs/zh/reference/runtime-api.md | 21 ++++---- docs/zh/reference/site-config.md | 42 +++++++-------- 23 files changed, 202 insertions(+), 211 deletions(-) diff --git a/docs/zh/guide/cms.md b/docs/zh/guide/cms.md index c23ef90b..734f4f22 100644 --- a/docs/zh/guide/cms.md +++ b/docs/zh/guide/cms.md @@ -24,16 +24,16 @@ outline: deep ```js export default { async paths() { - // use respective CMS client library if needed + // 如有需要，使用相应的 CMS 客户端库 const data = await (await fetch('https://my-cms-api', { headers: { - // token if necessary + // 如有必要，可使用 token } })).json() return data.map(entry => { return { - params: { id: entry.id, /* title, authors, date etc. */ }, + params: { id: entry.id, /* title, authors, date 等 */ }, content: entry.content } }) diff --git a/docs/zh/guide/custom-theme.md b/docs/zh/guide/custom-theme.md index 12bb7c89..bee26870 100644 --- a/docs/zh/guide/custom-theme.md +++ b/docs/zh/guide/custom-theme.md @@ -6,11 +6,11 @@ ``` . -├─ docs # project root +├─ docs # 项目根目录 │ ├─ .vitepress │ │ ├─ theme -│ │ │ └─ index.js # theme entry -│ │ └─ config.js # config file +│ │ │ └─ index.js # 主题入口 +│ │ └─ config.js # 配置文件 │ └─ index.md └─ package.json ``` @@ -24,26 +24,26 @@ VitePress 自定义主题是一个对象，该对象具有如下接口： ```ts interface Theme { /** - * Root layout component for every page + * 每个页面的根布局组件 * @required */ Layout: Component /** - * Enhance Vue app instance + * 增强 Vue 应用实例 * @optional */ enhanceApp?: (ctx: EnhanceAppContext) => Awaitable /** - * Extend another theme, calling its `enhanceApp` before ours + * 扩展另一个主题，在我们的主题之前调用它的 `enhanceApp` * @optional */ extends?: Theme } interface EnhanceAppContext { - app: App // Vue app instance - router: Router // VitePress router instance - siteData: Ref // Site-level metadata + app: App // Vue 应用实例 + router: Router // VitePress 路由实例 + siteData: Ref // 站点级元数据 } ``` @@ -52,8 +52,8 @@ interface EnhanceAppContext { ```js // .vitepress/theme/index.js -// You can directly import Vue files in the theme entry -// VitePress is pre-configured with @vitejs/plugin-vue. +// 可以直接在主题入口导入 Vue 文件 +// VitePress 已预先配置 @vitejs/plugin-vue import Layout from './Layout.vue' export default { @@ -77,7 +77,7 @@ export default { ``` @@ -200,7 +200,7 @@ export default { import baseConfig from 'awesome-vitepress-theme/config' export default { - // extend theme base config (if needed) + // 扩展主题的基本配置（如需要） extends: baseConfig } ``` @@ -216,7 +216,7 @@ import type { ThemeConfig } from 'awesome-vitepress-theme' export default defineConfigWithTheme({ extends: baseConfig, themeConfig: { - // Type is `ThemeConfig` + // 类型为 `ThemeConfig` } }) ``` diff --git a/docs/zh/guide/data-loading.md b/docs/zh/guide/data-loading.md index 5ee8ae75..69327c37 100644 --- a/docs/zh/guide/data-loading.md +++ b/docs/zh/guide/data-loading.md @@ -46,7 +46,7 @@ import { data } from './example.data.js' ```js export default { async load() { - // fetch remote data + // 获取远程数据 return (await fetch('...')).json() } } @@ -67,9 +67,8 @@ import { parse } from 'csv-parse/sync' export default { watch: ['./data/*.csv'], load(watchedFiles) { - // watchedFiles will be an array of absolute paths of the matched files. - // generate an array of blog post metadata that can be used to render - // a list in the theme layout + // watchFiles 是一个所匹配文件的绝对路径的数组。 + // 生成一个博客文章元数据数组，可用于在主题布局中呈现列表。 return watchedFiles.map((file) => { return parse(fs.readFileSync(file, 'utf-8'), { columns: true, @@ -99,14 +98,14 @@ export default createContentLoader('posts/*.md', /* options */) ```ts interface ContentData { - // mapped URL for the page. e.g. /posts/hello.html (does not include base) - // manually iterate or use custom `transform` to normalize the paths + // 页面的映射 URL，如 /posts/hello.html（不包括 base） + // 手动迭代或使用自定义 `transform` 来标准化路径 url: string - // frontmatter data of the page + // 页面的 frontmatter 数据 frontmatter: Record - // the following are only present if relevant options are enabled - // we will discuss them below + // 只有启用了相关选项，才会出现以下内容 + // 我们将在下面讨论它们 src: string | undefined html: string | undefined excerpt: string | undefined @@ -140,18 +139,18 @@ import { data as posts } from './posts.data.js' import { createContentLoader } from 'vitepress' export default createContentLoader('posts/*.md', { - includeSrc: true, // include raw markdown source? - render: true, // include rendered full page HTML? - excerpt: true, // include excerpt? + includeSrc: true, // 包含原始 markdown 源? + render: true, // 包含渲染的整页 HTML? + excerpt: true, // 包含摘录? transform(rawData) { - // map, sort, or filter the raw data as you wish. - // the final result is what will be shipped to the client. + // 根据需要对原始数据进行 map、sort 或 filter + // 最终的结果是将发送给客户端的内容 return rawData.sort((a, b) => { return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date) }).map((page) => { - page.src // raw markdown source - page.html // rendered full page HTML - page.excerpt // rendered excerpt HTML (content above first `---`) + page.src // 原始 markdown 源 + page.html // 渲染的整页 HTML + page.excerpt // 渲染的摘录 HTML（第一个 `---` 上面的内容） return {/* ... */} }) } @@ -167,7 +166,7 @@ export default createContentLoader('posts/*.md', { export default { async buildEnd() { const posts = await createContentLoader('posts/*.md').load() - // generate files based on posts metadata, e.g. RSS feed + // 根据 posts 元数据生成文件，如 RSS 订阅源 } } ``` @@ -177,24 +176,24 @@ export default { ```ts interface ContentOptions { /** - * Include src? + * 包含 src? * @default false */ includeSrc?: boolean /** - * Render src to HTML and include in data? + * 将 src 渲染为 HTML 并包含在数据中? * @default false */ render?: boolean /** - * If `boolean`, whether to parse and include excerpt? (rendered as HTML) + * 如果为 `boolean`，是否解析并包含摘录? (呈现为 HTML) * - * If `function`, control how the excerpt is extracted from the content. + * 如果为 `function`，则控制如何从内容中提取摘录 * - * If `string`, define a custom separator to be used for extracting the - * excerpt. Default separator is `---` if `excerpt` is `true`. + * 如果为 `string`，则定义用于提取摘录的自定义分隔符 + * 如果 `excerpt` 为 `true`，则默认分隔符为 `---` * * @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt * @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt_separator @@ -207,8 +206,7 @@ interface ContentOptions { | string /** - * Transform the data. Note the data will be inlined as JSON in the client - * bundle if imported from components or markdown files. + * 转换数据。请注意，如果从组件或 Markdown 文件导入，数据将以 JSON 形式内联到客户端包中 */ transform?: (data: ContentData[]) => T | Promise } @@ -222,14 +220,14 @@ interface ContentOptions { import { defineLoader } from 'vitepress' export interface Data { - // data type + // data 类型 } declare const data: Data export { data } export default defineLoader({ - // type checked loader options + // 类型检查加载器选项 watch: ['...'], async load(): Promise { // ... diff --git a/docs/zh/guide/deploy.md b/docs/zh/guide/deploy.md index 5f855f2d..c2514be0 100644 --- a/docs/zh/guide/deploy.md +++ b/docs/zh/guide/deploy.md @@ -122,61 +122,61 @@ Cache-Control: max-age=31536000,immutable 1. 在项目的 `.github/workflows` 目录中创建一个名为 `deploy.yml` 的文件，其中包含这样的内容： ```yaml - # Sample workflow for building and deploying a VitePress site to GitHub Pages + # 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程 # name: Deploy VitePress site to Pages on: - # Runs on pushes targeting the `main` branch. Change this to `master` if you're - # using the `master` branch as the default branch. + # 在针对 `main` 分支的推送上运行。如果您 + # 使用 `master` 分支作为默认分支，请将其更改为 `master` push: branches: [main] - # Allows you to run this workflow manually from the Actions tab + # 允许您从 Actions 选项卡手动运行此工作流程 workflow_dispatch: - # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages + # 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages permissions: contents: read pages: write id-token: write - # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. - # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. + # 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列 + # 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成 concurrency: group: pages cancel-in-progress: false jobs: - # Build job + # 构建工作 build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 with: - fetch-depth: 0 # Not needed if lastUpdated is not enabled - # - uses: pnpm/action-setup@v2 # Uncomment this if you're using pnpm - # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun + fetch-depth: 0 # 如果未启用 lastUpdated，则不需要 + # - uses: pnpm/action-setup@v2 # 如果使用 pnpm，请取消注释 + # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释 - name: Setup Node uses: actions/setup-node@v3 with: node-version: 18 - cache: npm # or pnpm / yarn + cache: npm # 或 pnpm / yarn - name: Setup Pages uses: actions/configure-pages@v3 - name: Install dependencies - run: npm ci # or pnpm install / yarn install / bun install + run: npm ci # 或 pnpm install / yarn install / bun install - name: Build with VitePress run: | - npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build + npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build touch docs/.vitepress/dist/.nojekyll - name: Upload artifact uses: actions/upload-pages-artifact@v2 with: path: docs/.vitepress/dist - # Deployment job + # 部署工作 deploy: environment: name: github-pages @@ -211,7 +211,7 @@ Cache-Control: max-age=31536000,immutable paths: - node_modules/ script: - # - apk add git # Uncomment this if you're using small docker images like alpine and have lastUpdated enabled + # - apk add git # 如果你使用的是像 alpine 这样的小型 docker 镜像，并且启用了 lastUpdated，请取消注释 - npm install - npm run docs:build artifacts: diff --git a/docs/zh/guide/extending-default-theme.md b/docs/zh/guide/extending-default-theme.md index e4890954..e5b0c760 100644 --- a/docs/zh/guide/extending-default-theme.md +++ b/docs/zh/guide/extending-default-theme.md @@ -72,7 +72,7 @@ export default DefaultTheme // .vitepress/config.js export default { transformHead({ assets }) { - // adjust the regex accordingly to match your font + // 相应地调整正则表达式以匹配字体 const myFontFile = assets.find(file => /font-name\.\w+\.woff2/) if (myFontFile) { return [ @@ -102,7 +102,7 @@ import DefaultTheme from 'vitepress/theme' export default { extends: DefaultTheme, enhanceApp({ app }) { - // register your custom global components + // 注册自定义全局组件 app.component('MyGlobalComponent' /* ... */) } } @@ -117,7 +117,7 @@ import DefaultTheme from 'vitepress/theme' export default { extends: DefaultTheme, enhanceApp({ app }) { - // register your custom global components + // 注册自定义全局组件 app.component('MyGlobalComponent' /* ... */) } } satisfies Theme @@ -136,8 +136,7 @@ import MyLayout from './MyLayout.vue' export default { extends: DefaultTheme, - // override the Layout with a wrapper component that - // injects the slots + // 使用注入插槽的包装组件覆盖 Layout Layout: MyLayout } ``` diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md index 5566349a..b9b2f268 100644 --- a/docs/zh/guide/getting-started.md +++ b/docs/zh/guide/getting-started.md @@ -115,12 +115,12 @@ $ bunx vitepress init ```js // .vitepress/config.js export default { - // site-level options + // 站点级选项 title: 'VitePress', description: 'Just playing around.', themeConfig: { - // theme-level options + // 主题级选项 } } ``` diff --git a/docs/zh/guide/i18n.md b/docs/zh/guide/i18n.md index d74b727a..c2fe88f6 100644 --- a/docs/zh/guide/i18n.md +++ b/docs/zh/guide/i18n.md @@ -17,7 +17,7 @@ docs/ import { defineConfig } from 'vitepress' export default defineConfig({ - // shared properties and other top-level stuff... + // 共享属性和其他顶层内容... locales: { root: { @@ -26,10 +26,10 @@ export default defineConfig({ }, fr: { label: 'French', - lang: 'fr', // optional, will be added as `lang` attribute on `html` tag - link: '/fr/guide' // default /fr/ -- shows on navbar translations menu, can be external + lang: 'fr', // 可选，将作为 `lang` 属性添加到 `html` 标签中 + link: '/fr/guide' // 默认 /fr/ -- 显示在导航栏翻译菜单上，可以是外部的 - // other locale specific properties... + // 其余 locale 特定属性... } } }) @@ -44,8 +44,8 @@ interface LocaleSpecificConfig { title?: string titleTemplate?: string | boolean description?: string - head?: HeadConfig[] // will be merged with existing head entries, duplicate meta tags are automatically removed - themeConfig?: ThemeConfig // will be shallow merged, common stuff can be put in top-level themeConfig entry + head?: HeadConfig[] // 将与现有的头部条目合并，重复的元标签将自动删除 + themeConfig?: ThemeConfig // 会进行浅层合并，常见内容可放在顶层的 themeConfig 属性中 } ``` diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md index d20a2a12..93db97e0 100644 --- a/docs/zh/guide/markdown.md +++ b/docs/zh/guide/markdown.md @@ -42,12 +42,12 @@ VitePress 带有内置的 Markdown 拓展。 假设现在处于 `foo/one.md` 文件中： ```md -[Home](/) -[foo](/foo/) -[foo heading](./#heading) -[bar - three](../bar/three) -[bar - three](../bar/three.md) -[bar - four](../bar/four.html) +[Home](/) +[foo](/foo/) +[foo heading](./#heading) +[bar - three](../bar/three) +[bar - three](../bar/three.md) +[bar - four](../bar/four.html) ``` ### 页面后缀 {#page-suffix} @@ -259,7 +259,7 @@ Wraps in a
```js postcssIsolateStyles({ - includeFiles: [/vp-doc\.css/] // defaults to /base\.css/ + includeFiles: [/vp-doc\.css/] // 默认为 /base\.css/ }) ``` @@ -523,23 +523,25 @@ export default { 可以在代码块中添加 `:line-numbers` / `:no-line-numbers` 标记来覆盖在配置中的设置。 +还可以通过在 `:line-numbers` 之后添加 `=` 来自定义起始行号，例如 `:line-numbers=2` 表示代码块中的行号从 2 开始。 + **输入** ````md ```ts {1} -// line-numbers is disabled by default +// 默认禁用行号 const line2 = 'This is line 2' const line3 = 'This is line 3' ``` ```ts:line-numbers {1} -// line-numbers is enabled +// 启用行号 const line2 = 'This is line 2' const line3 = 'This is line 3' ``` ```ts:line-numbers=2 {1} -// line-numbers is enabled and start from 2 +// 行号已启用，并从 2 开始 const line3 = 'This is line 3' const line4 = 'This is line 4' ``` @@ -548,19 +550,19 @@ const line4 = 'This is line 4' **输出** ```ts {1} -// line-numbers is disabled by default +// 默认禁用行号 const line2 = 'This is line 2' const line3 = 'This is line 3' ``` ```ts:line-numbers {1} -// line-numbers is enabled +// 启用行号 const line2 = 'This is line 2' const line3 = 'This is line 3' ``` ```ts:line-numbers=2 {1} -// line-numbers is enabled and start from 2 +// 行号已启用，并从 2 开始 const line3 = 'This is line 3' const line4 = 'This is line 4' ``` @@ -701,11 +703,11 @@ export default config ```md ::: code-group - + <<< @/snippets/snippet.js - + <<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region] @@ -853,12 +855,13 @@ $$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$ ## 图片懒加载 {#image-lazy-loading} -You can enable lazy loading for each image added via markdown by setting `lazyLoading` to `true` in your config file: +通过在配置文件中将 `lazyLoading` 设置为 `true`，可以为通过 markdown 添加的每张图片启用懒加载。 + ```js export default { markdown: { image: { - // image lazy loading is disabled by default + // 默认禁用图片懒加载 lazyLoading: true } } @@ -876,16 +879,16 @@ import markdownItFoo from 'markdown-it-foo' export default defineConfig({ markdown: { - // options for markdown-it-anchor + // markdown-it-anchor 的选项 // https://github.com/valeriangalliat/markdown-it-anchor#usage anchor: { permalink: markdownItAnchor.permalink.headerLink() }, - // options for @mdit-vue/plugin-toc + // @mdit-vue/plugin-toc 的选项 // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options toc: { level: [1, 2] }, config: (md) => { - // use more markdown-it plugins! + // 使用更多的 Markdown-it 插件！ md.use(markdownItFoo) } } diff --git a/docs/zh/guide/routing.md b/docs/zh/guide/routing.md index 3e752e43..0573bbc9 100644 --- a/docs/zh/guide/routing.md +++ b/docs/zh/guide/routing.md @@ -40,8 +40,8 @@ VitePress 项目的文件结构中有两个重要的概念：项目根目录 (** ``` . -├─ docs # project root -│ ├─ .vitepress # config dir +├─ docs # 项目根目录 +│ ├─ .vitepress # 配置目录 │ ├─ getting-started.md │ └─ index.md └─ ... @@ -65,9 +65,9 @@ docs/getting-started.md --> /getting-started.html `srcDir` 选项是相对于项目根目录解析的。例如，对于 `srcDir: 'src'`，文件结构将如下所示： ``` -. # project root -├─ .vitepress # config dir -└─ src # source dir +. # 项目根目录 +├─ .vitepress # 配置目录 +└─ src # 源目录 ├─ getting-started.md └─ index.md ``` @@ -218,8 +218,8 @@ export default { ``` . └─ packages - ├─ [pkg].md # route template - └─ [pkg].paths.js # route paths loader + ├─ [pkg].md # 路由模板 + └─ [pkg].paths.js # 路由路径加载器 ``` 路径加载器应该提供一个带有 `paths` 方法的对象作为其默认导出。`paths` 方法应返回具有 `params` 属性的对象数组。这些对象中的每一个都将生成一个相应的页面。 @@ -338,7 +338,7 @@ export default {