ترجمه‌ی محتوا

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

متأسفانه تیم اصلی BeeWare عمدتاً تک‌زبانهٔ انگلیسی‌زبان هستند. ما برای ترجمهٔ مستنداتمان به زبان‌های دیگر به کمک شما نیاز داریم.

ما از Weblate برای مدیریت ترجمه‌هایمان استفاده می‌کنیم. Weblate ابزاری است که به ما امکان می‌دهد هر پاراگراف از محتوای مستندات‌مان را به‌عنوان فهرستی از کارها در نظر بگیریم و آن‌ها را یکی‌یکی انجام دهیم.

ما از DeepL برای ترجمهٔ ماشینی و تولید اولین پیش‌نویس ترجمه‌ها استفاده می‌کنیم. ترجمه‌های ماشینی از کمال بسیار دور هستند، اما معمولاً به‌عنوان پیش‌نویس اول کافی‌اند. انتظار می‌رود این ترجمه‌های ماشینی ویرایش، بازبینی و در صورت لزوم بهبود یابند.

مشارکت در ترجمه‌ها

محتوا را ترجمه کنید

شروع به ترجمه

اگر مایلید در تلاش‌های ترجمه BeeWare مشارکت کنید، به یک حساب کاربری در Weblate نیاز دارید. اگر در حال حاضر حساب کاربری ندارید، یک حساب جدید ایجاد کنید؛ سپس به ما اطلاع دهید که علاقه‌مند به کمک در ترجمه‌ها هستید.

دو گزینه برای اطلاع‌رسانی به ما مبنی بر تمایل شما به کمک در ترجمه‌ها وجود دارد:

