BlogBooks & scholarship7 min read

Turn the reference list of a scanned Arabic book into Zotero entries

Convert only the bibliography pages to Word and check them against the scan. Put one reference per row in a spreadsheet, keep the Gregorian and Hijri years in separate columns, then turn the rows into a RIS file and import it with File > Import. Check names, editors, years and language on a small batch before importing the rest.

You are working from a printed Arabic edition or an older thesis. Its list of sources (قائمة المصادر والمراجع) runs to twenty or forty pages, and you want those works in Zotero so you can cite them, tag them and find them again. Typing them in one by one takes days. Pasting OCR text into Zotero doesn't work, because Zotero needs structured fields, not lines.

This guide shows a route that works: convert only the bibliography pages, put each reference into a spreadsheet row, turn the rows into a RIS file and import that. It also covers four traps that only show up after the import: names that don't split, Hijri years read as Gregorian years, editors filed as series editors and transliterated titles that get capitalised. It is written for researchers, muhaqqiqs and editors, and for anyone preparing a reference library for a project.

What goes wrong if you import without checking

Zotero imports RIS through File > Import, choosing "A file". It is one of the formats Zotero's documentation lists for importing. The RIS importer is strict in ways that matter for Arabic references. Reading the source code of Zotero's RIS translator shows four of them:

  • Names split only at a Latin comma. The importer treats the text before the first , as the last name and the rest as the first name. The Arabic comma ، is not a split point. الحلبي، أحمد بن يوسف becomes a single-field name, while الحلبي, أحمد بن يوسف is split into last name and first name. A name with no comma at all, such as ابن المثال, is also stored as one field, which is often what you want for a classical name known by a single nisba or kunya.
  • A year is just a number. PY - 1420 becomes the date 1420. Zotero has no Hijri calendar field. If the edition prints only 1420هـ, a citation will show a year in the fifteenth century CE. The RIS date parser also matches only Western digits (0–9), so ٢٠٠١ is kept as text rather than read as a year.
  • The editor tag depends on the item type. For a book, A2 is imported as series editor and A3 as editor. A muhaqqiq entered under A2 ends up in the wrong role. ED is also read as editor, and A4 as translator.
  • The Language field controls capitalisation. Title-case styles such as Chicago apply English capitalisation rules, and Zotero's documentation says to set each item's Language field so that non-English titles are not title-cased. A transliterated title such as Sharh al-Mithal fi al-fiqh in an item marked en can come out as "Sharh Al-Mithal Fi Al-Fiqh". Setting the language to ar prevents that, so don't leave the field to chance.

Step 1: Convert only the bibliography pages

Split the bibliography pages out of the scan (or note their page range) and convert just those to Word. A list of references is dense, so check it against the scan before you build anything on it. Look for:

  • dropped or swapped letters in names, especially ابن/بن, the article ال and hamza seats
  • death dates (ت 204هـ) attached to the wrong name, or merged into the title
  • volume counts and edition numbers (ط2, 4 مج) read as part of the publisher
  • entries that run over a page break and were split into two entries
  • Arabic-Indic and Western digits mixed in the same entry

Arabic PDF to Word covers the conversion itself. If the bibliography is part of a whole book you are digitising, see digitising Arabic books. The QA checklist for an Arabic OCR Word file covers the general checks.

Step 2: One reference per paragraph

Bibliographies are typeset with hanging indents. After conversion an entry often sits on two or three lines. Turn on formatting marks (¶) and join each entry into one paragraph. Number the paragraphs in a scratch copy and compare the count with the printed list. This is the simplest way to catch a merged or split entry.

Step 3: Build a table with one column per field

Put a tab between the parts of each entry that you want as separate fields, then select the list and use Insert > Table > Convert Text to Table, separating text at tabs, as Microsoft describes. Paste the table into a spreadsheet. Doing this by hand is slow, but it is where the real decisions are made. Use these columns:

