Muundo wa Kawaida

export interface TranslationBookChapter {
    /**
     * Taarifa za tafsiri ya sura ya kitabu.
     */
    translation: Translation;

    /**
     * Taarifa za kitabu kwa ajili ya sura ya kitabu.
     */
    book: TranslationBook;

    /**
     * Kiungo cha sura ya sasa.
     */
    thisChapterLink: string;

    /**
     * Viungo vya matoleo tofauti ya sauti kwa sura hiyo.
     */
    thisChapterAudioLinks: TranslationBookChapterAudioLinks;

    /**
     * Viungo vya muda wa sauti kwa matoleo tofauti ya sauti kwa sura hiyo.
     * Kila kiungo kinaelekeza kwenye faili ya muda wa sauti kwa msomaji huyo - tazama "Pata Muda wa Sauti kwa Sura" hapa chini.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsLinks;

    /**
     * Kiungo cha sura inayofuata.
     * Bati ikiwa hii ndiyo sura ya mwisho katika tafsiri.
     */
    nextChapterApiLink: string | null;

    /**
     * Viungo vya matoleo tofauti ya sauti kwa sura inayofuata.
     * Bati ikiwa hii ndiyo sura ya mwisho katika tafsiri.
     */
    nextChapterAudioLinks: TranslationBookChapterAudioLinks | null;

    /**
     * Viungo vya muda wa sauti kwa matoleo tofauti ya sauti kwa sura inayofuata.
     * Bati ikiwa hii ndiyo sura ya mwisho katika tafsiri.
     */
    nextChapterAudioTimings: TranslationBookChapterAudioTimingsLinks | null;

    /**
     * Kiungo cha sura iliyotangulia.
     * Bati ikiwa hii ndiyo sura ya kwanza katika tafsiri.
     */
    previousChapterApiLink: string | null;

    /**
     * Viungo vya matoleo tofauti ya sauti kwa sura iliyotangulia.
     * Bati ikiwa hii ndiyo sura ya kwanza katika tafsiri.
     */
    previousChapterAudioLinks: TranslationBookChapterAudioLinks | null;

    /**
     * Viungo vya muda wa sauti kwa matoleo tofauti ya sauti kwa sura iliyopita.
     * Bati ikiwa hii ndiyo sura ya kwanza katika tafsiri.
     */
    previousChapterAudioTimings: TranslationBookChapterAudioTimingsLinks | null;

    /**
     * Kiungo cha maelezo ya kiwango cha neno kwa sura hiyo.
     * Imeachwa ikiwa sura haina maelezo yoyote ya kiwango cha neno.
     */
    thisChapterWordsLink?: string;

    /**
     * Kiungo cha maelezo ya kiwango cha neno kwa sura inayofuata.
     * Imeachwa ikiwa hii ndiyo sura ya mwisho katika tafsiri, au ikiwa sura inayofuata haina maelezo yoyote ya kiwango cha maneno.
     */
    nextChapterWordsLink?: string;

    /**
     * Kiungo cha maelezo ya kiwango cha neno kwa sura iliyotangulia.
     * Imeachwa ikiwa hii ni sura ya kwanza katika tafsiri, au ikiwa sura iliyotangulia haina maelezo yoyote ya kiwango cha maneno.
     */
    previousChapterWordsLink?: string;

    /**
     * Idadi ya mistari ambayo sura hiyo ina.
     */
    numberOfVerses: number;

    /**
     * Kiungo cha toleo lililorahisishwa la sura hii.
     * Imeachwa ikiwa sura zilizorahisishwa hazipatikani.
     */
    simpleChapterApiLink?: string;

    /**
     * Taarifa kwa ajili ya sura.
     */
    chapter: ChapterData;
}

interface ChapterData {
    /**
     * Idadi ya sura.
     */
    number: number;

    /**
     * Maudhui ya sura hiyo.
     */
    content: ChapterContent[];

    /**
     * Orodha ya maelezo ya chini ya sura hiyo.
     */
    footnotes: ChapterFootnote[];
}

/**
 * Aina ya muungano inayowakilisha kipande kimoja cha maudhui ya sura.
 * Maudhui ya sehemu ya sura yanaweza kuwa mojawapo ya mambo yafuatayo:
 * - Kichwa cha habari.
 * - Mgawanyiko wa mstari.
 * - Mstari.
 * - Kichwa Kidogo cha Kiebrania.
 */
type ChapterContent = ChapterHeading | ChapterLineBreak | ChapterVerse | ChapterHebrewSubtitle;

/**
 * Kichwa cha habari katika sura.
 */
