چگونه فایل‌های PO را بدون خراب شدن برنامه ترجمه کنیم

TABLE OF CONTENTS

فایل‌های PO در نگاه اول مانند فایل‌های متنی ساده به نظر می‌رسند، اما یک ترجمه‌ی اشتباه برای %s، نبود فرم جمع، یا ویرایش msgid می‌تواند برنامه‌ی شما را مختل کند. با این روش، رشته‌های قابل مشاهده توسط کاربر را ترجمه کنید و ساختار gettext را دست‌نخورده نگه دارید.

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

روش اول: استفاده از مترجم فایل PO

این روش را زمانی انتخاب کنید که می‌خواهید سریع‌ترین پیش‌نویس ایمن را داشته باشید و نمی‌خواهید جفت‌های msgid / msgstr را دستی ویرایش کنید.

از فایل اصلی .po نسخه پشتیبان تهیه کنید. قبل از ارسال فایل برای ترجمه، یک نسخه‌ی تمیز در مخزن خود نگه دارید. اگر فایل ترجمه‌شده خراب شد، باید یک نسخه‌ی سالم برای مقایسه داشته باشید.
یک مترجم آگاه به PO باز کنید. از ابزاری که برای فایل‌های gettext ساخته شده استفاده کنید، مانند OpenL PO Translator، که یک ابزار ترجمه‌ی اسناد با پرداخت به ازای استفاده است. یک ابزار آگاه به PO باید رشته‌های هدف را ترجمه کند و در عین حال رشته‌های منبع، توضیحات، جای‌نگهدارها و ساختار فایل را دست‌نخورده نگه دارد. اگر هنوز در حال انتخاب ابزار هستید، گزینه‌ها را در راهنمای بهترین مترجم PO مقایسه کنید.
فایل .po را بارگذاری کنید. از فایل زبانی استفاده کنید که شامل ورودی‌های msgid و msgstr باشد. اگر فقط یک قالب .pot دارید، ابتدا یک فایل .po به زبان هدف از آن بسازید و سپس فایل .po را بارگذاری کنید.
زبان مبدا و مقصد را انتخاب کنید. زبان مبدا را مطابق با متن داخل msgid انتخاب کنید، نه زبان رابط مدیریت خود. برای مثال، اگر فایل شامل رشته‌های انگلیسی msgid است و خروجی اسپانیایی نیاز دارید، انگلیسی به اسپانیایی را انتخاب کنید.
فایل ترجمه‌شده را دانلود کنید. آن را با الگوی نام‌گذاری محلی که چارچوب شما انتظار دارد ذخیره کنید. افزونه‌های وردپرس معمولاً از الگوی دامنه متن به علاوه محلی استفاده می‌کنند، در حالی که Django معمولاً فایل‌ها را زیر locale/<language>/LC_MESSAGES/ ذخیره می‌کند.
ابتدا رشته‌های پرریسک را بازبینی کنید. در فایل ترجمه‌شده به دنبال نمادهای %، {، }، <، >، msgid_plural، msgctxt و #, fuzzy بگردید. این موارد بیشترین احتمال را دارند که بر رفتار زمان اجرا تأثیر بگذارند.
فایل ترجمه‌شده را در اپلیکیشن خود تست کنید. زبان را به صورت محلی بارگذاری کنید و صفحات مختلفی که از رشته‌های ترجمه‌شده استفاده می‌کنند را مرور کنید. یک فایل PO زمانی کامل نیست که فقط ترجمه شده باشد؛ زمانی کامل است که اپلیکیشن همچنان به درستی نمایش داده شود.

روش دوم: ترجمه فایل‌های PO در Poedit

این روش را زمانی انتخاب کنید که به بازبینی انسانی، سازگاری با وردپرس یا یک روند دقیق و مرحله‌به‌مرحله نیاز دارید.

