Better Translateالرئيسية
GitHub
البدء
  • المقدمة
  • المهمة
  • التثبيت
  • CLI
  • المهارات
  • RTL
  • سجل التغييرات
المحولات
  • الأساس
  • React
  • Expo
  • Astro
  • MD & MDX
  • Next.js
  • TanStack Router

Core

@better-translate/core يعمل في أي مشروع TypeScript. لا يوجد اعتماد على إطار عمل، ولا يوجد متطلب وقت تشغيل. نفس الإعدادات ونفس واجهة البرمجة تنطبق سواء كنت في Next.js أو Astro أو React أو Bun أو Node.js أو سكربت أو أي بيئة TypeScript أخرى.

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

متى تستخدم النواة مباشرة

استخدم النواة بدون محول عندما لا تحتاج إلى مساعدات خاصة بالإطار. يشمل ذلك الخوادم، وواجهات برمجة التطبيقات، والسكربتات، والمكتبات المشتركة، أو أي بيئة TypeScript حيث لا يوجد محول لإعدادك.

1. تثبيت الحزمة

npm install @better-translate/core

2. إنشاء ملف مترجم واحد

أنشئ src/i18n.ts:

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. استخدام المترجم في أي مكان

ts
1import { translator } from "./i18n";23translator.t("home.title"); // "Hello"4translator.t("home.title", { locale: "es" }); // "Hola"5translator.t("home.description", { locale: "es" });

4. تحديث src/i18n.ts لإضافة لغة أخرى لاحقاً

ts
1const fr = {2  home: {3    title: "Bonjour",4    description: "Ceci est la version francaise.",5  },6} as const;78// استبدل تعريف translator السابق بهذا التعريف المحدّث9export const translator = await configureTranslations({10  availableLocales: ["en", "es", "fr"] as const,11  defaultLocale: "en",12  fallbackLocale: "en",13  messages: { en, es, fr },14});

سلوك اللغة الاحتياطية

إذا لم يكن للغة النشطة مفتاح معين، يحاول better-translate اللغة الاحتياطية. إذا لم تكن اللغة الاحتياطية تحتوي عليه أيضاً، يُرجع سلسلة المفتاح نفسها.

  • → قيمة اللغة مفقودة → قيمة اللغة الاحتياطية
  • → قيمة اللغة الاحتياطية مفقودة → سلسلة المفتاح

محمّلات غير متزامنة

سجّل محمّلات اللغات للغات لا تريد تحميلها مسبقاً. يتم تخزين اللغات المحمّلة مؤقتاً بعد أول تحميل ناجح.

ts
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. استخراج السلاسل تلقائياً باستخدام CLI

بدلاً من تسمية المفاتيح يدوياً، علّم السلاسل بـ { bt: true } ودع CLI يستخرجها ويسمّيها تلقائياً:

ts
1import { t } from "@better-translate/core";23// اكتب السلسلة المصدر مباشرة — CLI يحوّلها إلى مفتاح صحيح4t("Hello world", { bt: true });

شغّل npx bt extract لمزامنة السلاسل في ملف اللغة المصدر وإعادة كتابة الاستدعاءات إلى مفاتيح صحيحة. راجع وثائق CLI للإعداد الكامل.

استمر مع

  • مزود React والخطافات
  • إعداد Next.js App Router
  • مساعدات طلب Astro

أمثلة

  • core-elysia-example — إعداد TypeScript/Node.js بسيط