Today we will talk about the implications and the preparation that proper placeholders and instructions require to ensure information is properly parsed and mistranslations are avoided.
This is a continuation of a previous post where we discussed how important it is to replace certain pieces of information in strings (like numbers, percentages, dates, etc.) with placeholders to ensure proper localization and reusability. In that way, we can make them independent of the language or region where our customers are located.
Usage of Placeholders
First, let’s discuss how descriptive placeholder names can help the localization team provide better translations for your product.
Consider one of the examples from the previous post:
"Obtain a {{currency_amount}} discount by clicking here"
The information in the placeholder “currency_amount” indicates that this will be a monetary amount (e.g., $5, €5, etc.). This may not seem significant, but for languages other than English, it is. The translation can change if, instead of a particular amount, a percentage discount is provided. Developers often overlook this and might provide something like:
"Obtain a {{1}} discount by clicking here"
Or worse, they might use the same sentence for both scenarios and alternate whatever they need in their case, currency or percentage.
So how can the language specialists know what the placeholder is referring to?
The best practice is always to use a different sentence for each scenario with a descriptive placeholder that explains the type of value it will contain and how it will be used.
In this case:
"Obtain a {{currency_amount}} discount by clicking here"
"Obtain a {{percentage_amount}} discount by clicking here"
This approach enables language specialists to provide the best possible translation.
Another point to remember is that placeholders need to follow a certain syntax and must be properly excluded from the translation process, in that way the linguists can add them to their translation, but they cannot edit them. This is important because if this is not done correctly by the localization engineers, bugs can occur during runtime, and the translation process might be affected.
Using the previous example, if the placeholder is not properly excluded, the translation might end up like:
"Obtén un descuento de {{cantidad_moneda}} haciendo clic aquí"
or:
"Obtén un descuento de {{ currency_amount }} haciendo clic aquí"
or:
"Obtén un descuento de {currency_amount} haciendo clic aquí"
All are very close to the correct version and tricky to catch during the review process, but all cause issues in the product’s UI.
Another area where we need to be very careful is when creating a sentence structure using placeholders. Using concatenations to add words to a string is quite complex in other languages and, for that reason, should be avoided. The only good reason to do it is when there are too many options to generate one string per case, and it has to be done programmatically.
For example, sentences like:
"{{person}} must agree to the {{legal_terms}} before accessing the system as a {{user_type}}."
don’t usually work unless the scope of the placeholders is clarified or the structure of the sentence is polished to work for international audiences.
Let’s take a look at the different placeholders:
{{person}}: If this placeholder is always a person’s name (like John), there won’t be any issue with this structure. However, since verb conjugations in English are simple, developers might be tempted to also use it for pronouns (like you, he, she), which will make this sentence not work in other languages where verb conjugation changes depending on the person (e.g., in Spanish: “yo tengo que aceptar”, “tú tienes que aceptar”, “él tiene que aceptar”, etc.).
{{legal_terms}} and {{user_type}}: Both have similar issues, so I will focus on explaining the issue with {{legal_terms}}, and you should be able to extrapolate it to {{user_type}}. Here, the usual suspects are “Privacy Notice” or “Terms of Use,” and the main challenge is that in certain languages, the article “the” will have a different gender depending on the noun it’s referring to. For example, in Spanish, we have: “Condiciones de uso” for Terms of Use and “Política de privacidad” for Privacy Notice. The first one is plural and feminine, and the second one is singular and feminine. For that reason, we need: “las Condiciones de uso” and “la Política de privacidad.” Imagine other languages where gender and declension are all different.
If the number of cases is small enough, the best practice is always to generate a different string per use case. However, there are situations where this is not possible, and I am not inferring that fragmentation and concatenation cannot be used at all. However, when constructing these types of sentences, it is always a good idea to get in contact with the localization team in your company so they can propose a rephrasing that might work better or a different solution that makes everyone happy.
Usage of Instructions
Another helpful practice that can enhance quality is using instructions at the segment level. In JSON files, this is quite easy to implement. For example:
"link_dialog_amount_discounted": {
"String": "Obtain a {{amount_discount}} discount",
"Instructions": "This is a link. The placeholder shows the amount that will be discounted from the total price. E.g., $5.00"
}
The best part of these instructions is that certain TMSs (like Smartling or Phrase) allow them to be displayed in the workbench, providing extra information to the translators. This is especially important for high-visibility content that can be mistranslated due to a lack of context. For example if we have a product called “Notary”, there might be situations where it is not clear if Notary refers to the person or the product.
"description_dialog_notary_enrollment": {
"String": "Notary ensures all your documents are authenticated and securely stored."
}
Adding instructions here can help ensure that the linguists know what terminology they need to follow.
"description_dialog_notary_enrollment": {
"String": "Notary ensures all your documents are authenticated and securely stored."
"Instructions": "Notary refers to our product. Please follow our glossary."
}
Another significant advantage of these best practices (the use of proper placeholders and instructions) is the use of AI to improve the quality of translations provided by Machine Translation engines. It can help assess if the delivered translation aligns with the key, placeholders, and instructions provided and flag possible issues or even amend them. However, this interesting and hot topic requires a specific post that I will present after finishing the series “How to Generate a First-Class Resource File”.
Thank you very much for taking the time to read this. I hope you found it informative. As you’ve seen today, placeholders and instructions play a crucial role in our resource files. In our next post, we will discuss best practices for including URLs in our resource files, as well as how to address people and their physical addresses.