مدونة

كيف يعيد localize.dev كتابة النصوص الثابتة دون كسر الكود الخاص بك

ما يعتبره المحرك نص واجهة مستخدم، وكيف يحرر ملفًا دون إعادة تنسيقه، وما يرفض تخمينه، ولماذا لا يؤدي التشغيل الثاني إلى تغيير أي شيء.

Stephen Ufort · 12 نوفمبر 2026 · 4 دقائق للقراءة

مكون قبل وبعد localize.dev: تم استبدال النص المكتوب بخط اليد باستدعاءات t()، وملفات اللغة التي كتبها

Pages CMS هو تطبيق Next.js مفتوح المصدر بدون i18n. قامت عملية تشغيل واحدة لـ npx localize-dev run --locales es,ar,zh-CN بنقل 535 سلسلة في 73 ملفًا إلى react-i18next: 395 مفتاحًا جديدًا، بالإضافة إلى 140 مكانًا أعادت استخدام مفتاح لأن نفس النص كان له واحد بالفعل. تم تجميع TypeScript قبل التشغيل وبعده. تم تخطي رسالتي تحقق، وقائمة طلب السحب تسردها مع السبب.

يمكنك فقط السماح للأداة بتعديل 73 ملفًا إذا كنت تثق في الفرق. تغطي هذه المشاركة كيف يقرر المحرك ما يجب تغييره، وكيف يقوم بالتغيير، ومتى يتوقف ويترك القرار لك.

القواعد تعيد كتابة الكود؛ النموذج يسمي المفاتيح ويترجم

كل ما يلمس ملفات المصدر الخاصة بك هو كود حتمي. لدى النموذج وظيفتان: اقتراح اسم مفتاح مثل settings.notifications_heading، والترجمة. لا يرى ملفًا كاملاً ولا يعدل واحدًا أبدًا، لذلك لا يمكنه إعادة تنسيق الكود الخاص بك أو إعادة تسمية متغير أو إسقاط استيراد.

العثور على النص الذي يراه الناس

يمر كل ملف عبر محلل للمكدس الخاص به. تمر JSX و TSX عبر @babel/parser. تمر قوالب Vue و Svelte و Angular و Astro و Ember عبر المترجم الخاص بكل إطار عمل، و HTML العادي عبر parse5. يتم ترميز العلامات ERB و Django و Blade وإخفاؤها أولاً، ثم تمر الصفحة عبر parse5 أيضًا. تتم قراءة Swift و Dart و Android باستخدام محللات أصغر مكتوبة يدويًا.

السلسلة في شجرة بناء الجملة ليست نص واجهة مستخدم تلقائيًا. القاعدة الرئيسية هي حول مكان انتهائها. يتم احتساب الحرفي عندما يصل إلى عنصر ابن JSX، أو سمة يقرأها الناس مثل placeholder، alt، title أو aria-label، وقد يمر عبر ثلاثي، &&، || أو أقواس في الطريق. اسم الفئة لا يصل إلى هناك أبدًا، ولا وسيطة لـ console.log أو لمكالمة تحليلية.

هذا المكون يأتي من مجموعة اختبار الماسح الضوئي. من بين جميع السلاسل فيه، يستخرج الماسح الضوئي واحدة:

test/scanner.test.ts
const A = ({ x }) => {
  console.log(`debug ${x}`);
  const label = 'Not in JSX';
  return <div className={`btn ${x}`} onClick={() => track('Clicked')}>
    <code>npm i</code><pre>raw</pre>
    <span translate="no">Brand</span>
    <div data-i18n-ignore><p>Skip me</p></div>
    <Trans>Already done</Trans>
    {t('existing.key')}
    {x ? 'primary' : 'secondary-btn'}
  </div>;
};
// extracted: ['primary']

كلا فرعي الثلاثي يصلان إلى المخرجات، لكن secondary-btn يفشل في مجموعة ثانية من المرشحات التي تنظر إلى القيمة نفسها. معرفات Snake و kebab و dotted لا تُحتسب أبدًا، ولا عناوين URL أو المسارات أو الألوان أو رسائل البريد الإلكتروني أو أسماء الملفات أو الأسعار أو الإصدارات أو قوائم الفئات. يُترك النص داخل code، pre أو <Trans>، أو تحت translate="no" أو data-i18n-ignore، بمفرده.

يصل بعض النص إلى الأشخاص من خلال الكود بدلاً من الترميز: toast()، alert()، confirm()، document.title، ورسائل التحقق في مخططات zod أو yup. يتعرف الماسح الضوئي على تلك من خلال المكالمة التي يتم تمريرها إليها.

التحرير دون إعادة طباعة الملف

الطريقة المعتادة لإعادة كتابة التعليمات البرمجية هي تغيير شجرة بناء الجملة وطباعتها مرة أخرى، مما يعيد تنسيق كل ما تلمسه الطابعة. لا تقوم localize.dev بطباعة الشجرة أبدًا. إنها تأخذ الإزاحات التي يبلغ عنها المحلل وتقوم بتقطيع كل تغيير في النص الأصلي باستخدام magic-string، بحيث تحتفظ كل سطر لا يتغير بتنسيقه الدقيق، بما في ذلك التعليقات.

