CONTRIBUTING.md

贡献方针

贡献方针是参与本项目贡献的指导文件。

目录：

• 贡献方针
  • 仓库结构
  • 翻译用语共识
  • 翻译贡献方针
    • 总则
    • Pull Request 相关规定
      • 标题与文字内容
      • PR 内容
    • 翻译审查
      • 审查规则
      • 审查人
      • PR 作者
    • 搁置规则
    • 提示
  • 代码贡献指南
  • 配置更改指南
    • Packer
  • 联系我们

仓库结构

Minecraft-Mod-Language-Package
  ├─.github --------------- // GitHub 相关配置文件
  ├─config ---------------- // 配置文件
  │ └─packer -------------- // 打包器配置文件
  ├─projects -------------- // 翻译文件
  │ └─(Minecraft 版本) ---- // 不带 fabric 字样的是用于 Forge 的
  │   └─assets
  │     ├─(CurseForge 项目名称) ---- // 见下
  │     │ └─(命名空间) ------------- // 见下
  │     │   └─lang ----------------- // 语言文件文件夹
  │     │     ├─en_us.json --------- // English (United States) 语言文件
  │     │     └─zh_cn.json --------- // 中文 (简体) 语言文件
  │     ├─minecraft
  │     │ └─minecraft -------------- // Minecraft 原版使用的命名空间
  │     │   ├─font
  │     │   │ └─glyph_sizes.bin ---- // 全角标点修复文件
  │     │   └─textures
  │     │     └─font --------------- // 全角标点修复文件
  │     ├─1UNKNOWN ----------------- // 存放不在 CurseForge 和 Modrinth 上发布的模组
  │     │   └─(命名空间)
  │     │     └─lang
  │     └─0-modrinth-mod ----------- // 存放仅发布在 Modrinth 上的模组
  │         └─(命名空间)
  │           └─lang
  └─src --------------- // 各种自动化工具的源码
    ├─Formatter ------- // 格式化工具，曾用于统一翻译文件格式
    ├─Language.Core 
    ├─Packer ---------- // 打包器，用于自动生成资源包文件并发布 Release
    ├─Spider ---------- // 爬虫，曾用于爬取热门模组的语言文件供翻译
    └─Uploader -------- // 上传器，用于将资源包文件上传到文件分发服务器

CurseForge 项目名称：以匠魂为例，它的 CurseForge 页面地址是 https://www.curseforge.com/minecraft/mc-mods/tinkers-construct，则 CurseForge 项目名称 为 tinkers-construct。因为它是唯一的，被用来追溯模组来源。

命名空间（Namespace）：以匠魂为例，用压缩软件打开模组文件（JAR 格式），它的 en_us.json 的路径为 assets/tconstruct/lang/en_us.json，则 {命名空间} 为 assets/ 和 /lang 之间的内容，即 tconstruct。一个模组可能有多个命名空间。命名空间介绍见 Minecraft Wiki。

仓库中“命名空间”文件夹下的目录结构与资源包的相应结构相同，其他可用资源包加载的本地化文件亦可接收。

projects 文件夹下只标出模组所属的大版本号，其中的模组翻译文件应满足以下优先级：

1. 模组活跃更新的 Minecraft 版本优先。若所有小版本都活跃更新，则
2. Minecraft 版本高者优先。

• 例：Minecraft 版本 1.19.2 与 1.19.4 均属同一大版本号 1.19 下的子版本。
  若某一模组在两个版本上的开发均活跃，由于 1.19.4 的版本号更高，因此优先考虑该模组在 1.19.4 下的译名标准化情况与适配情况。
  这一优先级不会影响到模组在其他大版本下（如 1.18、1.12 等）的分支。

翻译用语共识

1. “材料+质/制+中心词”的翻译，如“铁质涡轮”“铁制涡轮”，二者皆合理。只需单模组内统一。
2. 关于“木制品名称”的翻译，可参考 CFPAOrg#2715 (comment) 中的解决方法。

翻译贡献方针

以下内容只针对对 projects 文件夹下的贡献。

总则

• 翻译必须符合 Minecraft 模组简体中文翻译规范与指南的规定。
• 拒绝接收机器翻译（含生成式AI）、生硬翻译。
• 翻译必须在审查后才能进入仓库。

Pull Request 相关规定

可查看视频教程（已过时）或文字教程来学习。注意，视频或文字教程都只介绍了 Pull Request 的使用方法，贡献方针仍需阅读。

视频或文字教程中与翻译贡献方针不同的地方，以本方针为准。

标题与文字内容

• PR 标题应该简洁明了，格式为 {模组英文全名}{空格}{简述}。
  • ✔️Tinkers' Construct 翻译提交
  • ✔️Tinkers' Construct 和 Tinkers' Reforged 译名修正
  • ❌TiC 翻译更新（未使用全名）
  • ❌匠魂翻译更新（未包含英文名）
  • ❌提交 Tinkers' Construct 翻译（英文名前不应有文字）
• 提交时应签署贡献者许可协议，也可发送 PR 后签署。

PR 内容

