# ចូលរួមចំណែកក្នុង Co-op Translator

គម្រោងនេះស្វាគមន៍ការចូលរួម និងការផ្ដល់យោបល់។ ការចូលរួមភាគច្រើនត្រូវការឲ្យអ្នកយល់ព្រមលើសន្ធិសញ្ញាអាជ្ញាបណ្ណរបស់អ្នកចូលរួម (Contributor License Agreement - CLA) ដែលប្រកាសថាអ្នកមានសិទ្ធិ ហើយពិតជាផ្ដល់សិទ្ធិឲ្យយើងប្រើប្រាស់ការចូលរួមរបស់អ្នក។ សម្រាប់ព័ត៌មានលំអិត សូមចូលទៅកាន់ https://cla.opensource.microsoft.com។

ពេលអ្នកដាក់ស្នើ pull request មួយ កម្មវិធី CLA bot នឹងកំណត់ដោយស្វ័យប្រវត្តិថាតើអ្នកត្រូវផ្ដល់ CLA ឬយ៉ាងណា ហើយនឹងតុបតែង PR ទៅតាមលក្ខខណ្ឌ (ដូចជា ការត្រួតពិនិត្យស្ថានភាព ការកម្រែផ្សេងៗ)។ សូមគោរពតាមសេចក្ដីណែនាំពី bot។ អ្នកត្រូវធ្វើនេះតែមួយដងគត់ចំពោះ repos ទាំងអស់ដែលប្រើ CLA របស់យើង។

## ការតំឡើងបរិបទអភិវឌ្ឍន៍

ដើម្បីតំឡើងបរិបទអភិវឌ្ឍន៍សម្រាប់គម្រោងនេះ យើងណែនាំឲ្យប្រើ Poetry សម្រាប់គ្រប់គ្រងអាសយដ្ឋានពាក់ព័ន្ធ។ យើងប្រើ `pyproject.toml` ដើម្បីគ្រប់គ្រងអាសយដ្ឋាននានា ហើយដូច្នេះ ដើម្បីតំឡើងអាសយដ្ឋាន អ្នកគួរត្រូវប្រើ Poetry។

### បង្កើតបរិបទវើចប៊ាល់

#### ការប្រើ pip

```bash
python -m venv .venv
```

#### ការប្រើ Poetry

```bash
poetry init
```

### បញ្ចូលបរិបទវើចប៊ាល់

#### សម្រាប់ទាំង pip និង Poetry

- Windows:

    ```bash
    .venv\Scripts\activate.bat
    ```

- Mac/Linux:

    ```bash
    source .venv/bin/activate
    ```

#### ការប្រើ Poetry

```bash
poetry shell
```

### ការតំឡើងកញ្ចប់ និងកញ្ចប់ដែលចាំបាច់

#### ការប្រើ Poetry (ពី pyproject.toml)

```bash
poetry install
```

### ការសាកល្បងដោយដៃ

មុនពេលដាក់ស្នើ PR វាសំខាន់ក្នុងការសាកល្បងមុខងារបកប្រែជាមួយឯកសារពិតប្រាកដ៖

1. បង្កើតថតសាកល្បងក្នុងថតដើម៖
    ```bash
    mkdir test_docs
    ```

2. ចម្លងឯកសារ markdown និងរូបភាពដែលអ្នកចង់បកប្រែចូលក្នុងថតសាកល្បង។ ឧទាហរណ៍៖
    ```bash
    cp /path/to/your/docs/*.md test_docs/
    cp /path/to/your/images/*.png test_docs/
    ```

3. តំឡើងកញ្ចប់ក្នុងតំបន់ជាន់ដើម៖
    ```bash
    pip install -e .
    ```

4. រត់ Co-op Translator លើឯកសារសាកល្បងរបស់អ្នក៖
    ```bash
    python -m co_op_translator --language-codes ko --root-dir test_docs
    ```

5. ពិនិត្យឯកសារបកប្រែ​នៅក្នុង `test_docs/translations` និង `test_docs/translated_images` ដើម្បីបញ្ជាក់៖
   - គុណភាពការបកប្រែ
   - ការមតិយោបល់ metadata ត្រឹមត្រូវ
   - រចនាសម្ព័ន្ធ markdown ដើម ត្រូវបានរក្សាទុក
   - តំណ និងរូបភាពដំណើរការល្អ