هذا مكون صغير وما يكتبه المحرك له. تم تسمية المفاتيح هنا في وضع عدم الاتصال؛ في تشغيل فعلي، يقوم النموذج بتسميتها.

src/components/Settings.tsx (before)
export function Settings({ user }) {
  return (
    <section className="settings">
      <h2>Notifications</h2>
      <p>Signed in as {user.email}</p>
      <input placeholder="Search settings" />
      <p>Read the <a href="/help">help center</a> before you change these.</p>
    </section>
  );
}
src/components/Settings.tsx (after)
import { useTranslation, Trans } from 'react-i18next';

export function Settings({ user }) {
  const { t } = useTranslation();
  return (
    <section className="settings">
      <h2>{t('settings.notifications')}</h2>
      <p>{t('settings.signed_in_as', { email: user.email })}</p>
      <input placeholder={t('settings.search_settings')} />
      <p><Trans i18nKey="settings.read_the_help_center_before" components={{ a: <a href="/help" /> }} /></p>
    </section>
  );
}

أصبح {user.email} قيمة مسماة، لذا يرى المترجمون Signed in as {{email}} ويمكنهم نقله. ظلت الجملة التي تحتوي على الرابط كاملة كرسالة <Trans> واحدة، لأن المترجم يحتاج إلى الجملة الكاملة لوضع الرابط في المكان الصحيح.

يتبع إدخال t في النطاق التعليمات البرمجية الموجودة بالفعل. يتم إعادة استخدام const { t } = useTranslation() موجود في الدالة. بخلاف ذلك، يذهب سطر الخطاف قبل العبارة الأولى، ويتم فتح جسم سهم قصير لإفساح المجال له. تحصل مكونات خادم Next.js على await getTranslation() وتصبح async؛ تحصل المكونات الفئوية على withTranslation(). يذهب الاستيراد بعد آخر استيراد لك، وفقط إذا كان مفقودًا.

عندما لا يخمن

لا يمكن إعادة كتابة بعض السلاسل بأمان. يتم تخطي هذه السلاسل وإدراجها مع سبب. لا تحتوي الرسالة في مخطط تم إنشاؤه خارج أي مكون على t لاستدعائه في تلك النقطة، وهذا هو سبب تخطي سلسلتي Pages CMS. تشمل الأسباب الأخرى t التي تعني بالفعل شيئًا آخر في هذا النطاق، وثابت يتم تصديره أو قراءته بواسطة أكثر من مكون واحد، حيث يمكن أن يؤدي تغييرها إلى كسر القراء الآخرين.

تظهر السلاسل التي تم تخطيها في طلب السحب تحت "السلاسل التي تم تخطيها"، ويستمر localize-dev check في الإبلاغ عنها حتى يقوم شخص ما بنقلها.

تشغيله مرتين لا يغير شيئًا

بعد التشغيل، يكون النص t('key'). لا تصل السلسلة التي تم تمريرها إلى t() إلى الإخراج كحرف حرفي، لذا لا يلتقطها الماسح الضوئي مرة أخرى. يقوم خط الأنابيب فقط بتجميع السلاسل التي ليس لها مفتاح، أو المفاتيح التي تفتقد إلى ترجمة، ويتم ترك الملفات التي تساوى محتواها في النتيجة. يقوم جناح الاختبار بتشغيل المحرك على مخرجاته الخاصة ويتوقع عدم حدوث تغييرات.

التحقق من الترجمات قبل كتابتها

يتم فحص كل ترجمة مقابل مصدرها: العناصر النائبة، وعلامات الترميز، وكل صيغة جمع تحتاجها اللغة، وهي ست صيغ للغة العربية وصيغة واحدة للغة اليابانية. يُطلب من الترجمة التي تفشل مرة أخرى مع إرفاق السبب. إذا فشلت مرة أخرى، يتم حذفها والإبلاغ عنها، وعدم كتابتها أبدًا. يتناول منشور منفصل ذلك بالتفصيل.

ما يغادر جهازك

يتم تشغيل التحليل وإعادة الكتابة على جهازك أو مشغل CI الخاص بك. لكل سلسلة نصية، يحصل النموذج على النص مع العناصر النائبة الخاصة به، ومسار الملف، وتلميح قصير مثل "placeholder" attribute on <input> in component <Login>. لا يحصل على الكود المصدري الخاص بك. عمليات check و scan و --offline لا ترسل شيئًا.

ما لا يفعله

  • إخراج React و Next.js هو react-i18next. إذا كان تطبيقك يستخدم بالفعل react-intl أو next-intl أو Lingui، فلن يقوم localize.dev بالكتابة إليها.
  • يتم قراءة Swift و Dart و Android باستخدام المحللات (lexers)، وليس المترجمات الخاصة بها.
  • يتم سرد السلاسل النصية التي لا يمكنه وضعها، ونقلها متروك لك.

إذا أخطأ في الكود الخاص بك، أود رؤية الملف. يقوم الملعب بتشغيل هذا المحرك على الكود الذي تلصقه، بدون حساب.

جربه على الكود الخاص بك في الملعب، لا يلزم حساب