ColumnWhat goes in it
typebook, thesis, article or chapter
authorOne or more names, separated by ;. Use a Latin comma to split last and first name, or no comma for a single-field name
editorThe muhaqqiq or editor (for a book this becomes A3)
translatorIf any
titleThe title as printed, or your transliteration
series, volumes, editionEdition as a plain number, as Zotero's field guide asks
place, publisherAs printed
year_ceGregorian year only, four digits
year_ahHijri year as printed, if the edition gives one
thesis_typeFor theses, such as "PhD thesis" (the university goes in publisher)
languagear for Arabic-script and transliterated Arabic titles, en for English works

Where an edition gives only a Hijri year, leave year_ce empty rather than guessing. Save the sheet as CSV, choosing a UTF-8 CSV option if your spreadsheet offers one, and open the file in a plain text editor to confirm the Arabic is intact.

Step 4: Turn the rows into a RIS file

The script below (Python 3, standard library only) reads the CSV and writes a RIS file. It holds back any row with a problem and tells you why, so you fix the sheet rather than the library. It maps editors to A3 for books, normalises Arabic-Indic digits in years, edition and volume numbers, and puts the printed Hijri year in a note (N1) so it isn't lost.

import csv, sys

DIGITS = str.maketrans("٠١٢٣٤٥٦٧٨٩۰۱۲۳۴۵۶۷۸۹", "01234567890123456789")
TYPES = {"book": "BOOK", "thesis": "THES", "article": "JOUR", "chapter": "CHAP"}
ROLE_TAGS = [("author", "AU"), ("editor", "A3"), ("translator", "A4")]
FIELD_TAGS = [("title", "TI"), ("series", "T2"), ("volumes", "NV"), ("edition", "ET"),
              ("place", "CY"), ("publisher", "PB"), ("thesis_type", "M3")]

def problems(n, row):
    out = []
    if not row["title"].strip():
        out.append("no title")
    if row["type"].strip().lower() not in TYPES:
        out.append(f"unknown type '{row['type']}'")
    ce = row["year_ce"].translate(DIGITS).strip()
    ah = row["year_ah"].translate(DIGITS).strip()
    if ce and not (ce.isdigit() and len(ce) == 4):
        out.append(f"year_ce '{row['year_ce']}' is not a 4-digit year")
    elif ce and int(ce) < 1500:
        out.append(f"year_ce {ce} looks like a Hijri year")
    if ce and ah and ah.isdigit() and abs((int(ce) - 622) * 33 / 32 - int(ah)) > 3:
        out.append(f"year_ce {ce} and year_ah {ah} don't match")
    for col, _ in ROLE_TAGS:
        for name in filter(None, (x.strip() for x in row[col].split(";"))):
            if "،" in name and "," not in name:
                out.append(f"{col} '{name}' uses an Arabic comma: Zotero will not split it")
    return [f"row {n}: {p}" for p in out]

def to_ris(row):
    lines = [f"TY  - {TYPES[row['type'].strip().lower()]}"]
    for col, tag in ROLE_TAGS:
        for name in filter(None, (x.strip() for x in row[col].split(";"))):
            lines.append(f"{tag}  - {name}")
    for col, tag in FIELD_TAGS:
        value = row.get(col, "").strip()
        if col in ("volumes", "edition"):
            value = value.translate(DIGITS)
        if value:
            lines.append(f"{tag}  - {value}")
    ce = row["year_ce"].translate(DIGITS).strip()
    if ce:
        lines.append(f"PY  - {ce}")
    if row["year_ah"].strip():
        lines.append(f"N1  - Hijri year as printed: {row['year_ah'].strip()}")
    lines.append(f"LA  - {row.get('language', '').strip() or 'ar'}")
    lines.append("ER  - ")
    return "\r\n".join(lines) + "\r\n"

src, dst = sys.argv[1], sys.argv[2]
with open(src, encoding="utf-8-sig", newline="") as f:
    rows = list(csv.DictReader(f))
