کتابخانه‌ی استاندارد · متن

بین‌المللی‌سازی i18n

برنامه‌ی چندزبانه: ترجمه‌ی پیام‌ها، جای‌گذاری مقدار در پیام و انتخاب شکل مفرد و جمع.

واردسازی بین‌المللی‌سازی

نام آرگومان‌ها شناسه‌ی خود کد است و معادل فارسی ندارد؛ گونه‌ها، کلیدواژه‌ها و نام بسته‌ها با معادل فارسی نوشته می‌شوند.

اگر برنامه‌تان باید به چند زبان حرف بزند، پیام‌ها را در کد ننویسید؛ آن‌ها را با یک کلید در «فهرست ترجمه» بگذارید و هنگام نمایش، ترجمه‌ی زبان کاربر را بگیرید.

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

برای قالب‌بندی تاریخ با تقویم شمسی به calendar و برای رقم‌های فارسی و جهت متن به unicode و bidi سر بزنید؛ این بسته فقط تعیین می‌کند کدام پیام نشان داده شود.

نکته‌هایی که باید بدانید

  • ترجمه‌ی خالی نبودن ترجمه به حساب می‌آید، پس ترجمه از آن می‌گذرد و سراغ زبان پشتیبان می‌رود.
  • جمع دو شکل می‌شناسد: .one برای دقیقا ۱ و .other برای هر چیز دیگر، از جمله ۰. زبان‌هایی با شکل‌های بیشتر، مثل عربی یا روسی، منطق جداگانه‌ای پیرامون آن لازم دارند.
  • تشخیص زبان اول SALAM_LOCALE، بعد LANG و بعد LC_ALL را می‌خواند، پس LANG بر LC_ALL مقدم است که برعکس قاعده‌ی POSIX است. اگر هیچ‌کدام نباشد en برمی‌گرداند و با LANG=C مقدار c را.
  • جست‌وجو کل فهرست را می‌پیماید که برای چند صد پیام در هر زبان خوب است. برای هزاران پیام، خطوط پرکاربرد را در یک HashMap از خودتان نگه دارید.

ترجمه‌ی واژه‌های یک منو

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

i18n-guide-menu.salam
واردسازی بین‌المللی‌سازی

تابع آماده‌سازی(ف &: بین‌المللی‌سازی.فهرست ترجمه):
    بین‌المللی‌سازی.تنظیم(ف، "en"، "menu.open"، "Open")
    بین‌المللی‌سازی.تنظیم(ف، "en"، "menu.save"، "Save")
    بین‌المللی‌سازی.تنظیم(ف، "en"، "menu.quit"، "Quit")
    بین‌المللی‌سازی.تنظیم(ف، "fa"، "menu.open"، "باز کردن")
    بین‌المللی‌سازی.تنظیم(ف، "fa"، "menu.save"، "ذخیره")
    بین‌المللی‌سازی.تنظیم(ف، "fa"، "menu.quit"، "خروج")
    بین‌المللی‌سازی.تنظیم(ف، "de"، "menu.open"، "Öffnen")
    بین‌المللی‌سازی.تنظیم(ف، "de"، "menu.save"، "Speichern")
پایان

تابع نمایش منو(ف &: بین‌المللی‌سازی.فهرست ترجمه، زبان: رشته):
    باز := بین‌المللی‌سازی.ترجمه(ف، زبان، "menu.open")
    ذخیره := بین‌المللی‌سازی.ترجمه(ف، زبان، "menu.save")
    خروج := بین‌المللی‌سازی.ترجمه(ف، زبان، "menu.quit")
    سرچاپ زبان + ":"، باز، "|"، ذخیره، "|"، خروج
پایان

تابع ریشه:
    ناپایا ف := بین‌المللی‌سازی.جدید("en")
    دیرکن بین‌المللی‌سازی.آزادسازی(ف)
    آماده‌سازی(ف)
    هر زبان در ["en"، "fa"، "de"، "ja"]:
        نمایش منو(ف، زبان)
    پایان
پایان
خروجیen: Open | Save | Quit fa: باز کردن | ذخیره | خروج de: Öffnen | Speichern | Quit ja: Open | Save | Quit

نگه داشتن ترجمه‌ها در پرونده