interface ChapterHeading {
    /**
     * Inaonyesha kwamba maudhui yanawakilisha kichwa cha habari.
     */
    type: 'heading';

    /**
     * Maudhui ya kichwa cha habari.
     * Ikiwa nyuzi nyingi zimejumuishwa kwenye safu, zinapaswa kuunganishwa na nafasi.
     */
    content: string[];
}

/**
 * Mgawanyiko wa mstari katika sura.
 */
interface ChapterLineBreak {
    /**
     * Inaonyesha kwamba maudhui yanawakilisha mgawanyiko wa mstari.
     */
    type: 'line_break';
}

/**
 * Kichwa kidogo cha Kiebrania katika sura.
 * Hizi mara nyingi hutumika kama maudhui ya taarifa yaliyoonekana katika hati asilia.
 * Kwa mfano, Zaburi 49 ina Kichwa Kidogo cha Kiebrania "Kwa kiongozi wa kwaya. Zaburi ya Wana wa Kora."
 */
interface ChapterHebrewSubtitle {
    /**
     * Inaonyesha kwamba maudhui yanawakilisha Kichwa Kidogo cha Kiebrania.
     */
    type: 'hebrew_subtitle';

    /**
     * Orodha ya maudhui yaliyomo katika kichwa kidogo.
     * Kila kipengele katika orodha kinaweza kuwa mfuatano, maandishi yaliyopangwa, au marejeleo ya tanbihi.
     */
    content: (string | FormattedText | VerseFootnoteReference)[];
}

/**
 * Mstari katika sura.
 */
interface ChapterVerse {
    /**
     * Inaonyesha kwamba maudhui ni mstari.
     */
    type: 'verse';

    /**
     * Nambari ya mstari.
     */
    number: number;

    /**
     * Orodha ya maudhui ya mstari huo.
     * Kila kipengele katika orodha kinaweza kuwa mfuatano, maandishi yaliyopangwa, au marejeleo ya tanbihi.
     */
    content: (string | FormattedText | InlineHeading | InlineLineBreak | VerseFootnoteReference)[];
}

/**
 * Maandishi yaliyopangwa. Yaani, maandishi yaliyopangwa kwa namna fulani.
 */
interface FormattedText {
    /**
     * Maandishi yaliyopangwa.
     */
    text: string;

    /**
     * Kama maandishi yanawakilisha shairi.
     * Nambari inaonyesha kiwango cha ujongezaji.
     *
     * Kawaida katika Zaburi.
     */
    poem?: number;

    /**
     * Kama maandishi yanawakilisha Maneno ya Yesu.
     */
    wordsOfJesus?: boolean;
}

/**
 * Hufafanua kiolesura kinachowakilisha kichwa cha habari kilichopachikwa katika mstari.
 */
interface InlineHeading {
    /**
     * Maandishi ya kichwa cha habari.
     */
    heading: string;
}

/**
 * Hufafanua kiolesura kinachowakilisha mgawanyiko wa mstari ambao umepachikwa kwenye mstari.
 */
interface InlineLineBreak {
    lineBreak: true;
}


/**
 * Rejea ya tanbihi katika mstari au Kichwa kidogo cha Kiebrania.
 */
interface VerseFootnoteReference {
    /**
     * Kitambulisho cha noti.
     */
    noteId: number;
}

/**
 * Taarifa kuhusu tanbihi.
 */
interface ChapterFootnote {
    /**
     * Kitambulisho cha noti inayorejelewa.
     */
    noteId: number;

    /**
     * Maandishi ya tanbihi.
     */
    text: string;

    /**
     * Rejea ya mstari kwa tanbihi.
     */
    reference?: {
        chapter: number;
        verse: number;
    };

    /**
     * Mpigaji simu anayepaswa kutumika kwa maelezo ya chini.
     * Kwa maelezo ya chini, "mwitaji" ni herufi inayotumika katika maandishi kurejelea maelezo ya chini.
     *
     * Kwa mfano, katika maandishi:
     * Habari (a) Dunia
     *
     * ---- (a) Hii ni tanbihi.
     *
     * "(a)" ni mpigaji simu.
     *
     * Ikiwa "+", basi mpigaji simu anapaswa kuzalishwa kiotomatiki.
     * Ikiwa ni batili, basi mpigaji simu anapaswa kuwa mtupu.
     * Ikiwa ni kamba, basi mpigaji anapaswa kuwa kamba hiyo.
     */
    caller: '+' | string | null;
}

/**
 * Viungo vya sauti vya sura ya kitabu.
 */
