پرش به محتوای اصلی
فهرست مطالب

فصل ۵ از ۱۰

بومی‌سازی (Localization)

۶ دقیقه مطالعهبه‌روزرسانی

درست حساب کردن ریاضیات تقویم نیمی از راهه؛ نیمهٔ دیگه‌ش نمایش درست متنه: ارقام فارسی، کدهای یونیکد حروف، جهت نوشتار (RTL) و نام ماه‌ها.

شناسه‌های زبان و تقویم (Locale Identifiers)

پیوند به بخش شناسه‌های زبان و تقویم (Locale Identifiers)
شناسه (Locale) کاربرد و معنی
fa-IR فارسی (ایران). در استاندارد CLDR تقویم پیش‌فرض برای زبان fa تقویم persian و ارقام پیش‌فرض، اعداد فارسی (arabext) است
fa-AF دری (افغانستان): تقویم شمسی با نام‌های برجی ماه‌ها (حمل، ثور، جوزا و…)
ps-AF پشتو (افغانستان): تقویم شمسی با نام‌های پشتوی ماه‌ها
en-u-ca-persian زبان انگلیسی با تقویم شمسی (مثلا Farvardin 1, 1404 AP)
fa-IR-u-nu-latn زبان فارسی و تقویم شمسی، اما با ارقام انگلیسی (0-9)
fa-IR-u-ca-gregory زبان فارسی با تقویم میلادی (مثلا ۲۱ مارس ۲۰۲۵)

پسوندهای -u-ca-… (تعیین نوع تقویم) و -u-nu-… (تعیین نوع ارقام) بخشی از استاندارد افزونه‌های لوکیل یونیکد (BCP 47) هستن و توی Intl جاوااسکریپت، کتابخونهٔ ICU (در C/C++‎ و جاوا)، افزونهٔ intl در PHP و اکثر پلتفرم‌های مدرن کار می‌کنن.

خروجی‌های آمادهٔ پلتفرم (ICU 78 / CLDR 48)

پیوند به بخش خروجی‌های آمادهٔ پلتفرم (ICU 78 / CLDR 48)
تنظیمات (Intl.DateTimeFormat با timeZone: 'Asia/Tehran') خروجی برای تاریخ 2025-03-21
fa-IR، {} ۱۴۰۴/۱/۱
fa-IR، { year: 'numeric', month: '2-digit', day: '2-digit' } ۱۴۰۴/۰۱/۰۱
fa-IR، { dateStyle: 'long' } ۱ فروردین ۱۴۰۴
fa-IR، { weekday: 'long', day: 'numeric', month: 'long' } جمعه ۱ فروردین
fa-IR، { dateStyle: 'full' } ۱۴۰۴ فروردین ۱, جمعه ⚠️
fa-IR-u-nu-latn، { dateStyle: 'short' } 1404/1/1
en-u-ca-persian، { dateStyle: 'full' } Friday, Farvardin 1, 1404 AP
fa-AF، { dateStyle: 'full' } ۱۴۰۴ حمل ۱, جمعه

⚠️ نکتهٔ مهم دربارهٔ dateStyle: 'full': الگوی پیش‌فرض full در استاندارد CLDR برای زبان فارسی، ترتیب غیرطبیعی «۱۴۰۴ فروردین ۱, جمعه» (همراه با ویرگول انگلیسی!) تولید می‌کنه، در حالی که کاربر ایرانی انتظار داره عبارت «جمعه ۱ فروردین ۱۴۰۴» رو ببینه. برای داشتن این فرمت طبیعی، به جای dateStyle: 'full'، اجزای تاریخ رو با formatToParts بگیرید و کنار هم بذارید:

JavaScript
const parts = (d) => Object.fromEntries(new Intl.DateTimeFormat('fa-IR', {
  weekday: 'long', day: 'numeric', month: 'long', year: 'numeric', timeZone: 'Asia/Tehran',
}).formatToParts(d).map((p) => [p.type, p.value]))
const p = parts(new Date())
const text = `${p.weekday} ${p.day} ${p.month} ${p.year}`   // جمعه ۱ فروردین ۱۴۰۴

ارقام (فارسی، عربی و لاتین)

