Don't translate your documentation (yet)
Translation is expensive. Make sure you need it first.
“Can we support localized docs?”
Technically? Yes. Should you? Maybe not.
Teams underestimate what it takes to maintain translations. Documentation changes constantly. Translations need to keep up. Most teams can’t.
Mistake 1: Translating without a goal
Google Analytics shows traffic from Japan. Someone suggests translating to Japanse. Six months later, the Italian docs are outdated and nobody maintains them.
Traffic from a country doesn’t mean you need docs in that language. English might be fine for technical audiences.
Better reason to translate: You’re entering a specific market next quarter. You have native speakers on the team who will maintain it. You’ve validated that language blocks users from adopting your product.
Don’t translate “just in case.” Translate when you have a specific goal and resources to maintain it.
Mistake 2: Translating everything at once
You decide to support Italian. You translate all 200 pages.
Three months later, the English docs evolved. The Italian docs are behind. Users hit outdated instructions. Support tickets arrive in Italian. Nobody on support speaks Italian.
Translation isn’t a one-time project. It’s ongoing maintenance.
Start smaller: Translate the 20% that delivers 80% of the value. Installation guides. Quickstart. Core concepts. Leave advanced features and edge cases untranslated.
Users can handle some pages in English if the critical path is in their language.
Mistake 3: No version control strategy
You spin up separate documentation projects per language. English docs move fast. German docs lag behind. Users hit German tutorials that reference features from version 1.0. The current version is 3.0.
Outdated documentation is worse than no documentation.
You need a policy for managing translation lag. Three options:
Content availability: Keep translated sections that haven’t changed. Show new content in English until it’s translated. Gradually update the untranslated parts. Users see mostly German with some English sections clearly marked as “not yet translated.” Works for most technical documentation. Users can handle mixed languages if the critical path is translated.
Language consistency: Each language has its own version. German might be on v2.0 while English is on v3.0. Tag outdated docs with warnings. Link to the latest English version. Works when you want each language to feel complete, even if behind.
Perfect sync: Wait to release docs until all translations are ready. Medical devices, government contracts, financial services often legally require this. Documentation and product ship together, all languages synchronized. This works when you have no choice. Otherwise, documentation becomes a bottleneck.
Mistake 4: Ignoring SEO
You launch Portuguese docs. Google sees duplicate content (same structure, different language). Your search rankings drop.
Or worse: you don’t configure SEO properly. Users in Spain search for your product in Spanish. Google shows them your English docs. They never find the Spanish version.
Fix it:
Use separate URLs per language (`docs.yoursite.com/es/`)
add hreflang tags (tells Google which language each page is in)
Generate complete sitemaps including all languages
For untranslated pages, add <meta name=”robots” content=”noindex”> so they don’t compete with English versions.
Make translated docs discoverable. Otherwise, why translate at all?
Mistake 5: No consistency between translators
Two people translate your docs to Spanish. One translates “Software Development Kit” as “Kit de desarrollo.” The other uses “Herramientas de desarrollo.”
Both are valid. But inconsistency confuses users. They think these are two different things.
Create a glossary:
Map domain-specific terms to preferred translations:
Software Development Kit → Kit de desarrollo
API → API (don’t translate)
Webhook → Webhook (don’t translate)
Configuration → Configuración
Share it with translators. Make it part of the review process.
Technical terms often stay in English. That’s fine. Consistency matters more than translating everything.
When translation makes sense
You should translate when:
Regulation requires it (medical devices, government contracts, financial services in certain countries)
You’re entering a specific non-English market and English blocks a significant portion of users.
You have budget for ongoing translation (not just initial translation)
You have native speakers maintaining translations
You probably shouldn’t translate when:
Your users are developers (most read English technical docs)
You’re an early-stage product (docs change too fast)
You can’t commit to maintaining translations
You’re translating to “be international” without specific goals
Start with one language
Don’t launch with five languages. Pick one. The market you’re targeting. The language your team speaks natively.
Translate 20% of the docs. The critical path. See if it works. Measure if it helps.
If it does, expand. If not, you didn’t waste effort translating everything.
Technical setup
Use internationalization (i18n) tooling built for documentation.
The approach:
Choose a primary language (usually English)
Extract translatable strings into Portable Object Template (POT) files
Translators work with PO files (only the strings, not the full docs)
When original content changes, only changed strings need retranslation
Automate extraction. Every time docs update, regenerate the POT files. Translators see exactly what changed.
Tools like Transifex or Lokalise show what needs translation in a friendly UI. Team members can translate collaboratively. Built-in review process catches inconsistencies.
This is better than asking translators to edit markdown files directly.
The real cost
Translation isn’t just the initial cost. It’s ongoing maintenance.
Every docs update needs translation. Every new feature. Every bug fix that affects documentation. Every restructure.
If you ship docs in three languages, every change multiplies by three. If you can’t handle that, don’t translate yet.
Focus on quality in one language first. Then expand when you have the resources to maintain it.