Format standard

export interface TranslationBookChapter {
    /**
     * Informations relatives à la traduction du chapitre du livre.
     */
    translation: Translation;

    /**
     * Informations relatives au chapitre du livre.
     */
    book: TranslationBook;

    /**
     * Le lien vers le chapitre actuel.
     */
    thisChapterLink: string;

    /**
     * Les liens vers les différentes versions audio du chapitre.
     */
    thisChapterAudioLinks: TranslationBookChapterAudioLinks;

    /**
     * Les liens vers les minutages audio des différentes versions audio du chapitre.
     * Chaque lien renvoie au fichier de minutage audio correspondant au lecteur ; voir « Obtenir le minutage audio d’un chapitre » ci-dessous.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsLinks;

    /**
     * Le lien vers le chapitre suivant.
     * Nul si c'est le dernier chapitre de la traduction.
     */
    nextChapterApiLink: string | null;

    /**
     * Voici les liens vers les différentes versions audio du chapitre suivant.
     * Nul si c'est le dernier chapitre de la traduction.
     */
    nextChapterAudioLinks: TranslationBookChapterAudioLinks | null;

    /**
     * Voici les liens vers les minutages audio des différentes versions audio du chapitre suivant.
     * Nul si c'est le dernier chapitre de la traduction.
     */
    nextChapterAudioTimings: TranslationBookChapterAudioTimingsLinks | null;

    /**
     * Le lien vers le chapitre précédent.
     * Nul si c'est le premier chapitre de la traduction.
     */
    previousChapterApiLink: string | null;

    /**
     * Les liens vers les différentes versions audio du chapitre précédent.
     * Nul si c'est le premier chapitre de la traduction.
     */
    previousChapterAudioLinks: TranslationBookChapterAudioLinks | null;

    /**
     * Voici les liens vers les minutages audio des différentes versions audio du chapitre précédent.
     * Nul si c'est le premier chapitre de la traduction.
     */
    previousChapterAudioTimings: TranslationBookChapterAudioTimingsLinks | null;

    /**
     * Le lien vers les annotations au niveau du mot pour ce chapitre.
     * Omis si le chapitre ne comporte aucune annotation au niveau du mot.
     */
    thisChapterWordsLink?: string;

    /**
     * Le lien vers les annotations au niveau du mot pour le chapitre suivant.
     * Omis si c'est le dernier chapitre de la traduction, ou si le chapitre suivant ne comporte aucune annotation au niveau du mot.
     */
    nextChapterWordsLink?: string;

    /**
     * Le lien vers les annotations au niveau des mots pour le chapitre précédent.
     * Omis si c'est le premier chapitre de la traduction, ou si le chapitre précédent ne comporte aucune annotation au niveau du mot.
     */
    previousChapterWordsLink?: string;

    /**
     * Le nombre de versets que contient le chapitre.
     */
    numberOfVerses: number;

    /**
     * Voici le lien vers la version simplifiée de ce chapitre.
     * Omis si les chapitres simplifiés ne sont pas disponibles.
     */
    simpleChapterApiLink?: string;

    /**
     * Informations relatives à ce chapitre.
     */
    chapter: ChapterData;
}

interface ChapterData {
    /**
     * Le numéro du chapitre.
     */
    number: number;

    /**
     * Le contenu du chapitre.
     */
    content: ChapterContent[];

    /**
     * Liste des notes de bas de page du chapitre.
     */
    footnotes: ChapterFootnote[];
}

/**
 * Un type union qui représente un seul élément de contenu de chapitre.
 * Un élément du contenu d'un chapitre peut être l'un des éléments suivants :
 * - Un titre.
 * - Un saut de ligne.
 * - Un verset.
 * - Un sous-titre en hébreu.
 */
type ChapterContent = ChapterHeading | ChapterLineBreak | ChapterVerse | ChapterHebrewSubtitle;

/**
 * Un titre de chapitre.
 */