written = 0
with open(dst, "w", encoding="utf-8", newline="") as f:
    for n, r in enumerate(rows, start=2):
        found = problems(n, r)
        for p in found:
            print(p)
        if not found:
            f.write(to_ris(r))
            written += 1
print(f"{len(rows)} rows, {written} written to {dst}, {len(rows) - written} held back")

Run it with python3 refs_to_ris.py refs.csv refs.ris. The year check is a rough conversion (a Hijri year is about 33/32 of the Gregorian years since 622). It flags pairs more than three years apart, which catches typos and swapped columns. It doesn't replace a proper conversion table.

Illustrative example

We ran the script in this session on a six-row CSV with invented entries. Each problem row was planted on purpose:

row 2: author 'الحلبي، أحمد بن يوسف' uses an Arabic comma: Zotero will not split it
row 4: year_ce 1420 looks like a Hijri year
row 5: year_ce 1999 and year_ah 1300 don't match
row 7: no title
6 rows, 2 written to out.ris, 4 held back

One of the two rows it wrote, a book with a muhaqqiq, came out like this:

TY  - BOOK
AU  - al-Halabi, Ahmad ibn Yusuf
A3  - Abd al-Karim, Salim
TI  - Sharh al-Mithal fi al-fiqh
NV  - 4
ET  - 2
CY  - Cairo
PB  - Dar al-Mithal
PY  - 2001
N1  - Hijri year as printed: 1422
LA  - ar
ER  - 

After we fixed the comma and removed the other three problem rows, the script wrote all three remaining rows and held back none. We did not import the file into a running copy of Zotero in this session. The field mapping above comes from reading Zotero's RIS translator, so test it on your own installation as described below.

Step 5: Import a small batch first

  1. In Zotero, create an empty collection for the test, then use File > Import > A file and choose your .ris file.
  2. Import ten entries, not the whole list.
  3. Open each item and check it against the printed page.

Review checklist after the import

  • Each author shows the split you intended: last name and first name, or one field.
  • The muhaqqiq appears as Editor, not Series Editor or Author.
  • Translators appear as Translator.
  • The Date field holds a Gregorian year, and the Hijri year is in the note.
  • Number of Volumes and Edition hold plain numbers.
  • Language is ar for Arabic and transliterated titles and en for English works.
  • Theses show the university and thesis type in the right fields.
  • A test citation in your style shows the title without unwanted capitals.
  • Vocalised and unvocalised spellings of the same author are not stored as two people.
  • The number of imported items matches the number of entries in the printed list.

If one field comes out wrong for every entry, fix the column or the tag and re-import the batch. Don't correct it item by item.

Limitations

  • This route depends on the conversion being right. A wrong letter in a name or a misread year will be imported faithfully, so the check against the scan in step 1 matters most.
  • Splitting entries into fields is a judgement call. For classical works it is often unclear what counts as the title, the commentary and the edition. Make those decisions once, write them down and apply them to the whole list.
  • Zotero has no field for a Hijri date. The note keeps the printed year, but your citation style will not print it unless you add it yourself. If your style expects both years, check with your editor or journal how they want them shown.
  • Zotero's documentation does not say how searches treat vocalised and unvocalised Arabic. If you search your library in Arabic, keep a consistent spelling, for example without harakat, in the fields you search.
  • The field mapping in this guide comes from the current RIS translator. Zotero updates its translators, so check a small batch after any major Zotero update.
  • No citation style handles every convention used in Arabic scholarship. Check a sample of formatted references before you submit.

Sources

  1. Zotero documentation: How do I import BibTeX or other standardized formats?
  2. Zotero documentation: Item types and fields
  3. Zotero documentation: Preventing title casing for non-English titles
  4. Zotero translators: RIS import and export translator (source code)
  5. Microsoft Support: Convert text to a table or a table to text