tldr-maintenance: measuring the health of the tldr-pages translation set

What tldr-maintenance measures that a normal linter does not

tldr-pages is a set of short command examples, split into an English tree and one tree per language. The English tree is the source of truth; translations follow it. That two-tree arrangement creates a class of problem a plain Markdown linter cannot see. A translated page can be perfectly valid Markdown and still be wrong, because the English page it mirrors has since gained a command, lost one, or changed its arguments.

tldr-maintenance exists to count those problems. The README lists the English metrics: malformed more-info links, missing TLDR pages (a page references another page that does not exist), misplaced pages (a page that sits outside the list of supported platforms), and linter errors from markdownlint and tldr-lint. The other-language metrics are a superset. On top of the same malformed, missing and misplaced checks, it adds outdated more-info links, outdated pages based on the number of commands, outdated pages based on the commands themselves, missing English pages, and missing translated pages.

The audience follows from that. This is a maintainer tool. The README names CODEOWNERS as a user: someone who owns a language folder can watch that language for changes that need attention. If you only read tldr pages, nothing here concerns you.

How the comparison between English and translated commands works

The interesting mechanism is the command-level diff. The README defines an outdated page based on the commands themselves as one where every line starting with a backtick differs from the English commands, after removing everything between double curly braces, double quotes and single quotes. Stripping those spans is what makes the comparison useful: the placeholders and quoted arguments in a translated page are expected to differ from the English ones, so they are discarded before the two sets of command lines are compared.

A second check compares only the count. If the number of commands in a translated page differs from the number in the English page, the page is flagged as outdated on that basis alone. The two checks catch different failures. A translation that dropped a command but kept the rest identical fails the count check. A translation that kept the right number of commands but rewrote them fails the command check.

Everything is computed by a Bash script in scripts/, driven by two GitHub Actions workflows, calculate-metrics.yml and check-links.yml. The README describes the project as a repo that runs a Bash script, even though the language breakdown points at Python. The Python side is the linting setup: requirements.txt pins black and flake8, and package.json wires black --check and flake8 into the lint script. The tldr repository itself is present as a submodule, which is how the script reaches the pages it measures.

Installing tldr-maintenance and reading your first metrics run

There is no published package and no install section in the README. The project is a repository you clone, and the two dependencies come from npm and pip. Because tldr is a submodule, clone recursively or the script has no pages to read.

git clone --recurse-submodules https://github.com/tldr-pages/tldr-maintenance
cd tldr-maintenance

Install the Node tools that the metrics run shells out to. markdownlint-cli and tldr-lint are both listed as dependencies in package.json, and husky is a devDependency that installs a Git hook through the prepare script.

npm install

The Python side is only needed if you intend to run the project's own linting. requirements.txt pins two packages, black and flake8.

pip install -r requirements.txt

To run the same checks the project runs on itself, use the npm scripts. lint chains the three linters in order.

npm run lint-bash
npm run lint

The real output is not on stdout. The README states that a workflow run produces an artifact that can be downloaded and viewed to see the exact output per language per metric, so you can tell which page needs attention. A summary is written at the end of metrics-log.md and is also downloadable from the latest GitHub Release. Expect long per-language lists, not a single pass or fail line.

Where tldr-maintenance gives you wrong answers

The README carries an explicit warning, and it is the most important thing on the page. Running set-alias-page.py and wrong-filename.sh, both of which live in the tldr repository rather than here, generates false positives. The results need to be checked by hand. That is a direct statement that the alias and filename metrics are advisory. If you wire this into a gate that blocks a pull request, you will block work that is not actually broken.

The second limitation is structural. Every metric is defined against the tldr repository layout: the platform folder list, the more-info link template, the English page as the reference for translations. Point the script at a different documentation set and the concepts of misplaced, missing and outdated stop meaning anything. This is not a general purpose documentation linter that happens to ship with tldr defaults.

The third is staleness of the tooling around it. The repository's last push was on 2024-09-07, and the only release, tagged latest, carries the same timestamp. The dependency ranges in package.json are carets, so a fresh npm install will pull newer markdownlint-cli and tldr-lint versions than were current when the workflow last ran. A new lint rule in either tool shows up as a new lint error count in your metrics, and nothing in this repository pins it back.

tldr-maintenance against the tldri18n translation dashboard

The README points twice at an external site, tldr translation, for the missing, misplaced, outdated and missing-English checks, noting that each of those can also be seen there implicitly. That site is the natural alternative, and the difference is in the shape of the answer rather than the underlying data.

A dashboard is for browsing. You open it, pick a language, and look at coverage. tldr-maintenance is for machine consumption: it emits a per-language, per-metric list into a workflow artifact and appends a summary with percentages to metrics-log.md, which is then tracked in a GitHub issue. The percentages are calculated against specific denominators, and those denominators differ by metric: total pages for the more-info and misplaced counts, total TLDR commands for the missing-command count, total non-English pages for the two outdated counts, total unique non-English pages for missing English pages, and the total of English pages multiplied by the number of languages for missing translated pages. If you need a number to put in a tracking issue, that is the thing the dashboard does not give you.

The other honest alternative is to run markdownlint and tldr-lint directly and skip this project. You would get the lint error line and nothing else, and you would lose the cross-language comparison that is the reason this repository exists.

Maintenance cost, licence status and what to check before adopting

The last push to tldr-maintenance was on 2024-09-07. That is the only maintenance signal available, and it means you should treat the project as something you may need to fix yourself rather than something that will be fixed for you. The code surface is small, which keeps that cost low: a Bash script under scripts/, a Python lint configuration, and two workflows. The dependencies are the larger liability, because markdownlint-cli and tldr-lint are version-ranged and their rule sets move independently of this repository.

The licence is not stated anywhere in the repository. No licence identifier appears on the record and no LICENSE file is listed among the top-level entries, which are .editorconfig, .flake8, .gitattributes, .github/, .gitignore, .gitmodules, .husky/, .lycheeignore, .markdownlint.json, README.md, package-lock.json, package.json, requirements.txt, scripts/ and tldr. Before you copy any of this into your own repository, establish the licensing position yourself. That is a factual gap, not a legal opinion, and it matters more here than usual because the project is designed to be run inside another project's CI.

One practical detail worth knowing before you start: the lint script covers Markdown, Python and Bash, so a change to the Bash script is checked by shellcheck, and a change to the Python lint configuration is checked by black and flake8. The husky prepare script installs a Git hook on npm install, which will run in your clone whether or not you wanted it.

Editorial conclusion

Adopt tldr-maintenance if you own a language folder in tldr-pages or you maintain the English pages and want a per-page list of what is broken. Do not adopt it if you want a general documentation linter for your own project: it is wired to the tldr repository layout, it shells out to markdownlint and tldr-lint, and the README itself warns that two of the scripts in the tldr repo produce false positives that need hand checking. Before relying on it, verify two things yourself: whether the tldr submodule is pinned to the commit you care about, and whether the workflow in .github/workflows/calculate-metrics.yml still runs on the schedule you expect, given the last push to this repository was on 2024-09-07.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes