CA-R Header Translator

Translate California Revealed CSV column headers between machine names (obj_call_number) and human-readable labels (Call Number) — in both directions — without touching any of the data.

Only the header row changes. Every data row is copied through exactly as-is, including quoting and in-cell delimiters. It runs the same on Windows and macOS and, for everyday translating, needs nothing but Python 3 (no Excel, no extra libraries).

---

Install

1. Install Python 3.9+.
2. Download this repository (green Code button → Download ZIP, or git clone).
3. Open a terminal in the folder:
   • Windows: open the folder in File Explorer, click the address bar, type powershell, press Enter.
   • macOS: right-click the folder → New Terminal at Folder.

That's it. mapping.csv ships with the tool, so you can translate right away.

---

Translate a file

Auto-detect the direction:

python translate_headers.py yourfile.csv

The tool looks at your headers, determines whether they are machine names or human labels, and translates to the other side.

Force a direction (recommended):

python translate_headers.py yourfile.csv --direction to-human
python translate_headers.py yourfile.csv --direction to-machine

Because the mapping is unique on both sides, translating a file to human labels and back to machine names returns the exact original headers — useful for handing a readable file to a partner and re-mapping their corrected metadata for ingest.

Translate a whole folder

Point the tool at a folder and it processes every .csv inside it, choosing the direction per file:

python translate_headers.py path/to/folder
python translate_headers.py path/to/folder --direction to-human
python translate_headers.py path/to/folder --output-dir path/to/results

Files the tool has already produced (those with _HRLT_ or _MRLT_ in the name) and mapping.csv are skipped automatically, so it's safe to re-run on the same folder. A summary at the end lists any files that had unrecognized headers.

Output file names

A new copy is written for each file — the original is never modified. The name encodes the operation and the run date:

<originalname>_HRLT_YYYY-MM-DD.csv    # Human Readable Label Translated  (machine -> human)
<originalname>_MRLT_YYYY-MM-DD.csv    # Machine Readable Label Translated (human   -> machine)

Example: csdz_allStreams_HRLT_2026-07-08.csv

By default the copy lands next to the input; use --output-dir to collect them elsewhere, or -o to name a single file's output explicitly.

Data fidelity: quoting and line endings

The tool never changes, trims, or reformats your cell values — only the header row is translated and every data value is re-emitted exactly. Two options control how the file is written, which matters when you diff an output against the original DAMS export:

--quoting (default preserve)

• preserve — normal quoting, plus quotes any field with leading/trailing spaces. This protects trailing spaces, which an unquoted CSV can otherwise lose when opened in Excel or compared with some tools.
• all — quotes every non-empty field (closest to the DAMS export, which quotes text liberally).
• minimal — quotes only when strictly required (commas, quotes, newlines).

--line-ending (default crlf)

• crlf — the CSV standard, safe for Excel on Windows and macOS.
• lf — matches CA-R DAMS exports (which end rows with a bare line feed).

If you want an output that diffs as cleanly as possible against a DAMS export, use --quoting all --line-ending lf.

---

Unrecognized headers

Any header not found in mapping.csv is kept as-is (its column is never dropped) and listed in a report at the end of the run. If a skipped header looks like a machine field (it contains underscores), the tool prints a reminder to contact the DAMS team so the field can be added to the dictionary/mapping.

---

Updating the mapping (DAMS maintainers only)

mapping.csv is the source of truth: a plain two-column file (machine_name,human_label) you can open and edit in Excel or a text editor. Edit a label, commit, done.

When new fields are added to the metadata dictionary, regenerate the mapping from it (this is the only step that needs openpyxl):

pip install openpyxl
python translate_headers.py --rebuild-mapping --dictionary CaliforniaRevealed_Metadata_Dictionary.xlsx

A rebuild keeps every label you've already curated and only appends newly-defined fields (it reports what it added). Fields that share a human label are automatically disambiguated with a qualifier (e.g. Format (AV Item) vs Format (Print Item)); you can rewrite those in mapping.csv afterward.

---

Do not commit partner data

mapping.csv and the script are safe to share publicly. Partner metadata CSVs are not — the included .gitignore blocks *.csv by default except the mapping and the example. Keep it that way.

---

Files

File	What it is
translate_headers.py	The tool.
mapping.csv	machine ↔ human lookup (edit + commit this).
examples/sample_machine.csv	Tiny synthetic file to try it on.
requirements.txt	openpyxl, needed only for --rebuild-mapping.