1156785 - Add Localization Guide to documentation

Status: RESOLVED FIXED

(Bugzilla :: Documentation, enhancement)

Description

[Gervase Markham [:gerv]]

We should add the localization guide to the documentation, as seen here:

http://www.bugzilla.fr/docs/l10n/html/index.html

Cedric: can you point us at the raw data (reST files and images) to be imported?

Gerv

Comment 1

[Cédric Corazza]

Attachment: Bugzilla localization guide raw files

This tarball contains the .rst and .png files and also the modified bugzilla.css file and the main index.rst file modified to add the l10n directory.

Comment 2

[Gervase Markham [:gerv]]

Cédric: this is awesome :-) I have a few questions for you:

* Instead of supplying special instructions on how to get the source, can we just refer to the existing instructions?

* Instead of supplying special information for how to install the Perl modules and so on that you need to run the tests and compile the docs, would it not make more sense to suggest that localizers simply follow the installation instructions and get Bugzilla running? After all, they'll need to do that to view and test their localization anyway.

* On that point, we need to supply information about how to persuade Bugzilla to display your new locale instead of English.

* Would it make a sense to write a "new-locale.pl" script which took an install of Bugzilla, found all of the "en" directories, and copied them as "fr" or whatever locale code you give it?

* Would it make sense to write a script which tarballed up all of the parts which need to be shipped in a locale package?

* Do you think it's wise to suggest to people that they watch the trunk repo for changes? Might it not make more sense to suggest that they subscribe to the release announcements, and then do any new l10n in one go at that time?

Gerv

Comment 3

[Cédric Corazza]

(In reply to Gervase Markham [:gerv] from comment #2)

* Instead of supplying special instructions on how to get the source, can we just refer to the existing instructions?

Sure. Initially, I did not consider this guide to be part of the rest of the documentation.

* Instead of supplying special information for how to install the Perl modules and so on that you need to run the tests and compile the docs, would it not make more sense to suggest that localizers simply follow the installation instructions and get Bugzilla running? After all, they'll need to do that to view and test their localization anyway.

Yes, it would. It is just a matter of how one organizes his work. For my part, I do not want to install Bugzilla and Apache and so on on my main computer where reside all my repositories and where I make my daily stuff (Net, email, etc.), to keep it clean and fast.

* On that point, we need to supply information about how to persuade Bugzilla to display your new locale instead of English.

Unless I'm wrong, if Bugzilla detects another subdirectory than 'en' in the template directory, it will display it in the upper right corner of Bugzilla home page (after checksetup.pl is executed). Then based on the browser's user-agent, it will display Bugzilla in that locale. If not, the user can force the locale by clicking on it.

* Would it make a sense to write a "new-locale.pl" script which took an install of Bugzilla, found all of the "en" directories, and copied them as "fr" or whatever locale code you give it?

Why not, it would be easier for a first extraction to make sure we get all the subdirectories and files. But the output of this extraction would be outside the Bugzilla installation and not alongside the 'en' subdirectories: to create a clean tree structure containing only the localized files and then populate a DVCS repo of the localized files. I am not sure to be clear in my explanations here :) .

* Would it make sense to write a script which tarballed up all of the parts which need to be shipped in a locale package?

Why not.

* Do you think it's wise to suggest to people that they watch the trunk repo for changes? Might it not make more sense to suggest that they subscribe to the release announcements, and then do any new l10n in one go at that time?

In my experience, diff between major releases or even dot releases can be really scary for localization. For instance, think about the move to html5 or the documentation reorganization. That is why I suggested that. But I guess other localizers might think differently.

All my comments are based on the fact I use repositories to maintain my files and do not make localization in one go.

Comment 4

[Gervase Markham [:gerv]]

Attachment: Patch v.1

This is a patch which takes Cedric's excellent work, reworks and reorders it a little bit, and adds it as a new guide to the Bugzilla docs.

It would not be reasonable to ask a Bugzilla code reviewer to read all of this and do a "test localization" to see if it was all correct and worked! So my proposal is to check it in (for ease of review) and ask Cedric to review it, test out what it says, and file bugs if he finds problems.

Obviously, having not-quite-right docs on trunk is a different thing to having not-quite-right code, particularly if it's for something which hasn't been documented before anyway, so I think this is a reasonable way forward.

dkl: as another docs person, could you give feedback+ to approve this plan?

Gerv

Comment 5

[Frédéric Buclin]

Your patch contains twice the same code. Looks like you concatenated the patch to itself.

Comment 6

[David Lawrence [:dkl]]

Comment on attachment 8667379 [details] [diff] [review]
Patch v.1

Plan sounds good to me.

Comment 7

[Gervase Markham [:gerv]]

To ssh://[e-mail]/bugzilla/bugzilla.git
   b8a1ef4..7321534  master -> master

I will contact Cedric about re-reviewing this documentation.

Gerv