bilingual-documentation

Keeps paired bilingual documentation surfaces stating identical facts with verifiable numbers.

Updated Aug 6, 2021
One-click install
npx skills add https://github.com/the-homeless-god/dotfiles --skill bilingual-documentation-the-homeless-god
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bilingual-documentation
Source: https://github.com/the-homeless-god/dotfiles/tree/main/skills/bilingual-documentation
Command: npx skills add https://github.com/the-homeless-god/dotfiles --skill bilingual-documentation-the-homeless-god

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Repositories that document themselves in two languages drift apart silently: numbers diverge, translations go stale, and readers of one language act on facts the other language contradicts. This Skill defines the pairing rules, README routing, and verification checks that keep both surfaces stating one set of facts. ## Core Features & Use Cases - Pairing and routing rules: Establishes which surface takes the bare filename per artifact class, requires mutual links between paired documents, and keeps the README as a router rather than a second statement of facts. - Verifiable numbers: Enforces that every number in a document names the command that prints it, so any reader can refute a stale figure in one line. - Divergence detection and honest stubs: Uses structural comparison, source_sha256 stamps, and skeleton checks to catch drift, and publishes explicit stub pages instead of machine drafts passed off as translations. - Use Case: A repository ships README, docs, and specs in English and Russian. Use this Skill to audit the pair inventory in both directions, execute every command a document names against its printed number, and report coverage split by translated, machine-drafted, stubbed, and absent. ## Quick Start Use the bilingual-documentation skill to audit this repository's paired documents and README routing, then report what diverged between the two languages.

Frequently Asked Questions about bilingual-documentation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I keep bilingual documentation in sync in a repository?

Pair each document with its counterpart using a suffix convention decided per artifact class, link the surfaces to each other, and make updating both languages a numbered step of every change. Structural comparison and source_sha256 stamps catch drift in CI.

How do I detect stale numbers in documentation?

Require every number in a document to name the command that prints it, such as wc -l or a jq query. Verification then executes each named command and compares its output against the printed figure, so stale values are refuted in one line.

Which file should get the bare name in bilingual docs?

There is no repository-wide rule; the tool reading each artifact class decides. A Hugo site follows defaultContentLanguage, a prose tree follows the language outside contributors arrive in, and a router README means both surfaces carry a suffix.

Should I publish machine translations as documentation?

No. Publish an explicit stub with status: stub, noindex, and a link to the original instead of a machine draft presented as a reading. Report coverage split by translated, machine-drafted, and stubbed so the numbers stay honest.

What are the limits of automated translation consistency checks?

Automated checks compare shape only: code blocks, link targets, table structure, script ratios, and length corridors. No mechanical check compares what two surfaces assert, so factual equivalence remains the responsibility of the commit that changes it.