docs/ko/community/Contribution-Guide.md

# 프로젝트에 기여하기

> [!CAUTION]
>
> 현재 프로젝트 관리자들은 자동화된 문서 국제화를 연구 중입니다. 따라서 문서 국제화/번역과 관련된 PR 은 **절대 허용되지 않습니다**!
>
> 문서 국제화/번역과 관련된 PR 을 제출하지 마세요!

이 프로젝트에 관심을 가져 주셔서 감사합니다! 기여를 시작하기 전에, 원활한 기여를 위해 다음 가이드라인을 꼭 읽어 주시기 바랍니다.

## 허용되지 않는 기여 유형

1. 문서 국제화/번역
2. HTTP API 등과 같은 핵심 인프라와 관련된 기여
3. "도움 필요 없음"으로 명시적으로 표시된 이슈 ([Byaidu/PDFMathTranslate](Byaidu/PDFMathTranslate) 및 [PDFMathTranslate-next/PDFMathTranslate-next](PDFMathTranslate-next/PDFMathTranslate-next) 저장소의 이슈 포함).
4. 유지 관리자가 부적절하다고 판단한 기타 기여.
5. 문서 기여이지만 영어 이외의 언어로 문서를 변경하는 경우.
6. `PDF` 파일 수정이 필요한 PR.
7. `pdf2zh_next/gui_translation.yaml` 파일을 수정하는 PR.

위와 관련된 유형의 PR 은 제출하지 마십시오.

> [!NOTE]
>
> 문서에 기여하고 싶다면 **문서의 영어 버전만 수정해 주세요**. 다른 언어 버전은 기여자들이 직접 번역합니다.

- [ ] Adding new translation services.
- [ ] Adding new features.
- [ ] Adding new dependencies.

## PRs that are welcome to submit directly
- [ ] Fix typo.
- [ ] Fix grammatical errors.
- [ ] Fix broken links.
- [ ] Fix incorrect translation.
- [ ] Add missing translation.
- [ ] Improve translation quality.
- [ ] Add new language.

---

### OUTPUT

## 유지 관리자와 이슈를 통해 사전 논의가 권장되는 PR
- [ ] 새로운 번역 서비스 추가.
- [ ] 새로운 기능 추가.
- [ ] 새로운 의존성 추가.

## 직접 제출이 권장되는 PR
- [ ] 오타 수정.
- [ ] 문법 오류 수정.
- [ ] 깨진 링크 수정.
- [ ] 잘못된 번역 수정.
- [ ] 누락된 번역 추가.
- [ ] 번역 품질 향상.
- [ ] 새로운 언어 추가.

- Adding new translation services.
- Adding new features.
- Adding new dependencies.

For the following types of PRs, you are welcome to submit directly:
- Fix typo.
- Fix grammatical errors.
- Fix broken links.
- Fix incorrect translation.
- Add missing translation.
- Improve translation quality.
- Add new language.

---

### OUTPUT

다음 유형의 PR 은 제출 전에 유지 관리자와 먼저 논의하는 것이 권장됩니다:
- 새로운 번역 서비스 추가.
- 새로운 기능 추가.
- 새로운 의존성 추가.

다음 유형의 PR 은 직접 제출해 주셔도 좋습니다:
- 오타 수정.
- 문법 오류 수정.
- 깨진 링크 수정.
- 잘못된 번역 수정.
- 누락된 번역 추가.
- 번역 품질 향상.
- 새로운 언어 추가.

2. PRs related to adding new dependencies. (This project aims to maintain minimal dependencies).
3. PRs related to adding new translation services. (Translation services require extensive testing and maintenance, and we currently do not plan to add new ones).
4. PRs related to adding new features. (This project is currently in maintenance mode and does not plan to add new features).

---

### OUTPUT

1. 다중 사용자 공유 기능과 관련된 PR. (이 프로젝트는 주로 단일 사용자 사용을 위해 설계되었으며, 포괄적인 다중 사용자 시스템을 도입할 계획이 없습니다).
2. 새로운 의존성 추가와 관련된 PR. (이 프로젝트는 최소한의 의존성을 유지하는 것을 목표로 합니다).
3. 새로운 번역 서비스 추가와 관련된 PR. (번역 서비스는 광범위한 테스트와 유지보수가 필요하며, 현재 새로운 서비스를 추가할 계획이 없습니다).
4. 새로운 기능 추가와 관련된 PR. (이 프로젝트는 현재 유지보수 모드이며, 새로운 기능을 추가할 계획이 없습니다).

## 기여 프로세스

1. 이 저장소를 포크하고 로컬에 클론합니다.
2. 새로운 브랜치를 생성합니다: `git checkout -b feature/<feature-name>`.
3. 개발을 진행하고 코드가 요구 사항을 충족하는지 확인합니다.
4. 코드를 커밋합니다:
   ```bash
   git add .
   git commit -m "<semantic commit message>"
   ```