interface ChapterHeading {
    /**
     * Indique que le contenu représente un titre.
     */
    type: 'heading';

    /**
     * Le contenu de l'en-tête.
     * Si plusieurs chaînes de caractères sont incluses dans le tableau, elles doivent être concaténées avec un espace.
     */
    content: string[];
}

/**
 * Un saut de ligne dans un chapitre.
 */
interface ChapterLineBreak {
    /**
     * Indique que le contenu représente un saut de ligne.
     */
    type: 'line_break';
}

/**
 * Un sous-titre hébreu dans un chapitre.
 * Ces éléments sont souvent utilisés comme contenu informatif figurant dans les manuscrits originaux.
 * Par exemple, le Psaume 49 porte le sous-titre hébreu « Au chef de chœur. Psaume des fils de Coré. »
 */
interface ChapterHebrewSubtitle {
    /**
     * Indique que le contenu représente un sous-titre en hébreu.
     */
    type: 'hebrew_subtitle';

    /**
     * Liste du contenu figurant dans le sous-titre.
     * Chaque élément de la liste peut être une chaîne de caractères, un texte formaté ou une référence de note de bas de page.
     */
    content: (string | FormattedText | VerseFootnoteReference)[];
}

/**
 * Un verset dans un chapitre.
 */
interface ChapterVerse {
    /**
     * Indique que le contenu est un verset.
     */
    type: 'verse';

    /**
     * Le numéro du verset.
     */
    number: number;

    /**
     * Liste des éléments du verset.
     * Chaque élément de la liste peut être une chaîne de caractères, un texte formaté ou une référence de note de bas de page.
     */
    content: (string | FormattedText | InlineHeading | InlineLineBreak | VerseFootnoteReference)[];
}

/**
 * Texte formaté. C'est-à-dire un texte mis en forme d'une manière particulière.
 */
interface FormattedText {
    /**
     * Le texte formaté.
     */
    text: string;

    /**
     * Si le texte représente un poème.
     * Le chiffre indique le niveau de retrait.
     *
     * Fréquent dans les Psaumes.
     */
    poem?: number;

    /**
     * Si le texte représente les paroles de Jésus.
     */
    wordsOfJesus?: boolean;
}

/**
 * Définit une interface qui représente un titre intégré dans un verset.
 */
interface InlineHeading {
    /**
     * Le texte de l'en-tête.
     */
    heading: string;
}

/**
 * Définit une interface qui représente un saut de ligne intégré dans un verset.
 */
interface InlineLineBreak {
    lineBreak: true;
}


/**
 * Une référence en note de bas de page dans un verset ou un sous-titre hébreu.
 */
interface VerseFootnoteReference {
    /**
     * L'identifiant du billet.
     */
    noteId: number;
}

/**
 * Information concernant une note de bas de page.
 */
interface ChapterFootnote {
    /**
     * L'identifiant de la note référencée.
     */
    noteId: number;

    /**
     * Le texte de la note de bas de page.
     */
    text: string;

    /**
     * Référence du verset pour la note de bas de page.
     */
    reference?: {
        chapter: number;
        verse: number;
    };

    /**
     * L'appelant à utiliser pour la note de bas de page.
     * Pour les notes de bas de page, le « personnage référent » est celui utilisé dans le texte pour faire référence à la note.
     *
     * Par exemple, dans le texte :
     * Bonjour (a) Monde
     *
     * ---- (a) Ceci est une note de bas de page.
     *
     * Le « (a) » désigne l'appelant.
     *
     * Si "+", alors l'appelant doit être généré automatiquement.
     * Si la valeur est nulle, l'appelant doit être vide.
     * Si c'est une chaîne de caractères, alors l'appelant doit être cette chaîne.
     */
    caller: '+' | string | null;
}

/**
 * Les liens audio pour un chapitre de livre.
 */
interface TranslationBookChapterAudioLinks {
    /**
     * Le texte du chapitre et le lien URL vers le fichier audio.
     */
    [reader: string]: string;
}

