کامپوننت Trans در i18next

سلام به همه توسعه‌دهندگان عزیز!

در مقاله قبلی، با قدرت تابع t در کتابخانه i18next آشنا شدیم و دیدیم که چطور میتونیم به سادگی متن‌ها و متغیرها را در اپلیکیشن React خود ترجمه کنیم، اما گاهی با چالشی فراتر از یک متن ساده روبرو می‌شویم.

فرض کنید می‌خواهید در یک جمله ترجمه شده، یک کلمه را bold کنید، یا یک لینک قرار دهید. در اینجاست که تابع t به تنهایی کافی نیست، زیرا فقط یک رشته (string) ساده را برمی‌گرداند.

اینجاست که react-i18next وارد صحنه می‌شود: و کامپوننت <Trans> رو معرفی میکنه.

کامپوننت Trans چیست و چرا به آن نیاز داریم؟

کامپوننت <Trans> ابزاری تخصصی برای مدیریت ترجمه‌هایی است که شامل عناصر JSX (مانند تگ‌های HTML یا دیگر کامپوننت‌های React) هستند. این کامپوننت به شما اجازه می‌دهد ساختار JSX خود را مستقیماً درون کامپوننت بنویسید و به i18next بگویید که چگونه متن‌ها و کامپوننت‌ها را با هم ترکیب کرده و ترجمه نهایی را رندر کند.

تفاوت کلیدی با تابع t:

• تابع t('key'): یک کلید می‌گیرد و یک رشته متنی برمی‌گرداند.

• کامپوننت <Trans>: محتوای JSX را به عنوان فرزند (children) می‌گیرد و یک عنصر React کامل را رندر می‌کند.

وقتی شما از <Trans> استفاده می‌کنید، i18next به طور هوشمند فرزندان آن را اسکن کرده و به قطعات مختلفی تقسیم می‌کند، مثل متن‌های ساده و کامپوننت‌ها. سپس یک کلید ترجمه استاندارد با تگ‌های ایندکس‌گذاری شده (مانند <0> و <1>) می‌سازد تا شما در فایل JSON خود از آن استفاده کنید.

مثال‌های کاربردی

بهترین راه برای درک قدرت <Trans>، دیدن آن در عمل است.

مثال ۱: قالب‌بندی ساده متن (مثل Bold یا Italic)

فرض کنید می‌خواهید این جمله را ترجمه کنید: "برای شروع، به داشبورد خود بروید."

کد JSX:

فایل ترجمه (مثلاً public/locales/fa/translation.json): i18next انتظار دارد کلید goToDashboard را به این شکل دریافت کند:

در اینجا <1> جایگزین تگ <strong> شده است. i18next به طور خودکار ترتیب عناصر را تشخیص داده و ایندکس‌گذاری می‌کند.

مثال ۲: استفاده از کامپوننت‌های React (یک لینک قابل کلیک)

این یکی از رایج‌ترین سناریوهاست. فرض کنید می‌خواهید کاربر قوانین و مقررات سایت را بپذیرد.

کد JSX:

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

حالا باید به کامپوننت <Trans> بگوییم که termsLink چیست. این کار با پراپرتی components انجام می‌شود:

کد JSX (تکمیل شده):

حالا <Trans> تگ <termsLink> را در رشته ترجمه پیدا کرده و آن را با کامپوننت <Link> که به آن پاس داده‌اید، جایگزین می‌کند.

مثال ۳: ترکیب کامپوننت‌ها با متغیرها (Interpolation)

می‌توانید به راحتی متغیرها را نیز با کامپوننت‌ها ترکیب کنید، به طور مثال

کد JSX:

فایل ترجمه:

در اینجا <1> معادل <strong> و <3> معادل <Link> است. متغیر username نیز مانند قبل استفاده می‌شود.

نکات کلیدی و بهترین روش‌ها (Tips & Best Practices)

1. چه زمانی از Trans استفاده کنیم؟ یک قانون طلایی: همیشه از تابع t استفاده کنید، مگر اینکه مجبور باشید! تابع t ساده‌تر و سریع‌تر است. فقط و فقط زمانی به سراغ <Trans> بروید که نیاز دارید عناصر JSX (مثل تگ‌ها, لینک‌ها یا کامپوننت‌های اختصاصی یا ... ) را درون یک رشته ترجمه قرار دهید. استفاده بیش از حد از آن می‌تواند کد شما را پیچیده کند و در سرعت Renderingتون تاثیرگذار باشد.

2. استفاده از نام‌های خوانا برای کامپوننت‌ها همانطور که در مثال ۲ دیدید، استفاده از پراپرتی components با نام‌های مشخص (مثل <termsLink>) بسیار بهتر از ایندکس‌های عددی (<1>) است. این کار فایل‌های ترجمه شما را برای خودتان و به خصوص برای مترجمان، بسیار خواناتر و قابل مدیریت‌تر می‌کند.

3. چگونه کلید ترجمه صحیح را پیدا کنیم؟ (نکته طلایی دیباگ) گاهی اوقات فهمیدن اینکه i18next دقیقاً منتظر چه ساختاری در فایل JSON شماست، دشوار است. بهترین راه برای این کار، فعال کردن حالت debug در تنظیمات i18next است.

   در فایل i18n.js خود، debug: true را اضافه کنید:

• حالا کنسول مرورگر خود را باز کنید. وقتی کامپوننت <Trans> رندر می‌شود و کلید خود را پیدا نمی‌کند، یک پیام missing key در کنسول چاپ می‌کند و دقیقاً همان رشته‌ای که انتظار دارد را به شما نشان می‌دهد. شما می‌توانید به سادگی آن را کپی کرده و در فایل JSON خود استفاده کنید!

• جملات کامل را ترجمه کنید سعی نکنید با ترکیب چند کلید ترجمه شده، یک جمله بسازید. این کار باعث شکننده شدن ترجمه‌ها می‌شود، زیرا ترتیب کلمات در زبان‌های مختلف متفاوت است. <Trans> شما را تشویq می‌کند که یک عبارت کامل و منسجم را ترجمه کنید که این یک روش صحیح در بین‌المللی‌سازی است.

جمع‌بندی

کامپوننت <Trans> یک ابزار تخصصی و ضروری در react-i18next است.
این کامپوننت پلی است بین دنیای استاتیک رشته‌های متنی و دنیای داینامیک کامپوننت‌های React.
با استفاده هوشمندانه از آن، می‌توانید تجربه‌های کاربری بسیار غنی، کاملاً تعاملی و به زیبایی ترجمه شده را برای تمام کاربران خود در سراسر جهان فراهم کنید.