5. 자신의 저장소에 푸시합니다: `git push origin feature/<feature-name>`.
6. GitHub 에서 PR 을 생성하고 상세한 설명을 제공한 후 [@awwaawwa](https://github.com/awwaawwa) 에게 리뷰를 요청합니다.
7. 모든 자동화된 검사가 통과되는지 확인합니다.

> [!TIP]
>
> 개발이 완전히 완료될 때까지 기다릴 필요 없이 PR 을 생성할 수 있습니다. 일찍 생성하면 구현을 검토하고 제안을 제공할 수 있습니다.
>
> 소스 코드 또는 관련 사항에 대한 질문이 있으면 aw@funstory.ai 로 메인테이너에게 문의하세요.
>
> 2.0 버전의 리소스 파일은 [BabelDOC](https://github.com/funstory-ai/BabelDOC) 와 공유됩니다. 관련 리소스를 다운로드하는 코드는 BabelDOC 에 있습니다. 새로운 리소스 파일을 추가하려면 BabelDOC 메인테이너에게 aw@funstory.ai 로 문의하세요.

## 기본 요구 사항

<h4 id="sop">1. 워크플로우</h4>

   - `main` 브랜치에서 포크를 생성하고 포크된 브랜치에서 개발을 진행해 주세요.
   - Pull Request(PR) 를 제출할 때 변경 사항에 대한 상세한 설명을 제공해 주세요.
   - PR 이 자동화된 검사를 통과하지 못하는 경우 (`checks failed` 및 빨간색 십자가로 표시됨), 해당 `details` 를 확인하고 제출물을 수정하여 새로운 PR 이 모든 검사를 통과할 수 있도록 해 주세요.


<h4 id="dev&test">2. 개발 및 테스트</h4>

   - 개발 및 테스트를 위해 `pip install -e .` 명령을 사용하세요.


<h4 id="format">3. 코드 포맷팅</h4>

   - `pre-commit` 도구를 구성하고 코드 서식을 위해 `black` 과 `flake8` 을 활성화하세요.


<h4 id="requpdate">4. 종속성 업데이트</h4>

   - 새로운 종속성을 도입하는 경우, `pyproject.toml` 파일의 종속성 목록을 적시에 업데이트해 주세요.


<h4 id="docupdate">5. 문서 업데이트</h4>

   - 새로운 명령줄 옵션을 추가하는 경우, `README.md` 파일의 모든 언어 버전에서 명령줄 옵션 목록을 해당 사항에 맞게 업데이트해 주세요.


<h4 id="commitmsg">6. 커밋 메시지</h4>

   - [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) 를 사용하세요. 예: `feat(translator): add openai`.


<h4 id="코딩스타일">7. 코딩 스타일</h4>

   - 제출한 코드가 기본적인 코딩 스타일 표준을 준수하는지 확인하세요.
   - 변수 이름에는 snake_case 또는 camelCase 를 사용하세요.


<h4 id="doctypo">8. 문서 서식</h4>

   - `README.md` 포맷팅은 [중국어 카피라이팅 가이드라인](https://github.com/sparanoid/chinese-copywriting-guidelines) 을 따르세요.
   - 영어 및 중국어 문서는 항상 최신 상태로 유지하고, 다른 언어 문서 업데이트는 선택 사항입니다.

## 번역 엔진 추가하기

1. `pdf2zh/config/translate_engine_model.py` 파일에 새로운 번역기 구성 클래스를 추가합니다.
2. 동일한 파일의 `TRANSLATION_ENGINE_SETTING_TYPE` 타입 별칭에 새로운 번역기 구성 클래스의 인스턴스를 추가합니다.
3. `pdf2zh/translator/translator_impl` 폴더에 새로운 번역기 구현 클래스를 추가합니다.

> [!NOTE]
>
> 이 프로젝트는 RPS(초당 요청 수) 가 4 미만인 번역 엔진을 지원할 의도가 없습니다. 이러한 엔진에 대한 지원을 요청하지 마십시오.
> 다음 유형의 번역기도 통합되지 않습니다:
> - 업스트림 유지보수자에 의해 중단된 번역기 (예: deeplx)
> - 큰 의존성이 있는 번역기 (예: pytorch 에 의존하는 경우)
> - 불안정한 번역기
> - 리버스 엔지니어링 API 기반 번역기
>
> 특정 번역기가 요구 사항을 충족하는지 확실하지 않은 경우, 이슈를 보내 유지보수자와 논의할 수 있습니다.

## 프로젝트 구조

- **config 폴더**: 구성 시스템.
- **translator 폴더**: 번역기 관련 구현.
- **gui.py**: GUI 인터페이스를 제공.
- **const.py**: 일부 상수.
- **main.py**: 명령줄 도구를 제공.
- **high_level.py**: BabelDOC 기반의 고수준 인터페이스.
- **http_api.py**: HTTP API 를 제공 (시작되지 않음).

AI 에게 프로젝트 이해 요청: [DeepWiki](https://deepwiki.com/PDFMathTranslate-next/PDFMathTranslate-next)

## 문의하기

질문이 있으시면 Issue 를 통해 피드백을 제출하거나 Telegram 그룹에 참여해 주세요. 기여해 주셔서 감사합니다!

> [!TIP]
>
> [Immersive Translate](https://immersivetranslate.com) 는 이 프로젝트에 활발히 기여하는 분들을 위해 매월 Pro 멤버십 코드를 후원합니다. 자세한 내용은 다음을 참조하세요: [BabelDOC/PDFMathTranslate 기여자 보상 규칙](https://funstory-ai.github.io/BabelDOC/CONTRIBUTOR_REWARD/)

<div align="right"> 
<h6><small>이 페이지의 일부 내용은 GPT 에 의해 번역되었으며 오류가 포함될 수 있습니다.</small></h6>