Skip to main content

Vue i18n: إعداد التدويل الكامل مع vue-i18n

من التثبيت إلى الإنتاج: هيّئ vue-i18n مع Composition API، وتعامل مع صيغ الجمع وفق قواعد CLDR، واستخدم إقحام المكوّنات، وأضف سلاسل ارتداد ذكية للغات.

1

ثبّت vue-i18n

vue-i18n هو المكوّن الإضافي الرسمي للتدويل في Vue.js. يوفر ترجمات تفاعلية، وصيغ جمع بنمط ICU، وإقحام المكوّنات، وتنسيق التاريخ والوقت والأرقام، ويدعم كلاً من Options API وComposition API.

Terminal
npm install vue-i18n@9
2

هيّئ vue-i18n

أنشئ مثيل i18n باستخدام createI18n() وسجّله كمكوّن إضافي في Vue. عرّف رسائل اللغات، وحدد اللغة الافتراضية، وهيّئ اللغة الاحتياطية. يدعم vue-i18n كلاً من وضع legacy (Options API) ووضع composition (Composition API).

src/i18n.ts
// src/i18n.ts
import { createI18n } from 'vue-i18n'
import en from './locales/en.json'
import de from './locales/de.json'

const i18n = createI18n({
  legacy: false,           // Use Composition API mode
  locale: 'en',            // Default locale
  fallbackLocale: 'en',   // Fallback locale
  messages: { en, de },
})

export default i18n
src/main.ts
// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import i18n from './i18n'

const app = createApp(App)
app.use(i18n)
app.mount('#app')
إذا ظهرت أخطاء 'Not available in legacy mode' فهذا يعني أنك تمزج استدعاءات i18n الخاصة بـ Composition API (useI18n()) مع تهيئة وضع legacy. عيّن legacy: false في createI18n() لاستخدام وضع Composition API، أو التزم بصياغة $t() الخاصة بـ Options API بشكل متسق.
3

استخدام الترجمات في القوالب

يوفر vue-i18n الدالة $t() داخل القوالب (Options API) والدالة t() من useI18n() (Composition API). تقبل كلتاهما مفتاح الترجمة ومعلمات اختيارية مسماة أو قائمة للإقحام.

src/locales/en.json
// src/locales/en.json
{
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "greeting": "Hello, {name}!",
  "cart": {
    "itemCount": "no items | one item | {count} items"
  }
}

// src/locales/de.json
{
  "nav": {
    "home": "Startseite",
    "about": "Über uns",
    "settings": "Einstellungen"
  },
  "greeting": "Hallo, {name}!",
  "cart": {
    "itemCount": "keine Artikel | ein Artikel | {count} Artikel"
  }
}
4

التعامل مع صيغ الجمع

يدعم vue-i18n صيغ الجمع عبر صيغ مفصولة بعلامة الأنبوب ودالة $tc() (legacy) أو الدالة t() مع معامل count (Composition API). عرّف صيغ الجمع في رسائل اللغة باستخدام الفاصل الأنبوبي: 'no items | one item | {count} items'.

MyComponent.vue
<template>
  <div>
    <!-- Simple translation -->
    <h1>{{ $t('nav.home') }}</h1>

    <!-- With variables -->
    <p>{{ $t('greeting', { name: userName }) }}</p>

    <!-- In attributes -->
    <input :placeholder="$t('nav.settings')" />

    <!-- Composition API -->
    <p>{{ greeting }}</p>
  </div>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { t } = useI18n()
const userName = 'Alice'
const greeting = t('greeting', { name: userName })
</script>
صيغة الجمع المفصولة بعلامة الأنبوب تدعم جمع الأعداد الأساسية (cardinal) بما يصل إلى ثلاث صيغ فقط (zero | one | other). بالنسبة إلى اللغات ذات قواعد جمع CLDR المعقدة (العربية، الروسية، البولندية)، استخدم صياغة ICU MessageFormat أو المعدّل @.plural مع تعيينات صريحة لفئات CLDR.
5

أضف سلاسل ارتداد للغة

يدعم fallbackLocale المدمج في vue-i18n قائمة مسطحة من لغات الارتداد، وليس سلاسل لكل لغة على حدة. فمستخدم pt-BR الذي يواجه مفتاحاً مفقوداً يعود إلى الإنجليزية بدلاً من pt-PT. يضيف vue-i18n-locale-chain سلاسل دمج عميق قابلة للتهيئة لضمان أن يرى المستخدمون الإقليميون دائماً أقرب ترجمة متاحة.