فایل را در Poedit باز کنید. Poedit یک ویرایشگر تخصصی ترجمه برای فرمت‌های PO و سایر فرمت‌های بومی‌سازی است؛ ویرایشگر پایه رایگان است و امکانات حرفه‌ای پولی برای روندهای کاری سنگین‌تر دارد. برای وردپرس، راهنمای رسمی Polyglots توضیح می‌دهد که Poedit می‌تواند فایل‌های .po و .mo را از یک فایل POT بسازد و از فرم‌های جمع و UTF-8 پشتیبانی می‌کند.
در صورت تغییر منبع، از الگوی POT به‌روزرسانی کنید. اگر توسعه‌دهندگان متن اپلیکیشن را تغییر داده‌اند، قبل از ترجمه، فایل .po را از جدیدترین .pot به‌روزرسانی کنید. این کار باعث می‌شود رشته‌های جدید، حذف‌شده و مبهم قابل مشاهده باشند و متن‌های قدیمی به طور پنهانی ارسال نشوند.
فقط فیلد msgstr را ترجمه کنید. msgid همان رشته منبعی است که اپلیکیشن شما برای یافتن ترجمه استفاده می‌کند. در روند عادی gettext، مترجمان باید فقط msgstr را ویرایش کنند، نه msgid.
جای‌نگهدارها را دقیقاً دست‌نخورده نگه دارید. متغیرهایی مانند %s، %d، %1$s، {name}، %(count)s، :name یا تگ‌های HTML را ترجمه یا فاصله‌گذاری مجدد نکنید. اگر ترتیب کلمات باید تغییر کند، جای‌نگهدار را به صورت یک واحد جابه‌جا کنید.
فرم‌های جمع را به عنوان ترجمه‌های جداگانه مدیریت کنید. یک ورودی جمع می‌تواند شامل msgid، msgid_plural و چند مقدار msgstr[n] باشد. هر جایگاه جمع مورد نیاز زبان مقصد را به طور کامل پر کنید و از کپی کردن یک جمله در همه جا خودداری کنید.
فایل .mo را ذخیره و کامپایل کنید اگر برنامه شما به آن نیاز دارد. برخی پشته‌ها در زمان توسعه مستقیماً فایل‌های .po را می‌خوانند، اما وردپرس و بسیاری از تنظیمات gettext در زمان اجرا از فایل‌های کامپایل‌شده .mo استفاده می‌کنند. Poedit هنگام ذخیره می‌تواند فایل .mo را کامپایل کند؛ جنگو با دستور django-admin compilemessages پیام‌ها را کامپایل می‌کند.
قبل از آپلود هشدارها را رفع کنید. در Poedit، آیکون‌های هشدار معمولاً به جایگزین‌های خراب، متغیرهای گم‌شده یا ناسازگاری جمع اشاره دارند. این موارد را قبل از وارد کردن ترجمه به وردپرس، جنگو، دروپال یا شاخه انتشار خود اصلاح کنید.

روش سوم: استفاده از پلتفرم بومی‌سازی

این روش را زمانی انتخاب کنید که چند مترجم، بازبین یا مدیر انتشار باید روی یک فایل PO کار کنند.

فایل PO را در پلتفرمی وارد کنید که از gettext پشتیبانی می‌کند. Weblate و پلتفرم‌های مشابه بومی‌سازی از گردش‌کار PO پشتیبانی می‌کنند. پلتفرم‌های تیمی بومی‌سازی اغلب محصولات پولی هستند، اگرچه Weblate گزینه متن‌باز و خودمیزبان نیز دارد. نحوه مدیریت کامنت‌ها، هدرها، رشته‌های fuzzy و جایگزین‌ها در هر پلتفرم متفاوت است، پس قبل از آپلود فایل‌های تولیدی تنظیمات فرمت را بررسی کنید.
بررسی جایگزین‌ها و تگ‌ها را فعال کنید. قوانین QA را برای جایگزین‌های printf، متغیرهای نام‌گذاری‌شده، تگ‌های HTML/XML و فرم‌های جمع فعال کنید. این بررسی‌ها اشتباهاتی را می‌گیرند که چک‌کننده‌های معمولی املاء قادر به تشخیص آن‌ها نیستند.
کامنت‌های توسعه‌دهنده را قابل مشاهده نگه دارید. کامنت‌های PO می‌توانند زمینه‌هایی مانند ارجاع منبع، یادداشت‌های استخراج‌شده توسعه‌دهنده، پرچم‌ها و رشته‌های منبع قبلی را منتقل کنند. مترجمان به این یادداشت‌ها نیاز دارند، مخصوصاً زمانی که یک برچسب کوتاه رابط کاربری مانند “Open” می‌تواند فعل، صفت یا فرمان منو باشد.
از حافظه ترجمه با بازبینی استفاده کنید. حافظه ترجمه برای رشته‌های تکراری رابط کاربری مفید است، اما ممکن است یک ترجمه قدیمی را در زمینه‌ای جدید کپی کند. زمانی که msgctxt، ارجاع منبع یا رابط کاربری اطراف تغییر کرده، رشته‌های استفاده‌شده مجدد را بازبینی کنید.
فایل‌های PO را صادر کرده و بررسی‌های محلی انجام دهید. به خروجی صادرشده بدون بررسی اعتماد نکنید. فایل ترجمه‌شده را دوباره در برنامه قرار دهید، در صورت نیاز کامپایل کنید و صفحات را قبل از ادغام تست کنید.

