i18n

یک موتور بین‌المللی‌سازی مستقل از فریم‌ورک. طراحی‌اش آینه مسیریاب است: هسته‌ای کوچک (I18nCore) با یک singleton سراسری اختیاری (createI18n / useI18n) و بدون وابستگی به DOM، پس هرطور بخواهید آن را به رابط کاربری گره می‌زنید.

کجا به کار می‌آید: وقتی در یک برنامه ranui به تعویض زبان در زمان اجرا نیاز دارید. یک بار createI18n را صدا بزنید، سپس رشته‌ها را با useI18n().t(key, params) بخوانید و زبان را با setLocale عوض کنید. نه به فریم‌ورکی وابسته است و نه به DOM، پس در جاوااسکریپت ساده، در هر فریم‌ورکی و در SSR کار می‌کند.

این موتور با نقطه ورود مستقل خودش یعنی ranui/i18n عرضه می‌شود: وارد کردنش هیچ عنصر سفارشی‌ای ثبت نمی‌کند، پس صفحه‌ای که تنها به ترجمه نیاز دارد هرگز کتابخانه کامپوننت‌ها را با خود نمی‌کشد. همین خروجی‌ها از بسته سطح‌بالای ranui هم در دسترس‌اند.

شروع سریع

هنگام راه‌اندازی یک بار singleton را بسازید، بعد هرجا خواستید ترجمه کنید:

import { createI18n, useI18n } from 'ranui/i18n';

createI18n({
  // هر زبان یک واژه‌نامه تخت است — کلیدها عیناً جست‌وجو می‌شوند، نه تودرتو.
  messages: {
    en: { 'hero.title': 'Hi {name}', 'nav.home': 'Home' },
    zh: { 'hero.title': '你好 {name}', 'nav.home': '首页' },
  },
  fallbackLocale: 'en', // وقتی کلیدی در زبان فعال نباشد به کار می‌رود
  persist: true, // انتخاب را زیر کلید 'ran-locale' در localStorage به یاد می‌سپارد
  detectNavigator: true, // زبان آغازین را از ترجیح‌های زبانی مرورگر برمی‌دارد
});

const i18n = useI18n();

i18n.t('hero.title', { name: 'Ada' }); // → "Hi Ada"
i18n.setLocale('zh'); // ذخیره می‌کند و به مشترکان خبر می‌دهد
i18n.t('hero.title', { name: 'Ada' }); // → "你好 Ada"

t(key) نخست messages[activeLocale][key] را می‌جوید، سپس messages[fallbackLocale][key] را، و اگر هیچ‌کدام نبود خودِ key را برمی‌گرداند. جای‌های {param} درون رشته از آرگومان دوم پر می‌شوند. چون جست‌وجو یک دسترسی به نقشه تخت است، کلیدها رشته‌های عینی‌اند: 'hero.title' را یک کلید بنویسید، نه شیئی تودرتو مثل { hero: { title } }.

پارامترها (درج مقدار)

بله، پیام‌ها پارامتر زمان اجرا می‌گیرند. جای‌هایی به شکل {name} در رشته بگذارید و مقدارها را به‌عنوان آرگومان دوم به t() بدهید؛ هر {param} با مقدار متناظرش جایگزین می‌شود:

createI18n({
  messages: {
    en: {
      'cart.summary': '{count} items · ${total}',
      greeting: 'Welcome back, {user}!',
    },
    zh: {
      'cart.summary': '{count} 件商品 · ¥{total}',
      greeting: '欢迎回来，{user}！',
    },
  },
});

const i18n = useI18n();
i18n.t('cart.summary', { count: 3, total: 59.9 }); // → "3 items · $59.9"
i18n.t('greeting', { user: 'Ada' }); // → "Welcome back, Ada!"

جزئیات:

• نحو جای‌نگهدار {word} است (حرف، رقم، _). مقدارها می‌توانند رشته یا عدد باشند؛ عددها به متن تبدیل می‌شوند.
• جای‌نگهداری که کلید متناظر نداشته باشد دست‌نخورده می‌ماند ({oops} عیناً در خروجی می‌ماند)؛ این کار پارامتر جاافتاده را به چشم می‌آورد، به‌جای اینکه بی‌صدا خالی بماند.
• درج مقدار پس از بازگشت به زبان جایگزین اجرا می‌شود، پس همان پارامترها فرق نمی‌کند کدام زبان در نهایت رشته را حل کرده باشد.
• جمع‌بستن و قالب‌بندی عدد و تاریخ درون‌ساخت نیست؛ آن‌ها را با Intl.NumberFormat / Intl.PluralRules بسازید و رشته قالب‌بندی‌شده را به‌عنوان پارامتر بدهید.

