چندزبانه

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

فایل‌های زبان

src/locales/
├── fa.js          دیکشنری فارسی (زبان پیش‌فرض و مرجع)
├── en.js          انگلیسی
├── ar.js          عربی
├── chrome.js      متن‌های پوسته: ui.*، section.*، role.*
├── generated.js   تولیدشده: nav.*، صفحه‌ها، عنوان‌ها
└── index.js       ادغام دیکشنری‌ها + توابع کمکی

ترتیب ادغام در index.js: chrome → generated → دیکشنری دست‌نویس. یعنی دیکشنری زبان همیشه برنده است.

استفاده در HTML

<!-- متن -->
<button data-i18n="ui.export">خروجی</button>

<!-- صفت‌ها -->
<input data-i18n-placeholder="ui.searchPlaceholder" placeholder="جستجو…">
<button data-i18n-title="ui.close" aria-label="بستن"></button>

<!-- محتوای HTML (کمتر استفاده کنید) -->
<p data-i18n-html="landing.footerText"></p>

مقدار داخل تگ فقط متن پیش‌فرض است؛ اگر جاوااسکریپت اجرا نشود، همان نمایش داده می‌شود.

استفاده در جاوااسکریپت

import { t, setLanguage, language, dict } from './js/core/i18n.js';

t('ui.save');                       // ترجمه کلید
t('table.rows', '', { count: 24 }); // جای‌گذاری متغیر: "۲۴ سطر"
setLanguage('en');                  // تغییر زبان (جهت هم به‌روز می‌شود)

تغییر زبان از رابط کاربری

دکمه هدر با [data-language-switch]
پنل شخصی‌سازی: [data-customizer="language"] [data-value="ar"]
پالت فرمان (Ctrl+K) → «تغییر زبان»

import { setLanguage } from './js/core/i18n.js';
setLanguage('ar', { direction: 'rtl' });   // جهت را دستی هم می‌توان تعیین کرد

افزودن زبان جدید

فایل src/locales/tr.js را از en.js کپی کنید و ترجمه کنید:

export const tr = {
  meta: { code: 'tr', label: 'Türkçe', dir: 'ltr', locale: 'tr-TR' },
  ui: { save: 'Kaydet', cancel: 'İptal', … },
  …
};

در src/locales/index.js آن را import و به dictionaries اضافه کنید:

import { tr } from './tr.js';
const dictionaries = { fa, en, ar, tr };

اگر زبان راست‌به‌چپ است، dir: 'rtl' بگذارید؛ بقیه چیزها خودکار است (فونت، جهت، مجموعه ارقام).

ارقام و اعداد

زبان	مجموعه ارقام
fa	۰۱۲۳۴۵۶۷۸۹
ar	٠١٢٣٤٥٦٧٨٩
en	0123456789

اعداد همیشه با formatNumber، formatCurrency، formatPercent یا toDigits قالب می‌شوند — هیچ‌گاه Number را مستقیم در متن نگذارید:

import { formatCurrency, formatNumber, formatPercent } from './js/core/numbers.js';

formatCurrency(2480000000, 'IRR', { compact: true }); // ۲٫۵ میلیارد ریال
formatPercent(4.83);                                  // ۴٫۸٪

تاریخ و تقویم

با src/js/core/jalali.js تاریخ‌ها هم در تقویم شمسی و هم میلادی نمایش داده می‌شوند:

import { formatDate, relativeTime, toJalali, toGregorian } from './js/core/jalali.js';

formatDate('2026-09-22');        // ۳۱ شهریور ۱۴۰۵
relativeTime('2026-09-20');      // ۲ روز پیش

تقویم فعال با محور calendar در تنظیمات ظاهری جابه‌جا می‌شود (jalali ⇄ gregorian) و همه جدول‌ها، تقویم‌ها و نمودارهای زمانی همان را رعایت می‌کنند.

نکته: به‌روزرسانی زبان رویداد language:change را منتشر می‌کند

