A recurring request that I get very often is: “Would it be possible to support localized docs?”. In most cases, adding more than one language is technically feasible. Still, I have learned to pause before answering “yes” because the effort required to manage translations is often underestimated.

In this article, I'd like to share with you 5 Common Developer Documentation Localization Mistakes I have faced and how to avoid them:

  • Supporting languages without a goal
  • Aiming too high, too quickly
  • Poor versioning management
  • Forgetting about SEO
  • Lack of consistency

1. Supporting languages without a goal

Translating documentation is expensive, money, and time-wise. Docs continuously evolve along with the product; hence translations should too.

Receiving a bunch of visits on Google Analytics from Italy should not be the trigger to move all your docs into Italian. Having the docs available in five different languages, just in case, neither. So, when could it be interesting to support a new language then? A good reason might be to have the intention to enter a given market during the next year.

Instead, do this: Start small. Produce high-quality docs for just one language. Have a clear objective to offer docs in another language. Make sure to have a team that will take care of the translations, release after release.

2. Aiming too high, too quickly

You have clear goals to support localization. Nevertheless, supporting a new language does not necessarily mean translating all the docs at once. Prioritize. For example, getting the installation guides localized might be a good start. On the contrary, the pages that have risks to change shortly or are not relevant enough could remain untranslated.

Instead, do this: Less is more! Apply the Pareto principle and focus on translating the 20% that will provide the 80% value to your users.

3. Poor versioning management

When starting a localization project, the first idea that popped into my head was to replicate the infrastructure used to serve the docs per language. In practice, this solution leads to run entirely different projects. There are high chances for the docs in the original language to evolve faster than the translated content.

Once again, outdated documentation could be even worst than no documentation. It's very frustrating from the user perspective to start a guide and not be able to finish it because this targets a previous version that's not supported anymore.

Instead, do this: Be clear about your policy to manage translations. These are my preferences, in order:

Content Availability policy: Keep translated the parts that have not changed, but include the modifications in the base language. Gradually apply the necessary changes to renew the untranslated content.

🌐 Language Consistency policy: Multiple latest versions, depending on the language. If you decide to go with this policy, consider tagging clearly the outdated docs and redirect users to the original latest version. Then, release new versions per language as soon as the translations are ready.

🦄 Utopic policy: Wait to release new documentation versions until all translations are complete. I have baptized this policy as utopic because rarely docs and translations are ready at the same time. If localization becomes a blocker to publish new docs, opt to define a minimum completion threshold to release earlier.

Then, add internalization support to your docs via a plugin or a custom solution. Choose a principal language, and work with translations using portable objects:

  1. Portable Object Template: POT files contain the original text extracted from the documentation ready to be translated to other languages.
  2. Portable Object: PO files are derived from the templates and include the documentation completely or partially translated. When the original content changes, only the relevant lines must be provided again.
  3. Machine Object: MO is derived from the portable object but in a different format that's readable by machines.

Automate continuous delivery to refresh the portable objects every time there is new documentation. Adding automation to the localization process can help make the translations complete in less time — and enjoyable to maintain.

Finally, consider setting up a Translation Management System like Transifex or Lokalise to quickly detect what changed in a friendly UI and collaboratively translate the docs with your team with a proper revision process.

4. Forgetting about SEO

This mistake only occurs when serving docs publicly. Adding a second language can affect your site's SEO negatively due to duplicated content.

Importantly, one of the objectives to support multiple languages might be to acquire more users from certain countries. You could use the power of SEO to get more visitors into your developer portal if the translated content is discoverable by search engines.

Instead, do this: Use a separate URL for every language, like in documentation.yourdomain.com/es to keep translations organized. Make sure your website has a complete sitemap. If some page is not localized, opt to add the tag <meta name="robots" content="noindex"> to tell Google Robots that this page should not be indexed.

5. Lack of consistency

Imagine that you are getting the documentation translated by two different contributors into Spanish. Helena decides to turn “Software Development Kit” into “Kit de desarrollo”, but Juan chooses to use the term “Herramientas de desarrollo”. While both options are valid translations, it is preferable to achieve consistency between the different documents.

Instead, do this: Prepare a shared glossary, mapping the recurrent and domain-specific terms with the preferred translation. The list itself will not guarantee consistency - it should be used in the revision process. But even so, it could be a useful reference for translators in case of doubt.

All together

Installing an i18n plugin is not enough. While supporting multiple languages can help you reach new audiences, a localization project requires proper planning and constant commitment to become a success. At the end of the day, what matters is that your users find the content useful and can understand it. And, localization should not cause the opposite effect.