Contributing to the Project

Thank you for your interest in this project! Before you start contributing, please take some time to read the following guidelines to ensure your contribution can be smoothly accepted.

Types of Contributions Not Accepted

1. Documentation internationalization/translation
2. Contributions related to core infrastructure, such as HTTP API, etc.
3. Issues explicitly marked as "No help needed" (including issues in the Byaidu/PDFMathTranslate and the PDFMathTranslate/PDFMathTranslate-next repository).
4. Other contributions deemed inappropriate by the maintainers.
5. Contributing documentation, but changing the documentation in languages other than English.
6. PRs that require modifying PDF files.

Please do NOT submit PRs related to the above types.

Contribution Process

1. Fork this repository and clone it locally.
2. Create a new branch: git checkout -b feature/<feature-name>.
3. Develop and ensure your code meets the requirements.
4. Commit your code:

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

5. Push to your repository: git push origin feature/<feature-name>.
6. Create a PR on GitHub, provide a detailed description, and request a review from @awwaawwa.
7. Ensure all automated checks pass.

Basic Requirements

1. Workflow

• Please fork from the main branch and develop on your forked branch.
• When submitting a Pull Request (PR), provide a detailed description of your changes.
• If your PR does not pass automated checks (indicated by checks failed and a red cross), please review the corresponding details and modify your submission to ensure the new PR passes all checks.

2. Development and Testing

• Use the command pip install -e . for development and testing.

3. Code Formatting

• Configure the pre-commit tool and enable black and flake8 for code formatting.

4. Dependency Updates

• If you introduce new dependencies, please update the dependency list in the pyproject.toml file in a timely manner.

5. Documentation Updates

• If you add new command-line options, please update the list of command-line options in all language versions of the README.md file accordingly.

6. Commit Messages

• Use Conventional Commits, for example: feat(translator): add openai.

7. Coding Style

• Ensure your submitted code adheres to basic coding style standards.
• Use either snake_case or camelCase for variable naming.

8. Documentation Formatting

• For README.md formatting, please follow the Chinese Copywriting Guidelines.
• Ensure that both English and Chinese documentation are always up to date; other language documentation updates are optional.

Adding a Translation Engine

1. Add a new translator configuration class in the pdf2zh/config/translate_engine_model.py file.
2. Add an instance of the new translator configuration class to the TRANSLATION_ENGINE_SETTING_TYPE type alias in the same file.
3. Add the new translator implementation class in the pdf2zh/translator/translator_impl folder.

Project Structure

• config folder: Configuration system.
• translator folder: Translator-related implementations.
• gui.py: Provides the GUI interface.
• const.py: Some constants.
• main.py: Provides the command-line tool.
• high_level.py: High-level interfaces based on BabelDOC.
• http_api.py: Provides HTTP API (not started).

Contact Us

If you have any questions, please submit feedback via Issue or join our Telegram Group. Thank you for your contribution!