مترجم نباید مجبور باشد کد سلام را ویرایش کند. برای هر زبان یک پرونده با خط‌های کلید = مقدار بسازید و آن را با بارگذاری زبان بخوانید؛ این تابع تعداد کلیدهای خوانده‌شده را برمی‌گرداند. جای خالی‌هایی مثل {name} در متن می‌مانند و ترجمه قالبی در همان فراخوانی ترجمه، پرشان می‌کند.

i18n-guide-files.salam
واردسازی بین‌المللی‌سازی
واردسازی ورودی خروجی

تابع ریشه:
    ورودی خروجی.نوشتن پرونده("en.txt"، "# English\ntitle = Notes\nwelcome = Welcome back, {name}\nprice = 'Only $5 # today'\n")
    ورودی خروجی.نوشتن پرونده("fa.txt"، "# Persian\ntitle = یادداشت‌ها\nwelcome = {name}، خوش برگشتی\n")
    ناپایا ف := بین‌المللی‌سازی.جدید("en")
    دیرکن بین‌المللی‌سازی.آزادسازی(ف)
    سرچاپ "کلیدهای انگلیسی:"، بین‌المللی‌سازی.بارگذاری زبان(ف، "en"، "en.txt")
    سرچاپ "کلیدهای فارسی:"، بین‌المللی‌سازی.بارگذاری زبان(ف، "fa"، "fa.txt")
    ناپایا نام‌ها := وکتور {} برگردان وکتور<رشته>
    ناپایا مقدارها := وکتور {} برگردان وکتور<رشته>
    دیرکن نام‌ها.آزادکن()
    دیرکن مقدارها.آزادکن()
    نام‌ها.بیفزا("name")
    مقدارها.بیفزا("سارا")
    هر زبان در ["en"، "fa"]:
        سرچاپ بین‌المللی‌سازی.ترجمه(ف، زبان، "title")
        سرچاپ بین‌المللی‌سازی.ترجمه قالبی(ف، زبان، "welcome"، نام‌ها، مقدارها)
        سرچاپ بین‌المللی‌سازی.ترجمه(ف، زبان، "price")
    پایان
پایان
خروجیکلیدهای انگلیسی: 3 کلیدهای فارسی: 2 Notes Welcome back, سارا Only $5 # today یادداشت‌ها سارا، خوش برگشتی Only $5 # today

این پرونده‌ها با همان تجزیه‌گر پرونده‌های .env خوانده می‌شوند (نگاه کنید به config). یعنی خطی که با # شروع شود یادداشت است، # بی‌نقل‌قول در میان مقدار هم یادداشت را شروع می‌کند، و ${...} باز می‌شود. اگر مقداری یکی از این‌ها را دارد، مثل خط price آن را میان نقل‌قول تکی بگذارید.

عدد و جمع

جمع میان کلید.one و کلید.other یکی را برمی‌دارد و بعد جایگذاری عدد را در متن انتخاب‌شده می‌گذارد. فارسی معمولاً یک شکل بیشتر لازم ندارد («۵ فایل»)، ولی حواستان به زبان پشتیبان باشد: اگر زبان پشتیبان شکل .one دارد و زبان شما ندارد، برای n برابر ۱ متن زبان پشتیبان نشان داده می‌شود. نوشتن .one در همه‌ی زبان‌ها جلوی این غافلگیری را می‌گیرد.

i18n-guide-plural.salam
واردسازی بین‌المللی‌سازی
واردسازی رشته

تابع پیام شمارش(ف &: بین‌المللی‌سازی.فهرست ترجمه، زبان: رشته، کلید: رشته، ن: صحیح): رشته:
    ناپایا نام‌ها := وکتور {} برگردان وکتور<رشته>
    ناپایا مقدارها := وکتور {} برگردان وکتور<رشته>
    دیرکن نام‌ها.آزادکن()
    دیرکن مقدارها.آزادکن()
    نام‌ها.بیفزا("n")
    مقدارها.بیفزا(رشته.از عدد(ن))
    برگشت بین‌المللی‌سازی.جایگذاری(بین‌المللی‌سازی.جمع(ف، زبان، کلید، ن)، نام‌ها، مقدارها)
پایان

