Localisers Guide

[Gervase Markham]

Here's the first draft of a Bugzilla Localisers Guide. Comments welcome.

Gerv

<snip>

Bugzilla Localisers Guide

This guide outlines how to make a localised copy of Bugzilla.

Overview
--------

The key technology for localising Bugzilla is UI templates. Over the 
last few months, more and more of Bugzilla has been converted to use 
templates, and so now Bugzilla's user-facing UI is all done. This 
separates the content from the presentation.

We plan to templatise the administration UI as soon as we can but, in 
the mean time, you have to administer Bugzilla in English. Error 
messages are also not done in 2.16.

We recommend that you begin by localising Bugzilla 2.16. Although it is 
not fully localisable, it is still localisable enough for day-to-day 
use, and your localisation will form a good basis for a localisation of 
a later version in the future. In other words, by the time you've done 
that, we should have a better version ready for you to migrate to :-)

Doing the Localisation
----------------------

I am assuming you are creating a localisation for a country code "xx". 
You need to create a directory template/xx/default under the Bugzilla 
root, and recursively copy the contents of template/en/default into it.

Note that you can create a localisation for a two-part locale xx-YY - 
e.g. "en-GB" - but it will only be made available to people who 
specifically request "xx-YY"; people who request "xx" won't get it. If 
you do create an "xx-YY" localisation, make sure you have an "xx" 
localisation also.

Once you've got a copy of the templates, start translating the English 
in them. It should be obvious what to translate and what not to 
translate. Template toolkit directives and variables can be found inside 
[% %] tags - don't translate these. You can, however, move them around 
within a sentence for localisation purposes.

Also, some times are formatted in the template using time2str - if this 
is true, you can rearrange the time format to suit your locale.

This may take a significant amount of time - there are over 200 
templates. You may wish to share this work among multiple contributors.

Creating a Localisation Pack
-----------------------------

To create a localisation pack, tar up the contents of 
template/xx/default and make it available. Remember to mark it with the 
version number of the Bugzilla it corresponds to.

Using A Localisation
--------------------

To install a localisation pack, untar it into your Bugzilla directory so 
it appears in template/xx/default/ .

2.16: To get Bugzilla to use the localisation, you have two options. If 
you want Bugzilla always to be in that language, edit globals, pl, find 
INCLUDE_PATH and change the "en"s to "xx"s. If you want Bugzilla to pick 
up the user's browser language and use that, apply the patch from bug 
126955, and set the relevant parameters (lang and defaultlang) 
appropriately.

2.17 onwards: The patch from bug 126955 is already checked in - so just 
set the parameters to define what languages you want to use in what 
order. You can force use of a particular localisation by setting it as 
the default and giving no other options.