التنسيق القياسي

export interface TranslationBookChapter {
    /**
     * معلومات الترجمة الخاصة بفصل الكتاب.
     */
    translation: Translation;

    /**
     * معلومات الكتاب الخاصة بفصل الكتاب.
     */
    book: TranslationBook;

    /**
     * رابط الفصل الحالي.
     */
    thisChapterLink: string;

    /**
     * روابط لإصدارات صوتية مختلفة للفصل.
     */
    thisChapterAudioLinks: TranslationBookChapterAudioLinks;

    /**
     * روابط التوقيتات الصوتية للإصدارات الصوتية المختلفة للفصل.
     * يشير كل رابط إلى ملف التوقيتات الصوتية لهذا القارئ - انظر "الحصول على التوقيتات الصوتية لفصل ما" أدناه.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsLinks;

    /**
     * رابط الفصل التالي.
     * لا شيء إذا كان هذا هو الفصل الأخير في الترجمة.
     */
    nextChapterApiLink: string | null;

    /**
     * روابط لإصدارات صوتية مختلفة للفصل التالي.
     * لا شيء إذا كان هذا هو الفصل الأخير في الترجمة.
     */
    nextChapterAudioLinks: TranslationBookChapterAudioLinks | null;

    /**
     * روابط التوقيتات الصوتية للإصدارات الصوتية المختلفة للفصل التالي.
     * لا شيء إذا كان هذا هو الفصل الأخير في الترجمة.
     */
    nextChapterAudioTimings: TranslationBookChapterAudioTimingsLinks | null;

    /**
     * رابط الفصل السابق.
     * لا شيء إذا كان هذا هو الفصل الأول في الترجمة.
     */
    previousChapterApiLink: string | null;

    /**
     * روابط لإصدارات صوتية مختلفة للفصل السابق.
     * لا شيء إذا كان هذا هو الفصل الأول في الترجمة.
     */
    previousChapterAudioLinks: TranslationBookChapterAudioLinks | null;

    /**
     * روابط التوقيتات الصوتية للإصدارات الصوتية المختلفة للفصل السابق.
     * لا شيء إذا كان هذا هو الفصل الأول في الترجمة.
     */
    previousChapterAudioTimings: TranslationBookChapterAudioTimingsLinks | null;

    /**
     * رابط التعليقات التوضيحية على مستوى الكلمات للفصل.
     * يتم حذفها إذا لم يكن للفصل أي تعليقات توضيحية على مستوى الكلمات.
     */
    thisChapterWordsLink?: string;

    /**
     * رابط التعليقات التوضيحية على مستوى الكلمات للفصل التالي.
     * يتم حذف هذا الجزء إذا كان هذا هو الفصل الأخير في الترجمة، أو إذا لم يكن للفصل التالي أي تعليقات على مستوى الكلمات.
     */
    nextChapterWordsLink?: string;

    /**
     * رابط التعليقات التوضيحية على مستوى الكلمات للفصل السابق.
     * يتم حذف هذا الجزء إذا كان هذا هو الفصل الأول في الترجمة، أو إذا لم يكن للفصل السابق أي تعليقات على مستوى الكلمات.
     */
    previousChapterWordsLink?: string;

    /**
     * عدد الآيات التي يحتويها الفصل.
     */
    numberOfVerses: number;

    /**
     * رابط النسخة المبسطة من هذا الفصل.
     * يتم حذفها إذا لم تكن الفصول المبسطة متوفرة.
     */
    simpleChapterApiLink?: string;

    /**
     * المعلومات الخاصة بهذا الفصل.
     */
    chapter: ChapterData;
}

interface ChapterData {
    /**
     * رقم الفصل.
     */
    number: number;

    /**
     * محتوى الفصل.
     */
    content: ChapterContent[];

    /**
     * قائمة الحواشي السفلية للفصل.
     */
    footnotes: ChapterFootnote[];
}

/**
 * نوع اتحاد يمثل جزءًا واحدًا من محتوى الفصل.
 * يمكن أن يكون جزء من محتوى الفصل أحد الأشياء التالية:
 * - عنوان.
 * - فاصل أسطر.
 * - بيت شعري.
 * - ترجمة عبرية.
 */
type ChapterContent = ChapterHeading | ChapterLineBreak | ChapterVerse | ChapterHebrewSubtitle;

/**
 * عنوان في فصل.
 */
