ترجمة واجهة المستخدم

Pivotick يكتب نصًا خاصًا به: السكة، والقوائم، والشريط الجانبي، والجدول، واللوحة المحورية، التاريخ والأنخاب وكل title تلميح الأدوات وaria-label خلفهم. i18n الخيار يضع كل ذلك في لغتك.

const graph = new Pivotick(container, data, {
    i18n: { locale: 'fr' }, 
})

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

اللغات المجمعة

يتضمن كل إصدار ترجمات كاملة لواجهة المستخدم المضمنة:

اللغة	لغة	أمثلة على العلامات الإقليمية
الإنجليزية (الافتراضي)	en	en-GB, en-US
الصينية المبسطة	zh	zh-CN, zh-Hans
الفرنسية	fr	fr-FR, fr-CA
الألمانية	de	de-DE, de-CH
البرتغالية	pt	pt-BR, pt-PT
الهولندية	nl	nl-NL, nl-BE
اليابانية	ja	ja-JP
العربية	ar	ar-EG, ar-SA
الاسبانية	es	es-ES, es-MX

اضبط i18n.locale لاختيار واحد. تستخدم العلامات الإقليمية نفس كتالوج اللغة بينما الاحتفاظ بتنسيق الأرقام وفرزها وقواعد الجمع الخاصة بها. الكتالوج الصيني يستخدم أحرفًا مبسطة؛ لا توجد ترجمة صينية تقليدية منفصلة. لغة بدون كتالوج مجمع يستخدم اللغة الإنجليزية إلا إذا قمت بتوفير messages أو translate. يؤدي حذف locale إلى الاحتفاظ بالإعداد الافتراضي الحالي للغة الإنجليزية؛ لم يتم الكشف عن لغة المتصفح.

يتم تصدير الكتالوجات كـ messagesEn، messagesZh، messagesFr، messagesDe، messagesPt، messagesNl، messagesJa، messagesAr، messagesEs ومعاً كما bundledMessages، متاح أيضًا على Pivotick في إصدارات المتصفح.

الخيار

الملكية	اكتب	الافتراضي	الوصف
locale	string	'en'	علامة BCP 47 مثل 'fr' أو 'de-CH' أو 'pt-BR'. فهو يختار قواعد الجمع وكيفية كتابة الأرقام وكيفية فرز القوائم. عند تقديمه، يتم تعيينه أيضًا على أنه lang لجذر الرسم البياني.
messages	Partial<Messages>	{}	التجاوزات عن طريق المفتاح. تستخدم المفاتيح المفقودة اللغة المجمعة، ثم اللغة الإنجليزية.
translate	(key, params, fallback) => string | undefined		جسر إلى مكتبة الترجمة الخاصة بك، يطلب كل مفتاح messages لا يملك.

يتم تعيين اللغة عند إنشاء الرسم البياني. لتبديله اتصل على graph.destroy() وقم بالبناء الرسم البياني مرة أخرى مع الخيارات الجديدة.

كيف يتم العثور على الرسالة

يتم البحث عن كل جزء من النص بهذا الترتيب، وتفوز الإجابة الأولى:

1. الخيار الخاص بالميزة، عندما يكون بها خيار: UI.emptyState.render، UI.busyIndicator.label أو UI.simplify.typeLabel أو title وconfirmLabel أنت انتقل إلى ctx.confirm(). هذه أكثر تحديدًا من أي كتالوج.
2. messages، طاولة مفاتيحك.
3. translate، جسرك.
4. اللغة المجمعة، مختارة بواسطة locale.
5. الإنجليزية، عندما لا تحتوي اللغة على كتالوج مجمع.

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

المفاتيح والرسائل

تحتوي كل رسالة على مفتاح ثابت ومنقط يُسمى باسم المكان الذي تظهر فيه: 'contextMenu.node.pin'، 'history.menu.empty'، 'sidebar.neighbors.connections'. المفاتيح تمت كتابتها من الكتالوج الإنجليزي، لذا في TypeScript فشل المفتاح الذي به خطأ إملائي في التجميع و محررك يكمل الباقي.

تأخذ الرسالة أحد الأشكال الثلاثة.

النص مع العناصر النائبة

سلسلة تحتوي على {name} حيث تذهب القيمة:

