Writing with a global mindset – part 2

Sunny greetings, dear reader!

In part one I talked about the importance of casing, spelling, punctuation, and terminology. Part two adds a bit more complexity to it. Hold on to your socks and read on.

This mini-blog series is for all the writers out there, especially if you are not a professional writer and you wear many hats in your current position, such as being a designer, writer, and engineer all in one person, which often happens if the company is very small or a startup. If you are a seasoned writer, don’t stop reading. You might get a refresher.

As mentioned, parts one and two cover the basics. In part three, I am talking about what some of those fundamentals mean for the translation and localization process and why they are important to keep in mind while writing.

Alright, let’s move on to the next set of basics: references, URLs, placeholders, accessibility content, and cultural references.

References
If you write documentation like a user manual, you will most certainly include references to other sections within or outside the manual, sometimes also called cross-references. There is a right way and a wrong way in doing it. Let me explain and let’s see a DITA example.

Example of a poor reference

This is what the writer sees:
Navigate to the section Users to <xref href=”AddUsers.dita”></xref>.

This is what the reader sees:
Navigate to the section Users to Add Users.

Why is this a poor cross-reference?
The writer used the header of the section “Add Users” as a cross-reference. Using the header of another section is not bad per se; it’s the way it’s done that matters. In the above example, the section header “Add Users” is used with title casing, which makes it look very odd in the English source because it’s used as part of the sentence structure. However, this goes beyond just aesthetics.

In English, using the section header “Add Users” works, and there’s nothing wrong with the syntax. But what happens when the translated header section is inserted into the sentence structure of the translation?

The translator does not necessarily know how the section header for the cross-reference was translated, so this is a bad start. The translator might not have any access or means to check that header. It can also be very unclear what will be inserted. Is it a section, chapter, or page header? Even if the translator can check, when the translated header “Add Users” is inserted, the syntax is most likely not working as smoothly as the English and might read something like this in their native language:

Navigate to the section Users to Users add.

The syntax of other languages can be very different to the English, so it’s best to keep automatically inserted cross-references out of the sentence structure. It’s also crucial to mention what kind of segment will be inserted, such as a list header. It might be a bit more cumbersome and not as elegant as you want it to be but you could write something like this:

Navigate to the section Users to add new users. See topic <xref href=”AddUsers.dita”></xref>.

You might argue that the translators can do whatever they want and could just add “See topic” during their translation. Well, here is the thing. How does the translator know that the insertion is indeed a topic?

Furthermore, we don’t know if the translator can simply change the existing header translation. Even if the translator has access to the header translation, the existing style of the translated header might adhere to the style guide rules, and changing it causes an inconsistency with all other headers.

Your writing style should be consistent throughout your documentation because a common tool used by many companies is a translation memory (TM)¹. With content that is repeatedly used, such as in manuals and support articles, existing translations can be easily reused using the TM. This makes translation and localization faster and cheaper.

In addition, to be more efficient and to handle high volumes of content, companies leverage machine translation (MT), as well as language models (LM) for translating content. I’m sure MT and LM will have the same issues as the translator to get the above example Navigate to the section Users to Add Users. right. But more on this in part three.

URLs
URLs are also an important part when it comes to writing content with a global mindset. There are different kinds of URL behaviors:

• Original URLs that, when clicked, always guide you to the original content
• Original URLs that, when clicked, direct you to the language that is set in your browser or location settings (magic happening in the background!)
• Original URLs with locale parameters like DE or ES, which, when clicked, guide you to the language according to the locale parameter in the URL

Examples:

• Original URL: https://gilt-ninjas.com
• Original URL with locale parameter: https://gilt-ninjas.com/nl-nl²

If you use an URL in your content, make sure you use it in accordance with your company’s URL guidelines. If you need to include locale parameters, please do so, and they will be changed by the translators. Make sure that the URL is editable so the translators can change it. If URL forwarding is automated and locale parameters are not required, please don’t add any.

Having the translator alter the URL is error-prone and can lead to URLs guiding the users to error or blank pages. Best practice is to have the magic happen in the background! If this is not already implemented for your company’s URLs, ask your trusted engineering team to help you with that.

When referencing third-party content, it’s best if this content is available in the languages your company supports. If it’s only available in your language, make sure you set the expectations of the reader and the translator by adding a note to your content, such as “only available in English”.

Placeholders
Placeholder text serves as alternative text. Placeholders have the same issues as the cross-references. If the placeholder value, for example, is a noun and part of the sentence structure, it is a challenge for the translators. Placeholders are mostly used in UI copywriting but can also be found in email content.

Some examples:

• Email content: Dear [FIRSTNAME] [LASTNAME]³, …
• UI copy: {{NumberOfUsers}} copied users

The reader will then see something like:

• Email content: Dear Ralph Möbius, …
• UI copy: 5 copied users

The above examples are broken down to the simplest denominator, but it is indeed much more complicated. I can already see a future post on placeholder best practices coming up, oh, and another one on number placeholders.

Accessibility content
Who cares about the casing for accessibility content? It is read to the user, and no one will see it anyway. For starters, the translators will see it, and wrong casing can cause all kinds of issues.

As a detail oriented person, I always cringe if I see accessibility content that is written sloppy and without care. Besides my cringing, it is indeed very important to use the correct casing for accessibility content. I wrote about casing in Part one, check it out.

Cultural references
We all like a good joke or cultural reference, but consider this: they are very hard to handle when it comes to translation. The translator will need to find something similar in their language. If it’s a reference from another era, it might not even be understood by the audience of the original content. Knowing your audience is always very important! However, I digress … stick to your company’s content writing guidelines, and if you are writing for others, I’m sure they have guidelines for you as well. Otherwise, you end up with translations like “The dog in the pan goes crazy” or “Holla the forest fairy” (now I am chuckling!).

In part three and my last part of this series, I will talk a bit more about the consequences of some of those aspects in combination with machine translations and AI.

1. What is a Translation Memory? ↩︎
2. GILT Ninjas is currently only in English available … who am I kidding? It will only be available in English! ↩︎
3. Using placeholders for names is a beast in itself when it comes to localization. We will cover this topic in a future post. ↩︎