interface ChapterHeading {
    /**
     * يشير إلى أن المحتوى يمثل عنوانًا.
     */
    type: 'heading';

    /**
     * محتوى العنوان.
     * إذا تم تضمين عدة سلاسل نصية في المصفوفة، فيجب دمجها بمسافة.
     */
    content: string[];
}

/**
 * فاصل أسطر في الفصل.
 */
interface ChapterLineBreak {
    /**
     * يشير إلى أن المحتوى يمثل فاصل أسطر.
     */
    type: 'line_break';
}

/**
 * يوجد عنوان فرعي باللغة العبرية في أحد الفصول.
 * غالباً ما تُستخدم هذه المعلومات كجزء من المحتوى المعلوماتي الذي ظهر في المخطوطات الأصلية.
 * فعلى سبيل المثال، يحتوي المزمور 49 على العنوان الفرعي العبري "إلى قائد الجوقة. مزمور لبني قورح".
 */
interface ChapterHebrewSubtitle {
    /**
     * يشير هذا إلى أن المحتوى يمثل ترجمة عبرية.
     */
    type: 'hebrew_subtitle';

    /**
     * قائمة المحتويات الموجودة في العنوان الفرعي.
     * يمكن أن يكون كل عنصر في القائمة عبارة عن سلسلة نصية، أو نص منسق، أو مرجع حاشية سفلية.
     */
    content: (string | FormattedText | VerseFootnoteReference)[];
}

/**
 * آية في فصل.
 */
interface ChapterVerse {
    /**
     * يشير ذلك إلى أن المحتوى عبارة عن آية.
     */
    type: 'verse';

    /**
     * رقم الآية.
     */
    number: number;

    /**
     * قائمة محتويات الآية.
     * يمكن أن يكون كل عنصر في القائمة عبارة عن سلسلة نصية، أو نص منسق، أو مرجع حاشية سفلية.
     */
    content: (string | FormattedText | InlineHeading | InlineLineBreak | VerseFootnoteReference)[];
}

/**
 * النص المنسق. أي النص الذي تم تنسيقه بطريقة معينة.
 */
interface FormattedText {
    /**
     * النص المنسق.
     */
    text: string;

    /**
     * ما إذا كان النص يمثل قصيدة.
     * يشير الرقم إلى مستوى المسافة البادئة.
     *
     * شائع في المزامير.
     */
    poem?: number;

    /**
     * ما إذا كان النص يمثل كلمات يسوع.
     */
    wordsOfJesus?: boolean;
}

/**
 * يُعرّف واجهة تمثل عنوانًا مضمنًا في بيت شعري.
 */
interface InlineHeading {
    /**
     * نص العنوان.
     */
    heading: string;
}

/**
 * يُعرّف واجهة تمثل فاصل سطر مضمن في بيت شعري.
 */
interface InlineLineBreak {
    lineBreak: true;
}


/**
 * إشارة إلى حاشية في آية أو عنوان فرعي عبري.
 */
interface VerseFootnoteReference {
    /**
     * رقم تعريف المذكرة.
     */
    noteId: number;
}

/**
 * معلومات حول حاشية سفلية.
 */
interface ChapterFootnote {
    /**
     * رقم تعريف الملاحظة المشار إليها.
     */
    noteId: number;

    /**
     * نص الحاشية.
     */
    text: string;

    /**
     * مرجع الآية للحاشية.
     */
    reference?: {
        chapter: number;
        verse: number;
    };

    /**
     * المتصل الذي ينبغي استخدامه للحاشية السفلية.
     * بالنسبة للحواشي السفلية، فإن "المتصل" هو الحرف المستخدم في النص للإشارة إلى الحاشية السفلية.
     *
     * على سبيل المثال، في النص:
     * مرحباً بالعالم
     *
     * ---- (أ) هذه حاشية.
     *
     * "(أ)" هو المتصل.
     *
     * إذا كانت القيمة "+"، فيجب إنشاء المتصل تلقائيًا.
     * إذا كانت القيمة فارغة، فيجب أن يكون المتصل فارغًا.
     * إذا كانت سلسلة نصية، فيجب أن يكون المتصل هو تلك السلسلة النصية.
     */
    caller: '+' | string | null;
}

/**
 * روابط الصوت لفصل من كتاب.
 */
interface TranslationBookChapterAudioLinks {
    /**
     * قارئ الفصل ورابط URL لملف الصوت.
     */
    [reader: string]: string;
}

