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.
Actually, localization notes are documented at https://developer.mozilla.org/En/Localization_notes.
The question of what works and what doesn’t work is a sad story, actually. For example, pootle doesn’t support file-wide localization notes, even though Dwayne totally thinks that they’re the right tool to offer localization primers, or are a great tool to say “feel free to leave XSLT error message in English if there’s no eco-system around that standard in your language.”
So it’s not so much a question of just what works, but what should work as well.
The story about sequences of entities with localization notes is a bit tougher, and not really documented. I think the comma-separated list works for now.
We’re keeping the question of comments on l10n files on the top of our heads when talking about l20n, fwiw, so if/when we switch, things should improve in this regard as well.
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.