-
The L10n Documentation Overhaul
What could be worse than outdated and disorganized documentation for an open source project looking to grow its volunteers and support its contributors? I’m not sure, but the l10n-drivers had to wake up each day asking ourselves that question about the state of our localization documents.
Something had to change, but to rectify that problem was a daunting task. Not only were documents outdated or obsolete, but also they were scattered through the Mozilla Wiki (wikimo) and the Mozilla Developer Center (MDC) like wet leaves across a yard, over into flowerbeds and onto the driveway.
Staś (and the l10n team, but primarily Staś) took up the goal of overhauling Mozilla’s l10n documentation. One result of a lot of work and many meetings was a Delicious page that we created and titled “Mozdocs“. If you’ve clicked through on that link, you’ll see our attempt to bookmark and tag *every document written* about Mozilla localization. This became our base for updating all of our documentation.
The Mozdocs Site
Staś determined that the best way to work was to create an inventory of what we had, categorize that, and then begin work. And so, we began by finding pages in our documentation and adding them to the Mozdocs page. We then tagged each page we found with something that described it.
Tagging pages became critical in our ability to work on these docs. Staś created a set of meta tags that tell us some information about the state of the page. Namely, does it need to be updated, is it obsolete, does it need to be fixed, should it be deleted, and more. We also have “location” tags that tell us where we found the document (i.e. my blog, Axel’s blog, Mozilla Wiki, etc.). Lastly, we have general purpose tags that describe the document.
If you’re interested, Mozdocs could be a very helpful page for you to get a sense of what is in the Mozilla L10n inventory of docs.
New documents, New Naming Guidelines
As foreman of the cleanup crew, Staś also determined that we needed to separate our documents properly. MDC would serve as the place for docs that describe how to develop and localize and can be abstrated from the Mozilla process. The Mozilla Wiki would serve as the spot for anything specific to the Mozilla Project’s localization process.
Get that? MDC = how to/abstract from Mozilla; Wikimo = Mozilla process.
As we created and edited documents, we made sure that they were placed on the proper platform. Furthermore, we started to rename documents using new “Naming Guidelines“. If you plan to create a new localization document on the Mozilla Wiki or MDC, we are asking that you use the following (Below is one massive hyperlink to the Naming Guidelines from the previous sentence):
- Always use the L10n: namespace (wikimo only)
- For hierarchies, use /, not :. This will create breadcrumbs automatically.
- Prefer hierarchies than longer names if you need to disambiguate.
- If not ambiguous, simplify.
- Don’t repeat yourself:
- Add localization-related tags (on MDC) or categories (on wikimo)
Our hope is that all new pages that deal with Localization will follow these naming guidelines.
And now, your turn…
As I mentioned, if you’re interested in scanning the inventory of documents, take a look at Mozdocs and the tags we have created. This could be a very helpful page for you to get a sense of what is in the Mozilla L10n inventory of docs.
Also, if you are finding new documents, can you please tell us and we’ll tag them on the Delicious site? Staś is the module owner of this site and we are accepting any “patches” to it. So, if you want to add something, just let us know and we will make the change.
-
How To Make a Website “Localizable”
Ever wonder what it takes to make a website localizable?
Last quarter, the l10n-drivers set out to document the steps necessary to make a web site or web application localizable (i.e. designing a project so it can be translated and localized). All too often, we found ourselves providing feedback on projects that had begun with the intention to reach a global audience, but had not been designed to scale at the intended level.
To illustrate our point, we decided to choose a real life example that we could go through with a team of project managers to document the steps necessary to make a project localizable. What we needed was a pilot project that had launched quickly to test a concept and see if the idea had enough global appeal that it would require localization. We chose Get Personas as the test case because it fit our criteria perfectly. With this project, Mozilla Labs had a site that had launched to prove its concept. Mozilla Labs often moves quickly and may not have the time or resources to map out just what of its many projects might take off since some of them may not. In this case, Personas quickly appeared to have global appeal and a need for l10n, but it contained project design flaws that did not have localization in mind from the beginning.
After working for the entire quarter with Mozilla’s Ryan Doherty, who was charged with making the site localizable, Staś Małolepszy, with Pascal Chevrel’s guidance and some from me, compiled all that we learned into several documents now hosted on the Mozilla wiki and on the Mozilla Development Center. Our intended audience for these documents is marketing and web dev folks.
If you’ve ever wondered what it takes to make a website localizable so it can scale to a global audience, please take a look at this wiki page and its links to other important documentation.
We’ll walk through the piece of this wiki page in more detail in a few forthcoming posts.
-
L10n Track for the Moz EU Camp
For those of you who will be joining me at the MozEUCamp in Prague next weekend, I’ve updated the l10n track on the schedule and written longer descriptions of the presentations that will be given by the l10n-drivers and some critical volunteers (jhiatt and adriank).
Got a presentation or topic you want to discuss? Email me or comment or this blog and we’ll see how to get it in a slot. I intentionally left some open blocks so localizers can attend other non-l10n talks of interest. See you in Prague next week.
-
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.
-
More on Firefox in the Philippines
While we were in the Philippines, Gen and I learned quite a bit about the local Internet landscape there. I thought I would share some more information that I picked up from the trip.
- Population is 92 million, online population is between 20-24 million
- English is one of the official languages of the Philippines. Tagalog is spoken by roughly 22 million people in and around Manila. Cebuano is another language spoken by nearly 20 million Filipinos south of the Luzon region (where Manila is located).
- Depending on what factor we use as a multiplier for our blocklist/AUS ping data, we can estimate that between 3 and 6 million Filipinos are using Firefox. That is a rough guess, but it places Firefox market share at a low-end of 12.5% and a high-end of 30%
- Most people we spoke to browse the Web in English (Firefox US version), but some did suggest that a local version would have appeal.
- Even further debate arose on whether a Tagalog version would have traction, with an audience of bloggers at Wordcamp responding collectively that it might not.
That latter point does not rule out Mozilla shipping a local version of Firefox. But, like every other localization, if we were to ship something localized to the Philippines, it will be because a local community member(s) responds to my call to action and decides to help us complete the body of work.
Obviously, Mozilla Firefox is taking off in the the Philippines, so I wouldn’t be surprised to see if the nascent community stepped forward with an offer to localize Firefox.
Finally, take a look at some stats about Firefox in the Philippines. (All numbers are based on our blocklist data.)
Growth of blocklist pings over one year
The Philippines is #4 on the list
community website