interface TranslationBookChapterAudioLinks {
    /**
     * Msomaji wa sura na kiungo cha URL kwenye faili ya sauti.
     */
    [reader: string]: string;
}

/**
 * Viungo vya muda wa sauti kwa sura ya kitabu.
 */
interface TranslationBookChapterAudioTimingsLinks {
    /**
     * Kiungo cha msomaji wa sura na API kwenye faili ya muda wa sauti kwa msomaji huyo.
     */
    [reader: string]: string;
}

/**
 * Hufafanua muda wa sauti kwa sura ya kitabu, kwa msomaji mmoja.
 * Ramani za sehemu ya mwisho ya /api/{translation}/{book}/{chapter}.{reader}.audioTimings.json.
 */
export interface TranslationBookChapterAudioTimings {
    /**
     * Kitambulisho cha tafsiri.
     */
    translationId: string;

    /**
     * Kitambulisho cha kitabu.
     */
    bookId: string;

    /**
     * Idadi ya sura.
     */
    chapterNumber: number;

    /**
     * Kitambulisho cha msomaji ambacho nyakati hizi ni za.
     */
    reader: string;

    /**
     * Kiungo cha faili ya sauti ambacho muda huu unatumika.
     */
    audioLink: string;

    /**
     * Kiungo cha taarifa kwa sura hii.
     */
    thisChapterLink: string;

    /**
     * Kiungo cha taarifa kwa sura inayofuata.
     * Bati ikiwa hii ndiyo sura ya mwisho katika tafsiri.
     */
    nextChapterLink: string | null;

    /**
     * Kiungo cha taarifa kwa sura iliyotangulia.
     * Bati ikiwa hii ndiyo sura ya kwanza katika tafsiri.
     */
    previousChapterLink: string | null;

    /**
     * Kiungo cha faili hii ya muda wa sauti.
     */
    thisChapterAudioTimingsLink: string;

    /**
     * Kiungo cha muda wa sura inayofuata, kwa msomaji yule yule.
     * Bati ikiwa hii ndiyo sura ya mwisho katika tafsiri.
     */
    nextChapterAudioTimingsLink: string | null;

    /**
     * Kiungo cha muda wa sura iliyopita, kwa msomaji yule yule.
     * Bati ikiwa hii ndiyo sura ya kwanza katika tafsiri.
     */
    previousChapterAudioTimingsLink: string | null;

    /**
     * Nyakati kwa sekunde ambazo kila mstari huanza, kwa mpangilio.
     * Nambari ya kwanza (faharasa 0) ni wakati katika rekodi ambapo mstari wa kwanza huanza.
     */
    verses: number[];
}

export interface TranslationBookChapterWords {
    /**
     * Kitambulisho cha tafsiri.
     */
    translationId: string;

    /**
     * Kitambulisho cha kitabu.
     */
    bookId: string;

    /**
     * Idadi ya sura.
     */
    chapterNumber: number;

    /**
     * Kiungo cha taarifa kwa sura hii.
     */
    thisChapterLink: string;

    /**
     * Kiungo cha taarifa kwa sura inayofuata.
     * Bati ikiwa hii ndiyo sura ya mwisho katika tafsiri.
     */
    nextChapterLink: string | null;

    /**
     * Kiungo cha taarifa kwa sura iliyotangulia.
     * Bati ikiwa hii ndiyo sura ya kwanza katika tafsiri.
     */
    previousChapterLink: string | null;

    /**
     * Kiungo cha faili hii ya maneno.
     */
    thisChapterWordsLink: string;

    /**
     * Kiungo cha maneno ya sura inayofuata.
     * Batilisha ikiwa hii ndiyo sura ya mwisho katika tafsiri, au ikiwa sura inayofuata haina maelezo yoyote ya kiwango cha neno.
     */
    nextChapterWordsLink: string | null;

    /**
     * Kiungo cha maneno ya sura iliyopita.
     * Batilisha ikiwa hii ni sura ya kwanza katika tafsiri, au ikiwa sura iliyotangulia haina maelezo yoyote ya kiwango cha neno.
     */
    previousChapterWordsLink: string | null;

    /**
     * Maneno yaliyoandikwa kwa kila mstari katika sura, yameunganishwa na nambari ya mstari.
     * Kila orodha iko katika mpangilio ambao maneno yanatokea katika mstari.
     */
    verses: {
        [verseNumber: string]: ChapterWord[];
    };
}

interface ChapterWord {
    /**
     * Faharasa ya kipengee katika safu ya maudhui ya mstari ambayo maelezo yanatumika.
     */
    contentIndex: number;

