Skip to content

Commit 1d3a754

Browse files
committed
chore(init): initial repository setup with translation guidelines and todo roadmap
0 parents  commit 1d3a754

7 files changed

Lines changed: 252 additions & 0 deletions

File tree

‎.github/workflows/compile-pdf.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Compile Book PDF with Typst
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
- main
8+
paths:
9+
- '**.typ'
10+
- 'images/**'
11+
workflow_dispatch:
12+
13+
jobs:
14+
build:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout repository
18+
uses: actions/checkout@v4
19+
20+
- name: Setup Typst
21+
uses: typst-community/setup-typst@v3
22+
23+
- name: Download Vazirmatn Font
24+
run: |
25+
mkdir -p ~/.local/share/fonts
26+
wget -q https://github.com/rastikerdar/vazirmatn/releases/download/v33.003/vazirmatn-v33.003.zip -O /tmp/vazirmatn.zip
27+
unzip -q -o /tmp/vazirmatn.zip -d ~/.local/share/fonts/
28+
fc-cache -f -v
29+
30+
- name: Compile PDF
31+
run: |
32+
typst compile book.typ output.pdf
33+
34+
- name: Upload PDF Artifact
35+
uses: actions/upload-artifact@v4
36+
with:
37+
name: compiled-book-pdf
38+
path: output.pdf

‎.gitignore‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Typst build outputs
2+
*.pdf
3+
!*Persian.pdf
4+
5+
# OS files
6+
.DS_Store
7+
Thumbs.db
8+
9+
# Editors
10+
.idea/
11+
.vscode/
12+
*.swp
13+
*.swo
14+
15+
# Node / Scratch
16+
node_modules/
17+
scratch/

‎AGENTS.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# AI Agent Guidelines & Technical Translation Standards
2+
3+
This repository contains the Persian conceptual translation and interpretive typesetting of **Get Started with MicroPython on Raspberry Pi Pico** by گرث هالفاکری (Gareth Halfacree) و بن اورارد (Ben Everard).
4+
5+
---
6+
7+
## 1. Core Translation Directive: Interpretive, Not Literal
8+
**DO NOT TRANSLATE WORD-FOR-WORD OR LITERALLY.**
9+
- Re-explain technical concepts in natural, idiomatic Persian with the conceptual depth of a Senior Software/Systems Engineer.
10+
- Explain *why* architectures and patterns work, detailing trade-offs and real-world production mental models.
11+
- Maintain the original book structure (chapters, sections, sub-sections, diagrams, code blocks, and callouts).
12+
13+
---
14+
15+
## 2. Mandatory Terminology: Developer Persian (DO NOT TRANSLATE LITERALLY)
16+
17+
| English Term | FORBIDDEN (Literal Calque) | MANDATORY (Developer Persian) |
18+
| :--- | :--- | :--- |
19+
| **Scale / Scaling** | مقیاس / مقیاس‌دهی / مقیاس‌پذیری | **اسکیل / اسکیل کردن / اسکیل‌پذیری (Scaling)** |
20+
| **Scale up / Scale down** | افزایش مقیاس / کاهش مقیاس | **اسکیل‌آپ (Scale-up) / اسکیل‌داون (Scale-down)** |
21+
| **Auto-scaling** | مقیاس‌پذیری خودکار | **اسکیل خودکار / Auto-scaling** |
22+
| **Deploy / Deployment** | استقرار دادن | **دیپلوی کردن / دیپلویمنت (Deployment)** |
23+
| **Rollout / Rolling Update**| چرخش / استقرار غلتان | **رولینگ آپدیت (Rolling Update) / انتشار تدریجی** |
24+
| **Rollback** | عقب‌گرد | **رول‌بک (Rollback)** |
25+
| **Pipeline** | خط لوله | **پایپ‌لاین (Pipeline)** |
26+
| **Cache / Caching** | حافظه پنهان | **کش / کش کردن (Cache)** |
27+
| **Trace / Tracing** | ردیابی | **تریس / تریس کردن (Trace / Tracing)** |
28+
| **Queue** | صف | **صف / صف پیام (Queue)** |
29+
| **Worker / Node** | کارگر | **ورکر (Worker) / نود (Node)** |
30+
| **Cluster** | خوشه | **کلاستر (Cluster)** |
31+
| **Namespace** | فضای نام | **نیم‌اسپیس (Namespace)** |
32+
| **Ingress** | ورودی | **اینگرس (Ingress)** |
33+
| **Pod** | پیله | **پاد (Pod)** |
34+
35+
---
36+
37+
## 3. Workflow & Mandatory Review Phase
38+
All work must track against `todo.md`.
39+
- **CRITICAL:** The final phase of any book milestone MUST ALWAYS be the **Review Phase (`فاز بازبینی و تضمین کیفیت نهایی`)**.
40+
- The Review phase requires:
41+
1. Grep search across `chapters/` for forbidden terms (e.g. `مقیاس`, `استقرار دادن`, `حافظه پنهان`).
42+
2. Compiling with `typst compile book.typ` with zero errors and zero missing-font warnings.
43+
3. Validating bilingual terminology in glossary chapter.

