Publishing an OSS project in multiple languages is useful, but translated documentation introduces a maintenance problem very quickly. Typical failure modes are familiar: the English README changes but the Japanese version does not nobody is sure which version is authoritative a translation gains content that never reaches the canonical document developers or AI tools read an outdated translation as if it were current design documentation I ran into this while expanding the English documentation for PSXRecompStudio. GitHub: https://github.com/mao2009/PSXRecompStudio My solution was to make the English documents the explicit canonical source / SSOT and add CI checks that detect stale translations. Why translations need a source of truth Suppose a repository has: README.md README.ja.md If both files are treated as equally authoritative, every edit creates a coordination problem. Instead, I use a simpler rule: English is canonical. Translations are derived documents. A translated document is still valuable for readers, but architectural and specification decisions ultimately refer back to the canonical file. Store the relationship as data The canonical-to-translation mapping is kept in JSON rather than hard-coded into the CI script. For example: { "version": 1, "pairs": [ { "canonical": "README.md", "translation": "README.ja.md", "language": "ja", "canonicalMarker": "[English README (Canonical / SSOT)](README.md)" } ] } This describes which file is authoritative, which file is its translation, the language, and which canonical marker should appear in the translation. As the documentation set grows, adding a new pair is a data change rather than a code change. Make the canonical relationship visible to humans too The translated document should clearly say that it is a translation and link back to the canonical source. That helps in two ways: readers know which file wins when there is disagreement CI can verify that the relationship is still declared This avoids a common documentation smell: two almost-identical files with no explicit indication of which one is authoritative. Detect stale translations in CI The next step is to make freshness machine-checkable. A practical approach is to record which canonical revision a translation was last synchronized against. CI can then compare that information with the current canonical file. Conceptually: canonical changed ↓ translation metadata still points to old revision ↓ CI reports stale translation The exact implementation can vary. The important part is that freshness becomes a build-time property instead of something maintainers have to remember manually. Why this matters for AI-assisted development Outdated translations are especially dangerous when repositories are consumed by AI coding agents. A human may notice that a translated document looks old. An agent may simply treat the first relevant file it finds as the current specification. By declaring one SSOT and checking synchronization automatically, the repository gives both humans and tools a clearer hierarchy of trust. Treat documentation like code The broader lesson is that documentation maintenance benefits from the same ideas we already use for source code: define ownership define the source of truth represent relationships in machine-readable form validate invariants in CI fail visibly when derived artifacts become stale Translations are derived artifacts, even when humans maintain them manually. Once I started treating them that way, the maintenance model became much clearer. Closing thoughts Multilingual OSS documentation is valuable, but duplicating information without an explicit authority model creates ambiguity. Making one language canonical and validating translation freshness in CI gives the repository a predictable rule: translations may lag temporarily, but they cannot silently pretend to be current. That small distinction makes documentation easier to maintain and safer to consume.