tldr-maintenance: the per-language metrics script that audits the tldr-pages repo

One metrics.tsv file drives every script and every output path

The project is not an application. It is a Bash script that calculates metrics about the current state of the tldr pages repository, so that contributors can see quickly whether there is still work to do and can detect issues. Every metric is defined in scripts/metrics.tsv, and all scripts read that one file. That keeps the list of checks, their names and their output files in a single place.

Results are calculated per language. English results are written to check-pages/<metric>.txt, and every other language gets check-pages.<language>/<metric>.txt, so one file per metric per language. The consequence for a reader is that a translator only has to open the folder for their own language to see their own backlog. Some metrics are marked not for English, because they compare a translated page against its English counterpart and an English page has nothing to be compared with. If a metric file is absent for a language, that language had no results for that metric.

Filename, title and platform checks lean on a script from the main repository

Three metrics deal with where a page lives and what it is called. The inconsistent-filenames metric flags a page whose filename does not match its title, the line starting with # inside the page, and it relies on wrong-filename.py from the tldr repository. The mismatched-page-titles metric, not run for English, flags a translated page whose title differs from the English page's title. The misplaced-pages metric flags a page that is not inside a folder from the list of supported platforms.

The warning that follows from this is in the project's own note: running set-alias-page.py and wrong-filename.py generates false positives, and the results need to be checked by hand. So an inconsistent-filenames count is a list of candidates, not a list of confirmed errors. Fixing a filename because the number says so, without looking at the page, can break a page that was fine. The report is useful for CODEOWNERS who want to watch their own language and notice that changes are needed.

The two alias metrics tell you to check by hand

Alias pages are where the metrics are least trustworthy, and the README says so twice. The missing-alias-pages metric reports a translated alias page as missing when the English page is an alias page but the translated page does not exist. The outdated-alias-pages metric reports a translated alias page as outdated when the English page is an alias but the translated page does not match the alias template or refers to another command. Both entries carry the same sentence: this metric generates false positives, so the results need to be checked by hand.

Neither metric applies to English. For a translator the practical consequence is that the alias totals in the summary overstate the real work, and there is no way, from the number alone, to tell how much. Plan to open each listed page and compare it with the English alias page. Treat a high alias count as a prompt to look, not as proof that the translation is behind.

Outdated is judged by counting and stripping, never by reading meaning

Three metrics decide that a translated page is outdated, and all three are structural. Based on number of commands: the count of commands differs from the English page. Based on the commands itself: every line that starts with a backtick is compared with the English one after removing everything between {{...}}, <...>, (...), double quotes and single quotes. Based on number of header lines: every line starting with > is counted and compared with the English page.

These rules are cheap to compute and have a clear failure mode. A translation that has the same number of commands, the same command text outside placeholders and the same number of header lines passes, even if its description sentences no longer match the English wording. A page that changed only inside placeholders or quoted strings also passes the command-contents check. The metrics catch pages that drifted in shape, not pages that drifted in meaning. A clean result here means the shape agrees with English, and a human review is still needed for the prose.

See-also and more-info checks only fire when the English page has the right shape

The more-info and see-also checks compare a translated mention with a template and with the English page. A more-info line is malformed when the more-information link line does not match the TLDR template, and outdated when its link differs from the English page. For see-also mentions the checks only apply to pages whose English page has a See also mention as the second to last line of the description. Such a mention is malformed when it does not match the translation template, and outdated when the pages it names do not match the English ones.

The missing-see-also-mentions metric adds one rule that surprises people: a mention in the wrong place is reported as missing as well, because the check looks only at the second to last line of the description. The missing-see-also-pages metric is different again; it reports a page that mentions another page in its first translated See also line when that other page does not exist yet in the language. Pages without an English See also line never enter these checks, so their absence says nothing.

Where the totals land, and what the latest release tag means

At the end of metrics-log.md a summary is written with the total of every metric across all languages. The same summary goes to summary.tsv, with the number of results, the total and the percentage per language and for all languages together under the label total. The summary is also tracked in a GitHub issue, number 25 in the repository, along with the metrics per translation. Most totals include a percentage, rounded down to one decimal.

The metrics-log.md link points at a release named latest. That release was last published on 2024-09-07, while the repository's last push was on 2026-11-02, so the tag is a moving label and the release date alone says little about how current the log is. Check the date inside the log or the recent runs of the calculate-metrics workflow before quoting numbers. The README also lists a check-links workflow badge alongside calculate-metrics. Because the percentages round down, a language at 99.97 percent displays as 99.9 and never as 100.0 until it is actually complete.

Running it locally needs Node, Python and ShellCheck, and the repository declares no license

package.json is marked private and names the project tldr-maintenance, so it is not something you install from npm. Its scripts are calculate-metrics, which runs bash scripts/calculate-metrics.sh, plus check-codeowners and check-maintainers, which run Python 3 scripts. The lint script chains lint-markdown (markdownlint on the Markdown files), lint-python (black in check mode, then flake8) and lint-bash (shellcheck over scripts/*.sh). A husky prepare step installs git hooks.

Dependencies are markdownlint-cli ^0.50.0 and tldr-lint ^0.0.23 from npm, and black==26.10.1 and flake8==7.1.1 from requirements.txt. The lint-errors metric itself reports markdownlint and tldr-lint output, with some tldr-lint checks ignored for translations: TLDR104 about English tense, and capital letters and punctuation for some languages. A tldr entry sits at the top level next to .gitmodules, so the pages being measured come in as a checkout of the main repository. Finally, the license field is unknown. Without a stated license you have no clear permission to reuse the scripts in another project, so ask the maintainers before copying code.

Editorial conclusion

Use tldr-maintenance if you look after a language in tldr-pages and want a per-language to-do list of filename, alias, link and translation problems. Do not treat its counts as a final verdict, since the alias metrics and two page scripts raise false positives, and the repository declares no license.

Frequently asked questions

Official sources

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