# استراتژی چندزبانه IFNEX (i18n)

> **سند مطالعاتی** — برای فاز ۳.۵ و فاز ۵  
> **آخرین بروزرسانی:** 2026-08-29

---

## 🎯 هدف

پشتیبانی کامل از چند زبان در فرانت‌اند وردپرس و بک‌اند لاراول، با:
- زبان فارسی (پیش‌فرض، RTL)
- زبان انگلیسی (LTR)
- آماده برای افزودن زبان‌های دیگر در آینده (عربی، چینی، و...)

---

## 🏗️ معماری فعلی

### وردپرس
- **پلاگین:** Polylang (نصب‌شده)
- **قالب IFNEX:** فقط فارسی
- **پلاگین IFNEX Bridge:** فقط فارسی (hard-coded)
- **زبان‌های فعال:** فارسی (پیش‌فرض) + انگلیسی

### لاراول
- **APP_LOCALE:** fa
- **APP_FALLBACK_LOCALE:** fa
- **فایل‌های زبان:** موجود در `lang/fa/` و `lang/en/`
- **تاریخ:** morilog/jalali (فارسی) + Carbon (انگلیسی)

---

## 📋 برنامه پیاده‌سازی فاز ۳.۵

### ۱. وردپرس — استخراج رشته‌ها

#### ۱.۱ فایل‌های PHP پلاگین
تمام رشته‌های hard-coded فارسی باید با توابع ترجمه جایگزین شوند:

```php
// ❌ قبل:
return '<p class="ifnex-error">برای مشاهده پروفایل، باید وارد شوید.</p>';

// ✅ بعد:
return '<p class="ifnex-error">' . __('برای مشاهده پروفایل، باید وارد شوید.', 'ifnex-bridge') . '</p>';
```

#### فایل‌های موردنیاز برای اصلاح:
- [ ] `ifnex-bridge.php`
- [ ] `includes/api-client.php`
- [ ] `includes/user-bridge.php`
- [ ] `includes/shortcodes.php` (بزرگ‌ترین فایل)
- [ ] `includes/tracking-form.php`

#### ۱.۲ فایل‌های JS
استفاده از `wp_localize_script` برای ارسال ترجمه‌ها:

```php
// در PHP:
wp_localize_script('ifnex-order-form-js', 'ifnex_i18n', [
    'loading' => __('در حال بارگذاری...', 'ifnex-bridge'),
    'error_required' => __('لطفاً همه فیلدها را تکمیل کنید.', 'ifnex-bridge'),
    'select_country' => __('انتخاب کشور...', 'ifnex-bridge'),
    // ...
]);
```

```javascript
// در JS:
$('#ifnex-from-country').empty().append(
    '<option value="">' + ifnex_i18n.select_country + '</option>'
);
```

### ۲. ساخت فایل‌های ترجمه

#### ۲.۱ ساختار پوشه
```
ifnex-bridge/
└── languages/
    ├── ifnex-bridge-fa_IR.po
    ├── ifnex-bridge-fa_IR.mo
    ├── ifnex-bridge-en_US.po
    └── ifnex-bridge-en_US.mo
```

#### ۲.۲ ابزارها
- **Poedit** — برای ویرایش فایل‌های `.po`
- **WP-CLI** — برای استخراج خودکار: `wp i18n make-pot ifnex-bridge/ languages/ifnex-bridge.pot`

### ۳. اصلاح CSS برای RTL/LTR

```css
/* پیش‌فرض RTL (فارسی) */
.ifnex-form-grid {
    direction: rtl;
}

/* LTR برای انگلیسی */
html[lang="en"] .ifnex-form-grid {
    direction: ltr;
}
```

### ۴. اصلاح قالب IFNEX

- [ ] استخراج رشته‌های قالب
- [ ] افزودن فایل‌های ترجمه قالب
- [ ] اصلاح CSS برای پشتیبانی RTL/LTR

