CONTRIBUTING.md

ចូលរួមចំណែកក្នុង 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

python -m venv .venv

ការប្រើ Poetry

poetry init

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

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

• Windows:

  .venv\Scripts\activate.bat

• Mac/Linux:

  source .venv/bin/activate

ការប្រើ Poetry

poetry shell

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

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

poetry install

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

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

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

   mkdir test_docs

2. ចម្លងឯកសារ markdown និងរូបភាពដែលអ្នកចង់បកប្រែចូលក្នុងថតសាកល្បង។ ឧទាហរណ៍៖

   cp /path/to/your/docs/*.md test_docs/
   cp /path/to/your/images/*.png test_docs/

3. តំឡើងកញ្ចប់ក្នុងតំបន់ជាន់ដើម៖

   pip install -e .

4. រត់ Co-op Translator លើឯកសារសាកល្បងរបស់អ្នក៖

   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 ដែលបានផ្ដល់។
2. បញ្ចូលអថេរបរិបទបរិស្ថានតាមការណែនាំ។

Tip

ជម្រើសបន្ថែមសម្រាប់បរិបទអភិវឌ្ឍន៍

លើសពីការរត់គម្រោងក្នុងតំបន់ជាន់ដើម អ្នកអាចប្រើ GitHub Codespaces ឬ VS Code Dev Containers សម្រាប់ការតំឡើងបរិបទអភិវឌ្ឍន៍ជំនួស។

GitHub Codespaces

អ្នកអាចដំណើរការឧទាហរណ៍នេះដោយប្រើ GitHub Codespaces ដោយគ្មានការកំណត់ ឬតំឡើងបន្ថែមណាមួយ។

ប៊ូតុងនឹងបើក VS Code តាមគេហទំព័រនៅក្នុងម៉ាស៊ីនការប្រតិបត្តិរបស់អ្នក៖

1. បើកទម្រង់ (អាចចំណាយពេលប៉ុន្មាននាទី)៖

   

រត់ក្នុងតំបន់ជាន់ដើមដោយប្រើ VS Code Dev Containers

⚠️ ជម្រើសនេះអាចដំណើរការត្រឹមតែបើ Desktop Docker របស់អ្នកបែងចែក RAM យ៉ាងតិច ១៦ GB។ ប្រសិនបើអ្នកមានRAMតិចជាងនេះ អ្នកអាចព្យាយាមជម្រើស GitHub Codespaces ឬ តំឡើងក្នុងតំបន់ជាន់ដើម។

ជម្រើសដែលពាក់ព័ន្ធគឺ VS Code Dev Containers ដែលនឹងបើកគម្រោងនៅក្នុង VS Code តំបន់ជាន់ដើមរបស់អ្នកដោយប្រើកម្មវិធីបន្ថែម Dev Containers extension៖

1. ចាប់ផ្ដើម Docker Desktop (បើកបញ្ចូលបើមិនទាន់បានដំឡើង)

2. បើកគម្រោង៖

   

រចនាបថកូដ

យើងប្រើ Black ជាអ្នករៀបចំកូដ Python របស់យើង ដើម្បីរក្សារូបរាងកូដជាដើមទាំងមូលនៅលើគម្រោង។ Black ជាឧបករណ៍រៀបចំកូដដែលគ្មានការលំអររូបភាព ដែលបម្រុងបំលែងកូដ Python ដើម្បីស្របតាមរចនាបថកូដ Black។

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

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

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

ការតំឡើង Black

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

ការប្រើ Poetry

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

poetry install

ការប្រើ pip

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

pip install black

ការប្រើ Black

ជាមួយ Poetry

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

   poetry run black .

2. រៀបចំឯកសារឬថតជាក់លាក់៖

   poetry run black path/to/file_or_directory

ជាមួយ pip

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

   black .

2. រៀបចំឯកសារឬថតជាក់លាក់៖

   black path/to/file_or_directory

Tip

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

រត់ Co-op Translator

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

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

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

   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៖

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

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

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

# បង្កើត និងចាប់ផ្តើមបរិស្ថានហ вирту
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៖

<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. បោះពុម្ពផ្សាយការចេញផ្សាយ។

---

ការបដិសេធ៖
ឯកសារនេះត្រូវបានបកប្រែដោយប្រើសេវាបកប្រែ AI Co-op Translator។ ក្នុងខណៈដែលយើងខិតខំយ៉ាងហ្មត់ចត់ដល់ភាពត្រឹមត្រូវ សូមជ្រាបថាការបកប្រែដោយស្វ័យប្រវត្តិនេះអាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមក្នុងភាសាដើមគួរត្រូវបានចាត់ទុកជាអ្នកផ្ដល់ព័ត៌មានផ្លូវការជាដំបូង។ សម្រាប់ព័ត៌មានសំខាន់ៗ ការបកប្រែដោយមនុស្សជំនាញត្រូវបានផ្តល់អំណោយប្រសិនបើអាចធ្វើបាន។ យើងមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកបរបស់ខុសដែលកើតមានពីការប្រើប្រាស់ការបកប្រែនេះនោះទេ។