راهنمای بومی‌سازی و بین‌المللی‌سازی (i18n)

به راهنمای بومی‌سازی و بین‌المللی‌سازی Finch خوش آمدید! این راهنما شما را با مراحل بومی‌سازی و بین‌المللی‌سازی برنامه Finch آشنا می‌کند. چه توسعه‌دهنده حرفه‌ای باشید یا تازه‌کار، Finch مجموعه‌ای قدرتمند از ابزارها را برای ساده‌سازی توسعه وب سرور ارائه می‌دهد.

i18n در Finch

Finch یک سیستم داخلی i18n برای بومی‌سازی و بین‌المللی‌سازی برنامه شما ارائه می‌دهد. این سیستم به شما اجازه می‌دهد چندین زبان تعریف کرده و متون برنامه خود را به آن زبان‌ها ترجمه کنید.

چگونه از i18n در Finch استفاده کنیم؟

بومی‌سازی در Finch به دو روش انجام می‌شود: می‌توانید از فایل‌های Json استفاده کنید یا زبان‌ها را در فایل languages.dart تعریف کنید.

۱. استفاده از فایل‌های Json

در Finch می‌توانید از فایل‌های JSON برای تعریف زبان‌ها استفاده کنید. به طور پیش‌فرض، Finch به دنبال فایل‌های زبان در مسیر lib/languages می‌گردد. برای هر زبان مورد نظر، یک فایل JSON جدید ایجاد کنید. مثلاً برای زبان فارسی، فایل fa.json بسازید.

استفاده از i18n در Finch بسیار ساده است. کافی است زبان‌های خود را در فایل‌هایی مانند en.json یا زبان دیگر تعریف کنید. نمونه‌ای از تعریف زبان در فایل fa.json:

{
  "dir": "rtl",
  "example.params": "نام من {name} است، سن من {age} سال است",
  "example.path": "مسیر تست از example.path برای محلی‌سازی",
  "example.tstring": "تست اشیاء TString برای i18n",
  "logo": "Finch",
  "logo.title": "Finch"
}

۲. استفاده از فایل languages.dart

همچنین می‌توانید زبان‌ها را در فایل languages.dart تعریف کنید. نمونه‌ای از تعریف زبان‌ها در این فایل:

var languages = <String, Map<String, String>>{
  'fa': {
    'dir': 'rtl',
    'example.params': 'نام من {name} است، سن من {age} سال است',
    'example.path': 'مسیر تست از example.path برای محلی‌سازی',
  },
  'en': {
    'dir': 'ltr',
    'example.params': 'My name is {name}, I am {age} years old',
    'example.path': 'Test path from example.path for localization',
  },
};

پس از تعریف زبان‌ها، باید Finch را برای استفاده از فایل‌های dart برای i18n پیکربندی کنید. این کار با تنظیم ویژگی dartLanguages در شیء FinchConfigs انجام می‌شود. نمونه پیکربندی:

FinchConfigs configs = FinchConfigs(
  // فقط برای فایل‌های json
  languagePath: pathTo(env['LANGUAGE_PATH'] ?? "./lib/languages"), 
  // تعیین منبع زبان: dart یا json
  languageSource: LanguageSource.dart,
  // نقشه زبان‌های تعریف‌شده در فایل languages.dart
  dartLanguages: languages,
);

LanguageSource.dart و LanguageSource.json دو گزینه برای ویژگی languageSource هستند. می‌توانید هرکدام را بر اساس نیاز انتخاب کنید. سپس شیء configs را به سازنده FinchApp بدهید:

FinchApp app = FinchApp(configs: configs);

i18n در قالب‌ها

در قالب‌ها می‌توانید با استفاده از سینتکس {{ $t('logo.title') }} از i18n استفاده کنید. مثلاً برای ترجمه کلید logo.title:

<h1>{{ $t('logo.title') }}</h1>

i18n در کنترلرها

استفاده از i18n در کنترلرها بسیار ساده است. می‌توانید از متد "string".tr برای ترجمه متن استفاده کنید. مثلاً برای ترجمه کلید logo.title:

rq.renderString(text: 'logo.title'.tr);

پارامترها در i18n

می‌توانید از پارامترها در متن‌های i18n استفاده کنید. مثلاً برای ترجمه کلید example.params:

rq.renderString(text: 'example.params'.tr.write({'name': 'Alexandre', 'age': 30}));

و در قالب خود به این صورت:

<p>{{ $t('example.params', {'name': 'Alexandre', 'age': 30}) }}</p>

پارامترهای آرایه‌ای در i18n

می‌توانید از پارامترهای آرایه‌ای در متن‌های i18n استفاده کنید. مثلاً برای ترجمه کلید example.params:

rq.renderString(text: 'example.params'.tr.writeArr(['Alexandre', 30]));

و در قالب خود به این صورت:

{
    "example.params": "نام من {0} است، سن من {1} سال است",
}

<p>{{ $t('example.params', ['Alexandre', 30]) }}</p>