قوانین فایل PO که هرگز نباید زیر پا بگذارید

PO item	ترجمه شود؟	مثال ایمن	چرا مهم است
`msgid`	خیر	`msgid "Save changes"`	برنامه از این رشته منبع به عنوان کلید جستجو در بسیاری از گردش‌های کاری gettext استفاده می‌کند.
`msgstr`	بله	`msgstr "Guardar cambios"`	این متنی است که کاربران در زبان مقصد مشاهده می‌کنند.
`msgctxt`	خیر	`msgctxt "button"`	زمینه، رشته‌های منبع یکسان را از هم متمایز می‌کند.
`%s`, `%d`, `%1$s`	خیر	`Hello, %s` -> `Hola, %s`	کد زمان اجرا این جای‌نگهدارها را با مقادیر زنده جایگزین می‌کند.
`{name}`, `%(count)s`, `:name`	خیر	`Welcome, {name}`	متغیرهای نام‌گذاری شده باید همچنان با کد برنامه مطابقت داشته باشند.
تگ‌های HTML	معمولاً خیر	`<strong>Warning</strong>`	متن را ترجمه کنید، نه ساختار تگ.
`msgid_plural`	خیر	`msgid_plural "%d files"`	جمع منبع متعلق به مسیر کد اصلی است.
`msgstr[0]`, `msgstr[1]`	بله، با دقت	`msgstr[0] "%d file"`	هر زبان مقصد قوانین جمع‌بندی خاص خود را دارد.
`#, fuzzy`	ابتدا بررسی شود	`#, fuzzy`	fuzzy یعنی ترجمه ممکن است قدیمی یا تأیید نشده باشد.
`#.` توضیحات توسعه‌دهنده	معمولاً خیر	`#. Button label`	این یادداشت‌ها به مترجمان کمک می‌کند تا زمینه را بهتر بفهمند.

مثال سریع: ترجمه PO ایمن در مقابل خراب

در اینجا یک ورودی معمولی gettext آورده شده است:

#. %s نام نمایشی کاربر است.
#, c-format
msgid "Welcome back, %s"
msgstr ""

یک ترجمه ایمن به اسپانیایی %s را بدون تغییر نگه می‌دارد:

#. %s نام نمایشی کاربر است.
#, c-format
msgid "Welcome back, %s"
msgstr "Bienvenido de nuevo, %s"

یک ترجمه خراب جای‌نگهدار را تغییر می‌دهد:

msgid "Welcome back, %s"
msgstr "Bienvenido de nuevo, % s"

همان فاصله کوچک می‌تواند مهم باشد. ابزار GNU msgfmt --check-format برای شناسایی ناسازگاری‌های رشته قالب مانند جای‌نگهدارهای اشتباه % طراحی شده است و Poedit نیز درباره مشکلات رایج جای‌نگهدار هشدار می‌دهد. برای فهرست گسترده‌تر رشته‌هایی که نباید دست بخورند، از راهنمای ما درباره چه چیزهایی را نباید ترجمه کرد استفاده کنید.

چگونه یک فایل PO ترجمه‌شده را بررسی کنیم

