readability-consensus
v1.0.1
Published
7-Formula Consensus Readability Engine implementing Flesch Reading Ease, Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI, SMOG, and national adaptations (Fernández-Huerta, Amstad, Gulpease).
Maintainers
Readme
readability-consensus
Research-backed multi-formula readability and comprehension consensus engine for TypeScript, Node.js, and web browsers. Powering the Readability Checker at WordCount Pulse.
Live Demos & Free Online Tools
Experience the readability inspector live across our localized tools:
- English: Readability Scores Checker
- Spanish: Calculadora de Legibilidad
- German: Lesbarkeitsindex-Rechner
- French: Test de Lisibilité
- Italian: Calcolo Leggibilità Testo
- Japanese: 可読性チェッカー・読解難易度判定
- Core Editor: WordCount Pulse Home
The Consensus Methodology
Single-formula scores frequently produce erratic outliers depending on text length and syllable estimation errors. readability-consensus calculates a normalized consensus grade level by harmonizing 6 classic international indices plus validated national formulas:
Core Formulas Supported
- Flesch Reading Ease (FRE): Standard comprehension scale (0–100).
- Flesch-Kincaid Grade Level (FKGL): US academic school grade equivalent (1–18+).
- Gunning Fog Index: Evaluates sentence length and complex polysyllabic words.
- Coleman-Liau Index (CLI): Character and letter-frequency based metric without syllable ambiguity.
- Automated Readability Index (ARI): Character-per-word typewriter and screen metric.
- SMOG Index: Recommended standard for academic and healthcare texts.
Country-Specific National Adaptations
- Spanish (
es): Fernández-Huerta Formula ($206.84 - 0.60 \times (\text{Syllables}/100w) - 1.02 \times (\text{Sentences}/100w)$). - Portuguese (
pt): Flesch Adaptado Brasil / Martins ($248.835 - 1.015 \times \text{WPS} - 84.6 \times \text{SPW}$). - French (
fr): Kandel-Moles Formula ($207 - 1.015 \times \text{WPS} - 73.6 \times \text{SPW}$). - German (
de): Toni Amstad Formel ($180 - \text{WPS} - 58.5 \times \text{SPW}$). - Italian (
it): Indice Gulpease ($89 + (300 \times \text{Sentences} - 10 \times \text{Letters}) / \text{Words}$). - Japanese (
ja): Kanji-to-Kana density ratio and 400-grid Genko Yoshi manuscript sheet calculations.
Installation
npm install readability-consensus
# or
yarn add readability-consensus
# or
pnpm add readability-consensusQuick Start
import { analyzeReadability } from 'readability-consensus';
const text = `
The automated readability consensus engine evaluates multiple linguistic indices simultaneously.
It provides a calibrated consensus score for web writers, academics, and editors.
`;
const analysis = analyzeReadability(text, 'en');
console.log(analysis.consensusGrade); // e.g. 10.5 (Grade Level)
console.log(analysis.consensusLabel); // "High School / Sophisticated"
console.log(analysis.targetAudience); // Target reader demographic
console.log(analysis.isWebOptimal); // true/false (Optimal for SEO if grades 6-9)
// Individual formula scores
console.log(analysis.fleschReadingEase); // 52.4
console.log(analysis.fleschKincaidGrade); // 10.8
console.log(analysis.gunningFog); // 11.2
console.log(analysis.colemanLiau); // 12.1
console.log(analysis.smogIndex); // 10.4
// Linguistic diagnostics
console.log(analysis.complexWordsCount); // Number of 3+ syllable words
console.log(analysis.hardSentencesCount); // Number of long sentences (21+ words)
console.log(analysis.actionableTips); // Concrete recommendations to improve clarityMultilingual Usage
// German analysis (incorporating Toni Amstad index and 180 WPM pace)
const deAnalysis = analyzeReadability("Wissenschaftliche Texte erfordern präzise Formulierungen.", 'de');
console.log(deAnalysis.indexes.find(i => i.shortName === 'TA')?.score);
// Italian analysis (incorporating Indice Gulpease)
const itAnalysis = analyzeReadability("La leggibilità di un testo è fondamentale per la comunicazione.", 'it');
console.log(itAnalysis.indexes.find(i => i.shortName === 'IG')?.score);Documentation & Linguistic Benchmarks
For formula derivations and educational grade equivalencies, visit WordCount Pulse Readability Guide.
License
MIT © WordCount Pulse