‎GEMINI.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# راهنمای نگارش و واژه‌نامه تخصصی (Developer Persian Terminology)
2+
3+
این فایل قواعد ترجمه، بازنویسی و نگارش متون تخصصی، آموزشی و کتاب‌های فنی این پروژه را مشخص می‌کند.
4+
5+
## ۱. اصل بنیادین لحن فنی (Developer Persian)
6+
در ترجمه و نگارش مفاهیم مهندسی نرم‌افزار، DevOps، ابری و معماری سیستم:
7+
- **پرهیز از ترجمه تحت‌اللفظی:** از ترجمه لغوی واژگان استاندارد صنعتی خودداری کنید. واژگان باید به همان شکل متداول میان مهندسان نرم‌افزار استفاده شوند.
8+
- **افعال فارسی با واژگان فنی اصیل:** از ساختارهای افعال مرکب فارسی همراه با اصطلاح لاتین یا تلفظ فنی آن استفاده کنید (مانند «اسکیل کردن»، «دیپلوی کردن»، «لاگ انداختن»، «هندل کردن»).
9+
10+
---
11+
12+
## ۲. جدول اصطلاحات حساس (Do Not Translate Literally)
13+
14+
| واژه انگلیسی | معادل نادرست (تحت‌اللفظی) | معادل صحیح و استاندارد (Developer Persian) |
15+
| :--- | :--- | :--- |
16+
| **Scale / Scaling** | مقیاس / مقیاس‌دهی / مقیاس‌پذیری | **اسکیل / اسکیل کردن / اسکیل‌پذیری (Scaling)** |
17+
| **Scale up / Scale down** | افزایش مقیاس / کاهش مقیاس | **اسکیل‌آپ (Scale-up) / اسکیل‌داون (Scale-down)** |
18+
| **Auto-scaling** | مقیاس‌پذیری خودکار | **اسکیل خودکار / Auto-scaling** |
19+
| **Deploy / Deployment** | استقرار دادن | **دیپلوی کردن / دیپلویمنت (Deployment)** |
20+
| **Rollout / Rolling Update** | چرخش / استقرار غلتان | **رولینگ آپدیت (Rolling Update) / انتشار تدریجی** |
21+
| **Rollback** | عقب‌گرد | **رول‌بک (Rollback)** |
22+
| **Pipeline** | خط لوله | **پایپ‌لاین (Pipeline)** |
23+
| **Cache / Caching** | حافظه پنهان | **کش / کش کردن (Cache)** |
24+
| **Trace / Tracing** | ردیابی | **تریس / تریس کردن (Trace / Tracing)** |
25+
| **Queue** | صف | **صف / صف پیام (Queue)** |
26+
| **Worker / Node** | کارگر | **ورکر (Worker) / نود (Node)** |
27+
| **Cluster** | خوشه | **کلاستر (Cluster)** |
28+
| **Namespace** | فضای نام | **نیم‌اسپیس (Namespace)** |
29+
| **Ingress** | ورودی | **اینگرس (Ingress)** |
30+
| **Pod** | پیله | **پاد (Pod)** |
31+
32+
---
33+
34+
## ۳. نحوه ارجاع اولیه
35+
در اولین اشاره به هر مفهوم بنیادین، ترکیب «معادل فارسی روان + نام انگلیسی در پرانتز» ذکر شود. در ارجاعات بعدی، همان واژه فنی اصیل به کار رود.

