path: root/doc/translations.txt

Debian Installation Guide - notes for translation
--------------------------------------------------

!!! Please note, that this file mostly documents xml-based
!!! translations. But you can also translate this manual via po
!!! files, if you want. This is documented in the file
!!! translations_po.txt in this directory.
!!! And: using the po format is strongly recommended, using the
!!! xml format is deprecated!

!!! Additional note: this file is outdated to some degree, because of the
!!! migration of the repository from subversion to git!
!!! Thus, some of the scripts mentioned below no longer work as expected!
!!! Take this as one more encouragement on using po files (see
!!! translations_po.txt).


Note: if you happen to modify this file, please don't forget to
      update the trailing changelog

Where is the manual kept?
=========================

The manual is kept in a git repository on salsa.debian.org
as part of the Debian Installer (d-i) project.

The manual and its translations can be found in ./installation-guide.

How to join the translation effort for an existing translation
==============================================================

Try to find out who is working on the translation and contact them.
Alternatively you can send a mail to the mailing list for your language
(debian-l10n-<language>@lists.debian.org), if one exists or to the mailing
list for the debian installer project: debian-boot@lists.debian.org.

You should also coordinate with current translators on which parts to
translate and how to submit your translations.

How to start a new translation
==============================

Starting a translation for a new language without write access to the d-i git
repository really is not practical. See the section on getting GIT access below;
you will also have to get a local working copy of the manual as described there.

  1. Create a new directory structure for your translation
  --------------------------------------------------------
  Use the following commands to create a copy of the English documents as a
  base for your translation. This also ensures that your translation will be
  complete and can be built. A text that has not been translated yet, will be
  included in English.
  - change directory to: ./installation-guide/
  - cp -R en/ <lang>
    (where <lang> is the ISO code for your language: xx or xx_XX)
  - find <lang> -name .git | xargs rm -Rf
    (this removes all .git subdirectories)

  2. Convert revision comments
  ----------------------------
  This enables you to track changes in the original English documents.
  see 'Keeping your translation up to date' below for an explanation.
  - change directory to: ./installation-guide/
  - ./scripts/rev-update <lang>

  3. Commit the changes to git
  ----------------------------
  - change directory to: ./installation-guide/
  - git add <lang>/*
  - git commit -m "installation-guide: creating new translation for <lang>"

One more change is needed to get your translation building automatically:
<lang> needs to be added to the 'languages' variable in build/build.sh.
However, this is only usefull after you have translated your first couple
of chapters. Please send a request to the debian-boot mail list for your
language to be added.

Encoding
========

The default encoding for all .xml files is UTF-8. If you want to keep your
translation in UTF-8 encoding, you should use an editor that supports UTF-8
and make sure that UTF-8 encoding is selected when you open a .xml document.

If it is easier for you to work using another encoding, you will have to
specify which encoding you use in the first line of each translated document.
For example, to use ISO-8859-1 encoding (for most Western European languages),
add the following line at the top of each .xml file:
<?xml version="1.0" encoding="ISO-8859-1"?>

The use of HTML codes (like &egrave;) is possible but not advised.

Note: If you do not specify the correct encoding, your translation will fail
      to build.
Note: You should _not_ change the encoding of the following documents:
      - administrativa/contributors.xml

Translation order
=================

Suggested translation order:
- ./preface.xml, ./bookinfo.xml
- ./welcome/*.xml
- ./using-d-i/*.xml
- ./using-d-i/modules/*.xml
- ./boot-new/*.xml
- ./boot-new/modules/*.xml

Note that currently (may 10, 2004) it looks like there will be a fairly major
reorganization of parts of the manual in the next month(s).

Keeping your translation up to date
===================================

There are two perl scripts to help you keep track of changes in the original
English text of the manual. These scripts make use of special revision
comments that should be included in each file.

An original English file contains something like:
  <!-- retain these comments for translator revision tracking -->
  <!-- $Id: preface.xml 12756 2004-04-06 22:23:56Z some-user $ -->

The second line is important. It contains the filename, the revision number,
the date and time the last revision was committed and the user that committed
the last revision. The string '$Id:' is necessary for SVN to automatically
update this line each time the file is committed.

A document in a directory containing a translation should contain either:
  <!-- original version: 12756 -->
or
  <!-- original version: 12756 untranslated -->

When you translate a document, you should of course remove the word
'untranslated' from this comment.

The scripts will do several things:
- show which translated files have a different revision number from the
  original English files
- show what changes have been made in the original English file
- help you update revision comments
- help you keep track of which files have not yet been translated
You can find both scripts in the root directory for the manual. Both
scripts should be run from this directory.

The procedure below can be used for relatively simple changes. If there
have been major reorganizations in the English documents, you may have to
do additional checks to find out exactly what changes have been made.
Use 'git status' before you start this procedure to check the status of
your working copy.

  1. Update your local working copy from GIT
  ------------------------------------------
  - change directory to: ./manual/
  - git pull

  2. Copy new files (if any)
  --------------------------
  If there are any new files (appearing with "create mode" in the output from
  'git pull'),
  copy them to the directory for your translation and then:
  - ./scripts/rev-update <lang>
  This will change the revision comment in the copied file to:
  <!-- original version: ##### untranslated -->
  You will also have to run 'git add' for the new documents.

  3. Check for other changes
  --------------------------
  - ./scripts/doc-check <lang>
  If changes are listed for documents that are marked 'untranslated', you
  can copy the new English version to the directory for your translation
  by running:
  - ./scripts/cp-untrans <lang>
  (this script also runs rev-update automatically).
  If changes are listed for documents that are not marked 'untranslated',
  you can create a diff to find out what the changes are by running:
  - ./scripts/doc-check -d <lang>
  
  4. Update your translations
  ---------------------------
  Edit your translations to reflect the changes in the English documents.
  !! Don't forget to also update the revision number in the revision comment
     after you updated a translation. The revision number should be the same
     as the revision number in the new version of the English document.
  You should run './scripts/doc-check <lang>' again after you finish all updates
  and before you commit your changes to GIT; there should be no output.
  
  Other uses of the scripts
  -------------------------
  - doc-check -s <lang>: show which documents are marked untranslated
  - rev-update -u <lang>: automatically update revision numbers in the directory
    containing your translation to the revision numbers in the original English
    documents (use only after you have made sure there are no changes in content)

How to remain consistent with the installer
===========================================

It is important that your translation of the manual remains consistent with
the translation of Debian Installer and packages for your languages.

Probably the best way to do this, is to run the installer in 'expert' mode,
both in English and your own language.

As strings and their translations in the installer may change, you may have
to perform an installation once in a while to check if there have been
important changes (the main burden to check for changes in strings falls on
the maintainers of the English original, but if you spot inconsistencies,
please report them to the debian-boot list).

You can also use the xx(_XX).po files for packages (including d-i) to see
how strings have been translated. For more information on these files,
please refer to the translations.txt file in the parent directory of the
directory where this file is.

You can also try contacting the translator for a package or the maillist
for your language (debian-l10n-<language>@lists.debian.org) to try to clear
questions about translations.

How to test your work
=====================

When you have finished your translation, always re-read your file at
least once to correct all meaning-, spelling-, grammar-, typo-, etc-
mistakes.

You can also try to build the manual (create HTML pages) for a specific
architecture for your language.
See ./build/README for more information on building the manual.

How to get write access to the git repository
=============================================

  1) Installing git
  ------------------------

  You need to install subversion on your system. Just do
     apt install git
  
  2) Getting write access to the git repository
  ----------------------------------------------------

  If you are not a Debian Developer, you first need to create a guest account
  on https://salsa.debian.org/, than ask on debian-boot@lists.debian.org
  for somebody to add your guest account to the debian-installer project.
 
  3) Using git to get files
  --------------------------------

  Once your account is allowed to write to the project, you can retrieve the
  installation-guide using this:
    git clone git@salsa.debian.org:installer-team/installation-guide.git

  4) Commit your changed translation files to git
  -----------------------------------------------

  After you have finished editing your translation, use
    git add path-to-file(s)
    git commit -m "Your comment about this commit"
    git push
  to commit your changes to the git repository.


How to get help
===============

If you need further assistance, feel free to ask for help on
debian-boot (for debian-installer related stuff) or debian-i18n (for
l10n related questions) Debian mailing lists.

--------------------------------------------------------------------------

This guide is supposed to be be a first start for translators.  There
are probably errors.  Please fix it if you find errors.

--------------------------------------------------------------------------
Changelog:

2018-06-03 Samuel Thibault
 - migrate to git

2010-05-01 Tapio Lehtonen
 - Typo fixes

2006-07-14 Frans Pop
 - Correct and update information on subversion checkout

2005-10-07 Frans Pop
 - Location of manual changed in the d-i SVN repository

2005-02-12 Frans Pop
 - Minor corrections

2004-12-27 Frans Pop
 - Updated svn checkout info to refer to new server (costa)

2004/10/26 Holger Wansing
 - Added a chapter about how to commit + fixed the Link to the svnbook

2004/09/27 Frans Pop
 - Update in line with changes in SVN (moved files/directories)

2004/09/04 Guillem Jover
 - Refer to Adam Conrad's subversion backport instead

2004/06/04 Frans Pop
 - Added paragraph on updating translations

2004/05/10 Frans Pop
 - file creation

2005/07/28 Cristian Rigamonti
 - Added cp-untrans, fixed svn command and some typos

2017/04/12 Holger Wansing
 - Add hint on translations_po.txt

2018/06/03 Holger Wansing
 - Updating (most) content on git migration