When we talk about localizing content, we usually tend to assume that we just need the source content (normally English) to be translated into the target languages. While this assumption is fine for documentation content, it is not suitable for product UI content.
In this post, we will discuss how developers can help the localization team by following some best practices when generating their resource files and how these practices can improve the quality of the content delivered.
Just a side note: to keep it simple, I will focus on the JSON format. If you need some information about it, you can find some here.
I will divide this topic into four different posts, as this is an extensive topic that requires thorough discussion:
- Naming keys
- Usage of numbers, dates, and currencies
- Usage of placeholders plus instructions associated with a particular string
- Usage of URLs, user names, and addresses
Let’s start with the first topic, providing a good key for our strings!
Naming keys
One of the most important aspects of generating a resource file is how to choose a key for the string to be translated since it should be descriptive enough for the localization team to understand where in the UI it will be used, but it shouldn’t require too much time from developers/content writers. I have seen some companies take the approach of using the source string as the key value (to automate the process), which creates significant challenges for the localization team. For example:
"Access": "Access"
Besides being not descriptive, the main challenge here is that the English version may be the same in multiple scenarios, but the localized version might need to change (for example, if ‘access’ in the UI refers to a button and has to be translated as a verb, or if it refers to a noun). Keeping in mind that we cannot have repeated keys in the resource file, this would generate a poor localized experience.
The next thought you might have to automate the generation of the key is to add the component name where that string is used in the UI (or functionality), like button, subject, body, title or A11y. This would improve the quality of the file. However, there are some cases that need to be considered. For example:
"btn_close": "Close"
This seems like a good solution. However, even for that, there are some cases where some localized versions might encounter problems (for example, in Korean, “Close“ referring to “close a window” is different from “Close” referring to “close an account”). For this reason, a good recommendation is to generate a new string per use case (unless the usage is 100% the same). For example:
"btn_close_dialog": "Close"
"btn_close_account": "Close"
While this may be seen as more effort, a well-structured JSON file simplifies this process because the keys in CAT Tools are generated using all levels of the resource file. For example, a dialog to close a window might be structured as follows:
"dialog_close_window_not_saving": {
"button_close": "Close",
"button_no": "No",
"body_text1": "Are you sure you want to close this dialog without saving?",
"body_text2": "Click No to keep the dialog open",
"title_dialog": "Close Dialog"
}
The string “Close” will have the key: dialog_close_window_not_saving:button_close.
With this approach, there are multiple benefits. On top of ensuring that there is a string per use case, it allows the localization team to provide a higher quality translation. The majority of CAT Tools enable translators to see the key in their UI, which helps them provide the appropriate translation depending on the use case. In a future post, I will discuss how these keys can also help improve the translations provided by machine translation using large language models.
Thank you very much for the time spent reading this. I hope you learned something today. Soon enough, we’ll come back with the next topic: the usage of numbers, dates, and currencies in our resource files!
Leave a Reply