/**
 * روابط التوقيت الصوتي لفصل من كتاب.
 */
interface TranslationBookChapterAudioTimingsLinks {
    /**
     * قارئ الفصل ورابط واجهة برمجة التطبيقات (API) لملف التوقيتات الصوتية الخاص بهذا القارئ.
     */
    [reader: string]: string;
}

/**
 * يحدد التوقيتات الصوتية لفصل من كتاب، لقارئ واحد.
 * يتم ربطها بنقطة النهاية /api/{translation}/{book}/{chapter}.{reader}.audioTimings.json.
 */
export interface TranslationBookChapterAudioTimings {
    /**
     * معرّف الترجمة.
     */
    translationId: string;

    /**
     * رقم تعريف الكتاب.
     */
    bookId: string;

    /**
     * رقم الفصل.
     */
    chapterNumber: number;

    /**
     * معرف القارئ الذي تُخصص له هذه التوقيتات.
     */
    reader: string;

    /**
     * رابط ملف الصوت الذي تشير إليه هذه التوقيتات.
     */
    audioLink: string;

    /**
     * رابط المعلومات الخاصة بهذا الفصل.
     */
    thisChapterLink: string;

    /**
     * رابط معلومات الفصل التالي.
     * لا شيء إذا كان هذا هو الفصل الأخير في الترجمة.
     */
    nextChapterLink: string | null;

    /**
     * رابط معلومات الفصل السابق.
     * لا شيء إذا كان هذا هو الفصل الأول في الترجمة.
     */
    previousChapterLink: string | null;

    /**
     * رابط ملف التوقيت الصوتي هذا.
     */
    thisChapterAudioTimingsLink: string;

    /**
     * رابط لمواعيد الفصل التالي، لنفس القارئ.
     * لا شيء إذا كان هذا هو الفصل الأخير في الترجمة.
     */
    nextChapterAudioTimingsLink: string | null;

    /**
     * رابط لتوقيتات الفصل السابق، لنفس القارئ.
     * لا شيء إذا كان هذا هو الفصل الأول في الترجمة.
     */
    previousChapterAudioTimingsLink: string | null;

    /**
     * الأوقات بالثواني التي يبدأ عندها كل بيت شعري، بالترتيب.
     * الرقم الأول (الفهرس 0) هو الوقت في التسجيل الذي تبدأ فيه الآية الأولى.
     */
    verses: number[];
}

export interface TranslationBookChapterWords {
    /**
     * معرّف الترجمة.
     */
    translationId: string;

    /**
     * رقم تعريف الكتاب.
     */
    bookId: string;

    /**
     * رقم الفصل.
     */
    chapterNumber: number;

    /**
     * رابط المعلومات الخاصة بهذا الفصل.
     */
    thisChapterLink: string;

    /**
     * رابط معلومات الفصل التالي.
     * لا شيء إذا كان هذا هو الفصل الأخير في الترجمة.
     */
    nextChapterLink: string | null;

    /**
     * رابط معلومات الفصل السابق.
     * لا شيء إذا كان هذا هو الفصل الأول في الترجمة.
     */
    previousChapterLink: string | null;

    /**
     * رابط ملف الكلمات هذا.
     */
    thisChapterWordsLink: string;

    /**
     * رابط كلمات الفصل التالي.
     * قيمة فارغة إذا كان هذا هو الفصل الأخير في الترجمة، أو إذا لم يكن للفصل التالي أي تعليقات على مستوى الكلمات.
     */
    nextChapterWordsLink: string | null;

    /**
     * رابط كلمات الفصل السابق.
     * قيمة فارغة إذا كان هذا هو الفصل الأول في الترجمة، أو إذا لم يكن للفصل السابق أي تعليقات على مستوى الكلمات.
     */
    previousChapterWordsLink: string | null;

    /**
     * الكلمات المشروحة لكل آية في الفصل، مرتبة حسب رقم الآية.
     * كل قائمة مرتبة حسب ترتيب ورود الكلمات في الآية.
     */
    verses: {
        [verseNumber: string]: ChapterWord[];
    };
}

interface ChapterWord {
    /**
     * فهرس العنصر في مصفوفة محتوى الآية الذي ينطبق عليه التعليق التوضيحي.
     */
    contentIndex: number;

    /**
     * فهرس الحرف الأول من الكلمة المشروحة في نص عنصر المحتوى.
     */
    start: number;

