Creating en-X-dude
From MDC
This is almost a screencast, maybe someone could make a one or a few for this. What I'm going to talk you through here is how to start a new localization of Firefox 3, which files to edit. There will be a followup document on how to find out how to go back and forth between strings in the user interface and the source and other tips and tricks.
Now, why am I doing English, dude? 'Cause the only other language I speak is German, we have that, and it doesn't make a fun document title. And you know the language you want to do, right? Let's find the language code to use.
Contents |
[edit] Picking a language code
So let's pick a language code for my mostly English localization, en-X-dude it is. There is more information on how to do that on wikimo:L10n:Simple_locale_names. We'd like to use just language codes in general. That was simple, right? Next, we'll get the source, that is, the files to translate.
[edit] Get the source
Ok, I have to send you off for a second here. Please make sure that you have the build requirements for your platform, and that you can start a shell. If you're on a Mac or Linux, you should be familiar with that, if you're on Windows and downloaded MozillaBuild you want to open a command prompt.
Next, you want to create a new directory, we're playing games here, so open up a sandbox:
mkdir sandbox cd sandbox
Nothing breaks if you use a different directory name. You have to make sure that the full path of that directory doesn't contain spaces, though. In particular on windows, your initial directory ~ may expand to a path with spaces, so create the directory somewhere else. Next, we're really getting the source. First time you hit the cvs server, you may have to log in:
cvs -z3 -d:pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot login
Just hitting enter for the password does it, now for the source,
cvs -z3 -d:pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot co mozilla/client.mk cvs -z3 -d:pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot co mozilla/tools/l10n cd mozilla make -f client.mk l10n-checkout MOZ_CO_PROJECT=browser
Now you have the source. I used the l10n-checkout target above, because that's a smaller download, you can (and at some places have to) get all the sources for Firefox by using the checkout target instead. Now that you have the original English files, let's create a dummy localization.
[edit] Create a dummy localization
Now it's time to create the necessary files for our localization, there's a python script to help with that.
python tools/l10n/l10n.py en-X-dude
This creates all the files you need to have in ../l10n, in a subdirectory that is your language code. If your language code would be de, you'd use create-de instead of create-en-X-dude, and your files would be in ../l10n/de.
Let's take a look at what we got, first, change into the l10n directory,
cd ../l10n
Now you can look at the list of files created, just to get a feeling,
find . -type f
If you don't really understand what you just did, that's not too bad, it's really just to give you a feeling where you should find things. You should look at all files on the way to your localization, even though a few are only used if you create a full localization including installers and profile migration.
Next is to actually create a language pack, so we need to do some edits and pack them up into an installable language pack. Depending on your personal preference, you might want to read the following two sections the other way around. I'll start off with the second step as that gives you the chance to build the language pack at any time during the editing part below.
[edit] Create a language pack
First, we'll create a build directory. This sounds worse than it is, you won't need to actually build, but we'll need to setup something that looks like it. You're still in the l10n directory, right? We'll create build right next to it. The name of that directory doesn't really matter, so no reason to change it.
mkdir ../build cd ../build
Now we'll set up a not-so-compile enviroment by calling configure. If you just checked out the localizable parts of en-US above, it will create a plethora of warnings No such file or directory, but no errors.
../mozilla/configure --disable-compile-environment --enable-application=browser
Whenever you need a build directory, these are the steps that you need to do to initialize it. If you're downloading a new release of Firefox from CVS, you might want to run configure again, too.
Now we can actually create the language pack,
make -C browser/locales langpack-en-X-dude
You should find your newly created language pack in dist/install.
ls dist/install
You can open that file in Firefox and check it out. You have to set your selected language still. You can either use the Locale Switcher extension, or set it in about:config. Set the general.useragent.locale to your language code, in this case, en-X-dude, and restart Firefox once more.
[edit] Localize
Now it's time to actually localize Firefox. As you have seen, there are plenty of files that you created, the most important ones are .dtd-files and .properties-files. Both can be edited with any UTF-8 editor, so independent of which editor you use, please make sure that you save those files as plain text in utf-8 encoding. There is a third type of files, .inc-files which I'll cover here, too. To start with a language pack, that should be all you need.
[edit] Add yourself to the Add-on description
Open up l10n/en-X-dude/toolkit/defines.inc and you'll find one line,
#define MOZ_LANG_TITLE English (US)
Let's make that
#define MOZ_LANG_TITLE 'nglish (borked)
You'd insert your language name, and optionally region, in there for your own localization, of course.
In l10n/en-X-dude/browser/defines.inc, we'll uncomment the contributor lines,
# #define MOZ_LANGPACK_CONTRIBUTORS <em:contributor>Joe Solon</em:contributor> <em:contributor>Suzy Solon</em:contributor>
and add ourselves
#define MOZ_LANGPACK_CONTRIBUTORS <em:contributor>Axel Hecht <l10n@mozilla.com></em:contributor>
Again, you'd use your name and email, and of course the ones of other major contributors. You wouldn't mention everybody that reported back a typo here, this is more people that can be contacted for help and feedback.
Both of these files should be saved in UTF-8 again, and please make sure that you're not accidentally adding empty lines to the top or the bottom.
[edit] DTDs
DTDs are part of the XML standard and enable the XML parser to replace content, which Mozilla uses to localize its XUL interface. Let's start with something simple, the about dialog. Take a look at the searchbar, that's (per default) the Google search in the upper right corner. The language dependent strings for that are in searchbar.dtd. In your local files, the en-US version is in mozilla/browser/locales/en-US/chrome/browser/searchbar.dtd, and the localized copy of that is at l10n/en-X-dude/browser/chrome/browser/searchbar.dtd
mozilla/browser/locales/en-US/chrome/browser/searchbar.dtd l10n/en-X-dude/browser/chrome/browser/searchbar.dtd
The leading part is either mozilla or l10n, followed by a path to the module, in this case, browser. The module may be more than one level deep, there is extensions/reporter, too, for example. In the en-US repository, you can tell the module by taking everything between mozilla and locales/en-US. That is followed by the rest of the path, which for most files is in the chrome directory.
So, as you're looking at MDC right now, let's look at the popup in the searchbar, it should have all your installed search engines, plus two menu items, Add "MDC (English) and Manage Search Engines.... The accesskey for the latter is M.
So, now open your copy of searchbar.dtd in an editor. The first line will look like
<!ENTITY cmd_engineManager.label "Manage Search Engines...">
The only part you want to edit is the blue part. Let's do that, how about something as boring as
<!ENTITY cmd_engineManager.label "'anage 'earch 'ngines...">
As you can see, I used single quotes as part of the value, which is OK as the string value is in double quotes. You can use single quotes for the complete value instead of double quotes and then use double quotes inside the value, too, or you just use the XML entities.
So, where's Add "MDC (English)"? It's in a .properties file right next to searchbar.dtd, search.properties.
Save searchbar.dtd for now, make sure that it's saved in UTF-8.
[edit] Properties
Let's open l10n/en-X-dude/browser/chrome/browser/search.properties. We're looking for the string that's giving us Add..., so glance over the file for a moment.
We're looking for cmd_addFoundEngine in line 18.
cmd_addFoundEngine=Add "%S"
Again, you're only interested in editing the blue part. What's the %S, though? It's a parameter, in our example, it's getting replaced with MDC (English). Let's do the same kind of localization to it for the sake of this example,
cmd_addFoundEngine='dd "%S"
Save that file, again, make sure it's saved in UTF-8.
[edit] Updating intl.properties
One significant setting for your language is specified in intl.properties, most notably intl.accept_languages. Setting this to the right value will enable websites to serve content in a language that your users are likely to understand. It's a common practice to leave en-US and en in there, but list the language codes good for your region first. To see something in the field, let's use
intl.accept_languages=de-de,de,en-us, en
You'll find general.useragent.locale in intl.properties, too. That shouldn't be used anymore, but let's be safe and fix that as we go, too.
Now let's recreate the language pack and test it. Visit addons.mozilla.org, and it should come up in German.
[edit] Testing and ongoing work
Open build/dist/install/firefox-3.0b5pre.en-X-dude.langpack.xpi in Firefox install the addon and restart. You should be reading MDC again, so let's open up the searchbar popup again. You should be seeing (excuse the ASCII graphics)
'dd "MDC (English)" ------------------- 'anage 'earch 'ngines (M)...
What's the (M)? I mentioned above that the original accesskey for that menu item was M, and we didn't change that. Let's fix that now. Open up searchbar.dtd again, and let's change
<!ENTITY cmd_engineManager.accesskey "M">
to
<!ENTITY cmd_engineManager.accesskey "a">
Now you could repackage and reinstall, but now that we've actually done something, let's leave our marks on the languagepack for everyone to see.
Now repackage again, install, and restart.
You can see that the accesskey in the searchbar popup is fixed now, and if you go to the Add-ons dialog, you'll find your language pack in the Languages section, with the right language name. You can right click and look at the about dialog and find the changed contributor information.
This is the perfect time to stop working on en-X-dude and to start working on your localization, with your language name, language code, and contributors list.