/**
 * Liens vers les minutages audio d'un chapitre de livre.
 */
interface TranslationBookChapterAudioTimingsLinks {
    /**
     * Le lecteur du chapitre et le lien API vers le fichier de minutage audio correspondant.
     */
    [reader: string]: string;
}

/**
 * Définit la durée audio d'un chapitre de livre, pour un seul lecteur.
 * Correspond au point de terminaison /api/{translation}/{book}/{chapter}.{reader}.audioTimings.json.
 */
export interface TranslationBookChapterAudioTimings {
    /**
     * L'identifiant de la traduction.
     */
    translationId: string;

    /**
     * L'identifiant du livre.
     */
    bookId: string;

    /**
     * Le numéro du chapitre.
     */
    chapterNumber: number;

    /**
     * L'identifiant du lecteur auquel ces durées sont destinées.
     */
    reader: string;

    /**
     * Le lien vers le fichier audio auquel ces minutages se rapportent.
     */
    audioLink: string;

    /**
     * Le lien vers les informations de ce chapitre.
     */
    thisChapterLink: string;

    /**
     * Le lien vers les informations du chapitre suivant.
     * Nul si c'est le dernier chapitre de la traduction.
     */
    nextChapterLink: string | null;

    /**
     * Le lien vers les informations du chapitre précédent.
     * Nul si c'est le premier chapitre de la traduction.
     */
    previousChapterLink: string | null;

    /**
     * Voici le lien vers ce fichier de minutage audio.
     */
    thisChapterAudioTimingsLink: string;

    /**
     * Le lien vers le calendrier du chapitre suivant, pour le même lecteur.
     * Nul si c'est le dernier chapitre de la traduction.
     */
    nextChapterAudioTimingsLink: string | null;

    /**
     * Le lien vers le minutage du chapitre précédent, pour le même lecteur.
     * Nul si c'est le premier chapitre de la traduction.
     */
    previousChapterAudioTimingsLink: string | null;

    /**
     * Les instants en secondes auxquels chaque couplet commence, dans l'ordre.
     * Le premier nombre (indice 0) correspond au moment de l'enregistrement où commence le premier couplet.
     */
    verses: number[];
}

export interface TranslationBookChapterWords {
    /**
     * L'identifiant de la traduction.
     */
    translationId: string;

    /**
     * L'identifiant du livre.
     */
    bookId: string;

    /**
     * Le numéro du chapitre.
     */
    chapterNumber: number;

    /**
     * Le lien vers les informations de ce chapitre.
     */
    thisChapterLink: string;

    /**
     * Le lien vers les informations du chapitre suivant.
     * Nul si c'est le dernier chapitre de la traduction.
     */
    nextChapterLink: string | null;

    /**
     * Le lien vers les informations du chapitre précédent.
     * Nul si c'est le premier chapitre de la traduction.
     */
    previousChapterLink: string | null;

    /**
     * Le lien vers ce fichier Word.
     */
    thisChapterWordsLink: string;

    /**
     * Le lien vers le texte du chapitre suivant.
     * Nul si c'est le dernier chapitre de la traduction, ou si le chapitre suivant ne comporte aucune annotation au niveau des mots.
     */
    nextChapterWordsLink: string | null;

    /**
     * Le lien vers les mots du chapitre précédent.
     * Nul s'il s'agit du premier chapitre de la traduction, ou si le chapitre précédent ne comporte aucune annotation au niveau des mots.
     */
    previousChapterWordsLink: string | null;

    /**
     * Les mots annotés pour chaque verset du chapitre, classés par numéro de verset.
     * Chaque liste suit l'ordre d'apparition des mots dans le verset.
     */
    verses: {
        [verseNumber: string]: ChapterWord[];
    };
}

interface ChapterWord {
    /**
     * L'index de l'élément dans le tableau de contenu du verset auquel l'annotation s'applique.
     */
    contentIndex: number;