    /**
     * الفهرس الذي يلي الحرف الأخير من الكلمة المشروحة في نص عنصر المحتوى.
     * أي أن text.slice(start, end) هي الكلمة المشروحة.
     */
    end: number;

    /**
     * رقم (أرقام) سترونغ للكلمة.
     * يتم حذفها إذا لم تقدم الترجمة سوى شروح أخرى للكلمة.
     */
    strongs?: string[];

    /**
     * الصيغة المعجمية (الاقتباسية) للكلمة.
     * يتم حذف النص إذا لم توفر الترجمة نصًا.
     */
    lemma?: string;

    /**
     * رمز تحليل الصرف للكلمة.
     * يتم حذف النص إذا لم توفر الترجمة نصًا.
     */
    morph?: string;

    /**
     * المؤشر إلى الكلمة في النص المصدر، بتنسيق <sourceName> : <location> .
     * يتم حذف النص إذا لم توفر الترجمة نصًا.
     */
    srcloc?: string;

    /**
     * أي تكرار للكلمة الأصلية يمثل هذه الكلمة؟ (يبدأ من 1).
     * يتم حذف النص إذا لم توفر الترجمة نصًا.
     */
    occurrence?: number;

    /**
     * إجمالي عدد مرات ظهور الكلمة المصدرية.
     * يتم حذف النص إذا لم توفر الترجمة نصًا.
     */
    occurrences?: number;
}

/**
 * يحدد بيانات تنزيل الترجمة الكاملة.
 * يتم الربط بنقطة النهاية /api/:translationId/complete.json.
 */
export interface TranslationComplete {
    /**
     * بيانات الترجمة الوصفية.
     */
    translation: Translation;

    /**
     * القائمة الكاملة للكتب مع جميع فصولها.
     */
    books: TranslationCompleteBook[];
}

/**
 * كتاب مترجم بالكامل للتحميل.
 */
export interface TranslationCompleteBook {
    /**
     * رقم تعريف الكتاب.
     */
    id: string;

    /**
     * اسم الكتاب من الترجمة.
     */
    name: string;

    /**
     * الاسم الشائع للكتاب.
     */
    commonName: string;

    /**
     * عنوان الكتاب.
     */
    title: string | null;

    /**
     * ترتيب الكتاب.
     */
    order: number;

    /**
     * عدد فصول الكتاب.
     */
    numberOfChapters: number;

    /**
     * العدد الإجمالي للآيات في الكتاب.
     */
    totalNumberOfVerses: number;

    /**
     * سواء كان الكتاب منسوباً إلى مصادر غير موثوقة أم لا.
     */
    isApocryphal?: boolean;

    /**
     * القائمة الكاملة للفصول مع جميع محتوياتها.
     */
    chapters: TranslationCompleteChapter[];
}

/**
 * فصل من الترجمة الكاملة المتاحة للتحميل.
 */
export interface TranslationCompleteChapter {
    /**
     * عدد الآيات التي يحتويها الفصل.
     */
    numberOfVerses: number;

    /**
     * روابط لإصدارات صوتية مختلفة للفصل.
     */
    thisChapterAudioLinks: TranslationBookChapterAudioLinks;

    /**
     * توقيتات الصوت (أوقات بدء كل مقطع، بالثواني) للإصدارات الصوتية المختلفة للفصل.
     *
     * بخلاف `thisChapterAudioTimings` في نقطة نهاية الفصل الفردية (التي ترتبط بـ "الحصول على توقيتات الصوت للفصل" أدناه)، يحتوي هذا على التوقيتات نفسها - لأن الهدف من تنزيل الترجمة الكاملة هو الحصول على كل شيء في ملف واحد.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsMap;

    /**
     * رابط التعليقات التوضيحية على مستوى الكلمات للفصل.
     * يتم حذفها إذا لم يكن للفصل أي تعليقات توضيحية على مستوى الكلمات.
     */
    thisChapterWordsLink?: string;

    /**
     * المعلومات الخاصة بهذا الفصل.
     */
    chapter: ChapterData;
}

/**
 * التوقيتات الصوتية لفصل من كتاب، مضمنة مباشرة بدلاً من ربطها.
 * يربط معرف القارئ بقائمة الأوقات (بالثواني) التي يبدأ فيها كل بيت شعري، حسب ترتيب الأبيات.
 */
interface TranslationBookChapterAudioTimingsMap {
    [reader: string]: number[];
}