• اگر در دیسکورد هستید، به سرور [BeeWare] بپیوندید و به کانال (https://beeware.org/bee/chat/) بروید.
• اگر در دیسکورد نیستید، می‌توانید یک مشکل جدید در مخزن BeeWare ایجاد کنید.

در هر دو مورد، پیامی را که شامل اطلاعات زیر است، ارسال کنید:

• نام کاربری شما در Weblate
• زبانِ محتوایی که قصد دارید به آن ترجمه کنید

به محض اینکه این اطلاعات را دریافت کنیم، شما را به تیم اضافه خواهیم کرد.

افزودن یک ترجمهٔ جدید

اگر زبان مورد نظرتان برای کمک کردن هنوز وجود ندارد، قبل از شروع به کار، چند مرحله اضافی لازم است:

• فایل /docs/mkdocs.language-code.yml را با محتوای مخصوص به زبان ایجاد کنید.
• tox.ini را به‌روزرسانی کنید تا دستورات ساخت زبان جدید را شامل شود.
• /docs/config.yml را به‌روزرسانی کنید تا زبان را زیر extra: alternate: قرار دهید.

مثال زیر تغییرات لازم را با استفاده از زبان آلمانی نشان می‌دهد؛ یک ترجمه آلمانی از قبل موجود است؛ ارجاعات به آلمانی، de یا سایر محتوا را برای زبانی که هدف قرار داده‌اید جایگزین کنید.

یک فایل پیکربندی جدید MkDocs

ابتدا یک فایل جدید به نام mkdocs.de.yml را در دایرکتوری docs ایجاد کنید، با محتوای زیر:

INHERIT: config.yml
site_name: BeeWare Dokumentation
site_url: https://beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  translation_type: machine

در این فایل اتفاق می‌افتد:

• این فایل محتوای پیکربندی را از config.yml به ارث می‌برد.
• مقدار site_name ترجمه می‌شود.
• مقدار site_url نشانی وب سایت پروژه است که پس از آن کد زبان قرار می‌گیرد.
• docs_dir باید کد زبان باشد.
• مقدار theme: language: باید کد زبان باشد، همان‌طور که توسط تم Material در MkDocs مشخص شده است. برای اکثر زبان‌ها، این کد با کد زبان docs_dir یکسان خواهد بود؛ اما برای برخی (به‌ویژه زبان‌هایی با گونه‌های منطقه‌ای مانند zh_CN)، تفاوت‌هایی وجود دارد.
• extra: translation_type: باید تا زمانی که ترجمه برای اولین بار به ۱۰۰٪ برسد، به صورت machine باشد، در این نقطه باید به human تبدیل شود. اگر کیفیت ترجمه به زیر ۹۰٪ بازگردد، از machine به human بازمی‌گردد.

به‌روزرسانی tox.ini

شما باید چندین تغییر در فایل tox.ini ایجاد کنید.

شما موارد زیر را اضافه می‌کنید:

• پرچم محیط کد زبان جدید در خط سربرگی که با [testenv:docs شروع می‌شود، با کد زبان که با - پیش‌فرض شده و بدون هیچ فاصله‌ای، مثلاً -de.
• استثنای جدید کد زبان برای دستور اول، که با !lint آغاز می‌شود و قبل از آن -! قرار دارد و هیچ فاصله‌ای در آن نیست، مثلاً -!de
• کد زبان جدید تا انتهای خطی که با translate : build_po_translations شروع می‌شود.
• کد زبان جدید تا انتهای خط که با translate : update_machine_translations شروع می‌شود
• یک دستور جدید که برای مثال با de : build_md_translations برای زبان آلمانی آغاز می‌شود، پس از سایر دستورات اختصاصی زبان موجود که محتوای آن دستورات را با کد زبان جدید مطابقت می‌دهد.
• کد زبان جدید تا انتهای خطی که با all,serve : شروع می‌شود.

به‌روزرسانی config.yml

زبان را به config.yml اضافه کنید تا در انتخابگر زبان در هدر نمایش داده شود. بخش آغازشده با extra: را پیدا کنید، سپس زیربخشی را که با alternate: آغاز می‌شود بیابید. برای زبان آلمانی، موارد زیر را اضافه می‌کنید:

    - name: Deutsch
      link: /de/
      lang: de

نام زبان باید به آن زبان ترجمه شود. لینک باید شامل / باشد.

زبان جدید اکنون آمادهٔ شروع ترجمه است.

راهنمای ترجمه

پس از اینکه به تیم اضافه شدید، وقت آن است که وارد Weblate شوید و کار ترجمه رشته‌ها را آغاز کنید.

لحن در مقابل ترجمه کلمه‌به‌کلمه

حفظ لحن متن انگلیسی مهم‌تر از تلاش برای ترجمه کلمه‌به‌کلمه است. ما سعی می‌کنیم در محتوای خود صمیمی و کمی محاوره‌ای باشیم؛ در ترجمه‌هایتان سعی کنید روح همین سبک را حفظ کنید.

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

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

موارد زیر نباید ترجمه یا به‌روزرسانی شوند:

• دستورالعمل‌ها. برای مثال، در «شما باید `briefcase create` را اجرا کنید.»، تنها «شما باید اجرا کنید» باید ترجمه شود.
• فضاهای نام، مانند نام کلاس، متد یا ویژگی.
• URLهای لینک. لینک‌های استاندارد مارک‌داون باید در Weblate به‌صورت [Link text]{1} نمایش داده شوند، که در آن 1 موقعیت لینک در رشته را نسبت به سایر لینک‌های ممکن نشان می‌دهد. اگر URL کامل در رشته درج شده باشد، مانند [Link text](https://example.com)، باید از ترجمه آن صرف‌نظر شود.

• پیوندهای مرجع حاوی نام کلاس، متد یا ویژگی. این موارد باید بدون تغییر باقی بمانند، از جمله بک‌تیک‌ها. هر بخش از مثال لینک نمایش‌داده‌شده در اینجا ترجمه نخواهد شد.

  [`Class.attribute`][Class.attribute]
  

• محتوای پیوند مرجع. برای مثال، در موارد زیر link-content نادیده گرفته می‌شود:

  [Link text][link-content]
  

• دستورهای جینجا. این هرگونه محتوایی است که بین دو جفت براکت منحنی متناسب، یا یک جفت براکت منحنی تک‌تایی متناسب با نشانه‌های درصد در هر انتها قرار گرفته باشد. توجه: درج یک مثال از این نحو در اینجا باعث می‌شود افزونهٔ Macros تلاش کند آن را رندر کند؛ برای مثال‌ها به مستندات Macros مراجعه کنید.

• لنگرهای سفارشی. آن‌ها پس از هدرها یا بالای برخی محتوا قرار می‌گیرند و به صورت { #anchor } قالب‌بندی می‌شوند.

• دستور زبان تذکر. در مثال زیر، واژه «admonition» نباید ترجمه شود. این قاعده برای همه انواع تذکرات، از جمله یادداشت‌ها، هشدارها و غیره نیز صادق است. برای کسب اطلاعات درباره ترجمه سایر بخش‌های محتوا، به بخش بعدی مراجعه کنید.

  /// admonition | Page Title
  
  Content.
  
  ///
  

• بک‌تیک‌ها. آن‌ها قرار است به‌عنوان بک‌تیک باقی بمانند؛ برای قالب‌بندی هم کدهای درون‌خطی و هم بلوک‌های کد استفاده می‌شوند.

• نحوه درج محتوای خارجی. این هر چیزی است که در یک خط با -8<- قرار دارد، یا در خطوط بین دو -8<- در خطوط جداگانه.

موارد زیر باید ترجمه شوند:

• متن لینک. در نحو لینک، متن قبل از URL قرار می‌گیرد و در کروشه‌ها محصور می‌شود، مانند [Link text](URL). لینک‌های استاندارد مارک‌داون باید در Weblate به صورت [Link text]{1} نمایش داده شوند، جایی که 1 موقعیت لینک در رشته را با توجه به سایر لینک‌های ممکن نشان می‌دهد.

• متن پیوند مرجع. برای مثال، Link text به صورت زیر ترجمه می‌شود:

  [Link text][link-content]
  

• عناوین و محتوای هشدار. در مثال هشدار قبلی، «عنوان صفحه» و «محتوا.» باید ترجمه شوند.

وب‌لت

ما از Weblate برای ترجمه محتوای خود استفاده می‌کنیم. وقتی ترجمه جدیدی اضافه می‌کنیم، از DeepL برای ترجمه ماشینی استفاده می‌کنیم تا اولین پیش‌نویس ترجمه‌ها را تولید کند. این بدان معناست که معمولاً محتوایی که قرار است ترجمه کنید، قبلاً توسط ماشین ترجمه شده است. انتظار می‌رود که شما به‌عنوان مترجم، ترجمه ماشینی موجود را بازبینی، ویرایش و بهبود ببخشید.

وب‌لت همه چیز را به‌صورت رشته‌به‌رشته پردازش می‌کند. آن تغییرات را دسته‌ای جمع‌آوری می‌کند و هر چند ساعت یک‌بار یک commit دسته‌ای شامل همه رشته‌هایی که در آن بازه تغییر کرده‌اند را ارسال می‌کند. بنابراین ممکن است چند ساعت طول بکشد تا تغییرات شما در وب‌سایت نمایش داده شوند، اما می‌توانید انتظار داشته باشید که به‌روزرسانی ظرف چهار ساعت ظاهر شود.

اگر پس از آن مدت تغییرات شما هنوز ظاهر نشده‌اند، علت احتمالی یک خطای نشانه‌گذاری است که منجر به شکست در ساخت مستندات برای آن زبان شده است. هر مشکل نشانه‌گذاری در هر رشته مانع از عمومی شدن کل ترجمه می‌شود. می‌توانید صفحهٔ ساخت زبان خود را زیر نظر داشته باشید تا ببینید آیا با موفقیت ساخته شده است یا خیر. این لینک به شکل مشابهی با این لینک به صفحه ساخت نسخه فرانسوی فرمت شده است: https://app.readthedocs.org/projects/beewareorg/; کد زبان را به زبان خود تغییر دهید تا صفحه ساخت مناسب را مشاهده کنید. این کار وضعیت آخرین ساخت سایت را نشان می‌دهد. اگر ساخت با موفقیت انجام نشود، به گزارش ساخت (build log) نگاه کنید و ببینید آیا می‌توانید منبع مشکل را شناسایی کنید.