Source files for the Debian Administrator's Handbook - https://debian-handbook.info
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Petter Reinholdtsen 5f60a83878 Flagged incorrected structured index entries as fuzzy to fix the build. 1 month ago
ar-MA Corrected ar-MA XML error. 1 month ago
bin Correct nb locations, bring them in line with docbook-xsl and dblatex. 5 months ago
brand Add <meta name="flattr:id"> to the HTML head of the book 3 years ago
ca-ES Corrected ca-ES XML error. 1 month ago
cs-CZ Update broken link to virtual-package-names list 6 months ago
da-DK Update broken link to virtual-package-names list 6 months ago
de-DE Translated using Weblate (German) 6 months ago
debian Replace cover.png with cover.jpg in some forgotten places 7 months ago
el-GR el-GR: Translated using Weblate. 1 month ago
en-US Update broken link to virtual-package-names list 6 months ago
es-ES Update broken link to virtual-package-names list 6 months ago
fa-IR Update broken link to virtual-package-names list 6 months ago
fr-FR Translated using Weblate (French) 1 month ago
hr-HR Update broken link to virtual-package-names list 6 months ago
id-ID id-ID: Translated using Weblate. 1 month ago
it-IT it-IT: Translated using Weblate. 3 months ago
ja-JP ja-JP: Translated using Weblate. 1 month ago
ko-KR Update broken link to virtual-package-names list 6 months ago
nb-NO Translated using Weblate (Norwegian Bokmål) 6 months ago
nl-NL Translated using Weblate (Dutch) 1 month ago
pl-PL pl-PL: Update translation of 01_the-debian-project.po 2 months ago
pot Update broken link to virtual-package-names list 6 months ago
pt-BR Flagged incorrected structured index entries as fuzzy to fix the build. 1 month ago
ro-RO Update broken link to virtual-package-names list 6 months ago
ru-RU ru-RU: Translated using Weblate. 1 month ago
sv-SE sv-SE: Translated using Weblate. 1 month ago
tr-TR tr-TR: Translated using Weblate. 1 month ago
vi-VN vi-VN: Translated using Weblate. 1 month ago
zh-CN Corrected zh-CN XML error. 1 month ago
zh-TW zh-TW: Translated using Weblate. 6 months ago
.gitattributes Disable gettext catalogs (>95%) 1 year ago
.gitignore Rename the "build" directory into "bin" 3 years ago
.gitlab-ci.yml gitlab-ci: build pages only in the official repository 1 year ago
README.git Update README.git 1 year ago
README.maintainers Document how to manuall sync from Weblate 7 months ago
README.style Fix spelling error from README.style 1 year ago
README.translators Document how to setup ~/.publican.cfg 3 months ago
TODO Update TODO file for buster version 1 year ago
publican-pdf.cfg Use conditional tags to not include chapter pictures in non-PDF builds 8 years ago
publican.cfg Change doc_url so that the book icon points back to the table of contents 5 years ago

README.translators

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://sourceware.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.

Different translation workflows
-------------------------------
There are two ways to manage the translations:
- using the Weblate web application at
https://hosted.weblate.org/projects/debian-handbook/
- using the Git repository to grab and commit PO files

Translation with Weblate
------------------------

If you decide to use Weblate, you don't have to learn Git usage.
Get in touch with us on the above mailing list so that we can setup
the initial translation files for you, and once they appear
on Weblate, you can start working! You should communicate us
the ISO code of your translation (see "How to start a new translation" for
more information on possible ISO codes).

Note, however, that you can't translate pictures with Weblate, so someone
must still commit those on the Git repository for you. If Git is too
complicated for you, feel free to send the files to the mailing list and
ask someone else to commit them for you.

If you want to retrieve the content of Weblate via git you can use
this git repository as remote:
$ git remote add weblate https://hosted.weblate.org/git/debian-handbook/12_advanced-administration

Translation without Weblate
---------------------------

If you're not using Weblate, you'll have to interact with the Git
repository. So read README.git first. Really. And then please respect the
guidelines below.

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).

Write meaningful commit messages. Always start with the language
code of the affected translations. Some examples of good commit
messages:
* it-IT: Add initial README file
* es-ES: Complete translation of chapter 4
* zh-CN: Review of chapter 3

Take care to work on the most appropriate branch too. Currently
it's "buster/master" since that's the stable maintenance branch
for the current release of the book. If you already have downloaded the
repository, use "git checkout buster/master" to change the current
branch. Otherwise you can use one of the following commands to clone the
repository and start on the correct branch:

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:
https://jfearn.fedorapeople.org/en-US/Publican/4.2/html/Users_Guide/appe-Publican-Users_Guide-Language_codes.html

(I'll use "pt-BR" as example in the rest of this section)

Then you need to tell publican who you are by creating a ~/.publican.cfg
file (change the values with your own name and email):
$ cat >~/.publican.cfg <<END
firstname=Raphael
surname=Hertzog
email=hertzog@debian.org
END

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 "pt-BR: Start new 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 "pt-BR: Add initial README file"

You can certainly write that README file in your native language if you
want, but it's highly recommended to also have an English translation of
the instructions so that everybody else can see how a given team is
organized.

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 "pt-BR: Updated 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.

If you use a plain text editor, please double check that you haven't
broken the PO files. Here is an example checking
pt-BR/01_the-debian-project.po where some issues are detected:

$ msgfmt -c -o /dev/null --statistics pt-BR/01_the-debian-project.po
pt-BR/01_the-debian-project.po:1432: 'msgid' and 'msgstr' entries do not both end with '\n'
msgfmt: found 1 fatal error
348 translated messages, 100 fuzzy translations, 9 untranslated messages.
$ msgcat pt-BR/01_the-debian-project.po >/dev/null

Translating pictures and schemas
--------------------------------

Some schemas contain texts that need to be translated. In those cases,
you should copy the relevant .dia files from en-US/images/ into the images
directory within your own translations directory (e.g. 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.