‎README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# کتاب کار با میکروپایتون در رسپبری‌پای پیکو
2+
### Get Started with MicroPython on Raspberry Pi Pico
3+
4+
**نویسنده / پدیدآور:** گرث هالفاکری (Gareth Halfacree) و بن اورارد (Ben Everard)
5+
**وضعیت:** 🟡 در انتظار شروع ترجمه و بازتفسیر مفهومی (Backlog - Ready for Contributors)
6+
**تعداد صفحات مرجع:** 139 صفحه
7+
**مخزن هاب و پورتال اصلی:** [Book Hub](https://github.com/bit-orbit/book) • [مشاهده پورتال آنلاین](https://wiregeek.ir/book/)
8+
9+
---
10+
11+
## ۱. درباره این کتاب
12+
راهنمای شروع برنامه‌نویسی میکروکنترلر Raspberry Pi Pico با استفاده از مفسر بهینه MicroPython؛ کنترل پایه‌ها (GPIO)، اتصال قطعات الکترونیکی، حسگرها، نمایشگرها و رابط PIO.
13+
14+
---
15+
16+
## ۲. راهنمای مترجمان و هوش‌های مصنوعی (AI Agents)
17+
این پروژه بر مبنای **تفسیر مفهومی و عمیق مهندسی (Developer Persian)** توسعه می‌یابد:
18+
- لطفاً قبل از شروع به ترجمه هر بخش، فایل‌های [`AGENTS.md`](./AGENTS.md) و [`todo.md`](./todo.md) را به دقت مطالعه فرمایید.
19+
- از ترجمه‌های ماشینی و تحت‌اللفظی واژگان صنعتی (مانند معادل‌سازی Scale به مقیاس یا Deploy به استقرار) پرهیز کنید.
20+
- تمامی فازهای اجرایی در فایل [`todo.md`](./todo.md) مشخص شده‌اند.
21+
- **الزام قطعی:** فاز پایانی هر پروژه همواره باید **فاز بازبینی و تضمین کیفیت نهایی (Review Phase)** باشد.
22+
23+
---
24+
25+
## ۳. نحوه کامپایل PDF با Typst
26+
برای تولید خروجی PDF کتاب با صفحه‌آرایی استاندارد:
27+
```bash
28+
typst compile book.typ
29+
```

‎book.typ‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
#set document(title: "کتاب کار با میکروپایتون در رسپبری‌پای پیکو", author: "گرث هالفاکری (Gareth Halfacree) و بن اورارد (Ben Everard)")
2+
#set text(font: "Vazirmatn", lang: "fa", dir: rtl, size: 11pt)
3+
#set page(paper: "a4", margin: (x: 2.5cm, y: 3cm))
4+
#set par(justify: true, leading: 0.9em)
5+
6+
#align(center + horizon)[
7+
#text(size: 26pt, weight: "bold")[ کتاب کار با میکروپایتون در رسپبری‌پای پیکو ]
8+
9+
#v(1cm)
10+
#text(size: 16pt, style: "italic")[ Get Started with MicroPython on Raspberry Pi Pico ]
11+
12+
#v(1.5cm)
13+
#text(size: 13pt)[ *نویسنده:* گرث هالفاکری (Gareth Halfacree) و بن اورارد (Ben Everard) ]
14+
15+
#v(0.5cm)
16+
#text(size: 12pt, fill: rgb("#64748b"))[ پورتال کتاب‌های آزاد مهندسی • Bit-Orbit ]
17+
]
18+
19+
#pagebreak()
20+
21+
#outline(title: "فهرست مطالب", indent: 1.5em)
22+
23+
#pagebreak()
24+
25+
= مقدمه
26+
این کتاب در مرحله آماده‌سازی و ترجمه قرار دارد. برای اطلاعات بیشتر و مشارکت به مخزن گیت‌هاب پروژه مراجعه نمایید:
27+
https://github.com/bit-orbit/Halfacree-G-Raspberry-Pi-Pico-MicroPython

