Back to Details

readability-scorer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Readability Scorer

可读性评分工具

Analyze text readability using industry-standard formulas. Get grade level estimates, complexity metrics, and suggestions for improving clarity.
使用行业标准公式分析文本可读性，获取年级水平估算、复杂度指标以及提升清晰度的建议。

Quick Start

快速开始

python
from scripts.readability_scorer import ReadabilityScorer
python
from scripts.readability_scorer import ReadabilityScorer

Score text

为文本评分

scorer = ReadabilityScorer() scores = scorer.analyze("Your text to analyze goes here.") print(f"Grade Level: {scores['grade_level']}") print(f"Flesch Reading Ease: {scores['flesch_reading_ease']}")
undefined
scorer = ReadabilityScorer() scores = scorer.analyze("此处填入待分析的文本。") print(f"年级水平: {scores['grade_level']}") print(f"Flesch阅读舒适度: {scores['flesch_reading_ease']}")
undefined

Features

功能特性

  • Multiple Formulas: Flesch-Kincaid, Gunning Fog, SMOG, Coleman-Liau, ARI
  • Grade Level: US grade level estimate
  • Reading Ease: 0-100 ease score
  • Text Statistics: Words, sentences, syllables, complex words
  • Batch Analysis: Process multiple documents
  • Comparison: Compare readability across texts
  • 多公式支持：Flesch-Kincaid、Gunning Fog、SMOG、Coleman-Liau、ARI
  • 年级水平：美国年级水平估算
  • 阅读舒适度：0-100分的舒适度评分
  • 文本统计：单词数、句子数、音节数、复杂单词数
  • 批量分析：处理多个文档
  • 对比分析：跨文本比较可读性

API Reference

API 参考

Initialization

初始化

python
scorer = ReadabilityScorer()
python
scorer = ReadabilityScorer()

Analysis

分析功能

python
scores = scorer.analyze(text)
python
scores = scorer.analyze(text)

Returns:

返回结果:

{

{

'flesch_reading_ease': 65.2,

'flesch_reading_ease': 65.2,

'flesch_kincaid_grade': 8.1,

'flesch_kincaid_grade': 8.1,

'gunning_fog': 10.2,

'gunning_fog': 10.2,

'smog_index': 9.5,

'smog_index': 9.5,

'coleman_liau': 9.8,

'coleman_liau': 9.8,

'ari': 8.4,

'ari': 8.4,

'grade_level': 8.5, # Average

'grade_level': 8.5, # 平均值

'reading_time_minutes': 2.3,

'reading_time_minutes': 2.3,

'stats': {

'stats': {

'words': 250,

'words': 250,

'sentences': 15,

'sentences': 15,

'syllables': 380,

'syllables': 380,

'complex_words': 25,

'complex_words': 25,

'avg_words_per_sentence': 16.7,

'avg_words_per_sentence': 16.7,

'avg_syllables_per_word': 1.52

'avg_syllables_per_word': 1.52

}

}

}

}

undefined
undefined

Individual Scores

单独获取分数

python
undefined
python
undefined

Get specific scores

获取特定分数

fre = scorer.flesch_reading_ease(text) fkg = scorer.flesch_kincaid_grade(text) fog = scorer.gunning_fog(text) smog = scorer.smog_index(text)
undefined
fre = scorer.flesch_reading_ease(text) fkg = scorer.flesch_kincaid_grade(text) fog = scorer.gunning_fog(text) smog = scorer.smog_index(text)
undefined

Batch Analysis

批量分析

python
texts = [text1, text2, text3]
results = scorer.analyze_batch(texts)
python
texts = [text1, text2, text3]
results = scorer.analyze_batch(texts)

From files

从文件读取分析

results = scorer.analyze_files(["doc1.txt", "doc2.txt"])
undefined
results = scorer.analyze_files(["doc1.txt", "doc2.txt"])
undefined

Comparison

对比分析

python
undefined
python
undefined

Compare two texts

对比两个文本

comparison = scorer.compare(text1, text2) print(f"Text 1 grade: {comparison['text1']['grade_level']}") print(f"Text 2 grade: {comparison['text2']['grade_level']}")
undefined
comparison = scorer.compare(text1, text2) print(f"文本1年级水平: {comparison['text1']['grade_level']}") print(f"文本2年级水平: {comparison['text2']['grade_level']}")
undefined

CLI Usage

CLI 使用方法

bash
undefined
bash
undefined

Analyze text

分析文本

python readability_scorer.py --text "Your text here"
python readability_scorer.py --text "此处填入你的文本"

Analyze file

分析文件

python readability_scorer.py --input document.txt
python readability_scorer.py --input document.txt

Compare files

对比文件

python readability_scorer.py --compare doc1.txt doc2.txt
python readability_scorer.py --compare doc1.txt doc2.txt

Batch analyze directory

批量分析目录

python readability_scorer.py --input-dir ./docs --output report.csv
python readability_scorer.py --input-dir ./docs --output report.csv

Specific formula only

仅使用特定公式

python readability_scorer.py --input doc.txt --formula flesch
undefined
python readability_scorer.py --input doc.txt --formula flesch
undefined

CLI Arguments

CLI 参数

ArgumentDescriptionDefault
--text
Text to analyze-
--input
Input file-
--input-dir
Directory of files-
--output
Output file (json/csv)-
--compare
Compare two files-
--formula
Specific formulaall
参数描述默认值
--text
待分析的文本-
--input
输入文件-
--input-dir
文件目录-
--output
输出文件（json/csv格式）-
--compare
对比两个文件-
--formula
指定使用的公式all