تابع ریشه:
    ناپایا ف := بین‌المللی‌سازی.جدید("en")
    دیرکن بین‌المللی‌سازی.آزادسازی(ف)
    بین‌المللی‌سازی.تنظیم(ف، "en"، "files.one"، "{n} file selected")
    بین‌المللی‌سازی.تنظیم(ف، "en"، "files.other"، "{n} files selected")
    بین‌المللی‌سازی.تنظیم(ف، "fa"، "files.other"، "{n} فایل انتخاب شد")
    هر ن در [۰، ۱، ۲، ۲۵]:
        سرچاپ پیام شمارش(ف، "en"، "files"، ن)، "/"، پیام شمارش(ف، "fa"، "files"، ن)
    پایان
    بین‌المللی‌سازی.تنظیم(ف، "fa"، "files.one"، "{n} فایل انتخاب شد")
    سرچاپ پیام شمارش(ف، "fa"، "files"، ۱)
پایان
خروجی0 files selected / 0 فایل انتخاب شد 1 file selected / 1 file selected 2 files selected / 2 فایل انتخاب شد 25 files selected / 25 فایل انتخاب شد 1 فایل انتخاب شد

انتخاب زبان کاربر

تشخیص زبان اول SALAM_LOCALE، بعد LANG و LC_ALL را می‌خواند و مقداری مثل fa_IR.UTF-8 را به fa کوتاه می‌کند. هر زبانی را که سیستم بگوید برمی‌گرداند، پس نتیجه را با فهرست زبان‌هایی که واقعاً دارید مقایسه کنید و در غیر این صورت سراغ زبان پیش‌فرض بروید. یک کارساز وب به جای این کار سرآیند Accept-Language را می‌خواند و همان کد کوتاه را به ترجمه می‌دهد.

i18n-guide-detect.salam
واردسازی بین‌المللی‌سازی
واردسازی محیط

تابع انتخاب زبان(خواسته: رشته، پشتیبانی‌شده: وکتور<رشته>، پشتیبان: رشته): رشته:
    هر ز در پشتیبانی‌شده:
        اگر ز برابر خواسته: برگشت ز پایان
    پایان
    برگشت پشتیبان
پایان

تابع ریشه:
    ناپایا پشتیبانی‌شده := وکتور {} برگردان وکتور<رشته>
    دیرکن پشتیبانی‌شده.آزادکن()
    پشتیبانی‌شده.بیفزا("en")
    پشتیبانی‌شده.بیفزا("fa")
    هر تنظیم در ["fa_IR.UTF-8"، "EN-us"، "de_DE.UTF-8"]:
        محیط.تنظیم("SALAM_LOCALE"، تنظیم)
        زبان := بین‌المللی‌سازی.تشخیص زبان()
        سرچاپ تنظیم، "->"، زبان، "->"، انتخاب زبان(زبان، پشتیبانی‌شده، "en")
    پایان
پایان
خروجیfa_IR.UTF-8 -> fa -> fa EN-us -> en -> en de_DE.UTF-8 -> de -> en

پیدا کردن ترجمه‌های جاافتاده

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

i18n-guide-audit.salam
واردسازی بین‌المللی‌سازی

تابع ریشه:
    ناپایا ف := بین‌المللی‌سازی.جدید("en")
    دیرکن بین‌المللی‌سازی.آزادسازی(ف)
    بین‌المللی‌سازی.تنظیم(ف، "en"، "title"، "Settings")
    بین‌المللی‌سازی.تنظیم(ف، "en"، "save"، "Save changes")
    بین‌المللی‌سازی.تنظیم(ف، "en"، "reset"، "Reset to defaults")
    بین‌المللی‌سازی.تنظیم(ف، "en"، "help"، "Help")
    بین‌المللی‌سازی.تنظیم(ف، "fa"، "title"، "تنظیمات")
    بین‌المللی‌سازی.تنظیم(ف، "fa"، "save"، "ذخیره‌ی تغییرات")
    ناپایا همه := ۰
    ناپایا جاافتاده := ۰
    هر ک در ف.کلیدها:
        اگر ک.زیررشته(۰، ۳) برابر "en:":
            کلید := ک.زیررشته(۳، ک.طول() - ۳)
            همه++
            اگر بین‌المللی‌سازی.دارد(ف، "fa"، کلید) برابر نادرست:
                جاافتاده++
                سرچاپ "ترجمه‌ی فارسی ندارد:"، کلید، "و نشان می‌دهد:"، بین‌المللی‌سازی.ترجمه(ف، "fa"، کلید)
            پایان
        پایان
    پایان
    سرچاپ "فارسی:"، همه - جاافتاده، "از"، همه، "ترجمه شده"
