path: root/CONTRIBUTING.md

# Contributing to the manpages-l10n project

As described in the file README.md, the manpages-l10n project provides a
suitable infrastructure for man page translations. Here we describe the
workflow of fetching the upstream man pages, translating and finally publishing
the translations.


## Getting the upstream man pages

We support multiple distributions. To get the upstream man pages, we maintain
package lists for each distribution in
upstream/*distribution_name*/packages.txt. Usually we download all the listed
packages once or twice a month and unpack the man pages, using the script
upstream/update-distribution-manpages.sh. This script puts also the links
together so that they don't appear later as translatable files.

Note: Sometimes it is needed to keep the version number of a package in the
packages.txt files. In such cases, make sure that a package with that version
number really exists in the distribution repositories. If it doesn't exist,
nothing will be downloaded and the man pages of that package will vanish from
the upstream/ directory and finally vanish from the appropriate translation
templates. Currently this applies to some systemd* packages and sane-backends
in Opensuse (both Tumbleweed and Leap) and openssl in Archlinux. Improvements
of the script are welcome!

To get an overview which man pages are available from the supported packages,
but are still untranslated, the files
upstream/*distribution_name*/untranslated.txt will be created. This includes
only the man pages for which a template already exists, means: for which are
.po files available from other languages. Therefore the list is incomplete.
If you like to translate a certain man page, run the script
`../create-new-translation.sh` from the po/*your_language* directory. If it
succeeds, the appropriate man page already exists in at least one of the
upstream directories, and the .po file and the corresponding template
get created. If it fails, contact the manpages-l10n maintainer, giving some
hints where the man page can be found (package name).


## Creating the templates

After updating the contents of upstream/*distribution_name*/man*, we create the
templates. The script templates/update-all-templates.py updates the existing
\*.pot files based on the new upstream man pages. You can run the script
templates/generate-one-template.sh to generate a new or to update an existing
template.


## Updating the translations

Run the command `../update-translations.sh` to update the existing \*.po files
(ideally as `../update-translations.sh` from your language directory),
based on the previously changed templates. Later you can run
`../update-po.sh` to update a single .po file or
`../update-translations.sh` to update all existing .po files again
from the current templates and compendium files (see below for how to use the
compendium).


## Use consistent file headers

The header of a .po file usually looks as follows:

~~~
# German translation of manpages
# This file is distributed under the same license as the manpages-l10n package.
# Copyright © of this file:
# Mario Blättermann <mario.blaettermann@gmail.com>, 2015.
~~~

The first three lines will be added automatically if they don't exist. But from
the fourth line on, you must not write other lines than those with translator
names, mail adresses and the copyright year. Otherwise, some of our scripts
won't work properly. The script `../generate-manpage.sh`
needs this for generate the addendum. The script `create-authors-file.sh` also
reads translator names from there and would produce garbage if there are some
additional lines.

One exception: Comment lines starting with # FIXME will be ignored by the
scripts. But maybe it is more useful to put such FIXMEs directly above the
affected Gettext messages.

*NOTE:* Lokalize in version 23.08.1 generates header lines in the following shape:
~~~
# SPDX-FileCopyrightText: 2023 Mario Blättermann <mario.blaettermann@gmail.com>
~~~
This would lead to odd entries in the man page addendum and the file AUTHORS.md.
You need to fix this line manually. Obviously this can't be fixed in the
configuration of Lokalize. It has been filed as a bug:
https://bugs.kde.org/show_bug.cgi?id=475166

## Git workflow for reviewed .po files