Score Interpretation

分数解读

Flesch Reading Ease

Flesch阅读舒适度

ScoreDifficultyGrade Level
90-100Very Easy5th grade
80-89Easy6th grade
70-79Fairly Easy7th grade
60-69Standard8th-9th grade
50-59Fairly Hard10th-12th grade
30-49DifficultCollege
0-29Very DifficultCollege graduate
分数难度年级水平
90-100极易5年级
80-89容易6年级
70-79较易7年级
60-69标准8-9年级
50-59较难10-12年级
30-49困难大学
0-29极难大学毕业

Grade Level Scale

年级水平对照表

GradeAudience
1-5Elementary school
6-8Middle school
9-12High school
13-16College
17+Graduate level
年级受众
1-5小学生
6-8初中生
9-12高中生
13-16大学生
17+研究生及以上

Examples

示例

Analyze Blog Post

分析博客文章

python
scorer = ReadabilityScorer()

blog_post = """
Writing clear content is essential for engaging readers.
Short sentences help. Simple words work best.
Your audience will thank you for making things easy to understand.
"""

scores = scorer.analyze(blog_post)
print(f"Flesch Reading Ease: {scores['flesch_reading_ease']:.1f}")
print(f"Grade Level: {scores['grade_level']:.1f}")
print(f"Reading Time: {scores['reading_time_minutes']:.1f} minutes")

if scores['grade_level'] > 8:
    print("Consider simplifying for a wider audience.")
python
scorer = ReadabilityScorer()

blog_post = """
撰写清晰的内容对于吸引读者至关重要。
短句更有帮助，简单词汇效果最佳。
你的读者会感谢你让内容易于理解。
"""

scores = scorer.analyze(blog_post)
print(f"Flesch阅读舒适度: {scores['flesch_reading_ease']:.1f}")
print(f"年级水平: {scores['grade_level']:.1f}")
print(f"阅读时间: {scores['reading_time_minutes']:.1f} 分钟")

if scores['grade_level'] > 8:
    print("建议简化内容以覆盖更广泛的受众。")

Compare Document Versions

对比文档版本

python
scorer = ReadabilityScorer()

original = open("original.txt").read()
simplified = open("simplified.txt").read()

comparison = scorer.compare(original, simplified)

print("Original:")
print(f"  Grade Level: {comparison['text1']['grade_level']:.1f}")
print(f"  Flesch Ease: {comparison['text1']['flesch_reading_ease']:.1f}")

print("\nSimplified:")
print(f"  Grade Level: {comparison['text2']['grade_level']:.1f}")
print(f"  Flesch Ease: {comparison['text2']['flesch_reading_ease']:.1f}")

improvement = comparison['text1']['grade_level'] - comparison['text2']['grade_level']
print(f"\nImprovement: {improvement:.1f} grade levels easier")
python
scorer = ReadabilityScorer()

original = open("original.txt").read()
simplified = open("simplified.txt").read()

comparison = scorer.compare(original, simplified)

print("原版文档:")
print(f"  年级水平: {comparison['text1']['grade_level']:.1f}")
print(f"  Flesch舒适度: {comparison['text1']['flesch_reading_ease']:.1f}")

print("\n简化版文档:")
print(f"  年级水平: {comparison['text2']['grade_level']:.1f}")
print(f"  Flesch舒适度: {comparison['text2']['flesch_reading_ease']:.1f}")

improvement = comparison['text1']['grade_level'] - comparison['text2']['grade_level']
print(f"\n提升幅度: 降低了{improvement:.1f}个年级水平，更易阅读")

Batch Analyze Documentation

批量分析文档

python
scorer = ReadabilityScorer()
import os

results = []
for filename in os.listdir("./docs"):
    if filename.endswith(".md"):
        text = open(f"./docs/{filename}").read()
        scores = scorer.analyze(text)
        results.append({
            'file': filename,
            'grade': scores['grade_level'],
            'ease': scores['flesch_reading_ease']
        })
python
scorer = ReadabilityScorer()
import os

results = []
for filename in os.listdir("./docs"):
    if filename.endswith(".md"):
        text = open(f"./docs/{filename}").read()
        scores = scorer.analyze(text)
        results.append({
            'file': filename,
            'grade': scores['grade_level'],
            'ease': scores['flesch_reading_ease']
        })

Sort by difficulty

按难度排序

results.sort(key=lambda x: x['grade'], reverse=True)
print("Documents by Difficulty:") for r in results: print(f" {r['file']}: Grade {r['grade']:.1f}")
undefined
results.sort(key=lambda x: x['grade'], reverse=True)
print("文档难度排序:") for r in results: print(f" {r['file']}: 年级水平 {r['grade']:.1f}")
undefined

Dependencies

依赖项

nltk>=3.8.0
nltk>=3.8.0

Limitations

局限性

  • English language only
  • Formulas designed for prose (may not work well for lists, code, etc.)
  • Syllable counting is estimated (may have minor inaccuracies)
  • Doesn't assess comprehension, only surface-level complexity
  • 仅支持英语
  • 公式专为散文设计（对列表、代码等内容的分析效果可能不佳）
  • 音节计数为估算值（可能存在微小误差）
  • 仅评估表面复杂度，不涉及理解能力评估