پایان
خروجیترجمه‌ی فارسی ندارد: reset و نشان می‌دهد: Reset to defaults ترجمه‌ی فارسی ندارد: help و نشان می‌دهد: Help فارسی: 2 از 4 ترجمه شده
کارتابع
ترجمه‌ی یک پیام ثابتترجمه
ترجمه و پر کردن مقدارهاترجمه قالبی
یکی یا چندتاجمع و بعد جایگذاری
بارگذاری یک زبان از پروندهبارگذاری زبان
بررسی وجود یک ترجمهدارد
متن دقیقاً همان‌طور که ذخیره شدهدریافت خام

گونه‌ها

فهرست ترجمه Catalog

ساختار فهرست ترجمه
فهرست ترجمه‌ها. آن را با جدید بسازید و با آزادسازی رها کنید.
نامانگلیسیگونهتوضیح
کلیدهاkeysوکتور<رشته>کلیدهای ذخیره‌شده، به شکل «زبان:کلید».
ترجمه‌هاvalsوکتور<رشته>ترجمه‌ها، به همان ترتیب کلیدها.
زبان پشتیبانfallbackرشته = "en"زبان پشتیبان.
i18n-Catalog.salam
واردسازی بین‌المللی‌سازی

تابع ریشه:
    ناپایا ف := بین‌المللی‌سازی.جدید("en")
    دیرکن بین‌المللی‌سازی.آزادسازی(ف)
    بین‌المللی‌سازی.تنظیم(ف، "en"، "hello"، "Hello")
    بین‌المللی‌سازی.تنظیم(ف، "fa"، "hello"، "سلام")
    بین‌المللی‌سازی.تنظیم(ف، "en"، "bye"، "Goodbye")
    سرچاپ بین‌المللی‌سازی.ترجمه(ف، "fa"، "hello")، بین‌المللی‌سازی.ترجمه(ف، "fa"، "bye")، بین‌المللی‌سازی.ترجمه(ف، "fa"، "missing")
    سرچاپ بین‌المللی‌سازی.دارد(ف، "fa"، "bye")، بین‌المللی‌سازی.دریافت خام(ف، "fa"، "bye") == ""
    سرچاپ ف.زبان پشتیبان
پایان
خروجیسلام Goodbye missing false true en

تابع‌ها

جدید New

تابع جدید(default_locale: رشته): فهرست ترجمه
یک فهرست خالی با زبان پشتیبان داده‌شده می‌سازد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: i18n-Catalog.salam

تنظیم Set

تابع تنظیم(c &: فهرست ترجمه، locale: رشته، key: رشته، val: رشته)
ترجمه‌ی یک کلید را برای یک زبان ثبت می‌کند؛ اگر از قبل بوده، جایگزین می‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: i18n-Catalog.salam

دارد Has

تابع دارد(c &: فهرست ترجمه، locale: رشته، key: رشته): منطقی
اگر برای این زبان و کلید ترجمه‌ای ثبت شده باشد، درست برمی‌گرداند. زبان پشتیبان را نگاه نمی‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: i18n-Catalog.salam

دریافت خام RawGet

تابع دریافت خام(c &: فهرست ترجمه، locale: رشته، key: رشته): رشته
ترجمه‌ی ثبت‌شده را بی‌هیچ جایگزینی برمی‌گرداند؛ اگر نباشد، رشته‌ی تهی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: i18n-Catalog.salam

ترجمه T

تابع ترجمه(c &: فهرست ترجمه، locale: رشته، key: رشته): رشته
ترجمه‌ی کلید را برمی‌گرداند؛ اگر نباشد، ترجمه‌ی زبان پشتیبان را، و اگر آن هم نباشد، خود کلید را.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: i18n-Catalog.salam

جایگذاری Interpolate

تابع جایگذاری(msg: رشته، param_names: وکتور<رشته>، param_vals: وکتور<رشته>): رشته
هر {نام} در پیام را با مقدار هم‌نامش جایگزین می‌کند. نام‌ها و مقدارها در دو وکتور هم‌ترتیب داده می‌شوند.
i18n-Tf.salam
واردسازی بین‌المللی‌سازی

