How-to guide on preparing instructional documents for translation

An important part of a software localisation project is the localisation of any user guides and help functions that support the application and allow users to successfully navigate the software with ease.

The localisation of such content should always come after the software has been fully localised, assembled and compiled to ensure that what the guide refers to is, in fact, accurate and appropriate for the end-user.

In the world of agile delivery, we have seen a shift in the way that software, and supporting documentation, is distributed and updated. Gone are the days of waterfall processes, instead agile sprints are now the norm and translation and localisation has had to adjust to this change just as much as the developers who build the programs.

Examples of different help functions:

  • User guides

  • Installation manuals

  • Operating instructions

  • Maintenance instructions

  • Troubleshooting guides

  • Software descriptions

  • Functional specifications

  • Technical descriptions

Today, user guides and help systems are typically hosted online through website FAQs or knowledge bases, rather than the more traditional printed documentation that would have supported standalone software, say 10-15 years ago.

It is now common for these online systems to be responsive in their design to allow users to access the content on any device. This can bring several challenges for localisation if not addressed during the internationalisation stage, which is why we always recommend a pseudotranslation step for all our localisation projects.


Help files are typically created from a series of assets which are then compiled into an online help document, and most include images, graphics, videos, audio, diagrams and, of course, screenshots from the relevant application. Although the addition of these elements can make the translation process more complex, switching to online systems ultimately results in significant savings for software publishers as they no longer pay for printing and distribution.

Help systems typically include an overview of the application, dialogue box descriptions, error messages, reference materials, glossaries and indexes. It is vital to prioritise consistency and accuracy, ensuring that references to the software user interface are carried over to all supporting documentation.

Key features:

  • Contents / Index

  • Glossary

  • Search function

  • Images, diagrams, screenshots, etc.

  • Responsive design for web-based platforms

The first stage is to ensure that you provide your translation vendor with a glossary prior to localisation, along with appropriate style guidelines and all the original source files.

If you do not have a glossary, a term extraction can be easily conducted by taking frequently occurring terms or phrases from the source text. These should then be approved by your team, along with suitable definitions, uses and examples. This glossary can then be incorporated into the final documentation as a quick point of reference for your users.

Another area that should be addressed prior to localisation is style guidelines. These guidelines must address both cultural and linguistic differences, such as country-specific statements, which may need to be adapted for the target audience. For example, telephone numbers, local support contact information, metric versus imperial measurements, national holidays, and any other references to the location and culture of the source.

Alongside this cultural information, there are several linguistic and formatting instructions that should be included in the style guideline to ensure that the team of translators assigned to the project, all work in the same way. The use of acronyms, how bulleted and numbered lists should be structured, spelling and punctuation guidelines, capitalisation, and how numbers and measurements should be written, are all key pieces of information to include in a style guide.

During localisation

Like any translation project, as much reference material as possible should be provided to the linguists before they start working on the help content. By granting them access to the localised application they will be able to provide accurate and succinct instructions needed for the users. They can also ensure the correct use of terminology, relevant image alt text and/or annotations, etc.

As previously mentioned, it is uncommon for user guides to be produced prior to software localisation. If, however, if this is the case, then your language service provider will have to take into consideration a few elements. For example, any references to the software found in the supporting documentation should be flagged and revisited after the software has been localised.


Since translators are often required to translate out of context, which can be a particular challenge for software localisation, linguistic, cosmetic and functional testing should always be carried out post-translation as there are several components which can only be verified once the help files are complied.

This should always be done by a native speaker who is able to identify where linguistic changes need to be made and/or where cosmetic or functional issues may have arisen. For example, buttons not accommodating the localised text, broken links, etc.

Linguists who regularly work on software localisation projects will be used to following test scripts. You can either provide these or created in partnership with your language service provider. At the very least, a visual QA should be carried out prior to publication.

To summarise, the localisation of any help system is not too dissimilar to that of the original translation of the software. Remember, consistency is key! You should always partner with a professional language service provider who has experience working for similar organisations and has the tools and resources to do this successfully.

Click here for more insights into common challenges of software localization projects, or to find out more about search optimising your online help content, you should read our guide on optimising knowledge bases as a similar process can be applied here.