[Po4a-commits] "po4a README.maintainers, NONE, 1.1 MANIFEST, 1.28, 1.29"

[Nicolas FRANCOIS]

Update of /cvsroot/po4a/po4a
In directory haydn:/tmp/cvs-serv21955

Modified Files:
	MANIFEST 
Added Files:
	README.maintainers 
Log Message:
Add some notes for the maintainers.


--- NEW FILE: README.maintainers ---
This document provides some general rules to deploy a translation process
that will ease the work of maintainers (upstream and distribution
maintainers) and translators (or translation teams).


Translators usually fetch a POT (for a new translation) or retrieve the current
PO for their language, then they translate the untranslated strings and
update the translation of the strings marked as fuzzy.


Updating files
--------------

Translators need to know if a PO has to be updated:
 * they can verify the POs in the version control system or in the
   distributed archives/packages
 * they can be informed by the translation teams, which automatically
   check the status of the POs in various packages.
We want to avoid translators to be notified by a user reporting that
some strings are not translated even if the PO contains neither untranslated nor
fuzzy string.


Thus it is important to ensure that the POTs are up-to-date with the
original documents and that the POs contain the same strings as the
POTs.

 1. Upstream maintainers should update the POTs according to the original
    documents and update the POs according to these up-to-date POTs when they
    distribute an archive.

 2. If the switch to po4a has been done in a distribution, the source package
    should also contain up-to-date translation materials.

 3. If the documentation is patched by the distribution, the maintainer
    must not forget to update the POTs and POs.

It is important to ensure that the translation materials are updated
automatically.


Architecture
------------

A standardized architecture of the source tree will help the translation
teams when they try to detect the POTs that need to be updated.

Thus we recommend the following architecture:

  root
   |
   |-- doc, man, ...
   |    |
   |    |-- en
   |    |    |
   |    |    \-- original documents
   |    |
   |    |-- po4a
   |    |    |
   |    |    |-- po
   |    |    |    |
   |    |    |    |-- <package>.pot
   |    |    |    |-- <lang1>.po
   |    |    |    \-- ...
   |    |    |
   |    |    |-- add_<lang>
   |    |    |    |
   |    |    |    |-- <translator1>.add
   |    |    |    \-- ...
   |    |    |
   |    |    \-- <package>.cfg
   |    |
   |    |-- <lang1>
   |    |     |
   |    |     \-- generated translations
   |    |
   |    \-- ...

We recommend to use a configuration file for po4a that does not require
any option (put the options in the configuration file).
This permits to easily check if the POT is up-to-date with the
documentation and that the 


It is important to avoid a build failure if a generated
translation cannot be generated (the PO is too outdated, an addendum
cannot be applied, ...). You should therefore use wildcards or test if the file
was generated in the 'install' or 'dist' rules


Examples
========

Using po4a upstream
-------------------
When po4a is used upstream, we recommend to run po4a in the 'dist' rule.
This will update the POT and POs, and will generate the translated documents.
These translated documents can be distributed in the source archive if the
maintainer don't want to add a build dependency on po4a. You should then
add an autoconf check on po4a. It will allow you to update the documentation
if po4a is available on your system. If po4a is not available, documents
will be distributed without being synced with the original version, but the
build process won't fail.

It is important to distribute the POT and POs in the source archive.

A typical dist rule could then be:

dist:
	po4a --rm-backups <package>.cfg
	...

If automake is used, The following could also be used.

dist-hook:
	po4a --rm-backups <package>.cfg
	...


Using po4a in a distribution
----------------------------
(Debian packaging is taken as an example, you will have to adapt this to
your distribution)
In a Debian package, to ensure that the source package is released with
all the POT and POs are up-to-date, you should run po4a in the 'clean' rule
of debain/rules. The translated documents can be generated in the 'build'
(or 'build-indep') rule:

clean:
	# Update the POT and POs
	cd <...>/po4a && po4a --no-translations --rm-backups <package>.cfg

build:
	# Generate the translations
	cd <...>/po4a && po4a --rm-backups <package>.cfg

You should try to avoid distribution-specific build systems, to ensure the
portability of your software.

Index: MANIFEST
===================================================================
RCS file: /cvsroot/po4a/po4a/MANIFEST,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -d -r1.28 -r1.29
--- MANIFEST	27 Nov 2005 13:14:38 -0000	1.28
+++ MANIFEST	19 Feb 2006 00:24:13 -0000	1.29
@@ -4,6 +4,7 @@
 Build.PL			The rules to build this module (for ModuleBuild)
 Makefile
 README
+README.maintainers
 README.tests
 README.translators
 TODO