Readability and comprehensibility calculator for Spanish texts

This calculator allows you to analyze the readability and comprehensibility of any text written in Spanish. It automatically calculates some of the main reading ease indices used in research, education, publishing, institutional communication, and health communication. Paste the text you want to analyze below:

1. Readability formulas

Readability formulas attempt to estimate the reading difficulty of a text through quantifiable features, mainly the length of words and sentences. Although none can completely measure reading comprehension, they all offer useful information to adapt a piece of writing to its audience.

1.1. Readability (Fernández Huerta)

José Fernández Huerta created the second formula to measure the readability of Spanish texts in 1959¹. It is based on Flesch’s Reading Ease formula, originally developed for English. The equation appears with errors on numerous websites, but it is presented here corrected²:

L is the readability; P, the average syllables per word; F, the average words per sentence.

Readability is interpreted according to this table:

1.2. Crawford’s formula

It is used to calculate the years of schooling necessary to understand a text. It was devised by Alan N. Crawford in 1989³. It is only valid for elementary school children. The equation is as follows:

A is the number of years of schooling; OP, the number of sentences per hundred words; SP, the number of syllables per hundred words. The result is rounded to the nearest tenth.

1.3. Perspicuity (Szigriszt-Pazos)

In 1993, journalist Francisco Szigriszt-Pazos proposed a formula in his doctoral thesis⁴ to measure the readability or reading comprehension ease of a text. It is a Spanish adaptation of Flesch’s equation. It is calculated like this:

P is the perspicuity; S, the total syllables; P, the total words; F, the total sentences.

Perspicuity is interpreted according to the table:

1.4. García López’s formula

José Antonio García López proposed a formula in 1999⁵ to measure the age required to understand a text. It is another Spanish adaptation of Flesch’s original English formula. It uses the variables syllables per word (S) and words per sentence (P) in the following equation:

E is the minimum expected age to easily understand the text.

In addition, in 2001, he demonstrated its usefulness in determining the readability of informed consents⁶. He considers that the minimum age for this type of document should not exceed twelve years old (primary education level in Spain).

1.5. Readability μ (mu)

Readability μ (mu) is a formula to calculate the reading ease of a text. It was developed by Miguel Muñoz Baquedano and José Muñoz Urra in Chile in 2006⁷. It factors in the number of words, as well as the mean and variance of the number of letters in words.

μ is the readability index; n, the number of words; x̄, the mean number of letters per word; σ², its variance.

The result is interpreted as follows:

1.6. Inflesz Scale (Inés Barrio)

The Inflesz readability scale measures the reading ease of a text. It was developed by Inés María Barrio Cantalejo and is adapted to the average modern Spanish reader. It is calculated exactly the same way as Szigriszt-Pazos’s perspicuity:

I is the Inflesz scale; S, the total syllables; P, the total words; F, the total sentences.

According to Inés Barrio’s doctoral thesis⁸, the interpretation of Szigriszt-Pazos’s formula needs adaptation because it was based on an insufficient, non-representative, and non-random sample of texts. With the Inflesz scale, the result is interpreted differently:

The Inflesz scale has been used in the healthcare field to evaluate the readability of informed consents, patient leaflets, and health education materials. However, it can be applied to texts of any subject.

2. Other formulas to calculate Spanish text readability

The formulas included in the calculator are the most widely known and used. However, there are other Spanish readability assessment models that may be of historical or academic interest.

2.1. Comprehensibility (Gutiérrez de Polini)

Luisa Elena Gutiérrez de Polini (1972) created the first formula conceived, from the ground up, for Spanish (i.e., not an adaptation of an English formula). It is calculated as follows:

C is the text comprehensibility; L, the number of letters; P, the number of words; F, the number of sentences.

It is intended for school texts aimed at sixth-grade students. It is not suitable for texts aimed at adults or students of other ages.

I haven’t been able to locate the primary source⁹ on the internet; I’ve only found secondary references. A copy exists in the National Library of Venezuela.

I haven’t found an interpretation scale for it either. In principle, the lower the score obtained, the more difficult the text is.

2.2. SMOG-SOL Grade (Contreras)