نمایش عینی آکولاد

یک { یا } تنها، یا گروهی با فاصله مثل { color: red }، جای‌نگهدار نیست و دست‌نخورده رد می‌شود؛ پس CSS و JSON و تکه‌های کد درون یک پیام به‌طور پیش‌فرض در امان‌اند. تنها حالت مبهم یک {word} عینی است که می‌خواهید همان‌طور نشان داده شود. برای گریز از آن، آکولادها را دو برابر کنید (همان قراردادی که format! در Rust، str.format در پایتون و String.Format در دات‌نت دارند):

const i18n = useI18n(); // فرض بر این است که پیام‌های زیر ثبت شده‌اند

i18n.t('use {{ and }} for literal braces'); // → "use { and } for literal braces"
i18n.t('the {{count}} token'); // → "the {count} token"  (مقدار درج نمی‌شود)
i18n.t('{{{name}}}', { name: 'Ada' }); // → "{Ada}"  (مقدار درون آکولاد عینی)

در پیام	خروجی
{{	{
}}	}
{name}	پارامتر name، یا {name} اگر نباشد
{ name }	{ name } (فاصله دارد → جای‌نگهدار نیست)
{	{ (آکولاد تنها)

گریز در همان یک گذرِ چپ‌به‌راستِ درج مقدار انجام می‌شود و چه پارامتر بدهید و چه ندهید کار می‌کند، پس {{ و }} همیشه به‌معنای آکولاد عینی‌اند.

دو برابر کردن همان قرارداد format! در Rust، str.format در پایتون و String.Format در دات‌نت است، پس نیازی به کاراکتر گریز تازه نیست. اگر به دستور زبان واقعی جمع و جنس و عدد نیاز دارید، با Intl.* قالب‌بندی کنید و نتیجه را به‌عنوان پارامتر بدهید.

واکنش به تغییر زبان

onChange پس از هر setLocale فرستاده می‌شود؛ از آن برای بازکشیدن رشته‌هایی که پیش‌تر رسم کرده‌اید استفاده کنید:

const i18n = useI18n();

const unsubscribe = i18n.onChange((locale) => {
  document.documentElement.lang = locale;
  repaintStrings(); // فراخوانی‌های t() را دوباره اجرا کن
});

// بعدها، وقتی نما برچیده می‌شود
unsubscribe();

افزودن پیام‌ها به‌هنگام نیاز

واژه‌نامه یک زبان را هنگام نیاز بار کنید (مثلاً با جداسازی کد به تفکیک زبان) و آن را ادغام کنید:

const i18n = useI18n();

const { default: fr } = await import('./locales/fr.js');
i18n.addMessages('fr', fr); // با هر واژه‌نامه 'fr' موجود ادغام می‌شود
i18n.setLocale('fr');

بومی‌سازی متن کامپوننت‌ها

کامپوننت‌ها خودشان از این موتور نمی‌خوانند. این عمدی است: کامپوننتی که مستقیم از یک singleton سراسری بخواند، هر مصرف‌کننده‌ای را به یک نمونه و یک شیوه نام‌گذاری کلید گره می‌زند و کاری می‌کند صفحه‌ای که فقط یک دکمه وارد کرده، لایه ترجمه را هم با خود بیاورد. در عوض، هر رشته‌ای که کاربر می‌بیند یک ورودی است: یک اتریبیوت، یک ویژگی، یک گزینه، یا محتوای اسلات. پس بومی‌سازی ranui یعنی دادن خروجی t() به همان جایی که رشته پیش‌تر می‌رفت:

const i18n = useI18n(); // فرض بر این است که پیام‌های زیر ثبت شده‌اند

modal.setAttribute('title', i18n.t('dialog.deleteProject.title'));
themeSwitch.setAttribute('label-dark', i18n.t('theme.dark'));

بیشتر کامپوننت‌ها اصلاً متن از خود ندارند: متن از راه اسلات‌ها و اتریبیوت‌هایی می‌آید که خودتان می‌نویسید. تعداد انگشت‌شماری برای رشته‌ای که جای دیگری برای آمدن ندارد یک پیش‌فرض انگلیسی همراه دارند، که بیشترشان نام‌های دسترس‌پذیرند:

کامپوننت	انگلیسیِ درون‌ساخت	بازنویسی با
Modal.confirm / Modal.open	عنوان Confirm، دکمه‌های OK / Cancel	گزینه‌های title، okText، cancelText
Modal.info / .success / .warning / .error	عنوان‌های Info / Success / Warning / Error	گزینه title
<r-theme-switch>	aria-labelهای Theme، System theme، Light theme، Dark theme	label، label-system، label-light، label-dark
<r-voice-button>	aria-labelهای Start voice input / Stop voice input؛ راهنماهای Release to keep · slide up to cancel، Release to cancel	label، active-label، hold-hint، cancel-hint
<r-reasoning>	برچسب سربرگ Reasoning	label
<r-token-meter>	برچسب Context	label
<r-colorpicker>	aria-labelهای Choose color، Hue، Alpha opacity	label، hue-label، alpha-label

یک الگوی عملی این است که با هر تغییر زبان آن‌ها را از یک جا دوباره اعمال کنید، تا همان کد هم هنگام راه‌اندازی و هم پس از تعویض اجرا شود:

const i18n = useI18n();

const applyLabels = () => {
  document.querySelectorAll('r-voice-button').forEach((el) => {
    el.setAttribute('label', i18n.t('voice.start'));
    el.setAttribute('active-label', i18n.t('voice.stop'));
  });
};

applyLabels();
i18n.onChange(applyLabels);

یادتان باشد document.documentElement.lang را هم هم‌گام نگه دارید: مرورگر، صفحه‌خوان‌ها و گزینشگرهای :lang() به همان نگاه می‌کنند.

API

createI18n(config) singleton سراسری را می‌سازد و ثبت می‌کند (یک بار صدایش بزنید)؛ useI18n() آن را برمی‌گرداند، یا null اگر createI18n هنوز اجرا نشده باشد.

I18nConfig

میدان	نوع	پیش‌فرض	توضیح
messages	LocaleMessages	{}	locale → { key → string }. هر واژه‌نامه تخت است.
locale	string	زبان جایگزین	زبان آغازین (اگر انتخابی ذخیره شده باشد، آن اولویت دارد).
fallbackLocale	string	'en'	زبانی که وقتی کلیدی در زبان فعال نباشد سراغش می‌روند.
persist	boolean	false	زبان فعال را در localStorage نگه می‌دارد.
storageKey	string	'ran-locale'	کلید localStorage وقتی persist روشن است.
detectNavigator	boolean	false	زبان آغازین را از ترجیح‌های زبانی مرورگر برمی‌دارد. کل فهرست مرتب navigator.languages را می‌خواند، پس خواننده‌ای که برای انتخاب اولش واژه‌نامه نیست، به‌جای زبان جایگزین انتخاب دومش را می‌گیرد.

متدهای I18nCore

متد	بازگشت	توضیح
t(key, params?)	string	ترجمه می‌کند؛ به زبان جایگزین و سپس به خود کلید برمی‌گردد.
setLocale(locale)	void	زبان را عوض می‌کند؛ (در صورت روشن بودن) ذخیره و به مشترکان خبر می‌دهد.
getLocale()	string	زبان فعال.
onChange(handler)	() => void	تغییر زبان را مشترک می‌شود؛ تابعی برای لغو اشتراک می‌دهد.
addMessages(locale, dict)	void	پیام‌های بیشتری را در یک زبان ادغام می‌کند.
getMessages(locale?)	MessageDict	واژه‌نامه یک زبان را می‌خواند (پیش‌فرض: زبان فعال).
availableLocales	string[]	زبان‌هایی که واژه‌نامه ثبت‌شده دارند.
destroy()	void	همه مشترکان را برمی‌دارد.

تایپ‌ها

type MessageDict = Record<string, string>; // تخت: 'hero.title' → 'Hi {name}'
type LocaleMessages = Record<string, MessageDict>; // locale → MessageDict
type TranslateParams = Record<string, string | number>;

SSR

هسته در SSR امن است: دسترسی به localStorage و navigator محافظت شده، پس createI18n و t هنگام رندر سمت سرور بدون پرتاب خطا اجرا می‌شوند. ذخیره‌سازی و تشخیص زبان مرورگر روی سرور صرفاً کاری نمی‌کنند و به‌محض اجرای کد در مرورگر اثر می‌گذارند.