After translating and reviewing a .po file (assuming you was using a copy of
that file and haven't applied your changes directly in your local Git checkout),
you should do the following steps:

* Run `git pull` to get the latest changes from other submitters.
* Verify your .po file with `msgfmt -vc`.
* Put your .po file at the right place in the Git hierarchy (don't commit it for
  the time being).
* Run `git status` and/or `git diff` to see what would be changed.
* Run the script `../update-po.sh` to merge your .po file
  with the latest template and the messages from compendium. Now you should take
  a look again at the .po file. If there's something wrong, fix it.
* Commit your .po file. The command should look as follows:

~~~
git commit -a -m "[de] Update chown.1.po"
~~~

* To make it easier to distinguish between the different languages, prepend
  [your_language_code] to the commit message.
* Run `git push`. Normally, all should be fine after typing your SSH password.
  But in some cases, another contributor has applied some changes in the
  meantime. Then Git refuses the commit. Just run `git pull` first. This applies
  the remote changes to your local repo and opens an editor where you can change
  the commit message. In most cases, it is unneeded to change anything, just
  close the editor (after saving the message, if needed).
  
  
## Using the helper scripts

Most of the helper scripts in po/ accept the `-h` switch to display a short help
message. Usually the scripts are intended to be called from your language
subdirectory, for example `cd po/de && ../format-po.sh`

### Creating new translations

The script `../create-new-translation.sh` creates a new .po
file. This presupposes that the original Groff or Mdoc file already exists in
upstream/man\* for at least one of our supported distributions. If not, try to
figure out the name of the distribution package which contains that man page and
contact [Mario Blättermann](mailto:mario.blaettermann@gmail.com) to get it into
manpages-l10n. Besides the .po file creation, the script creates - if needed - a
template and updates the compendium templates in templates/common/ and the compendium
files for your language in po/*your_language_code*/common. The script never affects
other languages than your own. Note: Remember to run `git add <file>`
after you have created and/or updated the new file before you make the `git push` command.


### Fill and use the compendium

After reviewing and committing a .po file, you can run
`../use-for-compendium.sh` to add the previously reviewed
Gettext messages to your compendium. Example:
`../use-for-compendium.sh man1/chown.1.po`. This makes sense if your .po file
contains some messages which also appear in other .po files. The script
recognizes messages with at least two occurences in our man page collection.
Note, you always have to submit the relative path, a simple file name isn't
sufficient.

After adding the file to the compendium, you can write the changes back to all
.po files with the command `../update-translations.sh`.

It might happen that you encounter a Gettext message which is ambiguous and
shouldn't be used for the compendium. In such cases, add the message to the file
templates/exclude.pot, as follows:

~~~
msgid "I<source>"
msgstr ""
~~~

Don't forget the empty `msgstr ""`, otherwise the update of the templates will
fail next time! After adding the message, first run the script
`templates/create-common-templates.sh`. This makes sure that the undesired
message really vanishes from the compendium. After that, you should also run the
script `../update-common.sh` (at least for your own language) to prevent other
scripts like `../create-new-translation.sh` or `../update-po.sh` from
using this Gettext message again. Although this procedure will be done for all
supported languages during the next update from upstream packages, in the
meantime it can happen that the mentioned scripts let the undesired messages
reappear in your .po files.

### Formatting \*.po files

The script `../format-po.sh` formats all .po files of your
language as `msgcat -w 80` would do; it wraps all lines at 80 characters.
Besides that, the unused Gettext messages at the end of the .po files will be
removed. Note, this script expects proper .po files; run
`msgfmt -vc *your_po_file*` to make sure the file is properly formatted in terms
of Gettext. Otherwise, the script can destroy a file completely and you need to
revert the changes.


### Generating translated man pages

A single translated man page can be created with the command
`../generate-manpage.sh *distribution_name* *your_po_file*`,
for example (from your .po directory) `../generate-manpage.sh archlinux man1/chown.1.po`.
This creates the man page in a subdirectory named »archlinux«. But you can also
generate all man pages from the whole .po collection using the command
`../generate-all-manpages.sh *distribution_name*`. All the
generated man pages get an addendum, which consists of the translators names and
mail addresses as found in the .po file headers, and a license declaration,
taken from the file po/*your_language_code*/license.add.

### Safety checks using git hooks

Git hooks are a way to run scripts before or after specific steps.
The `hooks` directory currently contains the `pre-commit` script, which will check the formatting of .po files about to be commited and abort the commit with an explanation in case some of these files are invalid.

To 'install' this hook, run from the root folder of the project:

~~~
ln -s ../../hooks/pre-commit .git/hooks/pre-commit
~~~

### Automatic composing of [DONE] messages using git hooks

Using the same git hook as above, it as also possible to enable the automatic composing of "[DONE]" messages to your l10n mailing list when you commit new translations.
To enable this feature, follow the same instruction as above to activate the git hook, then create a configuration file using the template provided:

~~~
cp hooks/pre-commit.conf.template hooks/pre-commit.conf
~~~

Once the file _pre-commit.conf_ exists, just fill it with the required info.

WARNING: this hook requires the curl package to be installed.

## Get involved in the package management

manpages-l10n has a multidistros purpose, thus would need to be released every
3 months. If you want to help for this administrative tasks, here is what you need to do.

First, you need to get the appropriate rights on the salsa repo.

Next:
* Search with grep for the current version number. You'll get some
occurrences in 'configure', 'configure.ac', 'CHANGES.md' etc.
(Don't bother with the version numbers in .po file headers)

~~~
grep '^AC_INIT' configure.ac | sed 's/.*\[\(.*\)\].*/\1/'
grep '^##' CHANGES.md | head -n1
~~~

* Replace the old version number with the new one in configure.ac
* Write an appropriate entry in CHANGES.md.
* Run 'autoreconf'
* Commit and push the changes.

* Create the appropriate tag:
** In the web interface, click on Tags In the tag overview, click on 'New tag'
and fill with the new release number, let empty the field "create from master"
Message: Release XXX

** In commandline:
~~~
git tag -a -m 'Release 4.2.0' v4.2.0
~~~

replace with the appropriate release number
"-a" for annotation, commonly used for releases
(https://git-scm.com/docs/git-tag)

"-m " is the message you mentioned

"v4.2.0" is the tag name

Once the pipline completed, do the release in the web interface under
Deploy → Releases. Use the 'Release 4.21.0' and add the changelog
into the form.

That's all. Users and downstream packagers can now download the
tarball from the known location.