The SMOG grade (McLaughlin, 1969)¹⁰ measures the readability of an English text. It is calculated with this formula:

Where G is the grade level, P is the number of words with three or more syllables, and F, the number of sentences.

Contreras adapted it to Spanish¹¹ in 1999. It introduces the SOL formulas to convert the SMOG grade between English, Spanish, and French. For Spanish it looks like this:

Where E is the converted Spanish grade level and S is the grade level obtained with the first formula.

The grade level represents the years of education needed to understand the text. It’s the data obtained with the second formula.

2.3. Spaulding

This was the first readability formula developed specifically for Spanish. Seth Spaulding published it in 1956¹²:

Where D is the text difficulty; L is the average sentence length; R is the density of rare words (those not included in Milton Buchanan’s list of 1500 frequent Spanish lemmas). Furthermore, words repeated more than twice, days of the week, months, proper nouns, diminutives, augmentatives, toponyms, and demonyms are not considered rare.

The result is interpreted as follows:

2.4. Natividad López Rodríguez’s Formulas

Natividad López Rodríguez published her prediction equations for Spanish reading comprehension difficulty in her doctoral thesis¹², presented in 1981 and directed by José Luis Rodríguez Diéguez.

Her formulas include up to 27 linguistic variables:

• x₁: Percentage of commas.
• x₂: Percentage of semicolons.
• x₃: Percentage of periods.
• x₄: Percentage of new paragraph periods.
• x₅: Percentage of colons.
• x₆: Percentage of colons ending a paragraph.
• x₇: Percentage of exclamation marks.
• x₈: Percentage of question marks.
• x₉: Percentage of em dashes.
• x₁₀: Percentage of compound words.
• x₁₁: Percentage of proper nouns.
• x₁₂: Percentage of numerals.
• x₁₃: Percentage of words with more than 10 letters.
• x₁₄: Percentage of words with 9 and 10 letters.
• x₁₅: Percentage of words with more than 8 letters.
• x₁₆: Average number of words per sentence.
• x₁₇: Number of sentences per hundred words.
• x₁₈: Average number of letters per word.
• x₁₉: Percentage of words with more than 3 syllables.
• x₂₀: Average number of syllables per word.
• x₂₁: Redundancy index (TTR).
• x₂₂: Percentage of words missing from García Hoz’s Common Vocabulary.
• x₂₃: Percentage of words missing from García Hoz’s Merged Common Vocabulary.
• x₂₄: Percentage of words missing from Spaulding’s Density List.
• x₂₅: Percentage of first and second-person pronouns.
• x₂₈: Percentage of words missing from the broad Density List.

The amount of formulas in her thesis is huge, but they can be summarized in this table:

2.4.1. 8th Grade (E.G.B.) Formulas

Formulas with some of the 26 original variables

Computer formulas

Due to their complexity, a computer is required to calculate the difficulty index (D.I.).

Formula No. 4 (ten variables):

Formula No. 5 (seven variables):

Manual formulas

Formula No. 6 (six variables):

Formula No. 7 (five variables):

Formula No. 8 (four variables):

Formulas with the optimized subset of 18 variables

Redundant ones are removed because they do not provide great predictive value, leaving simpler formulas.

Computer formulas

Formula No. 9 (twelve variables):

Formula No. 10 (nine variables):

Manual formulas

Formulas obtained from the 18 optimized variables using 7 variables remain the same as those obtained from the 26 originals.

2.4.2. 7th Grade (E.G.B.) Formulas

Computer formulas

Formula No. 11 (nine variables):

Formula No. 12 (seven variables):

Manual formulas

Formula No. 13 (four variables):

3. What is text readability measurement for?

Readability formulas help estimate the reading difficulty of a text and can be useful for:

• Educational materials.
• Journalistic articles.
• Websites and blogs.
• Institutional communication.
• Patient information.
• Informed consents.
• Manuals and technical documentation.

These metrics allow detecting potentially complex texts to better adapt them to the audience’s needs.

4. Readability formulas limitations

Readability formulas are useful tools, but they shouldn’t be interpreted as an exact measure of a text’s quality.