‎todo.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# برنامه‌ریزی جامع ترجمه، تفسیر و تولید کتاب PDF: کتاب کار با میکروپایتون در رسپبری‌پای پیکو
2+
3+
**کتاب مبنا:** *Get Started with MicroPython on Raspberry Pi Pico*
4+
**نویسنده / مولف:** گرث هالفاکری (Gareth Halfacree) و بن اورارد (Ben Everard)
5+
**وضعیت:** 🟡 در انتظار شروع ترجمه (Backlog)
6+
**هدف نهایی:** ارائه ترجمه تفسیری، روان و کاملاً بومی‌سازی‌شده به همراه دیاگرام‌ها، نمونه کدها، تفسیر سناریوهای عملیاتی و تولید یک فایل **PDF کامل، نفیس و استاندارد با کیفیت چاپ با موتور Typst**.
7+
8+
---
9+
10+
## ۱. استانداردهای نگارش و ترجمه تفسیری
11+
1. **رویکرد تفسیری (Conceptual & Interpretive):** پرهیز از ترجمه ماشینی یا تحت‌اللفظی؛ انتقال کامل منطق فنی و معماری.
12+
2. **ادبیات مهندسی (Developer Persian):** دست‌نخورده باقی ماندن اصطلاحات استاندارد صنعتی و برنامه‌نویسی.
13+
3. **صفحه‌آرایی مدرن Typst:** خروجی چاپی با قلم زیبای وزیرمتن، باکس‌های نکته، هشدار و کدهای تمیز.
14+
15+
---
16+
17+
## ۲. فازبندی اجرایی پروژه
18+
19+
- [ ] **فاز ۰: راه‌اندازی تمپلیت و تایپوگرافی Typst**
20+
- [ ] آماده‌سازی `book.typ` و پیکربندی قلم وزیرمتن
21+
- [ ] تنظیم هدر، فوتر، شماره‌گذاری صفحات و استایل کدهای منبع
22+
23+
- [ ] **فاز 1: فصل ۱ - آشنایی با سخت‌افزار میکروکنترلر Raspberry Pi Pico**
24+
- [ ] استخراج سرفصل‌ها و مفاهیم بنیادین فصل ۱
25+
- [ ] نگارش و بازتفسیر مفهومی متن به فارسی مهندسی (Developer Persian)
26+
- [ ] استخراج و جای‌گذاری دیاگرام‌ها و فرمول‌ها در Typst
27+
- [ ] کامپایل و اعتبارسنجی اولیه فصل
28+
- [ ] **فاز 2: فصل ۲ - شروع برنامه‌نویسی سخت‌افزار با MicroPython**
29+
- [ ] استخراج سرفصل‌ها و مفاهیم بنیادین فصل ۲
30+
- [ ] نگارش و بازتفسیر مفهومی متن به فارسی مهندسی (Developer Persian)
31+
- [ ] استخراج و جای‌گذاری دیاگرام‌ها و فرمول‌ها در Typst
32+
- [ ] کامپایل و اعتبارسنجی اولیه فصل
33+
- [ ] **فاز 3: فصل ۳ - رایانش فیزیکی و کنترل پایه‌های GPIO**
34+
- [ ] استخراج سرفصل‌ها و مفاهیم بنیادین فصل ۳
35+
- [ ] نگارش و بازتفسیر مفهومی متن به فارسی مهندسی (Developer Persian)
36+
- [ ] استخراج و جای‌گذاری دیاگرام‌ها و فرمول‌ها در Typst
37+
- [ ] کامپایل و اعتبارسنجی اولیه فصل
38+
- [ ] **فاز 4: فصل ۴ - تعامل با کلیدها و کنترلرهای ورودی**
39+
- [ ] استخراج سرفصل‌ها و مفاهیم بنیادین فصل ۴
40+
- [ ] نگارش و بازتفسیر مفهومی متن به فارسی مهندسی (Developer Persian)
41+
- [ ] استخراج و جای‌گذاری دیاگرام‌ها و فرمول‌ها در Typst
42+
- [ ] کامپایل و اعتبارسنجی اولیه فصل
43+
- [ ] **فاز 5: فصل ۵ - مبدل آنالوگ به دیجیتال (ADC) و خواندن حسگرها**
44+
- [ ] استخراج سرفصل‌ها و مفاهیم بنیادین فصل ۵
45+
- [ ] نگارش و بازتفسیر مفهومی متن به فارسی مهندسی (Developer Persian)
46+
- [ ] استخراج و جای‌گذاری دیاگرام‌ها و فرمول‌ها در Typst
47+
- [ ] کامپایل و اعتبارسنجی اولیه فصل
48+
- [ ] **فاز 6: فصل ۶ - پروتکل‌های ارتباطی I2C و SPI و اتصال نمایشگرها**
49+
- [ ] استخراج سرفصل‌ها و مفاهیم بنیادین فصل ۶
50+
- [ ] نگارش و بازتفسیر مفهومی متن به فارسی مهندسی (Developer Persian)
51+
- [ ] استخراج و جای‌گذاری دیاگرام‌ها و فرمول‌ها در Typst
52+
- [ ] کامپایل و اعتبارسنجی اولیه فصل
53+
- [ ] **فاز 7: فصل ۷ - ورودی/خروجی برنامه‌پذیر پیشرفته (PIO)**
54+
- [ ] استخراج سرفصل‌ها و مفاهیم بنیادین فصل ۷
55+
- [ ] نگارش و بازتفسیر مفهومی متن به فارسی مهندسی (Developer Persian)
56+
- [ ] استخراج و جای‌گذاری دیاگرام‌ها و فرمول‌ها در Typst
57+
- [ ] کامپایل و اعتبارسنجی اولیه فصل
58+
59+
- [ ] **فاز 8: بازبینی و تضمین کیفیت نهایی (Review Phase) [الزامی]**
60+
- [ ] بررسی اصطلاحات با grep و اطمینان از عدم وجود ترجمه‌های تحت‌اللفظی ممنوعه
61+
- [ ] بازخوانی روان‌شناختی متن فارسی و انطباق کامل با روح متن انگلیسی
62+
- [ ] کامپایل نهایی پروژه با `typst compile book.typ` بدون هیچ خطا و اخطار
63+
- [ ] تولید نسخه انتشار (Release) و درج لینک در پورتال اصلی کتاب‌ها

0 commit comments

Comments
 (0)