مرجع سريع: إنشاء ملفات .po والترجمة

يوفر هذا المرجع السريع الخطوات الأساسية لإنشاء ملفات الترجمة .po وترجمة وثائق منصة نظام التشغيل العربي. استخدموه جنباً إلى جنب مع أدلة Translator Setup Guide و Translation Workflow الشاملة.

قائمة المتطلبات المسبقة

البرامج المطلوبة:

# Check if you have these installed:
python3 --version    # Python 3.8+
git --version        # Git 2.20+
# Optional but recommended:
poedit --version     # Poedit for GUI translation

الإعداد المطلوب:

✓ GitHub account with repository access
✓ Local repository clone
✓ Python virtual environment configured
✓ Sphinx and dependencies installed

الخطوة 1: إعداد البيئة (5 دقائق)

استنساخ وتحضير:

# Clone repository (replace YOUR-USERNAME)
git clone https://github.com/YOUR-USERNAME/documentation
cd documentation/docs

# Create and activate virtual environment
python3 -m venv sphinx-env
source sphinx-env/bin/activate  # Linux/macOS
# sphinx-env\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

# Verify Sphinx installation
sphinx-build --version

الخطوة 2: إنشاء ملفات الترجمة (دقيقتان)

استخراج النصوص القابلة للترجمة:

# Extract all translatable messages to .pot files
make gettext

# Alternative command:
# sphinx-build -M gettext source build/gettext

إنشاء/تحديث ملفات .po العربية:

# Generate Arabic translation files
sphinx-intl update -p build/gettext/gettext -l ar

# This creates/updates files in: locales/ar/LC_MESSAGES/

تحقق من إنشاء الملفات:

# Check generated files
find locales/ar/LC_MESSAGES -name "*.po" | head -10

# Should show files like:
# locales/ar/LC_MESSAGES/index.po
# locales/ar/LC_MESSAGES/user-guide/index.po
# locales/ar/LC_MESSAGES/developer-guide/index.po

الخطوة 3: عملية الترجمة

نظرة عامة على هيكل الملفات:

locales/ar/LC_MESSAGES/
├── index.po                    # Main page (START HERE)
├── user-guide/
│   ├── index.po               # User guide main
│   └── tools/
│       ├── cp1256-explorer.po
│       ├── utf8-visualizer.po
│       └── [other tools].po
├── developer-guide/
│   ├── index.po
│   └── translation/
│       ├── index.po
│       └── [translation docs].po
└── educator-guide/
    └── [educator files].po

طرق الترجمة:

الطريقة 1: Poedit (موصى بها)

1. Launch Poedit
2. File → Open → Select .po file
3. Translate strings one by one:
   - English source → Arabic translation
4. Save frequently (Ctrl+S)
5. File → Compile MO when done

الطريقة 2: محرر النصوص

# Edit .po files directly
#: source/index.rst:2
msgid "Documentation"
msgstr "الوثائق"

#: source/index.rst:4
msgid "Welcome to our platform"
msgstr "مرحباً بكم في منصتنا"

الطريقة 3: أدوات الويب

1. Upload .po file to Weblate/Crowdin
2. Translate online
3. Download completed .po file
4. Replace local file

ترتيب أولوية الترجمة:

Recommended sequence:
1. index.po                     # Main page
2. user-guide/index.po          # User guide overview
3. user-guide/tools/index.po    # Tools overview
4. developer-guide/index.po     # Developer guide
5. Individual tool files        # Specific tools
6. Advanced sections            # Reference materials

الخطوة 4: البناء والاختبار (دقيقتان)

بناء الوثائق العربية:

# Build Arabic version
make html-ar

# Alternative:
# sphinx-build -b html -D language=ar source build/html-ar

تحقق من الترجمة:

# Check build success
ls build/html-ar/

# Open in browser
open build/html-ar/index.html      # macOS
# xdg-open build/html-ar/index.html  # Linux
# start build/html-ar/index.html     # Windows

فحص الجودة:

Visual verification:
✓ Arabic text displays correctly (RTL)
✓ No English text in Arabic version
✓ Navigation works properly
✓ Fonts render correctly
✓ No layout issues

