Fwd: Translating the Debian Administrator's Handbook
-------- Original Message --------
Hello everybody,
you all expressed interests to translate the Debian Administrator's
Handbook in your native language. Since the book has been released a few
weeks ago, it's now possible to start with the translation work.
First off, if you're still interested, I'll ask you to subscribe
to this mailing so that we have a common discussion channel concerning
those translation projects:
http://lists.alioth.debian.org/mailman/listinfo/debian-handbook-translators
Then I have written some initial information in README.translators and
README.git in the Git repository. Check those files out to learn more
about what the translation work involves (I attach them for your convenience).
You're free to setup whatever workflow you want to work on the translation
but I would like to have one "leader" or "coordinator" for each
translation. He would be the person that I can contact to get updates
about the status of the translation (and coordinate new releases for
examples).
Now if you have questions, please ask them on
debian-handbook-translators@lists.alioth.debian.org and I'll provide you
the answers that you need.
Thank you again for your interest in this project and I look forward to
work with you all.
Cheers,
PS: I have also updated http://debian-handbook.info/contribute/ to point
to the mailing list and those files.
--
Raphaël Hertzog ◈ Debian Developer
Get the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/
|
Notes for translators
=====================
This book and its translations are managed with Publican [1]. It also uses
a custom publican brand available in the Debian package publican-debian.
$ sudo apt-get install publican publican-debian
[1] https://fedorahosted.org/publican/
Coordination mailing list
-------------------------
Please subscribe to this mailing list:
http://lists.alioth.debian.org/mailman/listinfo/debian-handbook-translators
It will be relatively low-volume and will be used to send important
information about the book updates to the current translators.
Git usage
---------
Read README.git first.
Please do not multiply commits uselessly. If you made several commits
which only complete PO files, please squash them together before pushing
(see man git-rebase for an explanation of how to squash commits together
with interactive rebase).
Take care to work on the most appropriate branch too. Currently
it's "squeeze/master" since that's the stable maintenance branch
for the current release of the book.
How to start a new translation
------------------------------
First you must find out the ISO code of your translation (it looks like
"pt-BR" or "fr-FR"). See here for the list supported by Publican:
http://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/appe-Users_Guide-Language_codes.html
(I'll use "pt-BR" as example in the rest of this section)
Then if this Git repository doesn't have any directory of this name,
you need to create the initial translation files:
$ publican update_po --langs=pt-BR
Now you have lots of PO files in pt-BR/*.po that you can translate.
You should probably commit the empty PO files before going further.
$ git add pt-BR/*.po
$ git commit -m "Add initial files for pt-BR translation"
Then add a pt-BR/README file where you put:
- the name and email of the (current) translation coordinator
- the name and email of the volunteers who contributed to the
translation
- explanations (for new contributors) about the workflow that you use to
coordinate the work
- translation choices that you made about the style to use, the
vocabulary, etc.
$ vim pt-BR/README
$ git add pt-BR/README
$ git commit -m "Add README for pt-BR translation"
Translating PO files
--------------------
You're free to use the tool of your choice to complete the PO files. Once
you have done enough, you can commit your updated PO files:
$ git add pt-BR/*.po
$ git commit -m "Updated pt-BR translation"
Depending on the workflow used by your translation team, you can either
push your work directly or make it available to your translation
coordinator that will integrate it for you.
Translating pictures and schemas
--------------------------------
Some schemas contain texts that need to be translated. In those case,
you should copy the relevant .dia files from en-US/images/ into the images
directory within your own translations directory (eg. pt-BR/images/),
update the dia file, and regenerate the corresponding PNG files (with the
help of the "make foo.png" Makefile target).
Some screenshots need to be remade to use a locale that matches your
language. Do the screenshot and put them in the images directory of
your translation (eg pt-BR/images/).
Note: there's currently no automatic way to verify whether your translated
schemas/pictures are up-to-date.
Questions?
----------
Just ask on debian-handbook-translators@lists.alioth.debian.org.
Notes about the Git repository
==============================
I attach some importance to having a clean history in the repository.
So please try to follow the rules and advice given in this file.
Learn git
---------
If you don't know Git, please take the time to read a good tutorial:
$ man gittutorial
If you want a full book, you can checkout http://progit.org
Configure git
-------------
Ensure you have properly configured Git with you real name and your email:
$ git config --global user.name "Your Complete Name"
$ git config --global user.email "your@email"
Retrieving the sources
----------------------
Read-only anonymous access:
$ git clone git://anonscm.debian.org/debian-handbook/debian-handbook.git
SSH access for contributors with write access:
$ git clone git+ssh://git.debian.org/git/debian-handbook/debian-handbook.git
Updating your working copy
--------------------------
>From time to time, you will have to integrate the changes commited by
others since your last synchronization (in particular before a push,
otherwise your push will be rejected), please use "git pull --rebase" for
this.
This will avoid merges and keep a clean linear history.
Pushing your work to the official repository
--------------------------------------------
The official repository is on git.debian.org. If you want write access to
this repository, you need to be added to the debian-handbook project.
Create an alioth account if you don't have any, login and then use
the "request to join" link on this page:
http://alioth.debian.org/projects/debian-handbook/
Fill in the reasons why you want to be added. If you plan to translate
the book, say on which translation you want to work on, etc.
Once you have been added, you can use this Git url to
clone the repository and push your changes:
git+ssh://git.debian.org/git/debian-handbook/debian-handbook.git
If you already have cloned a repository from the read-only URL
you can update the URL with this command:
$ git remote set-url origin git+ssh://git.debian.org/git/debian-handbook/debian-handbook.git
Before pushing changes to the official repository, please double
check what you're about to push with this command for example (you can
add -p if you want to see the details of the changes):
$ git log --stat @{u}..HEAD
(This command assumes that you're going to push the current branch).
If needed, use "git rebase -i" to clean the set of commits that you're
about to push.
Official branches
-----------------
- master: development branch (currently targeting Wheezy)
- squeeze/master: main branch for the version targeting Squeeze
- squeeze/print: print version of the book targeting Squeeze
(based on squeeze/master but with supplementary markup to
avoid some pitfalls of the dblatex conversion)
Official tags
-------------
They have this format <codename>-<type>-<lang>-<edition>.
<codename> is the Debian release codename.
<type> is "print" or "ebook".
<lang> is the language code (ex: "en" or "pt-BR")
<edition> is the edition number ("ed1" for the first edition)
debian/<version> tags point to the corresponding releases of the Debian
package.
Reply to: