Updating Localization Notes
Tomer, from the Hebrew localization team, highlighted an interesting problem the other day when he emailed the l10n-drivers to point out an issue that has been bothering him and many other localizers. Sometimes, developers will change entities in our locales/en-US directory, but forget to change the localization note above it to reflect the new entity. As Tomer explains,
“This causes the comment to become irrelevant to the text it references. Additionally, if someone then fixes the localization note, localizers won’t be notified on this change, and the comment does not get changed in our translations…As some of us are actually reading such comments before translating, it is important to get it 100% accurate.”
Here is an example that Tomer provides.
<!– LOCALIZATION NOTE (bookmarksSidebarGtkCmd.commandkey): This command
- key should not contain the letters A-F, since these are reserved
- shortcut keys on Linux. –>
<!ENTITY bookmarksGtkCmd.commandkey “o”>
You can see that example in our code on MXR here: http://mxr.mozilla.org/mozilla1.9.2/source/browser/locales/en-US/chrome/browser/browser.dtd#110
For those readers who may not be seeing what is happening here, notice that the <!– LOCALIZATION NOTE –> is referencing “bookmarksSidebarGtkCmd.commandkey“, but the !ENTITY variable name is actually “bookmarksGtkCmd.commandkey“.
That mismatch in the entity names has made that localization note untrackable by any locaization tools. Unfortunately, localization tools will not understand which comment belongs to bookmarksGtkCmd.commandkey. Furthermore, localizers who use these notes for translations will have to make the educated guess where the comment is pointing. If the note gets updated in the future, it’s likely that localizers will miss it.
Tomer suggested writing a script to look for these mismatches. In the very least, I am hoping this post will spread the awareness to developers to remember to do this. A quick request from l10n community: please maintain localization notes if entities get changed.
It would be unimaginably wonderful if someone would actually document what does and doesn’t work with l10n notes: the tree is chock-full of examples (by which I don’t mean “examples which all do the same thing the same way” but “dozens of different incompatible ways”) of notes for entire files, and notes for multiple keys, and various sorts of wrapping and whitespace and punctuation for single-key notes, going back to the dawn of l10n time, with absolutely no guidance that I’ve ever seen on what actually does and doesn’t work.
Hey Phil, Good idea. Ah…bless the quarterly goal system. Perhaps I’ll set that as one in the coming quarters: Documenting a policy on how to write localization notes. Appreciate the feedback.
Worse still, that comment is out of date, because it’s now Ctrl+Shift+U that’s reserved.
Well, isn’t already documented how to write localization notes?
The other thing is what developers are actually doing…
In Narro I assume that a localization note regardless of the way it is formatted and what it contains refers to the next entity. Which is how programmers usually work when commenting code.
That does pose a problem for notes like
# Localization Note (foo, bar, tender): This is just a test
foo: one string
bar: another
tender: wow, yet another string.
Right?
moz2po will also match a note to the entity or key that follows it. In my experience the notes are mostly badly formatted or out of date to do proper matching.
So yip we’ll choke on the example @Axel gave. But a translator looking at ‘tender’ is most likely going to miss that note and any notes that apply to the whole file.