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 - 1420becomes the date 1420. Zotero has no Hijri calendar field. If the edition prints only1420هـ, 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,
A2is imported as series editor andA3as editor. A muhaqqiq entered underA2ends up in the wrong role.EDis also read as editor, andA4as 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
encan come out as "Sharh Al-Mithal Fi Al-Fiqh". Setting the language toarprevents 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:
| Column | What goes in it |
|---|---|
| type | book, thesis, article or chapter |
| author | One or more names, separated by ;. Use a Latin comma to split last and first name, or no comma for a single-field name |
| editor | The muhaqqiq or editor (for a book this becomes A3) |
| translator | If any |
| title | The title as printed, or your transliteration |
| series, volumes, edition | Edition as a plain number, as Zotero's field guide asks |
| place, publisher | As printed |
| year_ce | Gregorian year only, four digits |
| year_ah | Hijri year as printed, if the edition gives one |
| thesis_type | For theses, such as "PhD thesis" (the university goes in publisher) |
| language | ar 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
- In Zotero, create an empty collection for the test, then use File > Import > A file and
choose your
.risfile. - Import ten entries, not the whole list.
- 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
arfor Arabic and transliterated titles andenfor 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
- Zotero documentation: How do I import BibTeX or other standardized formats?
- Zotero documentation: Item types and fields
- Zotero documentation: Preventing title casing for non-English titles
- Zotero translators: RIS import and export translator (source code)
- Microsoft Support: Convert text to a table or a table to text