为项目做贡献

感谢您对本项目的关注！在开始贡献之前，请花些时间阅读以下指南，以确保您的贡献能够顺利被接受。

不接受的贡献类型

1. 文档国际化/翻译
2. 与核心基础设施相关的贡献，例如 HTTP API 等
3. 明确标记为「无需帮助」的 Issues（包括 Byaidu/PDFMathTranslate 和 PDFMathTranslate-next/PDFMathTranslate-next 仓库中的 Issues）
4. 维护者认为不合适的其他贡献
5. 贡献文档，但修改非英语语言的文档
6. 需要修改 PDF 文件的 PR
7. 修改 pdf2zh_next/gui_translation.yaml 文件的 PR

请勿提交与上述类型相关的 PR。

To avoid wasting your time, we recommend that you create an Issue to discuss with the maintainers before submitting a PR for the following types of changes:

• Major changes: Changes that would significantly alter the structure of the codebase, such as adding a new major feature or refactoring large portions of the code.
• Breaking changes: Changes that would break existing functionality or change the API in a way that is not backward compatible.
• New dependencies: Adding new dependencies to the project, especially if they are large or have licensing implications.
• Performance optimizations: Changes that are intended to improve performance but might have trade-offs in terms of code readability or maintainability.
• UI/UX changes: Changes to the user interface or user experience that might affect how users interact with the application.
• Documentation updates: While minor documentation fixes are always welcome, major documentation overhauls or changes to the documentation structure should be discussed first.

By discussing these changes upfront, we can ensure that your contributions align with the project's goals and avoid unnecessary rework.

OUTPUT

建议在提交 PR 前通过 Issue 与维护者讨论的类型

为了避免浪费您的时间，我们建议您在提交以下类型的更改的 PR 之前，先创建一个 Issue 与维护者进行讨论：

• 重大更改：会显著改变代码库结构的更改，例如添加新的主要功能或重构大部分代码。
• 破坏性更改：会破坏现有功能或以不向后兼容的方式更改 API 的更改。
• 新依赖项：向项目添加新的依赖项，特别是如果它们体积较大或涉及许可问题。
• 性能优化：旨在提高性能但可能在代码可读性或可维护性方面有所权衡的更改。
• UI/UX 更改：对用户界面或用户体验的更改，可能会影响用户与应用程序的交互方式。
• 文档更新：虽然欢迎小的文档修复，但大的文档 overhaul 或文档结构的更改应首先讨论。

通过预先讨论这些更改，我们可以确保您的贡献符合项目的目标，并避免不必要的返工。

• Major changes: Changes that would significantly alter the structure of the codebase, such as adding a new major feature or refactoring large portions of the code.
• Breaking changes: Changes that would break existing functionality or change the API in a way that is not backward compatible.
• New dependencies: Adding new dependencies to the project, especially if they are large or have licensing implications.
• Performance optimizations: Changes that are intended to improve performance but might have trade-offs in terms of code readability or maintainability.
• UI/UX changes: Changes to the user interface or user experience that might affect how users interact with the application.
• Documentation updates: While minor documentation fixes are always welcome, major documentation overhauls or changes to the documentation structure should be discussed first.

By discussing these changes upfront, we can ensure that your contributions align with the project's goals and avoid unnecessary rework.

1. PRs that add new dependencies without sufficient justification.
2. PRs that change the core architecture of the project without prior discussion.
3. PRs that introduce breaking changes to the API or user interface without migration paths.
4. PRs that are not aligned with the project's goals or scope.

OUTPUT

1. 与多用户共享功能相关的 PR。（此项目主要为单用户使用而设计，不打算引入完整的多用户系统）。
2. 在没有充分理由的情况下添加新依赖项的 PR。
3. 未经事先讨论就更改项目核心架构的 PR。
4. 在没有迁移路径的情况下对 API 或用户界面引入破坏性更改的 PR。
5. 与项目目标或范围不符的 PR。

贡献流程

1. Fork 此仓库并在本地克隆它。
2. 创建一个新分支：git checkout -b feature/<feature-name>。
3. 进行开发并确保你的代码符合要求。
4. 提交你的代码：

   git add .
   git commit -m "<semantic commit message>"
   

5. 推送到你的仓库：git push origin feature/<feature-name>。
6. 在 GitHub 上创建一个 PR，提供详细描述，并请求 @awwaawwa 进行审查。
7. 确保所有自动化检查通过。

基本要求

1. 工作流程

• 请从 main 分支进行 fork，并在你的 fork 分支上进行开发。
• 提交 Pull Request（PR）时，请提供详细的变更描述。
• 如果你的 PR 未通过自动化检查（显示为 checks failed 和红色叉号），请查看对应的 details 并修改你的提交，确保新的 PR 能通过所有检查。

2. 开发与测试

• 使用命令 pip install -e . 进行开发和测试。

3. 代码格式化

• 配置 pre-commit 工具并启用 black 和 flake8 进行代码格式化。

4. 依赖项更新

• 如果您引入了新的依赖项，请及时更新 pyproject.toml 文件中的依赖列表。

5. 文档更新

• 如果添加了新的命令行选项，请相应地更新所有语言版本的 README.md 文件中的命令行选项列表。

6. 提交信息

• 使用 Conventional Commits，例如：feat(translator): add openai。

7. 代码风格

• 确保提交的代码符合基本的编码风格标准。
• 变量命名请使用 snake_case 或 camelCase。

8. 文档格式

• 对于 README.md 的格式，请遵循 中文文案排版指北。
• 确保英文和中文文档始终保持最新；其他语言文档的更新是可选的。

添加翻译引擎

1. 在 pdf2zh/config/translate_engine_model.py 文件中添加一个新的翻译器配置类。
2. 在同一文件中将新的翻译器配置类实例添加到 TRANSLATION_ENGINE_SETTING_TYPE 类型别名中。
3. 在 pdf2zh/translator/translator_impl 文件夹中添加新的翻译器实现类。

项目结构

• config 文件夹：配置系统。
• translator 文件夹：翻译器相关实现。
• gui.py：提供 GUI 界面。
• const.py：一些常量。
• main.py：提供命令行工具。
• high_level.py：基于 BabelDOC 的高级接口。
• http_api.py：提供 HTTP API（未启动）。

向 AI 询问以了解项目：DeepWiki

联系我们

如果您有任何问题，请通过 Issue 提交反馈或加入我们的 Telegram 群组。感谢您的贡献！