THIS DOCUMENTATION FILE IS OBSOLETE. Please refer to installer/doc/i18n/i18n.*

This file is kpt here as a reference during the translation method transition.


Debian Installer notes for translation and internationalisation
---------------------------------------------------------------

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

Translation order
-----------------

When starting to translate debian-installer, you should first make
sure to get your language choice included, then translate the core
udebs, next translate the common udebs, and finally complete the rest
of the udebs.  The second stage installer should also be translated,
but it consists of normal deb-packages, and not udebs.

Suggested translation order:

-languagechooser
  (read debian-installer/packages/languagechooser/README.trans for details)
-countrychooser and iso-codes (see APPENDIX)
-core udebs and console-data (see APPENDIX)
-common udebs
-supported architectures udebs
-second stage
-future architectures udebs
-prospective packages (not yet included in d-i)

See the complete packages list at the end of this document.

How to get files to be translated
---------------------------------

- Go to the first reference page:  
  http://people.debian.org/~seppy/d-i/translation-status.html

- After reading informations there, start by the 1st stage translations by
  using the 1st stage resources and more particularly 
  http://people.debian.org/~seppy/d-i/1st-stage/xx.txt
  where xx is your language ISO code (or xx_YY for languages which have 
  flavours, such as pt_BR or zh_*).

  If the 1st stage pages are not shown for your language, this means that 
  no translation has been done yet for it. Ask for it to be activated
  on debian-boot@lists.debian.org.

- For files reported as missing, go and pick up the POT file at
  http://people.debian.org/~seppy/d-i/1st-stage/POT/
  
  Example: 
  "Missing file: debian-installer/packages/countrychooser/debian/po/ar.po"
 --> pick up http://people.debian.org/~seppy/d-i/1st-stage/POT/countrychooser.pot

  Rename this file to xx.po and start working on it

  Don't forget to add the po metadata (Language-Team, Last-Translator, etc.)
  so it can be used to keep track of who is in charge of the translations.

- For files reported as incomplete, get the file in
  http://people.debian.org/~seppy/d-i/files/xx and complete it. Don't
  forget to first contact the original translator (see the PO file header
  metadata, specifically 'Last-Translator'). You should refrain from
  translating/revising a file until you have talked with the original
  translator (he might be already working on it, or will do it soon). This
  avoids duplicate work being done.

  Rename this file to xx.po and start working on it

- Getting 2nd stage files
 * base-config: hosted on alioth. Uses subversion
 * tasksel    : also hosted on alioth. Uses subversion
 * aptitude   : hosted on alioth. Uses subversion
 * discover1  : hosted on alioth. Uses CVS
 * others     : use "apt-get source <package>" and report translations
                as normal bugs against the given packages 

If you need web access to the debian-installer SVN repository, you may use
the following URL:

http://svn.debian.org/wsvn/d-i

How to translate
----------------
This document is not intended to be a tutorial for gettext-related
stuff. Please look for documentation of PO editing software such as
KBabel, gtranslator, PoEdit, EMacs PO-mode, etc.

Please use a dedicated PO-editing tool until you become very familiar
with translation work.

Don't forget to properly fill up the PO files header, especially the
Last-Translator field. 

Fill the Project-Id-Version field with the package name, that will help you
in translation maintenance.

ALWAYS update the PO-Revision-Date field : it is now used for detecting
changed translations and triggering new packages releases.
(Many gettext editors do this automatically)

If a translation team exists for your language, WORK WITH THEM. First
check the debian-l10n-xxxxx mailing list where xxxxx is your language
name in english (e.g. debian-l10n-polish, debian-l10n-portuguese...).
The list of all available translation teams is available at
http://lists.debian.org/i18n.html
If in doubt, contact debian-i18n@lists.debian.org for assistance.

For general translation issues or for finding other translators for
your language, you may also use the debian-i18n mailing list (don't
post translations there, however).

