AdventureBrew Translator

כלי CLI חזק לתרגום עמודות CSV באמצעות Google Translate. נבנה עם Bun לביצועים מהירים וכולל תכונות כמו מעקב התקדמות, יכולת המשך מנקודת עצירה, ועיכובים הניתנים להגדרה כדי להתמודד עם הגבלות קצב.

English README

תכונות

• 🌐 תרגום כל עמודה ב-CSV באמצעות Google Translate
• 🔄 היפוך כל התווים בעמודת CSV
• 📊 פס התקדמות בזמן אמת עם זמן משוער לסיום
• 💾 שמירת התקדמות אוטומטית ויכולת להמשיך מנקודת עצירה
• ⚙️ עיכוב הניתן להגדרה בין בקשות כדי להימנע מהגבלות קצב
• 🔄 לוגיקת ניסיון חוזר עם Exponential backoff למקרי הגבלות קצב
• 🛡️ כיבוי חלק (Ctrl+C) עם שמירת התקדמות
• 🎯 תמיכה במספר צמדי שפות
• 📝 תמיכה ב-UTF-8 BOM לטיפול נכון בטקסט עברי/RTL

התקנה

התקנה גלובלית (מומלץ)

npm install -g adventurebrew-translator

לאחר ההתקנה, השתמש בפקודה advheb-trns:

advheb-trns translate --file data.csv --column text

שימוש עם npx (ללא התקנה)

npx adventurebrew-translator translate --file data.csv --column text

לפיתוח

שכפל את המאגר והתקן תלויות:

git clone https://github.com/yhaggai/adventurebrew-translator.git
cd adventurebrew-translator
bun install

שימוש

פקודת תרגום

שימוש בסיסי:

advheb-trns translate --file data.csv --column text

או עם npx:

npx adventurebrew-translator translate --file data.csv --column text

פקודת היפוך

היפוך כל התווים בעמודת CSV:

advheb-trns reverse --file data.csv --column text

או עם npx:

npx adventurebrew-translator reverse --file data.csv --column text

אפשרויות CLI

אפשרויות פקודת תרגום

advheb-trns translate [options]

אפשרויות:
  --file, -f         נתיב לקובץ ה-CSV (חובה)
  --column, -c       שם העמודה לתרגום (חובה)
  --delay, -d        עיכוב בין תרגומים במילישניות (ברירת מחדל: 1000)
  --output, -o       נתיב לקובץ פלט (ברירת מחדל: החלפת קובץ הקלט)
  --source-lang, -s  קוד שפת מקור (ברירת מחדל: "en")
  --target-lang, -t  קוד שפת יעד (ברירת מחדל: "he")
  --resume, -r       המשך מהתקדמות קודמת אם קיימת (ברירת מחדל: true)
  --help, -h         הצג עזרה
  --version, -v      הצג גרסה

אפשרויות פקודת היפוך

advheb-trns reverse [options]

אפשרויות:
  --file, -f         נתיב לקובץ ה-CSV (חובה)
  --column, -c       שם העמודה להיפוך (חובה)
  --output, -o       נתיב לקובץ פלט (ברירת מחדל: החלפת קובץ הקלט)
  --help, -h         הצג עזרה
  --version, -v      הצג גרסה

דוגמאות

דוגמאות תרגום

תרגום אנגלית לעברית (ברירת מחדל):

advheb-trns translate --file data.csv --column text

תרגום עם עיכוב מותאם אישית (1.5 שניות):

advheb-trns translate --file data.csv --column description --delay 1500

תרגום לקובץ פלט שונה:

advheb-trns translate --file input.csv --column text --output output.csv

תרגום ספרדית לאנגלית:

advheb-trns translate --file data.csv --column text --source-lang es --target-lang en

התחלה מחדש (התעלם מהתקדמות קיימת):

advheb-trns translate --file data.csv --column text --resume false

דוגמאות היפוך

היפוך תווים בעמודה:

advheb-trns reverse --file data.csv --column text

היפוך ושמירה לקובץ שונה:

advheb-trns reverse --file data.csv --column text --output reversed.csv

איך זה עובד

1. קריאת CSV: קורא את קובץ ה-CSV ומאמת שהעמודה קיימת
2. בדיקת התקדמות: בודק אם קיימת התקדמות ומציע להמשיך
3. תרגום: מתרגם כל שורה אחת בכל פעם עם עיכובים הניתנים להגדרה
4. שמירת התקדמות: שומר התקדמות אוטומטית אחרי כל תרגום
5. פלט: מוסיף עמודה חדשה בשם קוד שפת היעד (למשל he) עם התרגומים
6. המשך: אם נקטע, הרץ את אותה הפקודה כדי להמשיך מהמקום שבו עצרת

טיפול בהגבלות קצב

Google Translate עשוי להגביל את קצב הבקשות. כלי זה מטפל בכך על ידי:

• הוספת עיכובים הניתנים להגדרה בין בקשות (ברירת מחדל: 1000ms)
• לוגיקת ניסיון חוזר עם Exponential backoff (3 ניסיונות עם הכפלה פי 2)
• שמירת התקדמות אוטומטית כאשר מגיעים להגבלת קצב
• הוראות ברורות להמתין ולהמשיך

אם הגעת להגבלת קצב:

1. המתן מספר דקות
2. הרץ את אותה הפקודה שוב
3. הכלי ימשיך אוטומטית מהמקום שבו נעצר

קבצי התקדמות

ההתקדמות נשמרת ב-.translation-progress-{filename}-{column}.json בתיקייה הנוכחית. קבצים אלה מנוקים אוטומטית כאשר התרגום מסתיים בהצלחה.

דוגמה לפלט

קובץ קלט:

id,text,category
1,Hello World,greeting
2,Good morning,greeting

קובץ פלט:

id,text,category,he
1,Hello World,greeting,שלום עולם
2,Good morning,greeting,בוקר טוב

הערה: עמודת התרגום נקראת על שם קוד שפת היעד (למשל he לעברית, en לאנגלית).

דרישות מערכת

• Bun גרסה 1.0 ומעלה

רישיון

MIT

תרומה לפרויקט

תרומות מתקבלות בברכה! אתם מוזמנים לפתוח Issues או להגיש Pull Requests.