Calendar:Translation

Translating releases after Sunbird 0.3a2

After Sunbird 0.3a2 was released, we migrated to the same means of translation being used by Firefox, Thunderbird, and other Mozilla applications in general.

Calendar localizers should follow the instructions found at Firefox:1.5 Localization when building Sunbird. We have added "calendar" directories to the directories already on /l10n/ab-CD.

Translating Sunbird 0.2 through 0.3a2:

The most practical ways to translate Sunbird 0.2/0.3a2 have proven to be the following which are based on the idea of replacing the en-US files:

• If the language of your choice is NOT being shipped with Sunbird 0.2/0.3a2, you have to provide a calendar-ab-CD.jar file that includes the locale files of your language for calendar. Once you have that file inside the chrome directory along-side other calendar.jar files you can proceed with the next step.

• If the language of your choice is being already shipped with Sunbird 0.2/0.3a2, to start using it in that language all you need to do is to follow the instructions here. If you repackage the Sunbird directory with the modified chrome.rdf file you should have a Sunbird dist in that language. Important note: Doing so will just get you a translation of the calendar UI only. Parts that belong to the toolkit like the password manager will still be English. If you want to go further in translating those parts too you have to translate the en-US.jar file as well as en-win.jar, en-unix.jar and en-mac.jar and modify chrome.rdf in the same manner you did to replace the en-US files for calendar but this hasn't been tested so you have to overcome the problems you may encounter on your own. In that case, please do share your experience for the benefit of others.

CALENDAR HAS MOVED TO THE FIREFOX/THUNDERBIRD LOCALIZATION FORMAT. THEREFORE THE PROCESS BELOW IS NO LONGER ENTIRELY CORRECT, BUT SOME CONCEPTS STILL APPLY

This page outlines how to translate Sunbird. (In future it might be updated to cover Calendar, and perhaps Lightning).

It is intended to be a brief guide for new translators.

For detailed help with translation, use the newsgroup: [1]

Before you start

Before you start, identify the locale that you plan to translate for. The locale name has the form xx-XX, where xx is a language code and XX is a country code.

Throughout this guide, wherever you see xx-XX you must use the name of your locale.

Tools

You need a tool for jar files, and an editor for text files.

Tools for jar files

For jar files, you can use any jar tool or zip tool.

Some zip tools only work if you rename the file so it has the .zip extension. If you have to do this, make sure that you rename each file with the correct extension after you have finished with it.

Tools for editing

Use an editor that saves files using UTF-8 encoding.

To check your editor, create a file named test.txt and type some text in it. Include many special characters and accents that your language uses.