Plurals.vue
<template>
  <div>
    <!-- Pipe-separated plurals -->
    <p>{{ $t('cart.itemCount', count) }}</p>

    <!-- Named plurals (recommended for complex languages) -->
    <p>{{ $t('orders', { n: orderCount }) }}</p>
  </div>
</template>

<!-- In your locale file: -->
<!-- "orders": "{n} order | {n} orders" -->
تُجري vue-i18n-locale-chain دمجاً عميقاً للرسائل عند وقت التحميل. ويقوم نظام التفاعلية في vue-i18n بتخزين مجموعة الرسائل المدمجة مؤقتاً، لذا لا توجد كلفة أداء وقت التشغيل لعمليات البحث عبر الارتداد.
6

أتمتة الترجمات

بعد تهيئة vue-i18n، ترجم ملفات JSON الخاصة باللغات باستخدام AI. من IDE، اطلب من مساعد AI ترجمة الملف المصدر، أو ادمج الترجمة في خط CI/CD للحصول على توطين مؤتمت بالكامل.

LanguageSwitcher.vue
<template>
  <select v-model="locale">
    <option v-for="lang in availableLocales" :key="lang" :value="lang">
      {{ lang }}
    </option>
  </select>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { locale, availableLocales } = useI18n()
</script>
src/i18n.ts (lazy loading)
// src/i18n.ts
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  legacy: false,
  locale: 'en',
  fallbackLocale: 'en',
  messages: {},
})

export async function loadLocale(locale: string) {
  const messages = await import(`./locales/${locale}.json`)
  i18n.global.setLocaleMessage(locale, messages.default)
  i18n.global.locale.value = locale
}

export default i18n
7

تهيئة سلسلة ارتداد للغة

هيّئ سلاسل ارتداد لكل لغة بحيث يرى المستخدمون الإقليميون أقرب ترجمة متاحة بدلاً من الانتقال مباشرة إلى الإنجليزية. يدعم vue-i18n نمط الكائن لـ fallbackLocale لتعريف سلاسل لكل لغة.

src/i18n.ts
// src/i18n.ts
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  legacy: false,
  locale: 'pt-BR',
  fallbackLocale: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant-TW': ['zh-Hant', 'zh', 'en'],
    'es-419': ['es', 'en'],
    default: ['en'],
  },
  messages: {
    en: { /* ... */ },
    pt: { /* ... */ },
    'pt-BR': { /* ... */ },
  },
})
يتيح كائن fallbackLocale تعريف سلاسل مختلفة للغات مختلفة. يعود مستخدم pt-BR إلى pt ثم en، بينما يعود مستخدم zh-Hant-TW إلى zh-Hant ثم zh ثم en.

المزالق الشائعة

مزج وضعي Legacy وComposition API

إن استخدام useI18n() مع legacy: true (الإعداد الافتراضي) يسبب أخطاء. عيّن legacy: false في createI18n() إذا كنت تستخدم Composition API، أو التزم باستخدام $t() في القوالب مع Options API. لا تمزج الوضعين داخل التطبيق نفسه.

استخدام v-html للسلاسل المترجمة

إن استخدام v-html لعرض الترجمات التي تتضمن HTML يمثل خطراً من نوع XSS إذا كانت أي قيم إقحام تأتي من إدخال المستخدم. استخدم المكوّن &lt;i18n-t&gt; للترجمات التي تتضمن HTML مُضمناً أو مكوّنات Vue—فهو آمن افتراضياً ويدعم تضمين المكوّنات بشكل تفاعلي.

المستخدمون الإقليميون يرون الإنجليزية بدلاً من لغة الأصل

إن fallbackLocale في vue-i18n عبارة عن قائمة مسطحة وليست سلسلة لكل لغة. يعود pt-BR إلى ما هو موجود في القائمة (عادة 'en')، متجاوزاً pt-PT بالكامل. استخدم vue-i18n-locale-chain لإضافة ارتداد إقليمي صحيح مع دمج عميق.

جرّب i18n Agent الآن

أفلت ملف الترجمة هنا

JSON, YAML, PO, XML, CSV, Markdown, Properties

أو انقر للاستعراض

اللغات المستهدفة

لا حاجة إلى التسجيلتقدير فوري

الأسئلة الشائعة حول Vue i18n