الخطوة 5: الحفظ والمشاركة

حفظ عملكم:

# Create feature branch
git checkout -b arabic-translation-SECTION

# Add translated files
git add locales/ar/LC_MESSAGES/

# Commit with descriptive message
git commit -m "Add Arabic translation for [section name]

- Translate main headings and content
- Follow Arabic style guide
- Build tested successfully"

# Push to your fork
git push origin arabic-translation-SECTION

مرجع الأوامر الشائعة

الأوامر الأساسية:

المهمة	الأمر
إنشاء ملفات .po	make gettext && sphinx-intl update -p build/gettext/gettext -l ar
بناء الوثائق العربية	make html-ar
فحص إحصائيات الترجمة	msgfmt --statistics file.po
Find untranslated	grep -l 'msgstr ""' locales/ar/LC_MESSAGES/*.po
Clean build	make clean

File Operations:

المهمة	الأمر
List all .po files	find locales/ar/LC_MESSAGES -name "*.po"
Count translations	find locales/ar/LC_MESSAGES -name "*.po" -exec msgfmt --statistics {} \;
Backup translations	cp -r locales/ar backup-$(date +%Y%m%d)

Troubleshooting Quick Fixes

Common Issues:

Problem	Cause	Solution
"sphinx-build not found"	Virtual environment not active	source sphinx-env/bin/activate
"No .po files generated"	gettext step skipped	make gettext first
"Arabic text shows as boxes"	Missing Arabic fonts	Install fonts: apt install fonts-noto
"Build warnings"	Untranslated strings	Continue translating or ignore
"RTL layout broken"	CSS/theme issue	Check browser Arabic support

Emergency Recovery:

# Reset environment
rm -rf sphinx-env
python3 -m venv sphinx-env
source sphinx-env/bin/activate
pip install -r requirements.txt

# Regenerate .po files
make gettext
sphinx-intl update -p build/gettext/gettext -l ar

Translation Statistics and Progress

Check Your Progress:

# Overall statistics
find locales/ar/LC_MESSAGES -name "*.po" -exec msgfmt --statistics {} \; | \
awk '{total+=$1; translated+=$4} END {print "Progress: " translated"/"total" ("int(translated/total*100)"%)"}'

# Per-file progress
for file in locales/ar/LC_MESSAGES/*.po; do
    echo "=== $(basename $file) ==="
    msgfmt --statistics "$file"
done

Translation Priorities:

High Priority (User-facing):
□ index.po                     # Main landing page
□ user-guide/index.po          # Getting started
□ user-guide/tools/index.po    # Tools overview

Medium Priority (Educational):
□ user-guide/tools/*.po        # Individual tools
□ developer-guide/index.po     # Developer overview

Low Priority (Reference):
□ developer-guide/api/*.po     # API documentation
□ reference/*.po               # Technical reference

Quick Start Workflow Summary

Complete Workflow (15 minutes):

# 1. Setup (once)
git clone https://github.com/YOUR-USERNAME/documentation
cd documentation/docs
python3 -m venv sphinx-env
source sphinx-env/bin/activate
pip install -r requirements.txt

# 2. Generate files (each update)
make gettext
sphinx-intl update -p build/gettext/gettext -l ar

# 3. Translate (ongoing)
poedit locales/ar/LC_MESSAGES/index.po
# OR edit directly with text editor

# 4. Test
make html-ar
open build/html-ar/index.html

# 5. Commit
git add locales/ar/LC_MESSAGES/
git commit -m "Add Arabic translations"
git push origin your-branch

Next Steps:

1. Review Arabic Style Guide for translation standards

2. Join translator community channels

3. Request assignment for specific documentation sections

4. Follow Translation Quality Assurance process for review

Success Metrics:

• Week 1: Complete environment setup, translate 1-2 small files

• Week 2: Complete major index page translations

• Month 1: Significant contribution to user-facing documentation

• Ongoing: Regular contributions, help onboard new translators

This quick reference covers the essential workflow. For detailed explanations, troubleshooting, and best practices, refer to the comprehensive guides in this section.