I Asked 15 DevTool Maintainers About Documentation Localization
2 comments
Context: I maintain multilingual automation workflows across several Microsoft OSS repositories and started reaching out to DevTool maintainers to understand how they approach documentation localization.
These were some patterns that came up repeatedly.
These were some patterns that came up repeatedly.
Hi from Argentina! We use a lot of loaned words while programming and related stuff. I usually prefer to read the English version, because in the Spanish version I have to untranslate. It's more common in es-es localized docs, they like to translate every single word.
A translated version may be useful for first year students, but somewhere in the middle of the degree every book is in English, the variables must be named in English, the API must use English names, and when you talk you use 95%Spanish+5%English.
The only exception I make is for some real world objects. I work in the first year of the University of Buenos Aires. I made a custom program that must handle the 10 "sedes" where the classrooms are. How do I translate "sede"? It's usually a "building", but sometimes a "sede" has two "buildings", or half a "building". Do I call them "campus", we used to have to "sedes" that were nearby "buildings" inside the same big park that everyone would call "campus". Now each "sede" is like 5 miles away form the nearest one, so they are pretty discrete. So I made an exception and the variable names in the code say "sede".
A translated version may be useful for first year students, but somewhere in the middle of the degree every book is in English, the variables must be named in English, the API must use English names, and when you talk you use 95%Spanish+5%English.
The only exception I make is for some real world objects. I work in the first year of the University of Buenos Aires. I made a custom program that must handle the 10 "sedes" where the classrooms are. How do I translate "sede"? It's usually a "building", but sometimes a "sede" has two "buildings", or half a "building". Do I call them "campus", we used to have to "sedes" that were nearby "buildings" inside the same big park that everyone would call "campus". Now each "sede" is like 5 miles away form the nearest one, so they are pretty discrete. So I made an exception and the variable names in the code say "sede".
Why do so few developer tools maintain multilingual documentation?
I expected to hear complaints about translation quality or tooling limitations. Instead, the most common answer was much simpler: most teams intentionally avoid localization.
Across many fast-moving DevTool projects, the lifecycle of documentation translation often looks like this:
project grows → community starts translating docs → source docs evolve quickly → translations drift → maintainers stop maintaining them → docs return to English-only
Several maintainers told me they had experimented with translation platforms or community-driven localization in the past. But keeping translations synchronized became difficult as documentation and APIs evolved rapidly. Eventually many teams chose to revert to English-only documentation.
In fast-moving DevTool teams, documentation changes frequently: APIs evolve, installation steps change, configuration examples update, screenshots and diagrams become outdated. When documentation changes weekly, translations can quickly fall behind. Reviewing translation pull requests also adds extra work for maintainers.
Instead of maintaining official translations, many teams rely on a simpler structure:
official docs → English community tutorials → other languages
Developers around the world often write guides in Korean, Japanese, Chinese, Spanish, and other languages, but these usually live outside the official documentation. This lets teams move quickly without adding localization maintenance overhead.
One interesting pattern from these conversations was this:
translation drift is a known problem ≠ teams are willing to pay to solve it
Even when maintainers acknowledged the issue, localization rarely ranked high enough to justify engineering time or tooling investment. Shipping features and keeping documentation current usually mattered more.
As developer tools grow globally, unofficial translations tend to appear naturally. At some point teams may want a way to keep multilingual documentation synchronized without slowing down development.
For now, though, many fast-moving DevTools seem comfortable with a simpler strategy: English-only documentation plus community translations.
Curious if others working on DevTools or documentation infrastructure have observed the same pattern.