    /**
     * L'indice du premier caractère du mot annoté dans le texte de l'élément de contenu.
     */
    start: number;

    /**
     * L'index suivant le dernier caractère du mot annoté dans le texte de l'élément de contenu.
     * Autrement dit, text.slice(start, end) est le mot annoté.
     */
    end: number;

    /**
     * Le ou les numéros Strong pour le mot.
     * Omis si la traduction ne fournissait que d'autres annotations pour le mot.
     */
    strongs?: string[];

    /**
     * La forme du mot telle qu'elle apparaît dans le dictionnaire (citation).
     * Omis si la traduction n'en comportait pas.
     */
    lemma?: string;

    /**
     * Le code d'analyse morphologique du mot.
     * Omis si la traduction n'en comportait pas.
     */
    morph?: string;

    /**
     * Le pointeur vers le mot dans le texte source, au format <sourceName> : <location> .
     * Omis si la traduction n'en comportait pas.
     */
    srcloc?: string;

    /**
     * À quelle occurrence du mot source ce mot appartient-il ? 1-basé.
     * Omis si la traduction n'en comportait pas.
     */
    occurrence?: number;

    /**
     * Le nombre total de fois où le mot source apparaît.
     * Omis si la traduction n'en comportait pas.
     */
    occurrences?: number;
}

/**
 * Définit les données complètes de téléchargement de la traduction.
 * Correspond au point de terminaison /api/:translationId/complete.json.
 */
export interface TranslationComplete {
    /**
     * Les métadonnées de traduction.
     */
    translation: Translation;

    /**
     * La liste complète des livres avec tous leurs chapitres.
     */
    books: TranslationCompleteBook[];
}

/**
 * Un livre en traduction intégrale à télécharger.
 */
export interface TranslationCompleteBook {
    /**
     * L'identifiant du livre.
     */
    id: string;

    /**
     * Le titre du livre d'après la traduction.
     */
    name: string;

    /**
     * Le nom commun du livre.
     */
    commonName: string;

    /**
     * Le titre du livre.
     */
    title: string | null;

    /**
     * L'ordre du livre.
     */
    order: number;

    /**
     * Le nombre de chapitres du livre.
     */
    numberOfChapters: number;

    /**
     * Le nombre total de versets dans le livre.
     */
    totalNumberOfVerses: number;

    /**
     * Que le livre soit apocryphe.
     */
    isApocryphal?: boolean;

    /**
     * La liste complète des chapitres avec leur contenu.
     */
    chapters: TranslationCompleteChapter[];
}

/**
 * Un chapitre du téléchargement de la traduction complète.
 */
export interface TranslationCompleteChapter {
    /**
     * Le nombre de versets que contient le chapitre.
     */
    numberOfVerses: number;

    /**
     * Les liens vers les différentes versions audio du chapitre.
     */
    thisChapterAudioLinks: TranslationBookChapterAudioLinks;

    /**
     * Les minutages audio (heures de début par verset, en secondes) pour les différentes versions audio du chapitre.
     *
     * Contrairement à `thisChapterAudioTimings` sur le point de terminaison de chaque chapitre (qui renvoie à « Obtenir les minutages audio d'un chapitre » ci-dessous), celui-ci contient les minutages eux-mêmes, puisque l'objectif du téléchargement de la traduction complète est de tout avoir dans un seul fichier.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsMap;

    /**
     * Le lien vers les annotations au niveau du mot pour ce chapitre.
     * Omis si le chapitre ne comporte aucune annotation au niveau du mot.
     */
    thisChapterWordsLink?: string;

    /**
     * Informations relatives à ce chapitre.
     */
    chapter: ChapterData;
}

/**
 * Les minutages audio d'un chapitre de livre, intégrés directement plutôt que liés.
 * Associe un identifiant de lecteur à la liste des heures (en secondes) auxquelles chaque verset commence, dans l'ordre des versets.
 */
interface TranslationBookChapterAudioTimingsMap {
    [reader: string]: number[];
}