"use i18n";

يمكّن توجيه "use i18n" من توطين مكونات React ملفًا تلو الآخر دون إعادة هيكلة الشفرة البرمجية الحالية. تمامًا مثل "use client" أو "use server"، ما عليك سوى إضافته في أعلى الملف لتوطين جميع المحتوى القابل للترجمة في ذلك المكون تلقائيًا.

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

كيف يعمل

عندما تضيف "use i18n" إلى أعلى ملف React، يقوم مترجم Lingo.dev تلقائيًا بما يلي:

  1. فحص الملف بأكمله بحثًا عن المحتوى القابل للترجمة
  2. استخراج نص JSX والسمات القابلة للترجمة
  3. إنشاء ترجمات باستخدام نموذج الذكاء الاصطناعي المُكوّن
  4. حقن النسخ المترجمة في وقت البناء
  5. الحفاظ على استبدال الوحدات الساخنة للتطوير السلس

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

تمكين التوجيه

لاستخدام توجيه "use i18n"، قم بتمكينه في تكوين المترجم الخاص بك:

{
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  useDirective: true, // تمكين توجيه "use i18n"
  models: "lingo.dev", // الخيار 1: محرك Lingo.dev
  // models: {
  //   "*:*": "groq:qwen/qwen3-32b", // الخيار 2: GROQ
  //   "*:*": "google:gemini-2.0-flash", // الخيار 2: Google AI
  //   "*:*": "openrouter:mistralai/mistral-small-24b-instruct-2501", // الخيار 2: OpenRouter
  //   "*:*": "ollama:mistral-small3.1", // الخيار 2: Ollama
  //   "*:*": "mistral:mistral-small-latest", // Mistral
  // },
}

ملاحظة: عندما يتم تعيين useDirective إلى false (الإعداد الافتراضي)، يعالج مترجم Lingo.dev جميع الملفات كما لو كان لديها "use i18n" في الأعلى. يمنحك تعيين useDirective: true تحكمًا دقيقًا لتوطين الملفات بشكل فردي.

تكوين النموذج: يمكنك استخدام إما محرك Lingo.dev مع بناء جملة مبسط (models: "lingo.dev") أو نماذج من مزودي LLM البديلين مع تعيين نموذج محدد (مثل models: { "*:*": "groq:qwen/qwen3-32b" }، انظر أعلاه). يختار المحرك تلقائيًا النماذج المثلى لكل زوج من اللغات.

الاستخدام الأساسي

أضف التوجيه في أعلى أي ملف مكون React:

"use i18n";

import React from "react";

export function WelcomeCard() {
  return (
    <div className="card">
      <h2>Welcome to our app!</h2>
      <p>
        Get started by exploring our features and discovering what makes our
        platform special.
      </p>
      <button>Get Started</button>
    </div>
  );
}

ملاحظة: أضف "use i18n" في أعلى الملف الذي يقوم بعرض <LingoProvider>.

هذا كل شيء! سيقوم المكون الآن تلقائيًا بالعرض بلغة المستخدم المحددة دون أي تغييرات في الكود.

يعمل مع التوجيهات الحالية

يعمل توجيه "use i18n" بشكل طبيعي جنبًا إلى جنب مع توجيهات React الأخرى التي قد تكون لديك بالفعل:

"use client";
"use i18n";

export function InteractiveComponent() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <h1>Click Counter</h1>
      <p>You've clicked {count} times</p>
      <button onClick={() => setCount(count + 1)}>Click me!</button>
    </div>
  );
}

"use server";
"use i18n";

export async function ServerComponent() {
  const data = await fetchData();

  return (
    <div>
      <h1>Server-rendered Content</h1>
      <p>This content is rendered on the server and localized at build time</p>
    </div>
  );
}

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

سير عمل التطوير

1. الترحيل التدريجي

ابدأ بإضافة التوجيه إلى المكونات الفردية:

// قبل: مكون باللغة الإنجليزية فقط
export function Header() {
  return <h1>My Application</h1>;
}

// بعد: مكون متعدد اللغات بسطر واحد
("use i18n");

export function Header() {
  return <h1>My Application</h1>;
}

2. استبدال الوحدة الساخن

يعمل التوجيه بسلاسة مع HMR. عندما تقوم بتعديل النص في مكون يحتوي على "use i18n"، يتم تحديث الترجمات فورًا في متصفحك:

"use i18n";

export function StatusMessage() {
  return (
    <div>
      {/* قم بتغيير هذا النص وشاهده يتحدث بجميع اللغات فورًا */}
      <p>Your changes have been saved successfully!</p>
    </div>
  );
}

3. نهج ملف تلو الآخر

مثالي لقواعد الشفرة البرمجية الكبيرة حيث ترغب في الترجمة بشكل تدريجي:

src/
├── components/
│   ├── Header.tsx          // ✅ "use i18n" - تمت الترجمة
│   ├── Navigation.tsx      // ✅ "use i18n" - تمت الترجمة
│   ├── ProductCard.tsx     // ✅ "use i18n" - تمت الترجمة
│   ├── Footer.tsx          // ⏳ لم تتم الترجمة بعد
│   └── Sidebar.tsx         // ⏳ لم تتم الترجمة بعد

المزايا

يجعل توجيه "use i18n" عملية الترجمة بسيطة مثل إضافة سطر واحد إلى مكونات React الخاصة بك، وهو مصمم للمشاريع الناضجة التي تتطلب ترجمة تدريجية.

الخطوات التالية