L10n:Tutorial
L10n:Home Page | L10n:Localization Teams | L10n:Tutorial | L10n:Grouse localization tutorial
Contents |
[edit] Overview
This tutorial will teach you how to localize Flock.
[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
Go to ./flock/searchplugins/ directory, where can find all searchplugins used by the browser. You can update the ones that provide localized search in your language. We'll write a policy about adding and modifying searchplugins engines shortly. For now, all new plugins have to be approved before shipping them.
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.
[edit] Favorites
You can localize default set of Favorites (how?).
[edit] Good 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 dukebody 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.
[edit] Updating the l10n files (default.opml, defaultMedia.js, defaultFavorite)
[edit] Summary
This document outlines how to update the localized (l10n) files (rss feeds, favorites and media streams) as well as the file locations to update SVN.
NOTE: you must update two locations for the localized l10n content.
Current Directory: /branches/grouse/de/flock/profile
File Location 1: /branches/grouse/de/flock/profile
File Location 2: /branches/grouse/de/flock/other-licenses/branding/flock/profile
Svn location:
- svn://svn.l10n.flock.com/l10n/branches/grouse/de/flock
[edit] RSS Feeds (default.opml)
RSS Feeds: (default.opml)
- File Location 1: /branches/grouse/de/flock/chrome/flock/feeds/opml/default.opml
- File Location 2: /branches/grouse/de/flock/other-licenses/branding/flock/chrome/flock/feeds/opml/default.opml
With RSS Feeds, simply add all your RSS feeds in flock and then export them. Flock will export all you RSS feeds as flock-export.opml. You will need to rename this file to default.opml in order to implement this file in the build process.
[edit] Favorites (defaultFavorite.js)
Favorites: (defaultFavorites.js) File Location 1: /branches/grouse/de/flock/profile profile/defaulFavorites.js File Location 2: /branches/grouse/de/flock/other-licenses/branding/flock/profile/defaultFavorites.js
Unlike the RSS feeds you cannot simply export these these files as html. Flock treats “Favorties” much differently and therefore we cannot use the exported bookmarks html file.
Just like the RSS feeds, setup your favorites in Flock the way you want them, then follow the steps below. Note: It may be easier to use content pack maker to generate this file then update according to the steps below if needed. You can also do this manually if you already have an exsisting favorites.js file as a template to work with.
What you will need:
1.Folder Name: Create a Folder Name. You can create as many as you want.
2.Favorite URL: Add all your your favorite urls in each folder(s)
3. Favorite Summary: Enter a summary for each favorite bookmark
4. Favorite Favicon: The favorite favicon must be a code base64 favicon encoding. Here is how you encode a favicon.ico file to base64:
Bellow is an example of creating a “Google” folder with a Google favorite bookmark.
Select your Favorite Bookmark Favicon: Copy the favicon. Most sites will have URL structure that will allow you to copy the associated favicon. (http://www.google.ca/favicon.ico). IMPORTANT: you must save favicon’s as a .ico file or you will not get the proper base64 encoding.