    /**
     * Faharasa ya herufi ya kwanza ya neno lililofafanuliwa katika maandishi ya kipengee cha maudhui.
     */
    start: number;

    /**
     * Faharasa baada ya herufi ya mwisho ya neno lililofafanuliwa katika maandishi ya kipengee cha maudhui.
     * Hiyo ni, text.slice(start, end) ni neno lililofafanuliwa.
     */
    end: number;

    /**
     * Nambari ya Strong kwa neno hilo.
     * Imeachwa ikiwa tafsiri ilitoa maelezo mengine tu kwa neno hilo.
     */
    strongs?: string[];

    /**
     * Umbo la kamusi (nukuu) la neno.
     * Imeachwa ikiwa tafsiri haikutoa moja.
     */
    lemma?: string;

    /**
     * Msimbo wa uchanganuzi wa mofolojia wa neno.
     * Imeachwa ikiwa tafsiri haikutoa moja.
     */
    morph?: string;

    /**
     * Kielekezi cha neno katika maandishi chanzo, katika umbizo la <sourceName> : <location> .
     * Imeachwa ikiwa tafsiri haikutoa moja.
     */
    srcloc?: string;

    /**
     * Neno hili linatokeaje katika neno chanzo? Linatokana na 1.
     * Imeachwa ikiwa tafsiri haikutoa moja.
     */
    occurrence?: number;

    /**
     * Jumla ya mara ambazo neno chanzo hutokea.
     * Imeachwa ikiwa tafsiri haikutoa moja.
     */
    occurrences?: number;
}

/**
 * Hufafanua data kamili ya upakuaji wa tafsiri.
 * Ramani za sehemu ya mwisho ya /api/:translationId/complete.json.
 */
export interface TranslationComplete {
    /**
     * Metadata ya tafsiri.
     */
    translation: Translation;

    /**
     * Orodha kamili ya vitabu vyenye sura zao zote.
     */
    books: TranslationCompleteBook[];
}

/**
 * Kitabu katika tafsiri kamili ya upakuaji.
 */
export interface TranslationCompleteBook {
    /**
     * Kitambulisho cha kitabu.
     */
    id: string;

    /**
     * Jina la kitabu kutoka kwa tafsiri.
     */
    name: string;

    /**
     * Jina la kawaida la kitabu.
     */
    commonName: string;

    /**
     * Kichwa cha kitabu.
     */
    title: string | null;

    /**
     * Mpangilio wa kitabu.
     */
    order: number;

    /**
     * Idadi ya sura katika kitabu.
     */
    numberOfChapters: number;

    /**
     * Jumla ya mistari katika kitabu.
     */
    totalNumberOfVerses: number;

    /**
     * Kama kitabu hicho ni cha apokrifa.
     */
    isApocryphal?: boolean;

    /**
     * Orodha kamili ya sura zenye maudhui yote.
     */
    chapters: TranslationCompleteChapter[];
}

/**
 * Sura katika upakuaji kamili wa tafsiri.
 */
export interface TranslationCompleteChapter {
    /**
     * Idadi ya mistari ambayo sura hiyo ina.
     */
    numberOfVerses: number;

    /**
     * Viungo vya matoleo tofauti ya sauti kwa sura hiyo.
     */
    thisChapterAudioLinks: TranslationBookChapterAudioLinks;

    /**
     * Muda wa sauti (wakati wa kuanza kwa kila mstari, kwa sekunde) kwa matoleo tofauti ya sauti kwa sura hiyo.
     *
     * Tofauti na `thisChapterAudioTimings` kwenye sehemu ya mwisho ya sura (ambayo inaunganisha na "Pata Muda wa Sauti kwa Sura" hapa chini), hii ina nyakati zenyewe - kwa kuwa lengo la upakuaji kamili wa tafsiri ni kuwa na kila kitu katika faili moja.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsMap;

    /**
     * Kiungo cha maelezo ya kiwango cha neno kwa sura hiyo.
     * Imeachwa ikiwa sura haina maelezo yoyote ya kiwango cha neno.
     */
    thisChapterWordsLink?: string;

    /**
     * Taarifa kwa ajili ya sura.
     */
    chapter: ChapterData;
}

/**
 * Muda wa sauti wa sura ya kitabu, uliopachikwa moja kwa moja badala ya kuunganishwa na.
 * Huunganisha kitambulisho cha msomaji kwenye orodha ya nyakati (kwa sekunde) ambazo kila mstari unaanza, kwa mpangilio wa mstari.
 */
interface TranslationBookChapterAudioTimingsMap {
    [reader: string]: number[];
}