جدول‌ها، نمودارها و تقویم‌ها به آن گوش می‌دهند و برچسب‌ها را دوباره می‌سازند؛ اگر ماژول جدیدی نوشتید، همین رویداد را مدیریت کنید.

هشدار: متن فارسی را داخل فایل‌های JS (کنترل‌کننده‌ها) برای رابط کاربری ننویسید — تنها داده نمونه و متن‌های دمویی مجاز هستند

Localization

The template ships with three complete languages: Persian (default), English and Arabic. All interface text is read from dictionaries, and a language change is applied at runtime.

Language files

src/locales/
├── fa.js          Persian dictionary (default and reference language)
├── en.js          English
├── ar.js          Arabic
├── chrome.js      shell strings: ui.*, section.*, role.*
├── generated.js   generated: nav.*, pages, titles
└── index.js       dictionary merge + helpers

Merge order in index.js: chrome → generated → hand-written dictionary. In other words, the language dictionary always wins.

Usage in HTML

<!-- text -->
<button data-i18n="ui.export">خروجی</button>

<!-- attributes -->
<input data-i18n-placeholder="ui.searchPlaceholder" placeholder="جستجو…">
<button data-i18n-title="ui.close" aria-label="بستن"></button>

<!-- HTML content (use sparingly) -->
<p data-i18n-html="landing.footerText"></p>

The value inside the tag is only the fallback text; it is what is shown if JavaScript does not run.

Usage in JavaScript

import { t, setLanguage, language, dict } from './js/core/i18n.js';

t('ui.save');                       // translate a key
t('table.rows', '', { count: 24 }); // variable interpolation: "24 rows"
setLanguage('en');                  // change language (direction is updated too)

Changing the language from the UI

The header button with [data-language-switch]
The customizer: [data-customizer="language"] [data-value="ar"]
Command palette (Ctrl+K) → "Change language"

import { setLanguage } from './js/core/i18n.js';
setLanguage('ar', { direction: 'rtl' });   // the direction can also be set manually

Adding a new language

Copy src/locales/tr.js from en.js and translate it:

export const tr = {
  meta: { code: 'tr', label: 'Türkçe', dir: 'ltr', locale: 'tr-TR' },
  ui: { save: 'Kaydet', cancel: 'İptal', … },
  …
};

Import it in src/locales/index.js and add it to dictionaries:

import { tr } from './tr.js';
const dictionaries = { fa, en, ar, tr };

If the language is right-to-left, set dir: 'rtl'; everything else is automatic (font, direction, digit set).

Digits and numbers

Language	Digit set
fa	۰۱۲۳۴۵۶۷۸۹
ar	٠١٢٣٤٥٦٧٨٩
en	0123456789

Numbers are always formatted with formatNumber, formatCurrency, formatPercent or toDigits — never put a Number directly into text:

import { formatCurrency, formatNumber, formatPercent } from './js/core/numbers.js';

formatCurrency(2480000000, 'IRR', { compact: true }); // 2.5 billion rials
formatPercent(4.83);                                  // 4.8%

Dates and calendars

With src/js/core/jalali.js dates are displayed in both the Jalali (Solar Hijri) and the Gregorian calendar:

import { formatDate, relativeTime, toJalali, toGregorian } from './js/core/jalali.js';

formatDate('2026-09-22');        // 31 Shahrivar 1405
relativeTime('2026-09-20');      // 2 days ago

The active calendar is switched with the calendar axis in the appearance settings (jalali ⇄ gregorian), and all tables, calendars and time-series charts respect it.

Tip: a language update emits the language:change event

Tables, charts and calendars listen to it and rebuild their labels; if you write a new module, handle the same event.

Warning: do not write interface text inside JS files (controllers) — only sample data and demo text are allowed there

تعدد اللغات

يأتي القالب بثلاث لغات كاملة: الفارسية (الافتراضية) والإنجليزية والعربية. تُقرأ جميع نصوص الواجهة من القواميس، ويُطبَّق تغيير اللغة وقت التشغيل.

ملفات اللغة