تابع ریشه:
    ناپایا ف := بین‌المللی‌سازی.جدید("en")
    دیرکن بین‌المللی‌سازی.آزادسازی(ف)
    بین‌المللی‌سازی.تنظیم(ف، "fa"، "greet"، "سلام {name}، {n} پیام تازه داری")
    ناپایا نام‌ها := وکتور {} برگردان وکتور<رشته>
    ناپایا مقدارها := وکتور {} برگردان وکتور<رشته>
    دیرکن نام‌ها.آزادکن()
    دیرکن مقدارها.آزادکن()
    نام‌ها.بیفزا("name")
    نام‌ها.بیفزا("n")
    مقدارها.بیفزا("مریم")
    مقدارها.بیفزا("۳")
    سرچاپ بین‌المللی‌سازی.ترجمه قالبی(ف، "fa"، "greet"، نام‌ها، مقدارها)
    سرچاپ بین‌المللی‌سازی.جایگذاری("{name} و باز هم {name}"، نام‌ها، مقدارها)
پایان
خروجیسلام مریم، ۳ پیام تازه داری مریم و باز هم مریم

ترجمه قالبی Tf

تابع ترجمه قالبی(c &: فهرست ترجمه، locale: رشته، key: رشته، param_names: وکتور<رشته>، param_vals: وکتور<رشته>): رشته
ترجمه و جای‌گذاری در یک قدم.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: i18n-Tf.salam

جمع Plural

تابع جمع(c &: فهرست ترجمه، locale: رشته، key: رشته، n: صحیح۶۴): رشته
شکل مناسب پیام را برای عدد n انتخاب می‌کند: کلید .one برای یک و .other برای بقیه. عدد را خودش در پیام نمی‌گذارد؛ برای آن جایگذاری را به کار ببرید. در فارسی معمولاً یک شکل کافی است («۵ سیب»)، پس همان .other کافی است، به شرطی که زبان پشتیبان هم .one نداشته باشد؛ وگرنه برای n برابر ۱ همان .one زبان پشتیبان نشان داده می‌شود، پس .one را هم بنویسید.
i18n-Plural.salam
واردسازی بین‌المللی‌سازی
واردسازی ورودی خروجی

تابع ریشه:
    ناپایا ف := بین‌المللی‌سازی.جدید("en")
    دیرکن بین‌المللی‌سازی.آزادسازی(ف)
    ورودی خروجی.نوشتن پرونده("en.txt"، "apple.one = one apple\napple.other = {n} apples\n")
    سرچاپ بین‌المللی‌سازی.بارگذاری زبان(ف، "en"، "en.txt")
    ناپایا نام‌ها := وکتور {} برگردان وکتور<رشته>
    دیرکن نام‌ها.آزادکن()
    نام‌ها.بیفزا("n")
    هر ن در [۱، ۵]:
        ناپایا مقدارها := وکتور {} برگردان وکتور<رشته>
        مقدارها.بیفزا("" + ن)
        سرچاپ بین‌المللی‌سازی.جایگذاری(بین‌المللی‌سازی.جمع(ف، "en"، "apple"، ن)، نام‌ها، مقدارها)
        مقدارها.آزادکن()
    پایان
    سرچاپ بین‌المللی‌سازی.تشخیص زبان().طول() > ۰
پایان
خروجی2 one apple 5 apples true

بارگذاری زبان LoadLocale

تابع بارگذاری زبان(c &: فهرست ترجمه، locale: رشته، path: رشته): صحیح
ترجمه‌های یک زبان را از پرونده‌ای با خط‌های کلید = مقدار بارگذاری می‌کند و تعداد کلیدهای خوانده‌شده را برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: i18n-Plural.salam

تشخیص زبان DetectLocale

تابع تشخیص زبان(): رشته
زبان کاربر را از متغیرهای محیطی حدس می‌زند: اول SALAM_LOCALE، بعد LANG و LC_ALL. اگر هیچ‌کدام تنظیم نشده باشد، en برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: i18n-Plural.salam

آزادسازی Free

تابع آزادسازی(c &: فهرست ترجمه)
حافظه‌ی فهرست را آزاد می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: i18n-Catalog.salam