From 912ff319de5a630a59ff07097170aa084803650e Mon Sep 17 00:00:00 2001 From: Purp1e <438518244@qq.com> Date: Thu, 28 Dec 2023 18:14:23 +0800 Subject: [PATCH] update: help translation --- docs/guides/help_translation.md | 170 +++++++++++++++++++++++- docs/zh-hans/guides/help_translation.md | 169 ++++++++++++++++++++++- 2 files changed, 337 insertions(+), 2 deletions(-) diff --git a/docs/guides/help_translation.md b/docs/guides/help_translation.md index 660e607..28656c0 100644 --- a/docs/guides/help_translation.md +++ b/docs/guides/help_translation.md @@ -3,4 +3,172 @@ title: Help Translation order: 90 --- -# Help Translation \ No newline at end of file +# Help Translation + +The project is built using [Vitepress](https://vitepress.dev/), thus it's ok to edit [Markdown](https://zh.wikipedia.org/wiki/Markdown) files and preview the results easily. You should have a [GitHub](https://github.com/) account to create pull requests (PRs). + +## Folder Structure + +Files and `.**` folders in the project directory have already been configured properly. You should focus on `docs/` folder. + +- `.vitepress/`: The config and theme of the site + - `config.ts`: Main config + - `sidebar.ts`: Sidebar config + - `theme/`: Theme config +- `components/`: Vue.js components that can be used in Markdown files +- `public/`: public assets +- `blog/` `commands/` `faq/` `guides/` `releases/`: Content of the document site +- `/`: Translation of a locale, such as `zh-hans/` represents `Simplified Chinese` +- `index.md`: Index file for the **Home Page**. In sub-folders, its metadata controls the `title`, `order` ... of the content. + + +## Add a new locale + +1. Edit `docs/.vitepress/config.ts`, please edit `` and specific texts to correct ones. + ```ts + themeConfig:{ + search: { + options: { + locales: { + ... + // Translate Search Texts for the + "": { + translations: { + button: { + buttonText: "", + buttonAriaLabel: "", + }, + modal: { + displayDetails: "", + backButtonTitle: "", + noResultsText: "", + resetButtonTitle: "", + footer: { + selectText: "", + navigateText: "", + closeText: "", + }, + }, + }, + }, + } + } + } + ``` +2. Edit `docs/.vitepress/config.ts`, please edit ``, ``, and specific texts to correct ones. + ```ts + locales: { + ... + + // Override Config for the + "": { + label: "", + lang: "", + link: "//", + title: "Advancedfx", + description: + "Half-Life Advanced Effects (HLAE) is a tool to enrich Source (mainly CS:GO) engine based movie making.", + themeConfig: { + lastUpdated: { + text: "Last Updated", + }, + editLink: { + pattern: + "https://github.com/advancedfx/afx-doc/edit/master/docs/:path", + text: "Edit this page on GitHub", + }, + docFooter: { + prev: "Previous Page", + next: "Next Page", + }, + footer: { + message: "Made with ❤️ by Advancedfx", + copyright: "Copyright © 2023-present advancedfx.org", + }, + nav: [ + { text: "Guides", link: "//guides/" }, + { text: "Commands", link: "//commands/" }, + { text: "FAQ", link: "//faq/" }, + { text: "Blog", link: "//blog/" }, + { text: "Releases", link: "//releases/" }, + { text: "Download", link: "//" }, // TODO: link to download # + ], + }, + }, + } + ``` +3. Edit `docs/.vitepress/sidebar.ts`, please edit `` to the correct one. + ```ts + const sidebar = generateSidebar([ + ... + + // Duplicate Previous Ones to modify + { + ...common_options, + scanStartPath: "", + resolvePath: "//", + excludeFolders: ["releases", "blog"], + }, + { + ...common_options, + scanStartPath: "/releases", + resolvePath: "//releases/", + sortMenusOrderByDescending: true, + }, + { + ...common_options, + scanStartPath: "/blog", + resolvePath: "//blog/", + sortMenusOrderByDescending: true, + }, + ]); + ``` +4. Duplicate `blog/` `commands/` `faq/` `guides/` `releases/` and `index.md` to a new `` folder. +5. Do edit and translation. Git Commit and push when you are ready. +6. Create a Pull Request to merge your contribution. + +## Translate new pages + +Similar to above steps, but this time without step 1~3. + +In step 4, copy new files to the correct path in `` folder. + + +## Edit a existed page + +If you see a existed page that need translation or improvement, simply click `Edit this page on GitHub` and follow the instructions. It would be like the above step 5~6. + +## Notice on writing `.md` for the site + +Before the Main content of markdown, we have a `metadata` section. `title` will be used in the sidebar. `order` will be used to determine the order of pages in the sidebar. + +```markdown +--- +title: Get Started +order: 0 +--- + +# Get Started + +Yo~✋🏻 +``` + +`index.md` in subfolders configures the title and order of the folder/group of content. + +::: warning +All `.md` file names must be `lower_cased`. +::: + +## Test Locally + +1. Install [Node.js](https://nodejs.org/) >= 18. +2. Install **pnpm** globally: `npm i -g pnpm` +3. Git clone the repository and change to the directory. +4. Install packages: `pnpm install` +5. Start Testing: `pnpm dev` +6. `CTRL+C` quit and re-dev triggers sidebar updates. + + +::: info +Checkout `package.json` > `scripts` to view all `pnpm *` commands. +::: \ No newline at end of file diff --git a/docs/zh-hans/guides/help_translation.md b/docs/zh-hans/guides/help_translation.md index 6c7963e..4ee9af4 100644 --- a/docs/zh-hans/guides/help_translation.md +++ b/docs/zh-hans/guides/help_translation.md @@ -3,4 +3,171 @@ title: 帮助翻译 order: 90 --- -# 帮助翻译 \ No newline at end of file +# 帮助翻译 + +项目使用 [Vitepress](https://vitepress.dev/)，故可轻松编辑 [Markdown](https://zh.wikipedia.org/wiki/Markdown) 文件和预览结果。你应该有一个 [GitHub](https://github.com/) 账号来创建拉取申请PR。 + +## 文件结构 + +项目文件夹的文件和 `.**` 文件夹已经被配置好了，你只用关注文件夹 `docs/` 。 + +- `.vitepress/`: 网站设置和主题 + - `config.ts`: 主要设置 + - `sidebar.ts`: 侧边栏设置 + - `theme/`: 主题设置 +- `components/`: 可用在 Markdown 文件的 Vue.js 组件 +- `public/`: 公共资源 +- `blog/` `commands/` `faq/` `guides/` `releases/`: 文档网站的内容 +- `/`: 某个语言的翻译，如 `zh-hans/` 代表 `简体中文` +- `index.md`: **主页** 的索引文件。子文件夹中，它的元信息用来控制内容的`标题`和`顺序`。 + + +## 新增一个语言 + +1. 编辑 `docs/.vitepress/config.ts`，请编辑 `` 和具体的文字为正确的文本。 + ```ts + themeConfig:{ + search: { + options: { + locales: { + ... + // 翻译 语言的搜索文字 + "": { + translations: { + button: { + buttonText: "", + buttonAriaLabel: "", + }, + modal: { + displayDetails: "", + backButtonTitle: "", + noResultsText: "", + resetButtonTitle: "", + footer: { + selectText: "", + navigateText: "", + closeText: "", + }, + }, + }, + }, + } + } + } + ``` +2. 编辑 `docs/.vitepress/config.ts`，请编辑 ``, ``和具体的文字为正确的文本。 + ```ts + locales: { + ... + + // 覆盖 语言的设置 + "": { + label: "", + lang: "", + link: "//", + title: "Advancedfx", + description: + "Half-Life Advanced Effects (HLAE) is a tool to enrich Source (mainly CS:GO) engine based movie making.", + themeConfig: { + lastUpdated: { + text: "Last Updated", + }, + editLink: { + pattern: + "https://github.com/advancedfx/afx-doc/edit/master/docs/:path", + text: "Edit this page on GitHub", + }, + docFooter: { + prev: "Previous Page", + next: "Next Page", + }, + footer: { + message: "Made with ❤️ by Advancedfx", + copyright: "Copyright © 2023-present advancedfx.org", + }, + nav: [ + { text: "Guides", link: "//guides/" }, + { text: "Commands", link: "//commands/" }, + { text: "FAQ", link: "//faq/" }, + { text: "Blog", link: "//blog/" }, + { text: "Releases", link: "//releases/" }, + { text: "Download", link: "//" }, // TODO: link to download # + ], + }, + }, + } + ``` +3. 编辑 `docs/.vitepress/sidebar.ts`，请编辑 `` 和具体的文字为正确的文本。 + ```ts + const sidebar = generateSidebar([ + ... + + // 复制之前的内容以修改 + { + ...common_options, + scanStartPath: "", + resolvePath: "//", + excludeFolders: ["releases", "blog"], + }, + { + ...common_options, + scanStartPath: "/releases", + resolvePath: "//releases/", + sortMenusOrderByDescending: true, + }, + { + ...common_options, + scanStartPath: "/blog", + resolvePath: "//blog/", + sortMenusOrderByDescending: true, + }, + ]); + ``` +4. 复制 `blog/` `commands/` `faq/` `guides/` `releases/` 和 `index.md` 到新的 `` 文件夹。 +5. 编辑和翻译。当你准备好了，用 Git 提交和推送修改。 +6. 提交拉取请求 PR 来合并你的贡献。 + +## 翻译新页面 + +和上面的步骤类似，但这次不用步骤1~3。 + +在第4步中复制新文件到 `` 中正确的位置。 + +## 编辑一个已经存在的页面 + +如果你发现一个已有的页面需要翻译或者改进，只用点击 `在 GitHub 编辑此页` 并跟随指导。它会和上述5~6步相似。 + +## 为本站编写 `.md` 的注意事项 + +Markdown 主要内容之前有一个 `元信息` 部分，`title` 标题会用在侧边栏。 `order` 用于决定页面在侧边栏的顺序。 + +```markdown +--- +title: Get Started +order: 0 +--- + +# Get Started + +Yo~✋🏻 +``` + +子文件夹的 `index.md` 设置文件夹/内容组的标题和顺序。 + +::: warning 警告 +所有 `.md` 文件名必须使用**小写下划线** `lower_cased`. +::: + +## 本地传达室 + +1. 安装 [Node.js](https://nodejs.org/) >= 18。 +2. 全局安装 **pnpm** : `npm i -g pnpm` +3. Git 克隆仓库并切换到对应目录。 +4. 安装包： `pnpm install` +5. 开始测试： `pnpm dev` +6. `CTRL+C` 结束并重新测试出发侧边栏更新。 + + +::: info 信息 +查看 `package.json` > `scripts` 获知所有 `pnpm *` 指令。 +::: \ No newline at end of file