اگر gettext را نصب کرده‌اید، اعتبارسنجی gettext را اجرا کنید.

msgfmt --check --check-format -o /tmp/messages.mo path/to/messages.po

این دستور نحو، هدرها و رشته‌های قالب را بررسی می‌کند و اگر فایل معتبر باشد، یک کاتالوگ موقت کامپایل‌شده ایجاد می‌کند.

فایل را به روشی که فریم‌ورک شما انتظار دارد کامپایل کنید.

django-admin compilemessages

برای پروژه‌های Django، دستور compilemessages فایل‌های .po ساخته‌شده توسط makemessages را به فایل‌های .mo برای پشتیبانی از gettext تبدیل می‌کند.

جستجو برای ترجمه‌های خالی.

grep -n 'msgstr ""' path/to/messages.po

فیلدهای خالی msgstr ممکن است برای موارد ترجمه‌نشده عمدی باشند، اما نباید هنگام انتشار شما را غافلگیر کنند.

جستجو برای رشته‌های fuzzy.

grep -n '#, fuzzy' path/to/messages.po

رشته‌های fuzzy باید قبل از انتشار توسط یک فرد بازبینی شوند. به طور پیش‌فرض، msgfmt ترجمه‌های fuzzy را استفاده نمی‌کند مگر اینکه با گزینه --use-fuzzy کامپایل کنید، بنابراین یک ورودی fuzzy می‌تواند مانند یک رشته ترجمه‌نشده در کاتالوگ نهایی رفتار کند.

رابط کاربری واقعی را تست کنید. صفحات شامل فرم‌ها، شمارش جمع، پیام‌های خطا، منوهای حساب کاربری و جریان‌های پرداخت را باز کنید. اعتبارسنجی PO مشکلات فایل را پیدا می‌کند؛ فقط تست رابط کاربری مشکلات عبارت‌بندی نامناسب، سرریز و کمبود زمینه را آشکار می‌کند.

کدام روش را باید استفاده کنید؟

وضعیت	بهترین روش	دلیل
نیاز به یک پیش‌نویس سریع برای یک فایل PO دارید	مترجم فایل PO	سریع‌ترین مسیر با حفظ ساختار
افزونه یا پوسته وردپرس را نگهداری می‌کنید	Poedit	روند کاری آشنای وردپرس با کامپایل `.mo`
یک اپلیکیشن Django را نگهداری می‌کنید	مترجم PO یا Poedit، سپس `compilemessages`	ترجمه می‌تواند سریع باشد اما کامپایل فریم‌ورک همچنان لازم است
زبان‌ها و بازبین‌های زیادی دارید	پلتفرم بومی‌سازی	مدیریت بهتر تخصیص، تاریخچه، کنترل کیفیت و بازبینی
رشته‌های مخصوص توسعه‌دهندگان را ترجمه می‌کنید	بازبینی انسانی پس از ترجمه ماشینی	اصطلاحات کد، جای‌نگهدارها و زمینه اهمیت بیشتری دارند
فایل‌های JSON یا i18n فرانت‌اند را هم بومی‌سازی می‌کنید	استفاده از روند کاری مخصوص فرمت	قوانین PO همیشه برای JSON، YAML یا پیام‌های ICU صدق نمی‌کند

اگر پروژه شما فایل‌های gettext PO را با فایل‌های محلی‌سازی JSON ترکیب می‌کند، هر فرمت را با ابزاری ترجمه کنید که ساختار آن را می‌شناسد. فایل‌های PO حول محور msgid و msgstr می‌چرخند؛ بومی‌سازی JSON حول کلیدها و مقادیر است. برای این روند کاری، راهنمای ما درباره بهترین مترجم‌های JSON در سال ۲۰۲۶ را ببینید.

پرسش‌های متداول

آیا می‌توانم فایل‌های PO را با Google Translate ترجمه کنم؟