How to remain consistent among packages
---------------------------------------

Some strings are identical in two or more packages. Please try to
translate them consistently.

The ranking page (http://people.debian.org/~seppy/d-i/1st-stage/rank.txt) will
show you the merged file status when your translation reaches 100%.

If you reach 100% and nothing show up there, then you're fine: all
identical strings have been translated.

If you see something like: (Merged PO file: 800t16f), then you got
inconsistencies.

##### OUTDATED INFORMATION
Look at the http://people.debian.org/~seppy/d-i/1st-stage/xx/xx.po and search
"fuzzy" markers there. They will show you which strings are inconsistently
translated. If you've properly used the Project-Id-Version, the package name
will also appear.
##### END OF OUTDATED INFORMATION


How to update existing translations
-----------------------------------

If you want to update a translation, please always contact the previous
translator in order to prevent duplication of work.  His mail address can
be found in the PO file.

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 (maybe your po-editor does include a spellchecker or a
translation helper like acheck).  Running
  msgfmt --check --statistics <YOUR LANGUAGE CODE>.po
(from the gettext package) before committing is also a good idea to
check that your file is valid and will be integrated without trouble.

You may also use the Debian aspell package.

You could also run podebconf-display-po (from po-debconf >= 0.8.3)
on your file:
  podebconf-display-po -fdialog debian/po/<YOUR LANGUAGE CODE>.po
to have a rough idea on how your translation will look like.  But
as cdebconf and debconf displays slightly differ, and as some scripts
do heavy use of text substitution, do not fully rely on this program.
Running debian-installer is the only solution to test translations.

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.

How to get your work included in debian-installer
-------------------------------------------------

Choose either of the methods below. SVN commits are encouraged. Create
an alioth account and ask in -boot for getting write access.

 SVN (Subversion) commit
 -----------------------

  1) Installing subversion
  ------------------------

  You need to install subversion on your system. For Debian unstable users,
  just do "apt-get install svn". Others may use backports from www.backports.org.
  Please add this entry to your /etc/apt/sources.list file:
    
    deb http://www.backports.org/debian stable subversion

  Or use Adam Conrad's backports:

    deb http://people.debian.org/~adconrad woody subversion

  2) Getting write access to the subversion repository
  ----------------------------------------------------

  If you are not a Debian Developper, you first need to create a guest account
  on http://alioth.debian.org/, than ask on debian-boot@lists.debian.org
  for somebody to add your guest account to the debian-installer project.
 
  3) Using the subversion to get and put back files
  -------------------------------------------------

  Once your account is allowed to write to the project, you can retreive the
  full project using this:
    svn co svn+ssh://<username>@svn.debian.org/svn/d-i/trunk debian-installer
  and commit files using something like this:
    cd debian-installer ; svn ci packages/languagechooser/languagelist.l10n

  Changelogs updates are not longer required because an automated tool
  is now used when releasing packages.

 File a bug
 ----------
You may send your translations as bug reports against the given
packages.  The packages names are the last part of the lines below.

Some packages have different names which are mentioned when needed.

For bug reports, please use the "d-i" and "l10n" tags.

 Send to debian-boot
 -------------------
You may also send the translations to the debian-boot mailing list.
Please use [INTL:xx] in Subjects where xx is your language code
(or xx_YY)

If you send a big bunch of translations altogether, please use the
debian-installer tree layout with just you xx.po files in place. This
will considerably help the commiters work.

