SLD2reader

SLD2reader is a command-line tool for inspecting .sdc SLD2 dictionary files and exporting their contents into more open, easier-to-process formats.

It is designed for BYO-files workflows: you supply your own SLD2 files, run the tool locally, and keep the original content under your control.

Purpose

Use SLD2reader to:

• inspect unknown SLD2 files
• extract readable data from supported file families
• export entries into generic formats such as plain text, JSONL, structured JSONL, and DSL
• produce machine-readable manifests and validation artifacts
• move data out of opaque source containers and into formats that are easier to preserve, search, transform, and reuse

Non-goals

This project intentionally does not:

• bundle dictionary content
• grant redistribution rights over source files or exports
• provide a GUI
• promise byte-faithful recreation of every original presentation detail

Requirements

• Python 3.10+
• Your own SLD2 .sdc files
• No required third-party Python packages for the core CLI
• Optional: downstream tools such as pyglossary if you want to convert DSL into other dictionary ecosystems

Quick start

1. Inspect a file:

   python3 sld2reader.py inspect your_dictionary.sdc

2. Export directly readable material where available:

   python3 sld2reader.py export-readable your_dictionary.sdc out_readable

3. Export the best currently supported open form:

   python3 sld2reader.py export-decoded your_dictionary.sdc out_export

4. See the full CLI surface:

   python3 sld2reader.py --help

Output formats

SLD2reader can produce several output styles. Choose the format that matches your workflow:

Output	Best for	Notes
Plain text	Quick inspection	Simple, readable exports
JSONL	Scripts and indexing	One JSON object per record
Structured JSONL	Highest-fidelity machine-readable export	Best choice when you want richer structure
DSL	Dictionary-oriented exchange	Useful as a bridge into other conversion tools
Manifest JSON	Automation and provenance	Summarizes written outputs and counts
Validation/report JSON	Regression and integrity checks	Useful for repeatable local workflows

Recommended defaults

• Prefer structured JSONL for the richest open export.
• Prefer flat JSONL for simpler entry-oriented pipelines.
• Prefer DSL when your goal is downstream dictionary conversion.
• Prefer plain text when you are first exploring an unfamiliar file.

Core commands

Command	Purpose
inspect	Show high-level metadata and section/container information
export-readable	Write directly readable text-based material where available
export-decoded	Write the best currently supported open export for the given file

Some specialized analysis and validation commands also exist for local research workflows. They are intentionally omitted from this high-level README so the public documentation stays generic and file-family-neutral. Use python3 sld2reader.py --help when you need the full command list.

Export behavior

Generic export goal

The public goal of this tool is to move SLD2 data into formats that are easier to inspect, preserve, transform, and use elsewhere.

For most users, that means:

1. inspect the source file
2. run export-decoded
3. choose JSONL or DSL depending on the next tool in the pipeline

Alias handling

Some decoded export paths use a conservative alias policy:

• aliases / export_aliases contain display-safe exported aliases
• raw_search_terms preserves the broader recovered lookup vocabulary
• rejected_search_terms records lookup terms intentionally kept out of DSL keys and other standard dictionary outputs

When available, --alias-mode legacy restores the broader legacy alias behavior for comparison/debugging.

Typical workflows

Explore an unknown SLD2 file

python3 sld2reader.py inspect your_dictionary.sdc
python3 sld2reader.py export-readable your_dictionary.sdc out_readable

Export into open formats

python3 sld2reader.py export-decoded your_dictionary.sdc out_export

Then choose:

• *.jsonl for flat machine-readable records
• *_structured_entries.jsonl for richer structure where available
• *.dsl for dictionary-oriented interchange

Convert into other dictionary formats

SLD2reader intentionally focuses on extraction and open intermediate formats.

If you need another dictionary format, the usual workflow is:

1. export DSL with SLD2reader
2. convert that DSL with a downstream tool such as pyglossary

Output layout

Exact filenames depend on the input file and export path, but common artifacts include:

• decoded entry exports (*.jsonl)
• structured entry exports (*_structured_entries.jsonl)
• DSL exports (*.dsl)
• manifest files (*_decoded_manifest.json)
• validation/report files (*_validation_report.json)
• optional analysis artifacts for deeper research commands

Current support model

SLD2reader is a generic SLD2 reader, but practical decoded export coverage still varies by file family.

The safest assumption is:

• every file should start with inspect
• some files may expose readable sections immediately
• some files may support richer decoded export
• some advanced research commands are still tailored to local sample fixtures

Repository layout

Path	Purpose
sld2reader.py	Thin CLI entrypoint
sld2reader_lib/	Internal parsing, decoding, exporting, and validation logic
README.md	High-level project overview
WORKFLOW.txt	Practical BYO-files usage walkthrough
FORMAT_NOTES.txt	Lower-level format and reverse-engineering notes
CONTRIBUTING.md	Contributor workflow and publishing guidance

Known limitations

• Decoded export coverage varies by file family.
• Unknown SLD2 files may be inspectable before they are exportable.
• Some export paths remain experimental.
• Higher-fidelity structured exports are still approximations rather than perfect recreations of original presentation layers.
• The deeper analysis commands are intended for investigation and refinement, not for everyday export workflows.