ref-style-converter

Citation Formatter

Reference format conversion tool that supports mutual conversion between the four mainstream academic citation formats APA (7th), MLA (9th), IEEE, and Harvard, while also providing format error checking and batch processing capabilities.

Supported formats

Format	Description	Example
APA	American Psychological Association 7th edition	Smith, J. A. (2023). Title. *Journal*, *1*(2), 10-20.
MLA	Modern Language Association 9th edition	Smith, John A. "Title." *Journal*, vol. 1, no. 2, 2023, pp. 10-20.
IEEE	Institute of Electrical and Electronics Engineers	[1] J. A. Smith, "Title," *Journal*, vol. 1, no. 2, pp. 10-20, 2023.
Harvard	Harvard Referencing Style	Smith, J.A. (2023) 'Title', *Journal*, 1(2), pp. 10-20.

Quick Start

1. Format conversion (text input)

Convert an APA format citation to IEEE format:

python3 scripts/citation_formatter.py convert --to ieee "Smith, J. A. (2023). Machine learning approaches. Nature, 12(3), 45-67."

2. Format conversion (structured JSON input, more precise)

echo '{"authors":["Smith, John A.","Jones, Mary B."],"year":"2023","title":"Machine learning approaches","journal":"Nature","volume":"12","issue":"3","pages":"45-67","entry_type":"article"}' | python3 scripts/citation_formatter.py format --style ieee

3. Format error checking

python3 scripts/citation_formatter.py check --style apa "Smith J (2023) Machine learning. Nature 12(3) 45-67"

4. Batch processing

# 从文件批量转换（每行一条引用）
python3 scripts/citation_formatter.py convert --to mla --input refs.txt

# 批量检查
python3 scripts/citation_formatter.py check --style apa --input refs.txt

5. Automatic format detection

python3 scripts/citation_formatter.py detect "Smith, J. A. (2023). Title. Nature, 12(3), 45-67."

Detailed description of subcommands

format — Structured data formatting

Convert structured citation data in JSON format into citation text in the specified format.This is the most reliable method, because there is no need to parse text.

# 通过 stdin 传入 JSON
echo '{"authors":["Zhang, Wei"],"year":"2024","title":"Deep Learning","publisher":"Springer","entry_type":"book"}' | python3 scripts/citation_formatter.py format --style harvard

# 通过 --data 参数传入
python3 scripts/citation_formatter.py format --style apa --data '{"authors":["Li, Ming"],"year":"2024","title":"AI Methods","journal":"Science","volume":"5","pages":"1-10","entry_type":"article"}'

# 批量：传入 JSON 数组文件
python3 scripts/citation_formatter.py format --style mla --input citations.json

JSON field descriptions:

Field	Type	Required	Description
authors	string[]	✓	Author list, format "姓, 名"
year	string	✓	Publication year
title	string	✓	Title
journal	string	Required for journal articles	Journal name
volume	string		Volume number
issue	string		Issue number
pages	string		Page numbers, such as "45-67"
publisher	string	Required for books	Publisher
doi	string		DOI
url	string		URL
entry_type	string		article / book / chapter / webpage
edition	string		Edition
city	string		Publication city

parse — Parse text into structured data

python3 scripts/citation_formatter.py parse "Smith, J. A. (2023). Title. Nature, 12(3), 45-67."
# 输出 JSON 结构化数据

convert — Format conversion

# 自动检测源格式，转为目标格式
python3 scripts/citation_formatter.py convert --to harvard "Smith, J. A. (2023). Title. Nature, 12(3), 45-67."

# 指定源格式
python3 scripts/citation_formatter.py convert --from apa --to ieee "Smith, J. A. (2023). Title. Nature, 12(3), 45-67."

# JSON 输出
python3 scripts/citation_formatter.py convert --to mla --json "Smith, J. A. (2023). Title. Nature, 12(3), 45-67."

check — Format error checking

# 检查 APA 格式是否正确
python3 scripts/citation_formatter.py check --style apa "Smith, J. A. (2023). Title. Nature, 12(3), 45-67."

# JSON 输出（方便程序处理）
python3 scripts/citation_formatter.py check --style apa --json "Smith, J. A. (2023). Title. Nature, 12(3), 45-67."

Check items include:

• Missing required fields (author, title, year)
• Correctness of year format
• Journal name, volume number, and page numbers for journal articles
• Publisher information for books
• DOI format
• Format-specific punctuation and structural conventions

detect — Automatic format detection

python3 scripts/citation_formatter.py detect "[1] J. Smith, \"Title,\" Nature, vol. 1, 2023."
# 输出: ieee

Usage recommendations

1. Most reliable method: First extract structured information from the user input, construct JSON, then use the format subcommand to format
2. Quick conversion: If the user already has citation text in a standard format, directly use the convert subcommand
3. Batch processing: Put citations into a file (one per line), use the --input parameter
4. Quality check: After conversion, use the check subcommand to verify the result

Prerequisites

• Python 3.7+
• No additional dependencies need to be installed (only the standard library is used)
• No API Key required