Open the file in Firefox (for example, by dragging the file's icon and dropping it in Firefox). From Firefox's menu bar, choose View – Character Encoding – Unicode (UTF-8). Check that you see the correct characters when UTF-8 is selected.

es-ES team has been working using Mozilla Translator, and with minor glitches it works good.

English source files

Download and install the English version of Sunbird.

Go to the directory where you installed Sunbird, then to the chrome directory there.

Unpack en-US.jar.

For Sunbird 0.3alfa1, unpack locale/* from calendar.jar. (Alternatively, unpack all of calendar.jar and delete the content and skin directories.)

For Sunbird 0.3alfa2, unpack calendar-en-US.jar, which contains just the locales specific to the calendar application. For Sunbird 0.3alfa2, you better keep the separation existing between en-US.jar and calendar-en-US.jar, thus providing for your localization ab-CD.jar and calendar-ab-CD.jar. In order to do this, make sure that you unpack en-US.jar in a separate subdirectory than the one used for calendar-en-US.jar.

Reusing other translations

Some translations might already exist for your locale.

If you install a translated Firefox, then you can reuse xx-XX.jar from Firefox.

If you install Calendar extension (or unpack the XPI file), you can reuse much of the translation in calendar-xx-XX.jar.

Some of the files in these translations might be a little different. The differences can cause errors in Sunbird. You must unpack the jars and fix every file so that it matches the English Sunbird files.

So if you use this method you have much less work translating, but much more work debugging.

What to translate

Translate files in the locale directory. Do not translate any other files.

Rename the en-US directory as xx-XX.

File formats

Translatable files use the following formats.

The character encoding is UTF-8, but DTD files can also use entities to represent special characters.

Symbols beginning with percent (%) are replaced by the program. Your translation must preserve the symbols.

dtd files

Translate the strings between double-quote characters.

properties files

Translate the string following the equals sign on each line.

Some properties might be settings that you should change for your locale (but not translate).

rdf files

Any file named contents.rdf is obsolete. Any other rdf file probably has special translation requirements.

css files

Translate the text between single-quote or double-quote characters in content rules. Adjust any other rules for your locale.

Using Mozilla Translator

es-ES team has used Mozilla Translator following these steps:

1. we started from a Glossary.zip with the updated calendar XPI translation and reused the Firefox es-ES.JAR for the shared components.
2. we built an en-US.jar with the full locale, like previously stated in "English source files" section.
3. Run MT option File -> Product Update. Dismiss the result window (or just review strings in "calendar" component.)
4. Run MT option Import -> Import Translation, and point to Fx 1.5 ab-CD.jar.
5. At your choice, review file-by-file in Chrome View or run Edit -> Untranslated Strings.
6. Mozilla Translator can't handle a PE reference in brand.dtd (which contains product names and so); thus, once you're done with translation review in MT, export a JAR (Export -> JAR file). Then you must copy the following files from the customized en-US.jar from point #2 in this instructions list to you ab-CD.jar (we do this with a Bash script):
   • locale/branding/brand.dtd --> locale/branding/brand.dtd
   • locale/en-US/global/brand.dtd --> locale/ab-CD/global/brand.dtd

Then follow the remaining steps of this documents. You may use Mozilla Translator to fix any errors as long as you don't forget to update every time both brand.dtd files.

Rebuilding

Pack the locale directory into a new jar file, xx-XX.jar. Do not use compression.

Note:   Some of the files came from calendar.jar, but do not put your translation there.

Check that the contents of xx-XX.jar look like:

locale/
locale/branding/
locale/branding/brand.dtd
...

Copy the file en-US.manifest, naming the copy xx-XX.manifest.

Edit your xx-XX.manifest.

Open app-chrome.manifest. Copy the lines starting with locale and paste them at the end of your xx-XX.manifest.

In your xx-XX.manifest, change calendar.jar to xx-XX.jar in the lines that you pasted.

Change en-US to xx-XX throughout.

Save the file.

Go back one directory to Sunbird's program directory.

Create a text file named .autoreg (that name is eight characters, starting with a full stop). The file does not need any content.

Now you have a bilingual Sunbird.

Testing

Start Sunbird using the command line switch:

-UILocale xx-XX

For example: Copy the icon that you use to start Sunbird. Open the copy's properties. Add -UILocale xx-XX to the end of the command that you find in there. Close the properties and use the icon to open Sunbird.

You should see your translated text.

Debugging

Check every window in Sunbird to ensure that it works. In the Options window, check every page.

If you see error messages or English text in the user interface, then you must fix your translation. Unfortuately the error messages do not always tell you exactly what to fix. Some trial and error is often needed.

Note:   Sunbird displays some dates directly from your operating system. They always appear in your operatng system's language. You cannot translate them.

Packaging

You can package your translation as a complete Sunbird download, or as a language pack.

A complete download is good for users who want to use only one language. But every time there is a new release of Sunbird, you must make a new download.

A language pack is good for users who want to use more than one language in the same installation. If there is a new release of Sunbird, the language pack might work unchanged with the new release (if the user interface has not changed).

Complete Sunbird download

To make a ZIP for users to download, remove .autoreg, en-US.jar, en-US.manifest and the locale directory.

Edit app-chrome.manifest and remove the lines that start with locale.

Pack the sunbird directory and all its contents, using maximum compression.

Check that the zip file contents look like:

sunbird/AccessibleMarshal.dll
sunbird/chrome/calendar.jar
sunbird/chrome/chromelist.txt
...

Note:   Some English files are still in calendar.jar, but they are harmless.

To test the download, rename your sunbird directory. Unpack your zip file, installing Sunbird in a new directory. Check that the Sunbird you have just installed works correctly.

Language pack

To make a language pack, create a temporary directory somewhere, then go to that directory.

Copy your xx-XX.manifest there, naming it chrome.manifest.

Create a chrome directory there and copy your xx-XX.jar into it.

Edit your chrome.manifest. Change jar: to jar:chrome/ throughout the file. Save the file.

Create a text file named install.rdf. Copy and paste this template:

 <?xml version="1.0"?>

 <RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:em="http://www.mozilla.org/2004/em-rdf#">

 <Description about="urn:mozilla:install-manifest"
   em:name=""
   em:version=""
   em:id=""
   em:description=""
   em:creator="" >

   <em:targetApplication><!-- Sunbird -->
     <Description
       em:id="{718e30fb-e89b-41dd-9da7-e25a45638b28}"
       em:minVersion=""
       em:maxVersion="" />
   </em:targetApplication>

 </Description>
 </RDF>

Where there are empty quotes, "", specify information about your language pack.

The id must have a special format, like this:

{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}

The first time you create this file, get a random id from one of these sites, or from another similar site:

http://jasonfarrell.com/misc/guid.php
http://www.hoskinson.net/webservices/guidgeneratorclient.aspx

Check that the id has the correct format and length.

Note:   When you release a new version of your translation, do not change the id.

The minVersion and maxVersion should correspond to the Sunbird versions that your language pack works with. For Sunbird 0.3a1, specify 0.2 and 0.4.

Save the file.

Note:   For more information about install.rdf, see: http://kb.mozillazine.org/Install.rdf

Pack the contents of your temporary directory in a file named something like: sunbird-v.v-xx-XX.xpi, where v.v is the version. Use maximum compression.

Check that the xpi file contents look like:

chrome/
chrome/xx-XX.jar
chrome.manifest
install.rdf

To test your language pack, start with a clean install of English Sunbird. In Sunbird, choose Tools – Extensions... and drop your language pack in the Extensions window. Permit the installation. Restart Sunbird using the command line switch -UILocale xx-XX.