These indices are mainly based on quantifiable variables, such as word and sentence length. Therefore, they offer a reasonable estimate of reading difficulty, but do not take into account all the factors that influence comprehension.

They do not consider important aspects such as:

• The reader’s prior knowledge.
• Interest in the subject.
• The organization of ideas.
• Typography and visual design.
• Contrast, spacing, and page layout.
• The presence of images, graphics, or supporting tables¹³.

It’s also not true that a short word is always easier to understand than a long one. For example, “loor” (praise) is shorter than “alabanza” (praise), but the latter is usually much more familiar to most readers¹⁴.

Furthermore, it’s possible to obtain high scores by writing very short sentences that, nevertheless, form a confusing or incoherent text. Likewise, a specialized text can obtain a low score and still be perfectly suited for its audience.

Different formulas can produce different results when applied to the same text. This is normal because they use different criteria, and all have limitations.

For this reason, they should be used as an aid to review and improve texts, not as a goal in themselves. The priority must always be that the content is clear, useful, and appropriate for those who will read it.

Ultimately, no formula can substitute the author’s knowledge of their readers.

5. Other tools

5.1. Trunajod

Trunajod deserves a full article of its own. It’s a very complete tool that runs circles around this readability calculator.

Here are the instructions to install Trunajod on Debian 13:

Install the python3-venv package:

$ sudo apt install python3-venv

Create the virtual environment (use whatever path you want):

$ python3 -m venv /home/alejandro/Otros/venv

Activate the virtual environment (with your chosen path):

$ source /home/alejandro/Otros/venv/bin/activate

Install the packages:

$ pip install spacy click seaborn textract trunajod

Install the es_core_news_sm model:

$ python -m spacy download es_core_news_sm

And it’s installed.

To use it well, it’s best to follow the Trunajod instructions, which are in English.

You might need to download trunajod_models_v0.1.tar.gz into your working directory.

In that same folder, create the script (adapted from the Trunajod instructions):

#!/usr/bin/env python3
"""
Linguistic document analysis using TRUNAJOD and spaCy.

This script extracts text from various document formats and
calculates linguistic complexity metrics, such as lexical diversity
and density. It allows exporting the results to a CSV file.

Supported formats (via textract):
    .docx, .doc, .odt, .rtf, .pdf, .txt, .epub, among others.

Basic usage:
    python3 text-analyzer.py document1.docx document2.pdf

Export to CSV:
    python3 text-analyzer.py document1.docx --csv results.csv
"""

import argparse
import csv
import sys
from pathlib import Path
from typing import Dict

import spacy
import textract
import TRUNAJOD.ttr
from TRUNAJOD import surface_proxies


def parse_arguments() -> argparse.Namespace:
    """Configures and parses command-line arguments."""
    parser = argparse.ArgumentParser(
        description="Analyzes the linguistic complexity of one or more documents."
    )
    parser.add_argument(
        "files",
        nargs="+",
        type=Path,
        help="Paths to the files to be analyzed (e.g. docx, pdf)."
    )
    parser.add_argument(
        "--model",
        type=str,
        default="es_core_news_sm",
        help="spaCy model to use (default: es_core_news_sm)."
    )
    parser.add_argument(
        "--csv",
        type=Path,
        metavar="CSV_FILE",
        help="Path to the CSV file where the results will be exported."
    )
    return parser.parse_args()


def analyze_document(nlp: spacy.Language, filepath: Path) -> Dict[str, float]:
    """
    Extracts text from a file and calculates its linguistic metrics.

    Args:
        nlp: Loaded spaCy language model object.
        filepath: Path to the file to process.

    Returns:
        A dictionary with the calculated metrics in key-value format.
    """
    text = textract.process(str(filepath)).decode("utf8")
    doc = nlp(text)

    return {
        "Lexical diversity (MTLD)": TRUNAJOD.ttr.lexical_diversity_mtld(doc),
        "Lexical density": surface_proxies.lexical_density(doc),
        "Dissimilarity (POS)": surface_proxies.pos_dissimilarity(doc),
        "Connection words ratio": surface_proxies.connection_words_ratio(doc),
    }


