Coding for the world, part 3: It is all about those clues
Sherlock Holmes needed clues to solve his mysteries. Observing, interviewing, and examination are the detective’s tools to find out what happened and who has done it. As translators, we are like detectives: we need clues to be able to understand the source that we are going to translate. Those clues are provided by developers, designers, and writers.
Writers can use the most descriptive way of writing. For instance, the word “name”; if the writer adds “first,” it becomes very clear that this is all about the “first name” and not about an API name, a company name, or a last name.
Designers give the visual context. Checkboxes, buttons, layout: it makes a big difference whether “Add user” is a title or a button label, as the translations can be different depending on whether the element is title text, a button label, accessibility content, or a checkbox label.
Developers have the most control over adding clues within the code, besides providing screenshots.
Using descriptive variable names
This not only helps translators to see what the variable is going to be once in action, but also makes the code easier to read and helps your future self to figure out in seconds what you have written months before.
Example: In this case, the variable can be many things, such as storage, folder, or cloud provider:
"Some templates could not be removed from {{1}}.": "Some templates could not be removed from {{1}}.",
Here the same string with the clue: it is a document!
"Some templates could not be removed from {{DocumentName}}.": "Some templates could not be removed from {{DocumentName}}.",
Here, with even more clues: the string key which only mirrored the UI string text before is now a descriptive key.
"SomeTemplatesCouldNotBeRemovedFromADocumentErrorMsg": "Some templates could not be removed from {{DocumentName}}.",
In this case there is a description, but it is very mysterious: is it a person, an object, or something totally different?
"More options for {{name}}": "More options for {{name}}",
With a tiny addition it is clear what it refers to: it is a feature and seen in the UI as a title.
"MoreOptionsForFeatureNameTitle": "More options for {{FeatureName}}",
Using variables only if necessary
With variables you might be able to write clever and very streamlined code, but for a global company, sometimes more code is better than keeping it minimal. Variables should be used for custom entries such as a filename, an error message, or an amount.
Examples:
"NumberOfPages": "{{count}} pages",
"StatusOfUploadingFiles": "{{progress}}% uploaded",
"ViewDocumentModalTitle": "View {{documentName}}",
"ErrorUploadingFileErrorMessage": "Error uploading {{file}}: {{message}}",
Keeping variables simple
Keep variables as simple as possible. Grammatical and syntax rules of other languages can be complex and surprisingly different.
Don’t integrate the unit within the variable. Some languages need to add a space between the number and the unit or need to move the unit before the number:
Poor
"SizeLimitIsLimitSizeUnit": "The size limit is {{SizeLimit}}.",
Good
"SizeLimitIsLimitSizeGB": "The size limit is {{sizeLimit}}GB.",
Using variables for both the amount and the unit is difficult for some languages, as the translator may need to localize the unit as well:
Poor
"SizeLimitIsLimitSitzeUnit": "The size limit is {{sizeLimit}}{{unit}}.",
Good
"SizeLimitIsLimitSizeKB": "The size limit is {{sizeLimit}}KB.",
"SizeLimitIsLimitStzeMB": "The size limit is {{sizeLimit}}MB.",
"SizeLimitIsLimitSizeGB": "The size limit is {{sizeLimit}}GB.",
"SizeLimitIsLimitSizeTB": "The size limit is {{sizeLimit}}TB.",
Use several strings for multiple units
Keep the flexibility for translators to move segments within the string.
Poor
"TimeRestrictionForAccess": "User may access file for {{TimePeriod}}.",
Good
"TimeRestrictionForAccessHours": "User may access file for {{sizeLimit}} hours.",
"TimeRestrictionForAccessDays": "User may access file for {{sizeLimit}} days.",
"TimeRestrictionForAccessWeeks": "User may access file for {{sizeLimit}} weeks.",
Use separate strings for singular and plural
It might look good in English, but other languages can turn out cumbersome to read, as not every language can just distinguish singular and plural by using ‘s’ in parentheses (think of “one knife” and “multiple knives”)
Poor
"TimeLeftUntilAccountLogOut": "{{count}} second(s) left ...",
Fair
"TimeLeftUntilAccountLogOutSingular": "{{count}} second left ...",
"TimeLeftUntilAccountLogOutPlural": "{{count}} seconds left ...",
In the above example, you might have noticed “Fair” instead of “Good”. Having singular and only one plural is just the beginning and not entirely correct. There is more to it. Some languages have multiple plurals. A good point to start for you is the Common Locale Data Repository (CLDR). The CLDR defines up to six different plural forms!
Good
"TimeLeftUntilAccountLogOutZERO": "{{count}} seconds left ...",
"TimeLeftUntilAccountLogOutONE": "{{count}} second left ...",
"TimeLeftUntilAccountLogOutPluralTWO": "{{count}} seconds left ...",
"TimeLeftUntilAccountLogOutPluralFEW": "{{count}} seconds left ...",
"TimeLeftUntilAccountLogOutPluralMANY": "{{count}} seconds left ...",
"TimeLeftUntilAccountLogOutPluralOTHER": "{{count}} seconds left ...",
Adding a descriptive key to the string
Descriptive keys are clues galore for translators. If done right, the descriptive key is seen during translation and gives vital information about the context of the string.
There are basically four different types of keys:
The nonexistent one:
"Upload",
The mirrored one:
"Upload": "Upload",
The half-baked descriptive one:
"ForUploading": "Upload",
The descriptive one:
"ToUploadFilesCTAButton": "Upload",
The descriptive one says it all: even without a visual context such as a screenshot, the translator knows right away that “Upload” is seen on a button and it is a verb.
Imagine the string “OK”. You now either think it is “Okay”, as on an OK button, or you thought right away of the US state Oklahoma.
Now you know what happened if you see a button in a software application labeled “Oklahoma” instead of “OK”: the translator had no clue what the context was about and just translated the first thing that came to mind when seeing “OK”.
Descriptive keys also allow you to have, for the same word, several strings for different contexts —which is super important, because the translation style of a button can differ from the translation style of a title. In addition, you can have the same word, but with a different meaning.
"ToUploadFilesCTAButton": "Upload",
"ToUploadFilesModalTitle": "Upload",
"OKButton": "OK",
"OklahomaUSState": "OK",
Phew! I know it started all light with a reference to an all-time greatest detective and ended with do’s and don’ts for developers. If you are working for a company whose software is used worldwide, try to be the best clue giver that can be. Listen, even if you work for a tiny startup, you never know what the future brings. Writing localizable-friendly code from the get-go makes the transformation from a local to a global player a smooth sea crossing without the choppy waves.
See you in the next part, when we talk about “Everyone talks about recycling; we are not, or are we?”. Until then, sunny greetings from the linguist that you can trust!
- Coding for the world
- Part 1: Why should I care about localization?
- Part 2: Keeping it together—or is separation a thing?
- Part 3: It is all about those clues
- Part 4: Everyone talks about recycling; we are not, or are we?
- Part 5: What’s in a name?
- Part 6: Time, money and arrangements
- Part 7: A form is a form. Wait. What?
- Part 8: Politics and your involvement
- Part 9: Casing, space, and commotion behind the scenes
- Part 10: The one with the genders and pluralization
Note: Thanks to Carlos Barbero-Cortés of DocuSign for consultation and feedback.
