langcheck

Overview ¶

langcheck reports where this fleet's own prose on GitHub is not in English.

The rule it measures is a standing one: everything we author on a public repository — doc comments, code comments, test case names, README and documentation prose — is in English, because a public repository is a multi-lingual surface and French-only content excludes the people who have to read it. The session where the work is decided happens in French; the artefact does not.

langcheck [-min 2] [-v] <path>...

It exits 1 when it finds something, 2 on a usage error, 0 otherwise, and it always says how many files and blocks it compared — a check that read nothing passes everything.

Why a parser and not a grep ¶

A grep over `.go` files for French words answers the wrong question. Measured on 2026-10-18 across 987 local checkouts, a word-list grep named 855 files in 25 repositories — and `go-tex/engine` alone accounted for 317 of them, because a TeX engine's test fixtures are full of French DOCUMENTS. Those are data under test, not prose we wrote, and a tool that cannot tell them apart names everybody and is therefore ignored.

So for Go files this reads the COMMENTS, through go/parser. A string literal, a testdata document, a fixture holding a French sentence on purpose: none of them is a comment, so none of them is reported. That removes the entire false-positive class rather than filtering it afterwards.

For Markdown it reads the prose, minus fenced code blocks — a transcript is what a program printed, and what a program printed is not ours to translate.

What it looks for, and what it cannot do ¶

It looks for FRENCH specifically, by a list of function words that are not also English words, and it needs -min of them in one block before it says anything. It is not a language identifier: it would not notice German, and it is not meant to. The risk being measured is the one this fleet actually has, which is that the person writing it thinks in French.

A block of English that quotes a French phrase in passing can reach the threshold. That is why the threshold exists, why -v prints the words that matched, and why the exit status is a report rather than a gate in CI until somebody decides it should be.

Measured, so the rate is a number and not a worry: on go-fileshare/docs — 200 files, 5243 blocks, a site deliberately translated into three languages — it reports exactly ONE block, and that block is this case:

1. `content/<lang>/`: a translation of every page … A translated heading keeps the English one's anchor as an explicit id (`## Certificats destinés à cet hôte …`)

English documentation quoting a French heading as its example. `-v` shows `cet ·accent`, which is enough for a reader to dismiss it in a second. One in 5243 is the residue after the comment unit, the worktree skip and the translation skip have each removed a whole class.