Resources Tools Docs FAQ CMS

Tutorial 12: Mutashabihat End-to-End

This tutorial is for users who want to integrate phrase-level similarity aids for memorization and comparison.

1) What This Resource Is

Mutashabihat resources provide phrase-level similarity mappings across ayahs.

The help model typically includes files such as:

  • phrases.json (shared phrases)
  • phrase_verses.json (ayah-to-phrase mappings)

Primary category:

2) When to Use It

Use mutashabihat data when building:

  • Memorization revision tools
  • Similar phrase comparison views
  • Confusion-reduction aids for close ayah wording

3) How to Get Your First Example Resource

  1. Open https://qul.tarteel.ai/resources/mutashabihat.
  2. Keep default listing order and open the first published card.
  3. Confirm the detail page includes:
    • Mutashabihat Preview tab
    • Help tab
  4. Confirm available download file(s) (commonly json).

This keeps onboarding concrete without hardcoded IDs.

4) What the Preview Shows (Website-Aligned)

On mutashabihat detail pages:

  • Mutashabihat Preview tab:
    • Jump to Ayah
    • Displays similar phrase relationships for selected ayah
    • Shows phrase words and repeat statistics
    • Lists phrase ayahs where the phrase appears
  • Help tab:
    • Explains phrases.json and phrase_verses.json
    • Shows lookup flow to retrieve related phrases

Practical meaning:

  • You should resolve phrase IDs first, then fetch phrase details.
  • Mutashabihat is phrase-level guidance, not full tafsir/translation content.

Concrete example (mutashabihat resource 73):

  • Phrase words:
    • بِسۡمِ
    • ٱللَّهِ
    • ٱلرَّحۡمَٰنِ
    • ٱلرَّحِيمِ
  • Summary:
    • This phrase is repeated 2 times in 2 ayahs across 2 surahs.
  • Phrase ayahs:
    • 1:1: بِسۡمِ ٱللَّهِ ٱلرَّحۡمَٰنِ ٱلرَّحِيمِ ١
    • 27:30: إِنَّهُۥ مِن سُلَيۡمَٰنَ وَإِنَّهُۥ بِسۡمِ ٱللَّهِ ٱلرَّحۡمَٰنِ ٱلرَّحِيمِ ٣٠

5) Download and Use (Step-by-Step)

  1. Download mutashabihat dataset (json).
  2. Load phrase_verses.json and phrases.json.
  3. For selected ayah, fetch phrase IDs from phrase-verses mapping.
  4. Resolve phrase IDs to phrase details.
  5. Optionally join with script words for visual highlighting.

Starter integration snippet (JavaScript):

JavaScript
// Required: load phrases.json, phrase_verses.json, and Quran words data.
const phraseIdsForAyah = (phraseVerses, ayahKey) => phraseVerses[ayahKey] || [];

const phrasesForAyah = (phraseVerses, phrasesById, ayahKey) =>
  phraseIdsForAyah(phraseVerses, ayahKey)
    .map((id) => phrasesById[id])
    .filter(Boolean);

// In phrases.json, each phrase can include:
// - source: where the phrase is first sourced from
// - ayah: a mapping like { "2:23": [[from, to], ...] } for word ranges
const phraseRangesForAyah = (phrase, ayahKey) =>
  phrase?.ayah?.[ayahKey] || [];

6) Real-World Example: Similar Phrase Helper

Goal:

  • User selects an ayah and sees phrase-level similar references.

Inputs:

  • phrases.json
  • phrase_verses.json

Processing:

  1. Resolve phrase IDs for selected ayah.
  2. Load matching phrase entries.
  3. Render phrase and related ayah references.
  4. On demand (View all), show all known ayahs where phrase appears.

Expected output:

  • User can compare similar phrase patterns quickly.

Interactive preview (temporary sandbox):

You can edit this code for testing. Edits are not saved and may not persist after refresh.

JavaScript Playground
Editor
Preview

7) Common Mistakes to Avoid

  • Treating mutashabihat as ayah-level one-to-one data.
  • Ignoring phrase ID indirection.
  • Not showing related ayah context alongside phrase matches.

8) When to Request Updates or Changes

Open an issue if you find:

  • Missing phrase IDs in mappings
  • Broken references from phrase ID to phrase object
  • Broken json download links

Issue tracker:

Related Docs