Skip to content
Leonidov.DEV

Readability Library: 4 Ports and One Identical Score

Engineering
Readability Library: 4 Ports and One Identical Score

The same Ukrainian paragraph scored 11.2 in PHP and 11.9 in Python. Both numbers looked reasonable, both went to a client dashboard, and the only reason anyone noticed was a screenshot in a meeting where two slides disagreed.

Code: ReadSight, MIT licensed.

That is how a porting project starts. A readability library written for PHP gets reimplemented in another language because the pipeline moved, and six months later nobody can say which implementation is right.

Mine now runs in four languages and returns the same numbers in all of them. Getting there was less about maths than about agreeing on what “the same” means.

Why port at all

Readability scoring lives where text lives. A PHP site needs it in a WP-CLI command. A Node service needs it in a request handler. A Python pipeline needs it before an embedding step. A Rust job needs it because the batch run is faster there.

Calling a service for that is a network hop per page, and the service becomes a dependency for something that is pure arithmetic over strings.

The four packages are PHP, Python, TypeScript and Rust, each with no runtime dependencies and bundled language data.

What diverges when you reimplement

The formulas themselves are published and stable. Gunning Fog is a fixed expression over words, sentences and complex words. Nothing in it is ambiguous.

The divergence comes from everything around the formula.

Character counting is first. PHP’s mb_strlen and JavaScript’s String.length count different things, so a word with a combining accent is four characters in one and two in the other, and the Coleman-Liau index reads characters per hundred words.

Rounding is second. A grade of 11.25 rounds to 11 in one language’s default formatting and to 11.3 in another, and a dashboard comparing two systems reports a difference that is a formatting artifact.

Word splitting is third. A hyphenated compound is one word in one implementation and two in another, which moves the average words per sentence and every grade level with it.

Syllables are fourth, and the hardest. The pattern files are the same, but the application order, the exception lists and the normalisation of apostrophes have to match exactly, or the same sentence produces a different count.

How to make four implementations agree

The answer is a shared test corpus, and it took three iterations to get right.

Every case is a text, a language and a formula, with the expected value stored at a fixed precision. Each port reads the same table and fails the build on a mismatch beyond a tolerance of zero. Not “close enough”, because closeness is where the drift lives.

The corpus has to include the ugly inputs, or the ports agree on clean prose and disagree on the text that ships. Accented characters, emoji, code snippets, numbers with units, a paragraph of legal boilerplate, a single word, an empty string.

The reference implementation is not automatically the PHP one. For each disputed case we check the published formula by hand and decide which behaviour is correct, then fix every port to match. Twice that decision went against PHP.

What the ports share

One syllable engine: the TeX hyphenation patterns by Frank M. Liang, applied per language, with the same exception lists.

One formula registry: 17 formulas, with five that work in any language and twelve that carry published coefficients. Each language declares which formulas it supports, so English gets nine and German gets eight.

One data file format, generated once and copied, so a coefficient correction lands in all four packages in the same release.

Is it worth it

For one implementation, no. Four implementations of the same arithmetic is a maintenance bill that only makes sense if the alternative is a network dependency in four different pipelines.

What makes it payable is the test corpus. Without it, four ports are four libraries that happen to share a name. With it, a change in one language fails in the other three before release, and the drift that started this project cannot happen again.

The discipline behind that is the same one that keeps a project from burning down: write the spec down before the code, which is what a missing spec does to a project covers. And when the port has to live in a larger system, the choice of boundaries matters, as in six architecture patterns.

Packages: Packagist, PyPI, npm, crates.io.