می‌توانید مقادیر تکی msgstr را در یک مترجم عمومی کپی کنید، اما بارگذاری یا چسباندن کل فایل PO در یک مترجم متنی ساده ریسک دارد. مترجم‌های عمومی ممکن است msgid، توضیحات، اسکیپ نقل‌قول، شاخص‌های جمع یا جای‌نگهدارها را تغییر دهند. به جای آن از یک مترجم آگاه به PO، Poedit یا یک پلتفرم بومی‌سازی استفاده کنید.

تفاوت بین `.po`، `.pot` و `.mo` چیست؟

.pot قالبی است که از کد منبع استخراج می‌شود. معمولاً فقط رشته‌های اصلی را دارد و ترجمه کامل‌شده‌ای ندارد. .po فایل ترجمه قابل ویرایش برای یک زبان هدف است. .mo کاتالوگ باینری کامپایل‌شده‌ای است که بسیاری از برنامه‌های مبتنی بر gettext هنگام اجرا بارگذاری می‌کنند.

آیا باید `msgid` را ترجمه کنم؟

نه، در جریان کاری معمول اینطور نیست. فقط msgstr را ترجمه کنید. راهنمای GNU gettext توضیح می‌دهد که msgid رشته اصلی ترجمه نشده است و msgstr ترجمه آن؛ رشته‌های msgid توسط ابزارهای gettext تولید و مدیریت می‌شوند.

چگونه بررسی کنم که یک فایل PO معتبر است؟

اگر gettext در دسترس است، دستور msgfmt --check --check-format را اجرا کنید، فایل را در Poedit باز کنید یا از بررسی‌های QA پلتفرم بومی‌سازی خود استفاده کنید. سپس فایل را درون برنامه کامپایل و تست کنید. اعتبارسنجی ضروری است، اما جایگزین تست رابط کاربری نمی‌شود.

اگر یک جای‌نگهدار را خراب کنم چه می‌شود؟

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

آیا OpenL می‌تواند فایل‌های PO را ترجمه کند؟

بله. OpenL PO Translator برای فایل‌های gettext .po ساخته شده و اعلام می‌کند که جای‌نگهدارها و متغیرها را هنگام ترجمه به بیش از ۱۰۰ زبان دست‌نخورده باقی می‌گذارد. این ابزار از جریان کاری ترجمه اسناد پرداخت به ازای استفاده بهره می‌برد، پس زمانی که حفظ ساختار PO مهم‌تر از انجام دستی همه مراحل است، برای تهیه پیش‌نویس سریع مناسب است. اگر فقط یک قالب .pot دارید، قبل از استفاده از OpenL یک فایل .po به زبان مقصد بسازید.

منابع

راهنمای GNU gettext: فایل‌های PO — توضیح رسمی gettext درباره فرمت فایل PO.
راهنمای GNU gettext: ورودی‌های فایل PO — مرجع برای msgid، msgstr، توضیحات، پرچم‌ها و ساختار ورودی‌ها.
راهنمای GNU gettext: ورودی‌ها با فرم‌های جمع — مرجع ساختار ورودی‌های فرم جمع.
راهنمای GNU gettext: اجرای msgfmt — مرجع برای msgfmt --check و اعتبارسنجی رشته‌های قالب.
OpenL PO Translator — صفحه محصول OpenL برای ترجمه فایل‌های .po با حفظ جای‌نگهدارها و متغیرها.
Poedit — سایت رسمی Poedit برای ویرایشگر ترجمه PO و نسخه حرفه‌ای آن.
راهنمای Polyglots وردپرس: Poedit — راهنمای وردپرس برای استفاده از Poedit، فایل‌های POT، فایل‌های PO، کامپایل MO و هشدارهای جای‌نگهدار.
مستندات Django: ترجمه — روند کاری Django برای فایل‌های پیام و ترجمه.
مستندات Django: compilemessages — مرجع دستور Django برای کامپایل فایل‌های .po به فایل‌های .mo.
مستندات Drupal: فایل‌های PO و POT — توضیح Drupal درباره فایل‌های .po، .pot، زمینه، فرم‌های جمع، توضیحات و متغیرها.
مستندات Weblate: GNU gettext PO — یادداشت‌های پلتفرم بومی‌سازی درباره هدرهای PO، رشته‌های منبع قبلی، رشته‌های منسوخ و فایل‌های MO تولیدشده.