Resources Tools Docs FAQ CMS

Tutorial 8: Transliteration End-to-End

This tutorial is for users who want to show pronunciation-friendly Quran text in non-Arabic script while preserving ayah mapping.

1) What This Resource Is

Transliteration resources provide Quran text transliterated into Latin/non-Arabic writing systems.

Typical entries include:

  • ayah_key in surah:ayah
  • Transliteration text for each ayah
  • Optional variants by language/provider

Primary category:

2) When to Use It

Use transliteration data when you are building:

  • Beginner-friendly reading modes
  • Pronunciation assistance features
  • Arabic + transliteration dual-display UI

3) How to Get Your First Example Resource

  1. Open https://qul.tarteel.ai/resources/transliteration.
  2. Keep default listing order and open the first published card.
  3. Confirm the detail page includes:
    • Transliteration Preview tab
    • Help tab
  4. Confirm downloads (json, sqlite).

This keeps onboarding concrete without hardcoded IDs.

4) What the Preview Shows (Website-Aligned)

On transliteration detail pages:

  • Transliteration Preview tab:
    • Jump to Ayah
    • Previous/next ayah navigation
    • Arabic line + transliteration line
  • Help tab:
    • Data shape keyed by ayah_key
    • Field examples for app integration

Practical meaning:

  • Transliteration must remain keyed exactly like script/translation for safe joins.
  • It is a reading aid layer, not a replacement for script text.

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

  1. Download transliteration package (json or sqlite).
  2. Normalize and index by ayah_key.
  3. Join with Quran Script rows by ayah key.
  4. Add display mode toggle (Arabic | Transliteration | Both).
  5. Validate ayah order and alignment.

Starter integration snippet (JavaScript):

JavaScript
const buildTransliterationIndex = (rows) =>
  rows.reduce((index, row) => {
    index[row.ayah_key] = row.text;
    return index;
  }, {});

const joinScriptAndTransliteration = (scriptRows, transliterationIndex) =>
  scriptRows.map((row) => {
    const ayahKey = `${row.surah}:${row.ayah}`;
    return {
      ayahKey,
      arabic: row.text,
      transliteration: transliterationIndex[ayahKey] || null
    };
  });

6) Real-World Example: Reading Mode Toggle

Goal:

  • User toggles transliteration under Arabic text for selected ayah.

Inputs:

  • Quran Script data
  • Transliteration data

Processing:

  1. App resolves selected ayah key.
  2. App loads Arabic and transliteration lines by same key.
  3. UI toggles transliteration visibility.

Expected output:

  • Stable Arabic-transliteration pairing for every ayah.

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

  • Joining transliteration to script by row order instead of ayah_key.
  • Showing transliteration without clear mode/toggle controls.
  • Mixing ayah-by-ayah and word-by-word formats without normalization.

8) When to Request Updates or Changes

Open an issue if you find:

  • Missing transliteration rows for known ayahs
  • Broken character mapping in transliteration text
  • Broken json/sqlite links

Issue tracker:

Related Docs