### ۵. لاراول

#### ۵.۱ فایل‌های زبان
```
lang/
├── fa/
│   ├── messages.php
│   ├── validation.php
│   └── ...
└── en/
    ├── messages.php
    ├── validation.php
    └── ...
```

#### ۵.۲ API پاسخ‌ها
```php
// در Controller:
return response()->json([
    'message' => __('messages.order_created'),
], 201);
```

#### ۵.۳ هدر Accept-Language
- اضافه‌کردن middleware برای تشخیص زبان از هدر `Accept-Language`
- تنظیم `App::setLocale()` بر اساس هدر

```php
// middleware:
public function handle($request, Closure $next)
{
    $locale = $request->header('Accept-Language', 'fa');
    App::setLocale(substr($locale, 0, 2));
    return $next($request);
}
```

### ۶. وردپرس Polylang Integration

#### ۶.۱ ثبت strings در Polylang
```php
// در functions.php قالب:
pll_register_string('ifnex-bridge', 'برای مشاهده پروفایل، باید وارد شوید.');
```

#### ۶.۲ استفاده در شورت‌کدها
```php
$login_prompt = pll__('برای مشاهده پروفایل، باید وارد شوید.');
```

#### ۶.۳ ترجمه صفحات
- ساخت نسخه انگلیسی برای صفحات: `/en/my-account/`, `/en/wallet/`, و...
- اتصال صفحات فارسی و انگلیسی در Polylang

---

## 🎯 معیارهای پذیرش (Acceptance Criteria)

### فاز ۳.۵:
- [ ] تمام رشته‌های پلاگین IFNEX Bridge قابل ترجمه هستند
- [ ] فایل‌های `.po/.mo` برای fa_IR و en_US موجود است
- [ ] سایت در زبان انگلیسی به‌درستی نمایش داده می‌شود
- [ ] فرم سفارش در زبان انگلیسی کار می‌کند
- [ ] پیام‌های خطا در زبان انگلیسی نمایش داده می‌شوند
- [ ] CSS در هر دو حالت RTL و LTR درست است
- [ ] API لاراول بر اساس هدر `Accept-Language` پاسخ می‌دهد

### فاز ۵ (آینده):
- [ ] افزودن زبان عربی
- [ ] افزودن زبان چینی
- [ ] ترجمه خودکار با API (Google Translate)
- [ ] انتخاب زبان در فرم سفارش

---

## 📊 برآورد زمان

| بخش | زمان تخمینی |
|------|-------------|
| استخراج رشته‌ها (PHP) | ۱ روز |
| استخراج رشته‌ها (JS) | نصف روز |
| ساخت فایل‌های ترجمه | ۱ روز |
| اصلاح CSS RTL/LTR | نصف روز |
| تست و رفع اشکال | ۱ روز |
| **مجموع** | **۴ روز** |

---

## ⚠️ نکات مهم

1. **هماهنگی با کارفرما:** قبل از شروع، باید تأیید بشه که ترجمه انگلیسی رو کارفرما تأمین می‌کنه یا خودمون انجام می‌دیم.
2. **تاریخ:** برای زبان انگلیسی، تاریخ میلادی نمایش داده بشه (نه شمسی).
3. **اعداد:** برای زبان انگلیسی، اعداد لاتین نمایش داده بشه.
4. **جهت:** RTL برای فارسی/عربی، LTR برای انگلیسی/چینی.
5. **فونت:** برای زبان انگلیسی از فونت مناسب (مثل Inter یا Roboto) استفاده بشه.

---

## 📚 منابع

- [Polylang Documentation](https://polylang.pro/doc/)
- [WordPress Internationalization](https://developer.wordpress.org/plugins/internationalization/)
- [Laravel Localization](https://laravel.com/docs/localization)
- [WP-CLI i18n](https://developer.wordpress.org/cli/commands/i18n/)

---

> 2026 VernaSoft Group. Internal use only.