We received last week the following request: “Would it be possible to support localized docs?”. Of course, serving the docs in more than one language is technically feasible. Still, we learned to pause before answering “yes” because the effort required to manage translations is often underestimated.

In this article, we'd like to share 5 common developer documentation localization mistakes we have faced and how you can avoid them.

1. Support languages without a goal

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

Receiving many visits on Google Analytics from Italy should not be the trigger to move all your docs into Italian. Nor translating the docs to make the content available in five different languages just in case. So, when could it be interesting to support a new language then? A good reason might be to enter a given market during the following 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. Aim 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! Focus on translating the 20% that will provide the 80% value to your users.

3. Poor version control

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 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 localized 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, tag the outdated docs (e.g. with a warning message), 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 refer to 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 negatively affect your site's SEO 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 organize translations. 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 robotos that this page should not be indexed.

5. Lack of consistency

Imagine two different contributors are in charge of the Spanish translation. 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 - tech writers and translators must use it in the revision process. Additionally, it becomes a practical 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 succeed. What matters at the end of the day is that your users find the content useful and understand it. And, localization should not cause the opposite effect.