CONTRIBUTING & Chinese Document

Lampese · peter-jerry-ye · commit dfa352fd55f7 · 2025-02-27T10:06:46.000+08:00
diff --git a/CONTRIBUTING-zh.md b/CONTRIBUTING-zh.md
@@ -0,0 +1,45 @@
+# 贡献指南
+
+_我们鼓励包括问题报告、拉取 PR，以及任何形式的贡献！_
+
+## :bulb: 提问
+
+请访问我们的论坛 ([英文](https://discuss.moonbitlang.com/)/[中文](https://taolun.moonbitlang.com/))。
+简而言之，GitHub 问题不是调试特定项目的地方，而是用于提交错误和功能请求。
+
+## :inbox_tray: 提交问题
+
+在提起 issue 之前，请先检查你使用的是否是 [最新版本](https://www.moonbitlang.com/download/) 的 MoonBit 工具链。如果不是，请先更新 MoonBit 工具链到最新版本并确定问题是否仍然存在。
+
+向项目贡献的一个很好的方式是在遇到问题时提交详细的 issue。我们始终感谢编写完善、详尽的错误报告。:v:
+
+简而言之，作为一名开发者，**请提供一个你自己也愿意收到的 issue** ：
+
+- 如果你使用的是 [playground](https://try.moonbitlang.com/)，只需点击分享图标分享代码：
+
+<img width="600" src="imgs/share_moonbit.png">
+
+- 如果你使用的是 [moon build](https://www.moonbitlang.com/docs/build-system-tutorial/)，请提供 `moon version` 和你的操作系统版本的输出。
+
+## :hammer: 贡献代码
+
+我们鼓励贡献者使用 [GitHub 的 Pull Request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) 来提交他们的贡献，包括但不限于以下的贡献：
+- 修正代码/文档中的错误
+- 提交缺失的中文翻译或改进翻译
+
+文档分为两部分，一部分为交互式的教程，一部分为静态的详细语言文档。
+
+- 对于交互式教程：可以在[这里](https://github.com/moonbitlang/moonbit-docs/tree/main/moonbit-tour/tour)找到其源码，而中文内容则在[这里](https://github.com/moonbitlang/moonbit-docs/tree/main/moonbit-tour/tour/zh)可以找到。
+
+- 对于静态的详细语言文档：可以在[这里](https://github.com/moonbitlang/moonbit-docs/tree/main/next)找到其源码，而中文内容则在[这里](https://github.com/moonbitlang/moonbit-docs/tree/main/next/locales/zh_CN/LC_MESSAGES)可以找到，需要额外注意到的是，中文内容是使用 gettext 工具生成的，因此需要额外注意其中的翻译文件的格式。
+
+## :scroll: 翻译指南
+
+这里是对于中文文档翻译的一些预期要求：
+
+- 翻译需要尽可能忠于原文，不要出现过于冗余的翻译。
+
+- 为保证美观和可读性，中文与英文相邻时要有空格分隔。
+
+- 非特殊情况下请使用中文标点符号，包括但不限于冒号、逗号、句号、引号、全角括号等。
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,7 @@
 # Contributing Guidelines
 
+view [CONTRIBUTING-zh.md](./CONTRIBUTING-zh.md) for Chinese version and translate guidelines.
+
 _Pull requests, bug reports, and all other forms of contribution are welcomed and highly encouraged!_
 
 ## :bulb: Asking Questions
@@ -19,3 +21,17 @@ In short, since you are most likely a developer, **provide a ticket that you wou
 <img width="600" src="imgs/share_moonbit.png">
 
 - If you are using [moon build](https://www.moonbitlang.com/docs/build-system-tutorial/), please provide the output of `moon version` and your OS version.
+
+## :hammer: Contributing Code
+
+We encourage contributors to use [GitHub's Pull Request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) to submit their contributions, including but not limited to the following contributions:
+- Fix errors in code/documentation
+- Submit missing Chinese translations or improve translations
+
+The documentation is divided into two parts: one is the interactive tutorial, and the other is the static detailed language documentation.
+
+- For the interactive tutorial: the source code can be found [here](https://github.com/moonbitlang/moonbit-docs/tree/main/moonbit-tour/tour), and the Chinese content can be found [here](https://github.com/moonbitlang/moonbit-docs/tree/main/moonbit-tour/tour/zh).
+
+- For the static detailed language documentation: the source code can be found [here](https://github.com/moonbitlang/moonbit-docs/tree/main/next), and the Chinese content can be found [here](https://github.com/moonbitlang/moonbit-docs/tree/main/next/locales/zh_CN/LC_MESSAGES), where it should be noted that the Chinese content is generated using the `gettext` tool, so special attention should be paid to the format of the translation files.
+
+If you are interested in translating the documentation, please refer to the [Chinese version Contributing Guidelines](./CONTRIBUTING-zh.md).
diff --git a/README-zh.md b/README-zh.md
@@ -1,11 +1,13 @@
 # MoonBit 文档网站
 
+查看 [README.md](./README.md) 获取英文版本。
+
 此存储库托管了 MoonBit 的文档网站 [docs.moonbitlang.com](https://docs.moonbitlang.com)。
 
 打开 `document.code-workspace` 以获得更好的开发体验。可以从终端面板中的 `+` 号选择命令运行，或在命令面板中运行 `Tasks: Run Build Task`。
 
 ## 布局
 
 - `legacy/examples`: 一些 MoonBit 的小示例。
-- `next`: 基于 Sphinx 的当前文档，托管在 readthedocs 上。查看 [README](./next/README)。
+- `next`: 基于 Sphinx 的当前文档，托管在 readthedocs 上。查看 [README](./next/README.md)。
 - `moonbit-tour`: 一个互动教程。查看 [README](./moonbit-tour/README.md)。
diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
 # MoonBit Docs Website
 
+view [README-zh.md](./README-zh.md) for Chinese version.
+
 This repository hosts the documentation website for MoonBit [docs.moonbitlang.com](https://docs.moonbitlang.com).
 
 Open `document.code-workspace` for a better development experience. Choose commands to run from either the `+` sign in the Terminal Panel or run `Tasks: Run Build Task` in the command palette.
diff --git a/imgs/share_moonbit.png b/imgs/share_moonbit.png
diff --git a/moonbit-tour/README-zh.md b/moonbit-tour/README-zh.md
@@ -0,0 +1,41 @@
+# MoonBit Language Tour
+
+查看该文件的英文版本：[English version](./README.md)
+
+一个用于学习 MoonBit 编程语言的交互式教程。
+
+## 开始
+
+```sh
+pnpm install
+pnpm build
+pnpm preview
+```
+
+打开 <http://localhost:3000> 查看 tour 网站。
+
+## 如何添加新的教程
+
+### 添加新的教程
+
+1. 设置开发环境。
+
+   ```sh
+   pnpm install
+   pnpm dev
+   ```
+
+1. 打开 <http://localhost:8080> 查看 tour 网站。
+
+1. 在章节文件夹下创建一个新的文件夹，遵循命名惯例 `lesson<n>_<lesson-name>` (从 1 开始计数)。
+
+1. 在创建的文件夹下编写教程内容（`index.md`），并编写教程代码（`index.mbt`）。
+
+### 添加新的章节
+
+1. 在 `tour` 文件夹下创建一个新的文件夹，遵循命名惯例 `chapter<n>_<chapter-name>`。
+1. 按照上述步骤添加新的教程。
+
+## 致谢
+
+该项目深受 [Gleam Language Tour](https://github.com/gleam-lang/language-tour) 启发。
diff --git a/moonbit-tour/README.md b/moonbit-tour/README.md
@@ -1,5 +1,7 @@
 # MoonBit Language Tour
 
+view the [Chinese version](./README-zh.md) of this file.
+
 An interactive tour to learn the MoonBit programming language.
 
 ## Get started
diff --git a/next/README-zh.md b/next/README-zh.md
@@ -0,0 +1,70 @@
+# Next gen moonbit-docs
+
+查看[README.md](./README.md) 获取英文版本。
+
+基于 Sphinx 的新一代 MoonBit 文档框架。
+
+## 开发指南
+
+### 安装
+
+- 对于 Python 环境，可以在 VSCode 中执行 `> Python: Create Environment` 命令，为 `next` 项目使用 `requirement.txt` 创建环境，或者：
+
+  ```bash
+  python3 -m venv .env
+  source .env/bin/activate
+  pip install -r requirements.txt
+  ```
+
+- 使用 Latex 构建 PDF 时，需要安装 `latexmk`：
+  - MacOS:
+    - 安装 [Mactex](https://www.tug.org/mactex/)
+    - 使用 TeX Live Utility 安装 `latexmk`
+
+### 开发
+
+在 VSCode 中执行 `Watch Document` 任务，或者：
+
+```bash
+sphinx-autobuild . ./_build/html
+# 或者 sphinx-autobuild -D language='zh_CN' . ./_build/html
+```
+
+### 构建
+
+在 VSCode 中执行 `Build Document` 任务，或者：
+
+```bash
+make html
+python3 -m http.server -d _build/html
+```
+
+对于中文版本：
+
+```bash
+LANGUAGE="zh_CN" make html
+python3 -m http.server -d _build/html
+```
+
+对于 PDF：
+
+```bash
+make latexpdf
+open ./_build/latex/moonbitdocument.pdf
+```
+
+对于 Markdown：
+
+```bash
+pip install sphinx-markdown-builder
+make markdown
+```
+
+### 更新翻译模板
+
+在 VSCode 中执行 `Translate Document` 任务，或者：
+
+```bash
+make gettext
+sphinx-intl update -p _build/gettext -l zh_CN
+```
diff --git a/next/README.md b/next/README.md
@@ -1,5 +1,7 @@
 # Next gen moonbit-docs
 
+view [README-zh.md](./README-zh.md) for Chinese version.
+
 A new MoonBit docs framework based on Sphinx.
 
 ## Develop
