Code Camp: Challenges of Translating Developer Content

When technical writers create developer content — migration guides, product documentation, or software development kits — they might not even be aware of how many pitfalls await when it is sent for translation. But with clear communication about the content’s purpose, context, and the users’ needs, quality translation is well within reach. Below, we’ve collected some of our best tips for managing the challenges of translating developer content.

LS: linguist selection

Since the language and context of software development is unfamiliar to many people, it requires significant effort to find linguists with the right experience to translate your developers’ technology. Ideally, the linguist has worked with similar content in the past or has an educational background in software-related fields. But even hobby experience can be an asset, as long as they have enough IT expertise. We make it a practice to find out if our linguists are former developers or are secretly coding their own website or building an app.

Translating developers’ /unique language

Software developers across the world are known to use a lot of English terms, even if they have local, target language equivalents available. They often opt to use that English terminology when local versions don’t seem natural to them, and don’t reflect the day-to-day lingo they use. For your content to resonate with the local developer community, you need linguists who know the climate and can localize the content appropriately. Otherwise, many developers will simply choose to read your content in English and not in their native language. While at face value this may not seem like an issue, what you are missing is creating that native experience which will foster engagement within the developer community (and most likely permeate to your end-users).

Read: natural

Often, when translating technical content, linguists focus on accuracy above all. However, linguists also need to understand the importance of readable content. When translating developer content, we strive for a balance between accuracy and readability. With this particular type of content, if the text doesn’t flow naturally in a local language, no one will read it and, as mentioned, this will damage the bond between you and your developer community.

Being aware of the context can help linguists create content that reads naturally. In the case of software development, this means that the linguist needs to know the process behind the product. Ideally, your linguists will also be users of the product, but if not, they’ll need other windows into the development process. Letting relevant parties know up front that linguists might need access to programs, screenshots, or someone to answer questions can help the process move along more smoothly.

Translating code blocks

Preparing developer content for translation often requires more effort and technological knowledge than standard translations. Localization engineers must figure out how to make the right content (text, images, links) available for translation while protecting code blocks and dealing with non-standard file formats and structures. To protect code blocks and other non-editable parts of the file, localization engineers analyze the content in search for patterns and create custom filters and parsers that ensure a repeatable and safe translation process.

If your teams have not fully adopted a consistent coding convention, the documentation they are generating will likely contain fewer and/or less-distinguishable patterns. Rigid languages (such as C++) where the syntax is very strict have clearer patterns, whereas flexible languages (such as PHP) can produce very heterogeneous files. Now, if the documentation itself has also been written using a non-strict language (such as Markdown) or stored in completely different formats, the fun just grows exponentially. When an author can use several syntax variations to achieve a same desired result (imagine having three different ways to make text bold, and four separate ways to create a bullet point list), detecting all such patterns makes it much harder to create and adjust parsers and filters. Think IKEA chairs – if you buy four chairs that have the same assembly instructions and pieces –  after you assemble the first one you can easily discern the pattern and use it to put together the next three (instructions are written in a rigid, consistent way). But if you buy four chairs with entirely different assembly instructions and elements (as happens with non-strict languages), it will be difficult to pick up any patterns, so their assembly will take you much more time to figure out.

This arrangement puts a lot of responsibility on the localization engineers, and while they are up to the challenge, it results in increased localization engineering costs. This is why it’s worth discussing a consistent style for writing code early on, so that both localization costs and complexity are reduced to a minimum.

touch: User Interface

Finally, when translating developer content, keep the final user interface in mind. Is the UI available in English only, or in all target languages? Do the UI terms need to be translated – and if yes, does the translation team have access to the localized UI? Context is important here, since linguists need to know how users will interact with the product, and they may not be able to get the full picture from the code. Similarly, if the UI will need to be provided in multiple languages, your translation team needs to access the tool or website to see the terms in context. Once they see how the site operates as a whole, they can create a reference document to store the necessary terms and make the translation process easier.

For more information on how Argos’ engineers can transform your next development project, visit our website or contact us.