src/locales/
├── fa.js          القاموس الفارسي (اللغة الافتراضية والمرجعية)
├── en.js          الإنجليزية
├── ar.js          العربية
├── chrome.js      نصوص الهيكل: ui.* وsection.* وrole.*
├── generated.js   مولّد: nav.* والصفحات والعناوين
└── index.js       دمج القواميس + دوال مساعدة

ترتيب الدمج في index.js: chrome ← generated ← القاموس المكتوب يدوياً. أي أن قاموس اللغة هو الغالب دائماً.

الاستخدام في HTML

<!-- نص -->
<button data-i18n="ui.export">خروجی</button>

<!-- السمات -->
<input data-i18n-placeholder="ui.searchPlaceholder" placeholder="جستجو…">
<button data-i18n-title="ui.close" aria-label="بستن"></button>

<!-- محتوى HTML (استخدمه بقلّة) -->
<p data-i18n-html="landing.footerText"></p>

القيمة داخل الوسم هي النص الاحتياطي فقط؛ وهي ما يُعرض إذا لم تُنفَّذ جافاسكريبت.

الاستخدام في جافاسكريبت

import { t, setLanguage, language, dict } from './js/core/i18n.js';

t('ui.save');                       // ترجمة مفتاح
t('table.rows', '', { count: 24 }); // إدراج متغير: "٢٤ صفاً"
setLanguage('en');                  // تغيير اللغة (ويُحدَّث الاتجاه أيضاً)

تغيير اللغة من الواجهة

زر الترويسة ذو [data-language-switch]
لوحة التخصيص: [data-customizer="language"] [data-value="ar"]
لوحة الأوامر (Ctrl+K) ← «تغيير اللغة»

import { setLanguage } from './js/core/i18n.js';
setLanguage('ar', { direction: 'rtl' });   // يمكن تحديد الاتجاه يدوياً أيضاً

إضافة لغة جديدة

انسخ الملف src/locales/tr.js من en.js وترجمه:

export const tr = {
  meta: { code: 'tr', label: 'Türkçe', dir: 'ltr', locale: 'tr-TR' },
  ui: { save: 'Kaydet', cancel: 'İptal', … },
  …
};

استورده في src/locales/index.js وأضفه إلى dictionaries:

import { tr } from './tr.js';
const dictionaries = { fa, en, ar, tr };

إذا كانت اللغة من اليمين إلى اليسار فاضبط dir: 'rtl'؛ وكل ما عدا ذلك تلقائي (الخط، الاتجاه، مجموعة الأرقام).

الأرقام والأعداد

اللغة	مجموعة الأرقام
fa	۰۱۲۳۴۵۶۷۸۹
ar	٠١٢٣٤٥٦٧٨٩
en	0123456789

تُنسَّق الأعداد دائماً بـ formatNumber أو formatCurrency أو formatPercent أو toDigits — لا تضع Number مباشرة في النص أبداً:

import { formatCurrency, formatNumber, formatPercent } from './js/core/numbers.js';

formatCurrency(2480000000, 'IRR', { compact: true }); // ٢٫٥ مليار ريال
formatPercent(4.83);                                  // ٤٫٨٪

التاريخ والتقويم

بواسطة src/js/core/jalali.js تُعرض التواريخ بالتقويم الهجري الشمسي وبالميلادي:

import { formatDate, relativeTime, toJalali, toGregorian } from './js/core/jalali.js';

formatDate('2026-09-22');        // ٣١ شهريور ١٤٠٥
relativeTime('2026-09-20');      // قبل يومين

يُبدَّل التقويم النشط بمحور calendar في إعدادات المظهر (jalali ⇄ gregorian)، وتلتزم به جميع الجداول والتقاويم والمخططات الزمنية.

ملاحظة: يُطلق تحديث اللغة الحدث language:change

تستمع إليه الجداول والمخططات والتقاويم وتعيد بناء تسمياتها؛ إذا كتبت وحدة جديدة، فتعامل مع الحدث نفسه.

تحذير: لا تكتب نصوص الواجهة داخل ملفات JS (المتحكمات) — المسموح فقط البيانات النموذجية ونصوص العرض التجريبي