پیوند به بخش ارقام (فارسی، عربی و لاتین)
دسته شکل ارقام بازهٔ یونیکد کجا استفاده کنیم؟
فارسی (arabext) ۰ ۱ ۲ ۳ ۴ ۵ ۶ ۷ ۸ ۹ U+06F0 تا U+06F9 رابط کاربری و متن فارسی (ایران و افغانستان)
عربی (arab) ٠ ١ ٢ ٣ ٤ ٥ ٦ ٧ ٨ ٩ U+0660 تا U+0669 متن عربی؛ در متن فارسی استفاده نکنید
لاتین / انگلیسی (latn) 0 1 2 3 4 5 6 7 8 9 U+0030 تا U+0039 دیتابیس، API، کدها و رابط کاربری انگلیسی
  • ظاهر ارقام ۴، ۵ و ۶ در فارسی و عربی (۴۵۶ در برابر ٤٥٦) با هم فرق داره و دیدن ارقام عربی وسط فونت و متن فارسی توی ذوق می‌زنه.
  • دریافت ورودی از کاربر: هر سه نوع عدد رو قبول کنید و قبل از پاس دادن به توابعی مثل parseInt یا int()، همه رو به ارقام لاتین تبدیل کنید.
  • سال، عدد شمارشی نیست: اگر عدد سال رو به Formatter معمولی اعداد بدید (مثلا Intl.NumberFormat('fa-IR').format(1404))، خروجی رو به شکل «۱٬۴۰۴» (با جداکنندهٔ هزارگان!) برمی‌گردونه. برای جلوگیری از این مشکل، گزینهٔ useGrouping: false رو ست کنید یا از Formatter مخصوص تاریخ استفاده کنید.
  • در دیتابیس، API، لاگ‌ها و نام فایل‌ها: همیشه از ارقام لاتین (0-9) استفاده کنید.
JavaScript
const toAscii = (s) => s.replace(/[۰-۹]/g, (c) => c.charCodeAt(0) - 0x06F0).replace(/[٠-٩]/g, (c) => c.charCodeAt(0) - 0x0660)
const toPersian = (s) => String(s).replace(/\d/g, (c) => '۰۱۲۳۴۵۶۷۸۹'[c])

حروف «ی» و «ک» فارسی در برابر عربی

پیوند به بخش حروف «ی» و «ک» فارسی در برابر عربی

در استاندارد یونیکد، حروف فارسی ی (U+06CC) و ک (U+06A9) با حروف عربی ي (U+064A) و ك (U+0643) کدهای متفاوتی دارن. بعضی کیبوردهای غیراستاندارد یا سیستم‌های قدیمی حروف عربی تولید می‌کنن؛ ظاهرشون در خیلی از فونت‌ها شبیه همه، اما از نظر کامپیوتر دو رشتهٔ متنی کاملا متفاوت هستن (یعنی "دي" !== "دی").

  • در خروجی برنامه: همیشه از ی (U+06CC) و ک (U+06A9) فارسی استفاده کنید (تمام داده‌های این مخزن و استاندارد CLDR هم از همین کدها استفاده می‌کنن).
  • در ورودی کاربر و جست‌وجو: قبل از مقایسهٔ رشته‌ها یا پیدا کردن نام ماه، همیشه حروف عربی رو به معادل فارسی تبدیل (Normalize) کنید: ي ← ی، ى ← ی و ك ← ک.

توی کلمهٔ «سه‌شنبه»، بین «سه» و «شنبه» یک کاراکتر نیم‌فاصله (U+200C) قرار داره. بدون نیم‌فاصله، کلمه یا به شکل غلط به هم می‌چسبه («سهشنبه») یا با فاصلهٔ کامل نوشته می‌شه («سه شنبه»). در خروجی‌های برنامه همیشه «سه‌شنبه» رو با نیم‌فاصله بنویسید، اما موقع خواندن ورودی کاربر هر سه حالت (با نیم‌فاصله، با فاصله و چسبیده) رو قبول کنید.

راست‌به‌چپ (RTL) و متن‌های دوسویه (BiDi)

پیوند به بخش راست‌به‌چپ (RTL) و متن‌های دوسویه (BiDi)

