الأساس
@better-translate/core يعمل في أي مشروع TypeScript. بلا اعتماد على إطار، بلا متطلبات وقت تشغيل. نفس الإعداد ونفس واجهة API سواء كنت في Next.js أو Astro أو React أو Bun أو Node.js أو سكربت أو أي بيئة TypeScript أخرى.
المحولات امتدادات للأساس تضيف مساعدات خاصة بالإطار: التوجيه المدرك للإعدادات المحلية، وسياق React، ومساعدات لكل طلب، وغير ذلك. لكن كل شيء مبني على نفس الأساس.
متى تستخدم الأساس مباشرة
استخدم الأساس دون محول عندما لا تحتاج مساعدات خاصة بالإطار. يشمل ذلك الخوادم وواجهات API والسكربتات والمكتبات المشتركة أو أي بيئة TypeScript لا يوجد لها محول.
1. تثبيت الحزمة
npm install @better-translate/core2. إنشاء ملف مترجم واحد
أنشئ src/i18n.ts:
1import { configureTranslations } from "@better-translate/core";23const en = {4 home: {5 title: "Hello",6 description: "This is the English version.",7 },8} as const;910const es = {11 home: {12 title: "Hola",13 description: "Esta es la version en espanol.",14 },15} as const;1617export const translator = await configureTranslations({18 availableLocales: ["en", "es"] as const,19 defaultLocale: "en",20 fallbackLocale: "en",21 messages: { en, es },22});3. استخدام المترجم في أي مكان
1import { translator } from "./i18n";23translator.t("home.title"); // "Hello"4translator.t("home.title", { locale: "es" }); // "Hola"5translator.t("home.description", { locale: "es" });4. إضافة إعداد محلي لاحقًا
1const fr = {2 home: {3 title: "Bonjour",4 description: "Ceci est la version francaise.",5 },6} as const;78export const translator = await configureTranslations({9 availableLocales: ["en", "es", "fr"] as const,10 defaultLocale: "en",11 fallbackLocale: "en",12 messages: { en, es, fr },13});سلوك الاحتياط
إذا لم يكن للإعداد المحلي النشط مفتاح، يجرب better-translate إعداد الاحتياط. إذا لم يكن الاحتياط يحتويه أيضًا، يعيد سلسلة المفتاح نفسها.
- → قيمة ناقصة في الإعداد المحلي → قيمة إعداد الاحتياط
- → قيمة ناقصة في الاحتياط → سلسلة المفتاح
محمّلات غير متزامنة
سجّل محمّلات الإعدادات المحلية للغات التي لا تريد تحميلها مسبقًا. تُخزَّن الإعدادات المحلية المحمّلة في الذاكرة المؤقتة بعد أول تحميل ناجح.
1const translator = await configureTranslations({2 availableLocales: ["en", "fr"] as const,3 defaultLocale: "en",4 messages: { en },5 loaders: {6 fr: async () => import("./messages/fr").then((m) => m.default),7 },8});910// يحمّل fr عند الطلب ويخزّنه11await translator.loadLocale("fr");5. استخراج النصوص تلقائيًا بواجهة سطر الأوامر
بدل تسمية المفاتيح يدويًا، علّم النصوص بـ { bt: true } ودع واجهة سطر الأوامر تستخرجها وتُنشئ مفاتيحها:
1import { t } from "@better-translate/core";23// اكتب النص المصدر مباشرة — واجهة سطر الأوامر تحوّله إلى مفتاح صحيح4t("Hello world", { bt: true });شغّل npx bt extract لمزامنة النصوص في ملف الإعداد المحلي المصدر وإعادة كتابة الاستدعاءات إلى مفاتيح صحيحة. راجع وثائق واجهة سطر الأوامر للإعداد الكامل.
تابع مع
أمثلة
- core-elysia-example — إعداد TypeScript/Node.js عادي