PACKAGES LIST
-------------

 The following list is provided specially for new translation teams
 that have not started translating d-i yet. The udeb packages are shown
 by priority order. You should start first by translating those packages
 on the top of the list and then proceed downwards.

 Language choice 
 ---------------

 languagechooser

 Core udebs
 ----------

 countrychooser (plus iso-codes, see APPENDIX)
 cdebconf
 anna
 main-menu
 kbd-chooser (plus console-data, see APPENDIX)
 base-installer
 prebaseconfig
 debian-installer-utils

 Common udebs
 ------------

 ddetect
 cdrom-detect
 retriever/cdrom (cdrom-retriever)
 retriever/floppy (floppy-retriever)
 netcfg
 retriever/net (net-retriever)
 choose-mirror
 cdrom-checker
 iso-scan
 autopartkit
 partman/* (several partman-* packages)
 bugreporter-udeb
 partconf
 baseconfig-udeb
 lvmcfg
 partitioner
 nobootloader

 Architecture-dependent udebs
 ----------------------------

 1) Already supported architectures specific tools
 -------------------------------------------------

  arch/i386/grub-installer
  arch/i386/lilo-installer
  arch/sparc/silo-installer
  arch/mips/arcboot-installer
  arch/powerpc/yaboot-installer
  arch/alpha/aboot-installer
  arch/ia64/elilo-installer

 2) Will be supported soon/in the future
 ---------------------------------------

  arch/hppa/palo-installer
  arch/s390/netdevice
  arch/s390/dasd
  arch/mipsel/delo-installer

 Post-reboot installation stage
 ------------------------------

 (some of these packages do not only need debconf-type translation, but
 also program translation)

 Translations must be reported as wishlist bugs against these
 packages.  

 Base-config, discover1 and tasksel are exceptions because they are
 maintained by the debian-boot team, so other methods (CVS or SVN
 commits and -boot filing) may apply for it.  Note that they are
 separate projects on alioth (tasksel uses subversion).

No CVS/SVN repository:
 shadow (debconf+programs)
    apt-get source shadow
 console-data (debconf)
    apt-get source console-data
 console-common (debconf)
    apt-get source console-common
 exim4 (debconf)
    apt-get source exim4
 pcmcia-cs (debconf)
    apt-get source pcmcia-cs

 base-config (debconf) : 
    uses Subversion (no anonymous access possible currently)
 apt (programs)
    http://cvs.debian.org/apt/?cvsroot=deity
 aptitude (programs)
    uses Subversion (no anonymous access possible currently)
 discover1 (debconf)
    http://cvs.alioth.debian.org/cgi-bin/cvsweb.cgi/pkg-discover/
 dpkg (programs, including dselect):
    http://cvs.debian.org/dpkg/?cvsroot=dpkg
 popularity-contest (debconf)
    http://cvs.alioth.debian.org/cgi-bin/cvsweb.cgi/popcon/

 As 2nd stage install uses debconf, you also need to translate the
 interface widgets used by debconf. On mosts systems, the "dialog" interface
 is used, which require to translate widgets from the "newt" package.

 Status pages similar to 1ststage status pages exist for these "2nd-stage"
 package. You may find these statistics
 at:

 http://people.debian.org/~seppy/d-i/2nd-stage/

 Once you have finished with this, you might want to consider proceeding based
 on the Package priority. This means that 'important' and 'standard' packages
 should be translated first. Since 'optional' and 'extra' priorities include
 quite a number of packages it is sensible to start working with common-used
 packages. The data from the 'popularity contest' is useful to decide
 what is commonly used (however, notice it might be biased).

 List of packages with debconf templates that should be translated first
 (as of this writing):

 Important
 ---------
 debconf man-db console-common netbase ifupdown console-data adduser
 setserial bsdmainutils lilo

 Standard
 --------
 ssh wamerican openssl locales ibritish flex
 dictionaries-common iamerican

 Optional 
 --------
 (only some very commonly installed packages -first 30 in the list-
 are included here, ordered by popularity)
 
 apache xfree86 cupsys ntp fontconfig samba mozilla libpaper pango1.0
 cvs xscreensaver tetex-bin screen powermgmt-base mysql-dfsg
 gdm apt-listchanges discover libnet-perl openslp

APPENDIX
--------
 Countrychooser/iso-codes
 ------------------------

The countrychooser package uses country names and codes from the
iso-codes package. The country name translations are taken from this
package instead of just sitting in the countrychooser package.

For this reason, you need to translate the iso_3166.tab file in the
iso-codes package:

 - check whether an incomplete translation exists for your language:
   http://people.debian.org/~seppy/d-i/2nd-stage/files/XX/iso-codes_iso_3166_XX.po
 - If it doesn't exist, get the POT file at:
   http://people.debian.org/~seppy/d-i/2nd-stage/POT/iso-codes_iso_3166.pot
 - copy iso-codes_iso_3166.pot file to xx.po or use the existing xx.po 
   and translate country names there or complete the existing translation

CVS commit access may be requested to the iso-codes package maintainer.

The countrychooser package includes a mechanism for using an interim
translated file instead of iso-codes package translations. This allows
you to immediately test your translations. Just drop your file in
countrychooser/iso-codes.updates and commit it. However, when
the upstream iso-codes package includes your translation, please
REMOVE the interim file from debian-installer CVS.

Note: You can also retrieve a full copy from the iso-codes CVS using Alioth,
for more information see http://alioth.debian.org/scm/?group_id=1438


 kbd-chooser/console-data
 ------------------------

The kbd-chooser package uses keyboard names from the console-data package.
Thus, in order to get it completely translated, translators need to
translate console-data debconf templates.

First check on http://people.debian.org/~pmachard/intl/l10n/po-debconf/<code
(where <code> is your language code) if this file is already translated.

If it is not shown, then you may get the templates.pot file at:
http://people.debian.org/~pmachard/intl/l10n/po-debconf/pot#console-data

Pick up the templates.pot file, modify it and send it back with a
bugreport to the package "console-data, with the "l10n" and "patch"
tag, severity wishlist.

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

This guide is supposed to be be a first start for translators.  There
are probably errors, and some packages we forgot.  Please add them if
you discover such packages, and fix it if you find errors.

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

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

2004/07/18 Dennis Stampfer
  - In statistics is no STATUS.utf8.txt anymore. It is called <lang>.txt
  
2004/06/12 Christian Perrier
  - Change all references to D. Barbier pages to Dennis Stampfer or Pierre
    Machard pages
  - Change reference from CVS to SVN for base-config
  - Adapt instructions for ISO-3166 translations

2004/04/17 Jean Christophe Andre
  - Completed the SVN section (alioth account, SVN co & ci)

2004/03/28 Christian Perrier
  - Added reference to a SVN browse URL
  - Review of the packages to be translated list by
    Konstantinos Margaritis

2004/03/26 Christian Perrier
  - Reordered arch-dependent packages accordign to release status

2004/03/24 Javier Fernandez-Sanguino
  - Minor changes: typo fixes and some more verbosity in some places.
  - Point people to the debian-i18n mailing list.
  - Added pointer to iso-codes CVS access (took me a bit to find it)

2004/03/24 Christian Perrier
 - Major update:
   - debian-installer switched to subversion
   - reference page is now Dennis Stampfer's page which references
     other specialised status pages
   - general modifications for fitting the current context of d-i
     development

2004/03/10 Christian Perrier
 - Added mention of Seppy's status page for 2nd-stage

2004/02/16 Christian Perrier
 - Added instructions for keeping translations consistent among packages

2004/02/14 Christian Perrier
 - Corrected instructions for iso-codes

2004/01/30 Christian Perrier
 - give details about kbd-chooser/console-data
 - mention *core* udebs in translation order

2004/01/22 Christian Perrier
 - updated packages information (countrychooser and partman-* added)
 - mentioned aspell in tools
 - appendix added with iso-codes note
 - reformatted changelog
 - new title

2004/01/20 Javier Fernandez-Sanguino
 - added more packages and mentioned the 'by priority' and 'popular' criteria

2003/12/20 Christian Perrier
 - updated packages list and more information
 - rewamped the file

2003/11/08 Petter Reinholdtsen
 - file creation