def main() -> None:
    args = parse_arguments()
    global_results = []

    print(f"Loading language model '{args.model}'...\n", file=sys.stderr)
    try:
        nlp = spacy.load(args.model, disable=["ner", "textcat"])
    except OSError:
        print(
            f"[!] Error: Could not load the model '{args.model}'.\n"
            f"Make sure you have downloaded it by running:\n"
            f"    python3 -m spacy download {args.model}",
            file=sys.stderr
        )
        sys.exit(1)

    for file in args.files:
        print(f"{'=' * 60}")
        print(f"File: {file.name}")
        print(f"{'=' * 60}")

        if not file.exists():
            print(f"[!] Error: The file '{file}' does not exist or the path is incorrect.\n")
            continue

        try:
            results = analyze_document(nlp, file)

            # Save the results for the CSV, adding the file name
            csv_row = {"File": file.name}
            csv_row.update(results)
            global_results.append(csv_row)

            for metric, value in results.items():
                print(f"{metric:<30}: {value:>8.4f}")
            print()

        except textract.exceptions.ExtensionNotSupported:
            print(f"[!] Error: Unsupported file format for '{file.name}'.\n")
        except Exception as exc:
            print(f"[!] Unexpected error processing '{file.name}': {exc}\n")

    # CSV file generation if requested and valid data exists
    if args.csv and global_results:
        try:
            with open(args.csv, mode="w", newline="", encoding="utf-8") as csv_file:
                fields = list(global_results[0].keys())
                writer = csv.DictWriter(csv_file, fieldnames=fields)

                writer.writeheader()
                writer.writerows(global_results)

            print(f"[*] Results successfully exported to '{args.csv}'.")
        except Exception as exc:
            print(f"[!] Error writing the CSV file: {exc}", file=sys.stderr)
    elif args.csv:
        print("[!] CSV was not generated because there were no valid results.", file=sys.stderr)

    print("\nAnalysis finished.")


if __name__ == "__main__":
    main()

Save it with any name with a .py extension, like text-analyzer.py, and run it like this:

$ python3 text-analyzer.py file1.docx file2.docx

Which gives an output similar to this:

Loading language model 'es_core_news_sm'...

============================================================
File: file1.docx
============================================================
Lexical diversity (MTLD)      :  40.6846
Lexical density               :   0.5739
Dissimilarity (POS)           :   0.5232
Connection words ratio        :   0.0771

============================================================
File: file2.docx
============================================================
Lexical diversity (MTLD)      :  36.3744
Lexical density               :   0.5107
Dissimilarity (POS)           :   0.4518
Connection words ratio        :   0.0521

============================================================
File: file3.odt
============================================================
Lexical diversity (MTLD)      :  47.9361
Lexical density               :   0.5425
Dissimilarity (POS)           :   0.4105
Connection words ratio        :   0.0512


Analysis finished.

We obtain:

• Lexical diversity: measure of the lexical diversity of the text.
• Lexical density: proportion of words with lexical meaning in the text.
• Dissimilarity: measure of the dissimilarity of grammatical categories between sentences.
• Connection words ratio: obtains the proportion of connectors over the total words of the text.

You can obtain many more text parameters from each file. They are all in the Trunajod API reference manual.

5.2. Estilector

Estilector is a writing aid program for academic texts in Spanish. It analyzes the text, detects stylistic and writing issues, and offers suggestions for improvement, as well as some spelling corrections. It works by copying and pasting the text into the platform to receive well-founded recommendations, although these should be interpreted as guidelines and not as mandatory rules.

5.3. Artificial Intelligence

Nowadays, artificial intelligence assistants can automatically simplify many texts and adapt them to different reading levels. You can enter a prompt similar to this:

Rewrite this Spanish text so it’s easier to understand for 16-year-olds: And here you paste the text

You quickly get a very good result.

However, knowing the fundamentals of readability is still useful. These formulas allow you to objectively evaluate the changes made, compare versions of the same document, and better understand what factors influence reading ease.

Furthermore, no automatic tool knows readers as well as the person who writes the text. It’s better to do things yourself, because AI makes you dumber the more you use it.