L10n:Tutorial
L10n:Home Page | L10n:Localization Teams | L10n:Tutorial | L10n:Grouse localization tutorial
[edit] What is Localization?
Localization (abbreviated to L10n), is to translate an application's menus, dialogue boxes, labels and other settings (font, character encodings, dictionaries, default search engine etc) for a particular locale.
[edit] Where do I Start?
[edit] Choose locale name
You must choose the locale name for your package. The policy is well described on Mozilla's Wiki in document Simple Locale Names.
Summary: you should try to use the most general locale name as possible. If you translate to French, you should use fr locale name. If there are several different countries using some version of French, the locale name for such country should be fr-CA (while the main French locale stays fr). In some rare cases, you will want to add a dialect suffix.
You can also take a look at the current Mozilla Firefox locale teams. Since a lot of l10n strings are common to Gecko and Flock (since Flock uses the Gecko toolkit), you will want to cooperate with a Firefox team if one exists. Another useful list is Firefox 1.5 localizations. It lists what locale names were chosen for Firefox, and it's generally a good idea to follow that.
[edit] Prepare the environment
First thing you have to do is to create some directory in your hard drive, and inside create en-US and your_locale_name dirs.
Second, get the en-US l10n files. You can download the zip file containing all localizable entities that you will need to localize from the link provided in the wiki page associated with a certain version, or you can checkout the files directly from SVN:
svn co svn://svn-mirror.flock.com/master/flock/branches/<codename>/mozilla/flock/locales
where codename is the bird name of the Flock version whose l10n files you want to checkout, for example, grouse.
If you've chosen the .zip file way, unpack it to ./yourdir/en-US and to ./yourdir/your_locale_name. Example:
./your-dir
+-/en-US
+-/pl
If you preferred the SVN way, you'll need a SVN account to be able to read and write into the l10n repository. File a bug in product Flock, component Internationalization with title in form "Localization account for ab-CD; email@domain.tld", indicating the nickname you'd want to use and we'll create an account for you. Then, pull Flock l10n trunk:
svn co svn://svn.l10n.flock.com/l10n
[edit] Translation routines
Gecko platform based applications stores language entities in two forms. One is a .properties Java-like file. Another is XML based .dtd file. Properties files looks like:
cmd_bm_open = Open cmd_bm_open_accesskey = O cmd_bm_expandfolder = Expand cmd_bm_expandfolder_accesskey = x cmd_bm_managefolder = Manage Folder
Those properties are later used in all JavaScript code inside the browser.
Much more often, you will work with .dtd files. To get more info you can read Wikipedia entry about DTD. To work with it, you should know a bit about XML. I said a bit, don't scream yet :)
Example:
am-main.xul:
<caption label="&identityTitle.label;"/> <description>&identityDesc.label;</description>
some.dtd:
<!ENTITY identityTitle.label "Identity"> <!ENTITY identityDesc.label "Each account has an identity, which is the ↵ ↳ information that other people see when they read your messages.">
So, somewhere in am-main.xul inside the Flock UI, some developer wants to display some text. He adds something like this and adds new entity in some .dtd file. Your role is to translate the value of this entity into your language.
[edit] Applying changes
Ok. Now, after some theory, let's try some practice. Go to ./yourdir/ab-CD/chrome/flock/toolbar/toolbarOverlay.dtd. Open this file in your favorite text editor with Unicode support. Translate the values and save the file checking twice if you're saving it as UTF-8 (no BOM).
Once you're ready, zip the ./yourdir/ab-CD/ directory to ab-CD.zip and send it to Israel Saeta. We will put it's contents into the SVN and release localized testing builds for you to QA them.
[edit] Localizing profile
There are other things you can profile for your locale.
Note: In the future our localization policy will be reviewed, but at the moment you should just try to get the best quality for your users.
[edit] Searchplugins - http://lxr.flock.com/source/flock/mozilla/flock/locales/en-US/searchplugins/
- Flock en-US includes default searchplugins for Yahoo!, Ask, Ebay, Amazon.com, Google, Wink People, Technorati, Digg and Wikipedia. Go to ./flock/searchplugins/ directory. Localizers are encouraged to use the local version of these search services where applicable. Localizers are free to translate the names of the search engines unless specifically prohibited by the engine's terms of service. Localizers are also welcome to offer suggestions for "relevant" searchplugins for their specific locale. If you have any questions, please contact bryan [at] flock [dot] com.
- IMPORTANT
- Flock has default settings for "Searchplugin Services" and "Searchplugin Order". Please do not modify this for any version of Flock.
- You should keep Yahoo! as a default searchplugin unless you have some reason not to do so, for example, if Yahoo! doesn't support searching in your language. If your locale does not support Yahoo! then please contact Bryan Hudson (bryan [at] flock [dot] com) for further assistance.
'Searchpluging Services and Order
- yahoo!
- ask
- ebay
- amazon
- wink people
- technorati
- digg
- wikipedia
- Same history as favorites. Edit/add files into the folder:
- trunk/es-ES/flock/searchplugins
- IMPORTANT: To get them put into the flock.com/versions official builds, please file a bug in bugzilla (https://bugzilla.flock.com). Component - "Localization", with description: "[ab-CD] Flock 2 searchplugins proposal" and assign the bug to bruno@flock.com.
- Attach the xml file(s).
- Bryan/ Bruno, will review the file and check it into the flock main repo.
- If you need help with this please contact bryan [at] flock [dot] com
[edit] Favorites (L10n) - http://lxr.flock.com/source/flock/mozilla/flock/locales/en-US/profile/bookmarks.html
- Flock en-US includes default Favorites:
- Favorites Toolbar Folder:
- Share Flock
- Flock Turtorial
- Favorites Menu Folder:
- Flock
- MySpace
- Youtube
- Digg
- Flickr
- Yahoo! Mail
- Gmail
- AOL Mail
- Photobucket
- Picasa Web Albums
- Delicious
- Ma.gnolia
- Pownce
- Favorites Toolbar Folder:
Localizers are encouraged to use the local version of these Favorites where applicable (If no localized version exsists, then english will be the default). Localizers are also welcome to offer suggestions for "relevant" Favorites for their specific locale. If you have any questions, please contact bryan [at] flock [dot] com.
- IMPORTANT
- Flock has default settings for "Favorites" and "Favorites Order". Please do not modify this for any version of Flock.
- We have changed the way we handle "Favorites' with Flock 2. We deal with the same as FireFox 3. (html source file).
- Simply replace all the default favorites urls with your specific locale urls and then export as an html file. (e.g yahoo.pl)
- Replace, where applicable, the “default favorites” en-US urls with the appropriate locale url’s.
- Then Export your "Favorites" as html.
How to export your Flock "Favorites" html file:
- Go to “Favorites” menu
- Select “Organize Favorites”
- Select “Import and Backup
- Select “Export HTML…”
- IMPORTANT: To get them put into the flock.com/versions official builds, please file a bug in bugzilla (https://bugzilla.flock.com). Component “Localization” with description: “[ab-CD] Flock 2 favorites proposal” assign the bug to bruno [at] flock [dot] com.
- Attach the "bookmarks.html" file.
- Bryan/ Bruno, will review the file and check it into the flock main repo.
- If you need help with this please contact bryan [at] flock [dot] com
[edit] RSS Feeds (L10n) - http://lxr.flock.com/source/flock/mozilla/flock/locales/en-US/chrome/flock/feeds/opml/
- Flock en-US includes the following default RSS Feeds
- Flock Folder
- Flock Blog
- News
- The New York Times
- Entertainment
- Digg Entertainment
- Technology
- Techcrunch.
- Flock Folder
Localizers are encouraged to use the local version of these RSS Feed favorites where applicable (If no localized version exsists, then english will be the default). Localizers are also welcome to offer suggestions for "relevant" RSS Feeds for their specific locale. If you have any questions, please contact bryan [at] flock [dot] com.
- IMPORTANT
- Flock has default settings for "RSS Feeds" and "RSS Feeds Order". Please do not modify this for any version of Flock.
- You will be able to localize the Flock's default feeds directly in the community edition, (i.e. the tinderbox builds). To do so, simply edit the file:
trunk/flock/chrome/flock/feeds/opml/default.opml
- Please ask the flock-l10n list if you don't know how to do that.
- IMPORTANT:To get them put into the flock.com/versions official builds, please file a bug in bugzilla (https://bugzilla.flock.com). Component “Localization” with description: “[ab-CD] Flock 2 feeds proposal” assign the bug to bruno@flock.com.
- the "default.opml" file.
- Bryan/ Bruno, will review the file and check it into the flock main repo.
- If you need help with this please contact bryan [at] flock [dot] com
[edit] Best Practice
[edit] Translate with heart, not with a dictionary
If you have a choice to follow directly the words from en-US version, or to make it easier to understand for users, you should follow the latter, but watch out. In the future it could lead to some troubles.
For example in Polish we had a real problem to translate the word "tabs". We chose to use a word "panels", but later we found a big problem to translate "sidebar" which should use the word "panel" in Polish. Because we already used "panels" for tabs, we had a problem to switch. (we finally switched just before Firefox 1.5 to the word "cards" for tabs). You must think twice to avoid future collisions when you diverge from original words.
[edit] Look around
As you might notice Flock is not the first application in the world. If you're not from some very exotic country there probably are other applications in your language around. There are probably some internet users who have some common words. You must not ignore them. You must not try to reinvent the wheel. It's really a rare case when the common routines are bad and you need to force usage of new words. It's always a pain for users, and will make product adoption harder. You should try to avoid it wherever possible.
Beside of that, remember that most of potential users will migrate from Internet Explorer. If it's possible to use similar words as Microsoft does (not always - Microsoft quite often does huge mistakes) - use it.
[edit] Test, test, test
Give your localization to friends, use it for a while. Make sure it looks OK in UI, not only in .dtd files.
[edit] compare-locales.pl
Download compare-locales.pl Perl script and compare directory with your localized version with en-US ones and make sure they're OK. This script will tell you if you missed some entities.
[edit] Byte Order Mark
Some editors might add Byte Order Mark at the beginning of the files using UTF-8 encoding. This usually will not shown when you open the file up using an UTF-8 compatible editor. However, the files containing Byte Order Mark cannot be used by UTF-8 non-compatitble editor/parser/compiler either. Currently we advise to remove the Byte Order Mark in all dtd, properties and js files. You know there is it when compare_locales.pl reports differences between your locale files and the en-US files but you cannot find the differnece. To remove Byte Order Mark, the safest way is to use a Hex editor (you might find ghex easy to use under gnome). When you open the file up with Hext editor like ghex, you usually will see the file becomes like:
EF BB BF ......
The first 3 bytes "EF BB BF" is the UTF-8 Byte Order Mark. Remove them and save the file up.
However, if your editor requires BOM to recognize the file as UTF-8 encoded, it usually will not be able to show the file in correct encoding after removed BOM. The usual editors under Linx like vim, gedit won't have the problem.
If you are working on Windows only and found the BOM problem with your locale files, please feel free to email bryan at gmail dot com for help - or find us on irc.
[edit] Report problems
If you'll face a hard problem during your localization, please post it to the Flock's L10n list so we can discuss the best way to make your life easier.