متن فارسی از راست به چپ نوشته می‌شه، اما اعداد داخل اون از چپ به راست چیده می‌شن. وقتی تاریخی مثل «۱۴۰۴/۰۱/۰۱» به تنهایی نمایش داده بشه مشکلی نداره؛ اما وقتی همون تاریخ در کنار متنی با جهت مخالف قرار می‌گیره (مثلا تاریخ فارسی وسط یک جملهٔ انگلیسی، یا تاریخ 1404/01/01 با ارقام انگلیسی وسط جملهٔ فارسی)، الگوریتم دوسویهٔ یونیکد ممکنه جای سال و روز رو برعکس نشون بده!

  • در HTML: تاریخ‌ها رو داخل تگ <bdi>۱۴۰۴/۰۱/۰۱</bdi> یا <span dir="rtl">…</span> قرار بدید.
  • در متن ساده (Plain text): قبل از تاریخ کاراکتر ایزولهٔ U+2068 (First Strong Isolate) و بعد از اون U+2069 (Pop Directional Isolate) بذارید.
  • توی صفحات فارسی حتما ویژگی‌های dir="rtl" و lang="fa" رو روی تگ اصلی ست کنید و جدول تقویم رو هم راست‌به‌چپ بچینید (طوری که ستون «شنبه» در سمت راست جدول باشه).

نام ماه‌ها در زبان‌های مختلف

پیوند به بخش نام ماه‌ها در زبان‌های مختلف

فهرست کامل نام ماه‌ها و روزهای هفته به ۱۱ زبان (فارسی، دری، پشتو، کردی سورانی، انگلیسی، عربی، ترکی استانبولی، آذربایجانی، آلمانی، فرانسوی و روسی) همراه با فرم‌های کوتاه و مستقل در فایل data/locale-names.json قرار داره (که با اسکریپت tools/generate_locale_data.mjs از CLDR 48 استخراج شده است).

برای نوشتن نام ماه‌ها به انگلیسی، دیکته‌های مختلفی دیده می‌شه (مثل Farvardin/Farwardin، Mordad/Amordad، Dey/Dei یا Esfand/Isfand). اگر استاندارد خاصی در سازمانتون ندارید، از املای استاندارد CLDR استفاده کنید: Farvardin, Ordibehesht, Khordad, Tir, Mordad, Shahrivar, Mehr, Aban, Azar, Dey, Bahman, Esfand.

همچنین ماه پنجم رو گاهی «امرداد» (شکل کهن‌تر واژه) می‌نویسن، اما در تقویم رسمی، استاندارد CLDR و اکثر نرم‌افزارها از همون «مرداد» استفاده می‌شه.

پسوندها و نشانه‌های تقویم

پیوند به بخش پسوندها و نشانه‌های تقویم
زبان پسوند رایج مثال
فارسی ه‍.ش (هجری شمسی)، و گاهی «ش» ۱۴۰۴ ه‍.ش
انگلیسی AP (مخفف Anno Persico) یا SH (مخفف Solar Hijri) 1404 AP

نکتهٔ ریز تایپوگرافی: در عبارت «ه‍.ش»، بعد از حرف «ه» کاراکتر اتصال مجازی (ZWJ با کد U+200D) قرار می‌گیره تا حرف «ه» به شکل «ه‍» نمایش داده بشه (مطابق استاندارد CLDR).

در گفتار و نوشتار رسمی فارسی، استفاده از اعداد ترتیبی برای روزهای ماه هم خیلی رایجه («یکم فروردین» یا «اول فروردین»، «دوم»، «سوم» و…)، ولی قالب‌های استاندارد CLDR از همون اعداد ساده («۱ فروردین») استفاده می‌کنن.

  • رابط کاربری فارسی از fa-IR، ارقام فارسی، چیدمان راست‌به‌چپ (RTL) و شروع هفته از شنبه استفاده می‌کنه.
  • بخش دریافت ورودی، هر سه نوع ارقام فارسی، عربی و انگلیسی رو قبول می‌کنه و حروف ي/ك عربی رو به ی/ک فارسی تبدیل می‌کنه.
  • عدد سال بدون جداکنندهٔ هزارگان نمایش داده می‌شه (۱۴۰۴، نه ۱٬۴۰۴).
  • تاریخ‌ها در متن‌های دوسویه (فارسی + انگلیسی) با <bdi> یا کاراکترهای ایزولهٔ یونیکد محافظت شدن.
  • کلمهٔ «سه‌شنبه» با نیم‌فاصله نوشته شده و در تمام نام‌ها از ی (U+06CC) و ک (U+06A9) استاندارد فارسی استفاده شده است.