messages: {
    'search.result.inGroup': 'dans {group}',
    'history.menu.count': '{count} sur {limit}',
}

تتم كتابة الرقم بالطريقة التي تكتبه بها اللغة المحلية قبل إدخاله: 1,234 ضمن 'en'، 1.234 تحت 'de'، 1 234 تحت 'fr'. سلسلة تدخل كما هو مكتوب.

صيغ الجمع

الرسالة التي تعتمد على العدد هي كائن ذو إدخال واحد لكل فئة جمع استخدامات اللغة. يتم اختيار الفئة من المعلمة count بواسطة المتصفح Intl.PluralRules، لذا فإن القواعد هي التي تحددها CLDR للغة. other هو مطلوبة، لأن كل لغة لديها ذلك.

// English and French need two forms; French counts zero as one
'count.nodes': { one: '{count} nœud', other: '{count} nœuds' },

// Polish needs four: 1 węzeł, 3 węzły, 5 węzłów, 1,5 węzła
'count.nodes': { one: '{count} węzeł', few: '{count} węzły', many: '{count} węzłów', other: '{count} węzła' },

الفئات هي zero، one، two، few، many و other. شكل ما تفعله اللغة لا يتم اختيار عدم الاستخدام أبدًا، ويعود المفقود إلى other.

تحتفظ لغة Fallback English بقواعد الجمع الإنجليزية تحت أي لغة. على سبيل المثال، غير معتمد اللغة التي تتعامل مع الصفر كمفرد لا تزال تحصل على "0 عقد" من النسخة الاحتياطية باللغة الإنجليزية.

وظيفة

بالنسبة لأي شيء لا يستطيع القالب قوله، يمكن أن تكون الرسالة وظيفة للمعاملات الأولية و الرسم البياني I18n:

'simplify.typeLabel': ({ count, type }, i18n) =>
    `${i18n.formatNumber(Number(count))} ${type === 'ip' ? 'adresses IP' : type}`,

مهما كان شكلها، الرسالة هي نص. يتم إدراجه كنص، ولا يتم تحليله أبدًا كـ HTML، لذا <b> يظهر كما هو مكتوب

تحرير ملفات ترجمة أمر الشراء

يحتوي دليل المستودع locales/ على قالب gettext، pivotick.pot، وكامل zh.po، fr.po، de.po، pt.po، nl.po، ja.po، ar.po و es.po الملفات. يتم شحن هذه الملفات أيضًا في الحزمة npm. افتح ملف .po في Poedit أو أي محرر نصوص UTF-8. كل msgctxt هو مفتاح الرسالة المستقر؛ msgid هو المصدر الإنجليزي و msgstr هي الترجمة. حافظ على {placeholders} سليمة. لإدخالات الجمع، ترجمة كل فتحة msgstr[n]: الصينية واليابانية لديها other فقط؛ اللغة العربية بها zero، one، two، few، many، ثم other؛ الفرنسية, الألمانية, البرتغالية والهولندية والإسبانية لديها one ثم other. يستخدم وقت التشغيل Intl.PluralRules، مع عودة الفئات المفقودة إلى other، بدلاً من تقييم رأس gettext على أنه JavaScript.

من الخروج المصدر مع npm ci مكتمل:

# Refresh the template and merge English changes into the PO files
npm run i18n:extract

# Edit locales/*.po, finish empty entries and review any fuzzy translations

# Compile PO files into the TypeScript catalogues used by every build
npm run i18n:compile

# Check completeness, source text, placeholders, plurals and generated files
npm run i18n:check
npm run test:i18n