ការសាកល្បងដោយដៃនេះជួយធានាថាបម្រែបម្រួលរបស់អ្នកដំណើរការល្អនៅក្នុងសេណារីយ៉ូពិតប្រាកដ។

### អថេរបរិបទបរិស្ថាន

1. បង្កើតឯកសារ `.env` ក្នុងថតដើមដោយចម្លងឯកសារ `.env.template` ដែលបានផ្ដល់។
1. បញ្ចូលអថេរបរិបទបរិស្ថានតាមការណែនាំ។

> [!TIP]
>
> ### ជម្រើសបន្ថែមសម្រាប់បរិបទអភិវឌ្ឍន៍
>
> លើសពីការរត់គម្រោងក្នុងតំបន់ជាន់ដើម អ្នកអាចប្រើ GitHub Codespaces ឬ VS Code Dev Containers សម្រាប់ការតំឡើងបរិបទអភិវឌ្ឍន៍ជំនួស។
>
> #### GitHub Codespaces
>
> អ្នកអាចដំណើរការឧទាហរណ៍នេះដោយប្រើ GitHub Codespaces ដោយគ្មានការកំណត់ ឬតំឡើងបន្ថែមណាមួយ។
>
> ប៊ូតុងនឹងបើក VS Code តាមគេហទំព័រនៅក្នុងម៉ាស៊ីនការប្រតិបត្តិរបស់អ្នក៖
>
> 1. បើកទម្រង់ (អាចចំណាយពេលប៉ុន្មាននាទី)៖
>
>     [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/azure/co-op-translator)
>
> #### រត់ក្នុងតំបន់ជាន់ដើមដោយប្រើ VS Code Dev Containers
>
> ⚠️ ជម្រើសនេះអាចដំណើរការត្រឹមតែបើ Desktop Docker របស់អ្នកបែងចែក RAM យ៉ាងតិច ១៦ GB។ ប្រសិនបើអ្នកមានRAMតិចជាងនេះ អ្នកអាចព្យាយាមជម្រើស [GitHub Codespaces](#github-codespaces) ឬ [តំឡើងក្នុងតំបន់ជាន់ដើម](#ការតំឡើងបរិបទអភិវឌ្ឍន៍)។
>
> ជម្រើសដែលពាក់ព័ន្ធគឺ VS Code Dev Containers ដែលនឹងបើកគម្រោងនៅក្នុង VS Code តំបន់ជាន់ដើមរបស់អ្នកដោយប្រើកម្មវិធីបន្ថែម [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)៖
>
> 1. ចាប់ផ្ដើម Docker Desktop (បើកបញ្ចូលបើមិនទាន់បានដំឡើង)
> 2. បើកគម្រោង៖
>
>    [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/azure/co-op-translator)


### រចនាបថកូដ

យើងប្រើ [Black](https://github.com/psf/black) ជាអ្នករៀបចំកូដ Python របស់យើង ដើម្បីរក្សារូបរាងកូដជាដើមទាំងមូលនៅលើគម្រោង។ Black ជាឧបករណ៍រៀបចំកូដដែលគ្មានការលំអររូបភាព ដែលបម្រុងបំលែងកូដ Python ដើម្បីស្របតាមរចនាបថកូដ Black។

#### ការកំណត់រចនា

ការកំណត់រចនាបថ Black ត្រូវបានបញ្ជាក់នៅក្នុង `pyproject.toml` របស់យើង៖

```toml
[tool.black]
line-length = 88
target-version = ['py310']
include = '\.pyi?$'
```

#### ការតំឡើង Black

អ្នកអាចតំឡើង Black ដោយប្រើ Poetry (ណែនាំ) ឬ pip៖

##### ការប្រើ Poetry

Black ត្រូវបានតំឡើងដោយស្វ័យប្រវត្តិពេលអ្នកតំឡើងបរិបទអភិវឌ្ឍន៍៖
```bash
poetry install
```

##### ការប្រើ pip

បើអ្នកប្រើ pip អ្នកអាចតំឡើង Black ដោយផ្ទាល់៖
```bash
pip install black
```

#### ការប្រើ Black

##### ជាមួយ Poetry

1. រៀបចំឯកសារ Python ទាំងអស់ក្នុងគម្រោង៖
    ```bash
    poetry run black .
    ```

2. រៀបចំឯកសារឬថតជាក់លាក់៖
    ```bash
    poetry run black path/to/file_or_directory
    ```

##### ជាមួយ pip

1. រៀបចំឯកសារ Python ទាំងអស់ក្នុងគម្រោង៖
    ```bash
    black .
    ```

2. រៀបចំឯកសារឬថតជាក់លាក់៖
    ```bash
    black path/to/file_or_directory
    ```

> [!TIP]
> យើងណែនាំឲ្យកំណត់កម្មវិធីកែសម្រួលរបស់អ្នកឲ្យរៀបចំកូដដោយ Black ដោយស្វ័យប្រវត្តិពេលរក្សាទុក។ កម្មវិធីកែសម្រួលទំនើបភាគច្រើនគាំទ្ររឿងនេះតាមបន្ថែមឬផ្លាក់អ៊ុន។

## រត់ Co-op Translator

ដើម្បីរត់ Co-op Translator ប្រើ Poetry នៅក្នុងបរិបទរបស់អ្នក សូមអនុវត្តជំហានខាងក្រោម៖

1. ទៅកាន់ថតដែលអ្នកចង់យកទៅសាកល្បងបកប្រែ ឬបង្កើតថតបណ្តោះអាសន្នសម្រាប់ការសាកល្បង។

2. ប្រតិបត្តិការបញ្ជាលេខខាងក្រោម។ ជំនួស `-l ko` ជាមួយកូដភាសាដែលអ្នកចង់បកប្រែចូល។ ទង់ដែង `-d` ជាប៊្លាសចុះក្នុងរបៀបផ្សព្វផ្សាយកំហុស។

    ```bash
    poetry run co-op-translator translate -l ko -d
    ```

> [!NOTE]
> សូមប្រាកដថាបរិបទ Poetry របស់អ្នកត្រូវបានបញ្ចូល (poetry shell) មុនពេលរត់បញ្ជា។

## ចូលរួមជាភាសាថ្មី

យើងស្វាគមន៍ការចូលរួមដែលបន្ថែមការគាំទ្រផ្នែកភាសាថ្មី។ មុនពេលបើក PR សូមបញ្ចប់ជំហានខាងក្រោមដើម្បីធានាការត្រួតពិនិត្យរលូន។

1. បន្ថែមភាសាទៅក្នុងផែនទីហ្វូន
   - កែប្រែ `src/co_op_translator/fonts/font_language_mappings.yml`
   - បញ្ចូលចំណុចមួយជាមួយ៖
     - `code`: កូដភាសាទ្រង់ទ្រាយ ISO (ឧ. `vi`)
     - `name`: ឈ្មោះបង្ហាញងាយស្រួលសម្រាប់មនុស្ស
     - `font`: ហ្វូនដែលផ្ដល់ជូននៅ `src/co_op_translator/fonts/` ដែលគាំទ្ររចនាសម្ព័ន្ធនោះ
     - `rtl`: `true` ប្រសិនបើពីស្តាំទៅឆ្វេង បើអត់ `false`

2. ខ្ចប់ឯកសារហ្វូនត្រូវការ (បើចាំបាច់)
   - ប្រសិនបើត្រូវហ្វូនថ្មី សូមធានាគុណភាពអាជ្ញាបណ្ណសម្រាប់ចែកចាយកូដប្រភពសាធារណៈ
   - បញ្ចូលឯកសារហ្វូនទៅ `src/co_op_translator/fonts/`

3. ពិនិត្យក្នុងតំបន់ជាន់ដើម
   - រត់បកប្រែសម្រាប់ឧទាហរណ៍តូច (Markdown, រូបភាព និងសៀវភៅកំណត់ទុកជាប្រភេទ notebook)
   - ពិនិត្យលទ្ធផលបង្ហាញបានត្រឹមត្រូវ រួមទាំងហ្វូន និងរចនាសម្ព័ន្ធ RTL ប្រសិនបើមាន

4. កែប្រែនៅក្នុងឯកសារ
   - ប្រាកដថាភាសាអាចមើលឃើញនៅក្នុង `getting_started/supported-languages.md`
   - មិនត្រូវកែប្រែ `getting_started/README_languages_template.md` ព្រោះវាត្រូវបានបង្កើតពីបញ្ជីភាសាដែលគាំទ្រ

5. បើក PR
   - ពណ៌នាភាសាដែលបានបន្ថែមជាមួយការពិចារណាអំពីហ្វូន/អាជ្ញាបណ្ណ
   - ភ្ជាប់រូបថតអេក្រង់នៃលទ្ធផលបើអាចបាន

គំរូ YAML៖

```yaml
new_lang(code):
  name: "New Language"
  font: "NotoSans-Medium.ttf"
  rtl: false
```

### សាកល្បងភាសាថ្មី

អ្នកអាចសាកល្បងភាសាថ្មីដោយរត់បញ្ជាលេខខាងក្រោម៖

```bash
# បង្កើត និងចាប់ផ្តើមបរិស្ថានហ вирту
python -m venv .venv
# វីនដូ
.venv\Scripts\activate
# ម៉ាក់អូស / លីនុច
source .venv/bin/activate
# ដំឡើងកញ្ចប់អភិវឌ្ឍន៍
pip install -e .
# រត់ការប្រែសម្រួល
translate -l "new_lang"
```

## អ្នកថែរក្សា

### សារ commit និងយុទ្ធសាស្រ្ត Merged

ដើម្បីធានាការស្របតាម និងច្បាស់លាស់នៅក្នុងប្រវត្តិ commit របស់គម្រោង យើងអនុវត្តសម្លេងសារ commit ជាក់លាក់ **សម្រាប់សារ commit ចុងក្រោយ** ពេលប្រើយុទ្ធសាស្ត្រ **Squash and Merge**។

ពេល pull request (PR) ត្រូវបាន merged commit ផ្សេងៗនឹងត្រូវដាក់បញ្ចូលជា commit តែមួយ។ សារចុងក្រោយ commit គួរតែជាប់ទៅតាមរចនាបថខាងក្រោម ដើម្បីរក្សារប្រវត្តិគម្រោងស្អាត និងស្របតាមទៀងទាត់។

#### រចនាបថសារ commit (សម្រាប់ squash and merge)

យើងប្រើរចនាបថខាងក្រោមសម្រាប់សារ commit៖

```bash
<type>: <description> (#<លេខ PR>)
```

- **type**: បញ្ជាក់ប្រភេទ commit។ យើងប្រើប្រភេទខាងក្រោម៖
  - `Docs`: សម្រាប់ការអាប់ដេតឯកសារព័ត៌មាន។
  - `Build`: សម្រាប់ការផ្លាស់ប្តូរភាពពាក់ព័ន្ធនឹងប្រព័ន្ធសាងសង់ ឬអាសយដ្ឋានពាក់ព័ន្ធ រួមទាំងការអាប់ដេតឯកសារកំណត់រចនា, បំណង CI ក៏ដូចជាកម្មវិធី Dockerfile។
  - `Core`: សម្រាប់ការបំលែងមុខងារចម្បង ឬលក្ខណៈពិសេសរបស់គម្រោង ជាពិសេសឯកសារនៅទីតាំង `src/co_op_translator/core`

- **description**: សេចក្ដីសង្ខេបខ្លីនៃការផ្លាស់ប្តូរ។
- **PR number**: លេខ pull request ដែលទាក់ទងនឹង commit។

**ឧទាហរណ៍**៖

- `Docs: Update installation instructions for clarity (#50)`
- `Core: Improve handling of image translation (#60)`

> [!NOTE]
> បច្ចុប្បន្ននេះ ប្រភេទ **`Docs`**, **`Core`**, និង **`Build`** នឹងត្រូវបញ្ចូលទៅក្នុងចំណងជើង PR ដោយស្វ័យប្រវត្តិផ្អែកលើលេខស្លាកដែលបានដាក់លើកូដ។ ដូច្នេះ ប្រសិនបើស្លាកត្រឹមត្រូវ អ្នកមិនចាំបាច់ធ្វើការកែប្រែចំណងជើង PR ដោយដៃឡើយ។ អ្នកគ្រាន់តែត្រូវផ្ទៀងផ្ទាត់ថាទាំងអស់ត្រឹមត្រូវ និង prefix ត្រូវបានបង្កើតនិងគិតគូរឲ្យត្រូវ។

#### យុទ្ធសាស្រ្ត Merged

យើងប្រើ **Squash and Merge** ជាយុទ្ធសាស្រ្តលំនាំដើមសម្រាប់ pull requests។ យុទ្ធសាស្ត្រនេះធានាថាសារជាប់ក្នុង commit ត្រូវនឹងរចនាបថ commit របស់យើង ទោះបី commit ផ្សេងៗមិនមានរចនាបថក៏ដោយ។

**ហេតុផល**៖

- ប្រវត្តគម្រោងស្អាត និងបន្ទាត់តែមួយ។
- មានតុល្យភាពសារបានយ៉ាងល្អ។
- បន្ថយសំឡេងរំខានពី commit តូចៗ (ដូចជា "fix typo")។

ពេល merged សូមអោយប្រាកដថាសារចុងក្រោយ commit ត្រូវនឹងរចនាបថ commit ដែលបានពិពណ៌នាខាងលើ។

**ឧទាហរណ៍នៃ Squash and Merge**  
បើ PR មាន commit ដូចខាងក្រោម៖

- `fix typo`
- `update README`
- `adjust formatting`

ពួកវានឹងត្រូវ squash ទៅជា៖  
`Docs: Improve documentation clarity and formatting (#65)`

### ដំណើរការចេញផ្សាយ

ផ្នែកនេះពិពណ៌នាវិធីសាមញ្ញបំផុតសម្រាប់អ្នកថែរក្សាទៅបោះពុម្ពផ្សាយចេញផ្សាយថ្មីនៃ Co-op Translator។

#### 1. បន្ទាន់បំផុត version នៅ `pyproject.toml`

1. សម្រេចលេខ version មុខក្រោយ (យើងអនុវត្ត semantic versioning៖ `MAJOR.MINOR.PATCH`)។
2. កែ `pyproject.toml` ហើយបន្ទាន់បំផុតវាល `version` នៅក្នុង `[tool.poetry]`។
3. បើក pull request ឯកជនដែលមានតែការផ្លាស់ប្តូរលេខ version (និងឯកសារចាក់សោ/metadata ដែលបច្ចុប្បន្នភាពដោយស្វ័យប្រវត្តិ ប្រសិនបើមាន)។
4. បន្ទាប់ពីការត្រួតពិនិត្យ ប្រើ **Squash and Merge** ហើយប្រាកដថាសារចុង commit នោះស្របតាមរចនាបថ commit ខាងលើ។

#### 2. បង្កើតការចេញផ្សាយ GitHub Release

1. ទៅកាន់ទំព័រឃ្លាំង GitHub ហើយបើក **Releases** → **Draft a new release**។
2. បង្កើត tag ថ្មី (ឧ. `v0.13.0`) ពីសាខា `main`។
3. កំណត់ចំណងជើងចេញផ្សាយទៅជាលេខ version ដូចគ្នា (ឧ. `v0.13.0`)។
4. ចុច **Generate release notes** ដើម្បីបង្កើតសេចក្ដីសង្ខេបអត្តបទដោយស្វ័យប្រវត្តិ។
5. អាចកែសម្រួលអត្ថបទ (ឧ. ដើម្បីបង្ហាញភាសាហើយលឿន ឬការផ្លាស់ប្តូរសំខាន់)។
6. បោះពុម្ពផ្សាយការចេញផ្សាយ។

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**ការបដិសេធ**៖  
ឯកសារនេះត្រូវបានបកប្រែដោយប្រើសេវាបកប្រែ AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ក្នុងខណៈដែលយើងខិតខំយ៉ាងហ្មត់ចត់ដល់ភាពត្រឹមត្រូវ សូមជ្រាបថាការបកប្រែដោយស្វ័យប្រវត្តិនេះអាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមក្នុងភាសាដើមគួរត្រូវបានចាត់ទុកជាអ្នកផ្ដល់ព័ត៌មានផ្លូវការជាដំបូង។ សម្រាប់ព័ត៌មានសំខាន់ៗ ការបកប្រែដោយមនុស្សជំនាញត្រូវបានផ្តល់អំណោយប្រសិនបើអាចធ្វើបាន។ យើងមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកបរបស់ខុសដែលកើតមានពីការប្រើប្រាស់ការបកប្រែនេះនោះទេ។
<!-- CO-OP TRANSLATOR DISCLAIMER END -->