How to provide comments for strings

Learn three important rules why adding the context through comments is important.

Providing context is important

To ensure high-quality translations, it’s key to provide as much additional information to your translators as possible. The context is essential for strings that may have more different meanings and for strings that you want to translate in a specific way.

At Localazy, we are working hard to introduce more tools for ensuring high-quality translations. Sometimes, it’s up to you too… and commenting strings is one of the situations we can’t help you much other than giving you the simplest possible way to do so.

How to do it with Localazy

The base/source language is one-way synchronized from your code with our Gradle plugin. When parsing your strings resources, we link the last XML comment before the actual string element together. It applies for strings, array lists, and plurals.

<resources>

    <!-- The comment for `string_share` -->
    <string name="string_share">Share</string>

</resources>

The golden rule #1

Keep a simple rule in mind… when adding new strings to your XML files, provide comments to improve your translations. You don’t need to do so for all strings but never miss comment for those that may have more meanings. The shorter the string is, the more important to comment on it as single words are usually hard to translate without the context.

Also, it’s critical to keep in mind that the string can have a different meaning in other languages. For example, translating words like share or book is especially complicated without the context in the Czech language (my native language).

The translator can understand the word book as:

  • make a reservation which is rezervovat
  • paper book for reading which is kniha

The golden rule #2

For the very same reason as described above, it’s essential not to reuse the same string for different meanings. To reduce the number of items in your language resources, you may be tempted to introduce a single element and use it across the whole app like this:

<resources>
    <string name="book">Book</string>
</resources>

Don’t do that! Use different strings with a descriptive name to prevent accidental reusing of bad string and provide context with a comment like this:

<resources>

    <!-- The item on our eshop; meaning 'publication' -->
    <string name="eshop_book">Book</string>

    <!-- Booking a flight; meaning 'making a reservation' -->
    <string name="book_flight">Book</string> 

</resources>

The golden rule #3

You should define your app-specific terms in the glossary. It’s another essential tool for providing the context.

However, it’s not always the best way how to let the translator know your requirements for high-quality translation. In many situations, comments are more likely to suit your needs.

Often, I see punctuation to be a big issue. Sometimes, the translator forgets to add a dot at the end of the sentence or replace exclamation mark with dot, etc. If you want to be sure that the translator considers the punctuation with the desired importance, let her know:

<resources>

    <!-- Please keep '...' at the end of the text. -->
    <string name="save_as">Save as ...</string>

</resources>

Speaking about punctuation, keep in mind that there are differences between languages that you have to respect and not consider as a bad translation.

Let’s take French as an example. The sentence “apples or oranges?” would be correctly translated as “les pommes ou les oranges ?”. Do you see the space before the question mark in the French version? That’s correct. Generally, colons, semicolons, exclamation points, and question marks are all preceded by a space in French.

The rule is: Provide your translators with the context and all relevant information, but whenever you think the translation is incorrect, learn the language differences.

Learn more about the best practices

You can learn more about how to translate your app from our blog where we share tips, insights and important information.

Also, don’t miss what you should know before uploading your android strings guide to get high-quality translations for your app.