• 必须提交 PR 至main分支。
• 必须路径合规，详见仓库结构。
• 必须包含简体中文、翻译源语言的语言文件。
  • 若翻译源语言不是英语，且模组有英语语言文件，则必须包含英语语言文件。
• 建议每个 PR 仅含一个模组。
  • 若多个模组的中文总行数不超过 200，建议合并为一个 PR。
• 建议用相关词语填写提交消息（Commit Message），如提交、更新、修改、删除。

翻译审查

审查规则

• 审查的基本依据是翻译贡献方针。
• 审查流程必须满足本文档翻译审查内容所述。
• 审查过程中各方应遵守礼仪（备用）。

审查人

• 任何人都能利用 GitHub 提供的相关功能来审查 PR 中翻译。所有参与审查的用户即为审查人。
• CFPA团队的成员（Member）和仓库的协作者（Collaborator）是具有团队官方性质的审查人。
• 至少一位具有官方身份的审查人对 PR 给出批准（Approval）审查后，PR 才能合并。
• 审查人在给出批准审查后应给 PR 加上“即将合并”标签，此后需等待大于 24 小时，若等待期间没有新动态则可以合并 PR。
  • “动态”包括但不限于 PR 作者发送提交（Commit）、审查人提出意见。

PR 作者

• PR 作者应对审查作出合理回应，或接受建议，或提出异议。
  • 在接受审查人的建议后，PR 作者应解决（Revolve）相应的对话（Conversation）。
  • 若拒绝审查人的建议，或和审查人的观点相左，PR 作者不应急于解决（Revolve）对话（Conversation）
• PR 作者应及时做出回应，否则 PR 可能会按搁置规则关闭。
• PR 作者如遇到 Git/GitHub 操作上的困难，应先询问后操作，避免造成混乱。

搁置规则

搁置规则的目的是解决由于 PR 作者迟迟不出面响应审查要求而导致的 PR 积压问题。

1. 若 PR 中存在未作者未响应的审查超过 7 天，审查人有权提及（@）PR 作者，提醒其相应审查意见，然后加上“即将被搁置”标签。
2. 若“即将被搁置”标签存在超过 7 天，PR 作者将被视为无法回应。此时 2.1 若存在要求 PR 作者参与的审查意见，PR 将被加上“即将拒收”标签。1 天后 PR 将被关闭。 2.2 若审查意见都无需 PR 作者参与，PR 将被加上“即将拒收”标签。1 天缓冲期内官方审查人可以直接采纳审查意见，并终止计时，转入合并流程。
3. 在 1、2 所述过程中，若 PR 作者做出了回应，标签将被清除，计时重新从 1 开始。

因搁置而关闭的 PR，PR 作者若想继续更新，可重新打开（Reopen）PR。

提示

• 如果上传的文件中包含非文本文件（如.ttf，.jpg等），有可能需要修改 Packer 配置，否则它们会被打包器排除，不会进入用户使用的资源包。
  • 如果这些文件放置在font或textures中，一般不用修改配置；默认已经对这两处进行了特殊处理。
• 不同版本的同一模组可通过自定义文件检索策略同步翻译。

代码贡献指南

以下内容只针对对 src 文件夹下的贡献。

• 我们默认你已了解 C#、GitHub Actions 以及相关计算机的基本知识。
• 贡献代码有着更加严格的审查，请不要发无意义的、影响本项目运作的 PR（例：SPAM）。
• 在提交前，你已测试过你的代码能够正常的运行。
• 请简要描述提交的代码的作用。

配置更改指南

以下内容只针对对 config 文件夹下的贡献。这里里只列出了部分修改可能较大的文件。

Packer

路径：./config/packer/[version].json（如1.12的文件在1.12.2.json）

该文件内放置了所有正在维护的版本的打包配置。 不要随意删去内容，除非你知道它为什么弃用。 加入内容相对而言宽松一些，但最好还是说明理由。

下面没有提到的一般都不适合改动；如果需要，最好说明理由。

主要的更改场景：

• 增加新翻译版本
  • 需要将所有项填写一遍，同时需要更新.github/workflows/packer.yml、.github/workflows/pr-packer.yml、.github\boring-cyborg.yml，以及 CFPABot 等相关服务。没有规划最好不要乱动。
• 更改字符替换表
  • 修改replacementMap，格式与已有文本一致。Unicode*基础多语种平面（BMP）*以外的字符需要使用UTF-16代理对输入，否则可能无法识别。
  • 同时可能需要修改字体文件。
• 处理非文本文件
  1. 如果该文件所在的文件夹与lang文件夹同级，且对任何模组都不会有文本文件（如font\），将该文件夹加入对应版本的noProcessNamespace中。
  2. 否则，将该模组的CurseForge 项目名称或命名空间中的一个（具体选哪一个看具体情况）加入modNameBlackList或domainBlackList，并将所有受影响的文件的相对位置加入additionalContents。
• 添加非标准位置（在assets/以外）的文件
  • 直接加入additionalContents
• 停止对某模组的支持
  • 把该模组的CurseForge 项目名称或命名空间中的加入相应的modNameBlackList或domainBlackList（二者取其一）。

联系我们

若有不明白的地方，可前往 QQ 群（630943368，较为活跃）或 Discord 提问。