قم بربط ملفات PO والقالب والملفات src/i18n/locales/*.ts التي تم إنشاؤها معًا. لا تقم بالتحرير الملفات التي تم إنشاؤها مباشرة. يحافظ الاستخراج على الترجمات والمترجم الموجود التعليقات، وتغيير النص الإنجليزي إلى fuzzy، وترك الإدخالات الجديدة فارغة. حل تلك الإدخالات قبل التجميع. يتم إسقاط المفاتيح التي تمت إزالتها من الكتالوج النشط. npm run build يعمل i18n:check، لذلك تفشل الترجمة غير الكاملة أو الكتالوج الذي تم إنشاؤه قديمًا بناء. تستخدم هذه الأوامر تبعيات العقدة الموجودة؛ ليست هناك حاجة إلى تثبيت gettext للنظام.

لتجميع لغة أخرى، أضف موقعها وتعيين فتحات الجمع إلى scripts/i18n.mjs، قم باستخراج وترجمة ملف PO الجديد، وتجميعه، ثم تصدير الكتالوج الذي تم إنشاؤه منه src/i18n/locales/index.ts وأضفه إلى bundledMessages. بالنسبة للغة التطبيق فقط، تمرير الكتالوج كـ i18n.messages لا يزال يعمل دون تغيير Pivotick.

بدء الكتالوج من messagesEn

يتم تصدير الكتالوج الإنجليزي كـ messagesEn، من إصدار ES وكما Pivotick.messagesEn من تصميمات المتصفح. يحمل كل مفتاح مع النص الإنجليزي الخاص به، و إنها بيانات بسيطة، لذا يمكن كتابتها كملف يبدأ منه المترجمون:

import { messagesEn } from 'pivotick'

console.log(JSON.stringify(messagesEn, null, 4))

قم بتحميل الملف المترجم مرة أخرى كـ messages. في TypeScript، تم الإعلان عن كتالوج بـ satisfies Messages يجب تسمية كل مفتاح، لذلك يظهر المفتاح المضاف في إصدار لاحق على هيئة خطأ في الترجمة بدلاً من سلسلة إنجليزية ضالة:

import type { Messages } from 'pivotick'

export const messagesFr = {
    'count.nodes': { one: '{count} nœud', other: '{count} nœuds' },
    // …every other key
} satisfies Messages

استخدم Partial<Messages> بدلاً من ذلك للترجمة أثناء تقدمك.

سد مكتبة الترجمة الخاصة بك

إذا كان تطبيقك يُترجم بالفعل من خلال مكتبة، فإن translate يحتفظ بمصدر واحد لـ الحقيقة وتبديل لغة واحدة. ويسمى لكل مفتاح لا يوجد فيه messages، مع:

• key: مفتاح الرسالة، مثل 'count.nodes'؛
• params: القيم الأولية، مع أرقام غير منسقة، لذلك رقم الجمع والرقم الخاص بمكتبتك تنطبق القواعد؛
• fallback: النص الإنجليزي، تم ملؤه بالفعل.

قم بإرجاع سلسلة لاستخدامها، أو undefined لاستخدام اللغة المجمعة ثم اللغة الإنجليزية. هنا مع i18next، الذي تقود معلمته count بالفعل جمعه:

const graph = new Pivotick(container, data, {
    i18n: {
        locale: i18next.language,
        translate: (key, params, fallback) => {
            const found = i18next.exists(`pivotick.${key}`)
            return found ? i18next.t(`pivotick.${key}`, params) : undefined
        },
    },
})

تقوم ملفات الموارد الخاصة بك بعد ذلك بكتابة رسائلها في بناء جملة مكتبتك الخاصة ("{{count}} nœuds" في i18next)، تحت نفس المفاتيح.

تم اكتشاف translate الذي يلقي: وحدة التحكم تقول أي مفتاح واللغة المجمعة (أو اللغة الإنجليزية للغة غير المدعومة). الخطاف لا يزال يستقبل اللغة الإنجليزية كما هي وسيطة fallback، مع الحفاظ على عقد الجسر. عندما يكون لدى كل من messages وtranslate مفتاح، يفوز messages ولا يُطلب من translate.

الأرقام والقوائم والفرز و lang

locale يغطي أكثر من مجرد كلمات. تحته:

• Counts مكتوبة بـ Intl.NumberFormat: "1,234 عقدة" باللغة الإنجليزية، "1.234 Knoten" باللغة الإنجليزية الألمانية. تستخدم لغة Fallback English أيضًا تنسيق الأرقام الخاص باللغة المحددة.
• قوائم من الأسماء في جملة واحدة مرتبطة بـ Intl.ListFormat: "أ، ب، ج"، "أ، ب وآخرون" ج".
• الفرز في الجدول، تستخدم قائمة الجيران وجزء الفرز المحوري Intl.Collator، لذلك يتم فرز "Émile" بجانب "Emma"، وتضع اللغة السويدية "ä" بعد "z"، ويأتي "item 10" بعده "البند 9".

عندما تعلن عن locale، يصبح العنصر الجذر للرسم البياني lang، وكذلك الأجزاء يتم تثبيت المكتبة خارج الجذر (تلميحات الأدوات، والقوائم المنسدلة، وقوائم الاقتراحات). قارئات الشاشة إذن اقرأ الواجهة بالصوت الصحيح. بدون locale، لا يتم تعيين lang: المكتبة النص باللغة الإنجليزية، لكن بياناتك الموجودة داخل الرسم البياني موجودة بلغة صفحتك ولغة الصفحة الخاص lang يصف ذلك بشكل أفضل.

التخطيط من اليمين إلى اليسار غير مدعوم: لا يوجد معالجة dir، والواجهة موضوعة من اليسار إلى اليمين في كل لغة.

لغة واحدة لكل رسم بياني

كل رسم بياني له لغته الخاصة. يمكن أن يستخدم رسمان بيانيان في صفحة واحدة لغتين، ولا يمكن استخدام أي منهما يؤثر على الآخر.

الرسم البياني الموجود داخل الرسم البياني يتحدث عن أصله: الرسم البياني الفرعي المرسوم داخل مجموعة، والصغير الرسم البياني للجيران في الشريط الجانبي.

يتم كتابة النص الذي تكتبه المكتبة في بياناتك مرة واحدة، بلغة الرسم البياني: التاريخ تسمية الإدخال ("Hid 3 عقد") والنص الذي تبدأ به الملاحظة الجديدة. إعادة بناء الرسم البياني في لغة أخرى تترك هؤلاء كما كانوا.

في الكود: graph.i18n والإضافات

graph.i18n هي لغة الرسم البياني، وهي نفس الكائن الذي تكتب به المكتبة:

عضو	ماذا يفعل
locale	العلامة المستخدمة: لك، أو 'en'.
t(key, params?)	نص الرسالة المضمنة، من خلال البحث أعلاه.
formatNumber(value, options?)	رقم في أرقام اللغة. يأخذ Intl.NumberFormat الخيارات.
formatList(items, options?)	تم ضم العناصر كجملة. يأخذ Intl.ListFormat الخيارات.
compare(a, b)	مقارنة بترتيب الإعدادات المحلية، يمكن تمريرها بأمان إلى sort كما هي.
collator(options?)	Intl.Collator خلف compare، رقم افتراضي.

يقرأ plugin نفس الكائن مثل ctx.i18n. النص الذي يكتبه البرنامج المساعد نفسه هو البرنامج المساعد للترجمة، اضغط على ctx.i18n.locale؛ تنسيق أعدادها وفرزها القوائم من خلال ctx.i18n تحافظ على اتساقها مع بقية الرسم البياني.

const nodeCounter = {
    name: 'node-counter',
    install(ctx) {
        const words = { fr: 'Total', de: 'Gesamt' }
        const label = words[ctx.i18n.locale.split('-')[0]] ?? 'Total'
        const count = ctx.i18n.formatNumber(ctx.graph.getNodes().length)
        // …draw `${label}: ${count}`
    },
}

ما يبقى كما هو

• بياناتك. يتم رسم تسميات العقدة والحافة وأسماء الخصائص وقيمها كما هي. أ اسم الخاصية بدون تسمية معلنة يكون مغلفًا بالعنوان من مفتاحه (first_seen يقرأ "المشاهدة لأول مرة")؛ أعلن nodePropertiesMap أو edgePropertiesMap للتسمية في لغتك. تتم كتابة الصف id الذي تضيفه قوائم الخصائص فوق المفاتيح الخاصة بك كمفتاح هو.
• نص المطور. تظل تحذيرات وحدة التحكم والأخطاء التي تم طرحها باللغة الإنجليزية.
• ** الحروف الرسومية الرئيسية.** ⌃ ⇧ ⌥ ⌘ تظهر كما هي. الأسماء الرئيسية هي الرسائل (keys.ctrlCombo، keys.escape)، لذلك يمكن للواجهة الألمانية أن تقول Strg+Z.
• عدد الشارات على حافة العقدة (2k، 99+)، والتي يجب أن تحتوي على ثلاثة أحرف.