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 was 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:

  /
  /doc/
  /doc/en/
  /doc/en/
  /doc/po4a/
  /doc/po4a/add_<ll>/
  /doc/po4a/po4a.cfg
  /doc/po4a/po/
  /doc/po4a/po/<pkg>.pot
  /doc/po4a/po/<ll>.po
  /doc/translated/<ll>/

Or, if you want to avoid a big POT and split it according to the packages,
documents, formats, or subjects, you can use the following architecture:

  /
  /doc/
  /doc/en/
  /doc/en/
  /doc/po4a/
  /doc/po4a/add_<ll>/
  /doc/po4a/<pkg1>/po4a.cfg
  /doc/po4a/<pkg1>/po/
  /doc/po4a/<pkg1>/po/<pkg1>.pot
  /doc/po4a/<pkg1>/po/<ll>.po
  /doc/translated/<ll>/


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, etc.). 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 <package>.cfg
	...

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

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


Using po4a in a distribution
----------------------------
(Debian packaging is taken as an example, you will have to adapt this to
your distribution)
To ensure that the source of a Debian package contains only up-to-date POT
and POs, you should run po4a in the 'clean' rule
of debian/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 <package>.cfg
	# Delete translated documentation
	rm -rf <...>/translated

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

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

# Introduction to Po4a

[![Build Status](https://travis-ci.org/mquinson/po4a.svg?branch=master)](https://travis-ci.org/mquinson/po4a)
[![First Timers Friendly](https://img.shields.io/badge/Beginners-Welcome-brightgreen.svg?style=flat-square)](http://www.firsttimersonly.com)

The goal of po4a (PO for anything) project is to ease translations (and
more interestingly, the maintenance of translations) using gettext
tools on areas where they were not expected like documentation.

In po4a each documentation format is handled by a module. Presently, we have a
module for the following formats:

  - asciidoc: AsciiDoc format.
  - dia: uncompressed Dia diagrams.
  - docbook: DocBook XML.
  - guide: Gentoo Linux's XML documentation format.
  - halibut: Simon Tatham's documentation production system.
  - ini: INI format.
  - kernelhelp: Help messages of each kernel compilation option.
  - latex: LaTeX format.
  - bibtex: bibtex format.
  - man: Good old manual page format.
  - pod: Perl Online Documentation format.
  - sgml: either DebianDoc or DocBook DTD.
  - texinfo: The info page format.
  - tex: generic TeX documents (see also latex).
  - text: simple text document.
  - wml: WML documents.
  - xhtml: XHTML documents.
  - xml: generic XML documents (see also docbook).
  - yaml: YAML documents.
  - rubydoc: RubyDoc (RD) documents.

# Installation

To install this module type the following:

```
   perl Build.PL
   ./Build
   ./Build install
```

# Contributing

po4a is particularly welcoming contributions from the community. If
you are new to Open Source, we'd love to mentor you for your first
contributions. Please see the
[CONTRIBUTING](https://github.com/mquinson/po4a/blob/master/CONTRIBUTING.md)
file to see how you could help.

# Use without installation

If you want to use a version without installing it (e.g. directly from
the git tree), use the PERLLIB environment variable as such:

```
   PERLLIB=~/git-checkouts/po4a/lib ~/git-checkouts/po4a/po4a-gettextize [usual args]
```

# Po4a dependencies

* Locale::gettext (v1.01)

  This module being itself internationalized, it needs the Locale::gettext
  library to translate its own messages.
  If it is not present, then po4a's messages won't be translated, but
  po4a will remain fully functional.

* Text::WrapI18N

  This module is used to format po4a's warnings and error messages.  It
  permits to wrap long error messages without splitting words.
  If it is not present, the formatting of messages will be different,
  but po4a will remain fully functional.

* Term::ReadKey

  This module is used to retrieve the terminal's line width.  It is not
  used if Text::WrapI18N is not available.
  If it is not present, the line width can be specified with the COLUMN
  environment variable.


## SGML module specific dependencies

* SGMLS (1.03ii)

  This is a set of Perl5 routines for processing the output from the onsgmls
  SGML parser.

* opensp (1.5.2) OpenJade group's SGML parsing tools

  This is the SGML parser we use.

* docbook: used in the tests. Without this package, the test fails with:
  ```
  onsgmls:<OSFD>0:1:59:W: cannot generate system identifier for public text "-//OASIS//DTD DocBook V4.1//EN"
  onsgmls:<OSFD>0:6:0:E: reference to entity "REFENTRY" for which no system identifier could be generated
  onsgmls:<OSFD>0:1:0: entity was defined here
  onsgmls:<OSFD>0:6:0:E: DTD did not contain element declaration for document type name
  po4a::sgml: Error while running onsgmls -p.  Please check if onsgmls and the DTD are installed.
  ```
  You don't need it if you don't want to run the tests.

## Text module specific dependencies

* Unicode::GCString

  This module is used to compute text width; it is needed by AsciiDoc to
  determine two line titles in encodings different from ASCII.
  https://github.com/hatukanezumi/Unicode-LineBreak


## YAML module specific dependencies

* YAML::Tiny

  This module is used to parse and serialize the YAML file.

# Project hosting

 - Webpage: https://po4a.org
 - Source code: https://github.com/mquinson/po4a
 - Bug tracker: https://github.com/mquinson/po4a/issues
 - Source of the web pages: https://github.com/mquinson/po4a-website

# Copyright and license

This program is free software; you may redistribute it and/or modify it
under the terms of GPL (see COPYING file).

Copyright © 2002-2O18 by SPI, inc.

Authors:
- Denis Barbier <barbier@linuxfr.org>
- Martin Quinson (mquinson#debian.org)