diff --git a/README b/README
index 7dfde158f61eaafc4d8d2a23bcad0e96b22ab71a..a337fcb9cdb7b248fc28d5dd20b12feb81ae3d80 100644
--- a/README
+++ b/README
@@ -1,17 +1,19 @@
GIT Documentation Translations
=====================
-This directory holds the translations for the documentation of
-Git. This document describes how you can contribute to the effort of
-enhancing the language coverage and maintaining the translation.
+This project holds the translations for the documentation of Git. This
+document describes how you can contribute to the effort of enhancing
+the language coverage and maintaining the translation.
-The two character language translation codes are defined by ISO_639-1, as
-stated in the gettext(1) full manual, appendix A.1, Usual Language Codes.
+The two character language translation codes are defined by ISO_639-1,
+as stated in the gettext(1) full manual, appendix A.1, Usual Language
+Codes.
Contributing to an existing translation
---------------------------------------
-As a contributor for a language XX, you should first check TEAMS file in
-this directory to see whether a dedicated team for your language XX
+
+As a contributor for a language XX, you should first check TEAMS file
+in this directory to see whether a dedicated team for your language XX
exists. Fork the dedicated repository and start to work if it exists.
Sometimes, contributors may find that the translations of their Git
@@ -21,19 +23,28 @@ Git distributions (such as from Ubuntu, etc.) have their own l10n
workflow. For this case, wrong translations should be reported and
fixed through their workflows.
-Creating a new language translation
------------------------------------
+Creating a new language translation (direct translation)
+--------------------------------------------------------
If you are the first contributor for the language XX, please fork this
repository, prepare and/or update the translated message file
-po/documentation.XX.po (described later), and ask the l10n coordinator to
-pull your work.
+po/documentation.XX.po (described later), and ask the l10n coordinator
+to pull your work.
If there are multiple contributors for the same language, please first
coordinate among yourselves and nominate the team leader for your
language, so that the l10n coordinator only needs to interact with one
person per language.
+
+Creating a new language translation (direct translation)
+--------------------------------------------------------
+
+Alternatively, you can start translating in your own language by
+registering to Weblate and starting a new language translation at
+
+https://hosted.weblate.org/projects/git-manpages/translations/
+
Translation Process Flow
------------------------
@@ -53,10 +64,10 @@ The overall data-flow looks like this:
* The original documentation files are updated by the development team
* L10n coordinator pulls from the source (1) and updates the local
documentation source files and the message template
- documentation.pot, and merges the changes into all
- documentation.XX.po files
+ po/documentation.pot, and merges the changes into all
+ po/documentation.XX.po files
* Language team pulls from L10n coordinator (2)
- * Language team updates the message file documentation.XX.po
+ * Language team updates the message file documentation.XX.po (2)
* L10n coordinator pulls from Language team (3)
* L10n coordinator asks the result to be integrated (4).
@@ -68,11 +79,11 @@ Maintaining the documentation.pot file
The documentation.pot file contains a message catalog extracted from
Git's documentation sources. The l10n coordinator maintains it by
adding new translations or update existing ones with po4a(1). In
-order to update the document sources to extract the messages from, the l10n
-coordinator is expected to pull from the main git repository at
+order to update the document sources to extract the messages from, the
+l10n coordinator is expected to pull from the main git repository at
strategic point in history (e.g. when a major release and release
-candidates are tagged), and then run "make update-sources" at the top-level
-directory.
+candidates are tagged), and then run "make update-sources" at the
+top-level directory.
Language contributors use this file to prepare translations for their
language, but they are not expected to modify it.
@@ -88,10 +99,10 @@ documentation.XX.po yet, you add a translation for the first time by
* editing the file create_po4a_conf.sh and adding your language code
to the first line, e.g. "[po4a_langs] fr XX", where XX is the
- locale, such as "de", "is", "pt_BR", "zh_CN", etc. * running in
- the Documentation/ directory
+ locale, such as "de", "is", "pt_BR", "zh_CN", etc.
+ * running in the root directory of the project
- make man
+ make all
A file po/documentation.XX.po was created, corresponding
to the newly created translation.
@@ -128,14 +139,9 @@ documentation.XX.po file to improve the translation, just edit the
file.
If there's an existing documentation.XX.po file for your language, but
-the repository of the l10n coordinator has newer
-documentation.pot file, you would need to first pull
-from the l10n coordinator (see the beginning of this document for its
-URL), and then update the existing translation by running:
-
- msgmerge --add-location --backup=off -U documentation.XX.po documentation.pot
-
-where documentation.XX.po is the file you want to update.
+the repository of the l10n coordinator has newer documentation.pot
+file, chances are the new documentation.XX.po already includes the
+changes of the new version.
Once you are done testing the translation (see below), commit the result
and ask the l10n coordinator to pull from you.
@@ -146,17 +152,24 @@ Testing your changes
(This is done by the language teams, after creating or updating
documentation.XX.po file).
+
+Before being able to compile the documents, you need to have a working
+compilation toolchain which you can get by running:
+
+ $ sh ci/install_po4a.sh # install a patched version of po4a
+ $ bundle install # install asciidoctor
+
Before you submit your changes do:
- $ make install
+ $ make all
On systems with GNU gettext (i.e. not Solaris) and po4a this will try
to merge translations with the source asciidoc files into translated
-asciidoc files, compile them to manpages and install the resulting
-files in your system.
+asciidoc files and compile them to manpages.
-Then you can check the translated manpage, for instance for `git add`:
+Then you can check the translated manpages, for instance for `git add`
+in French:
- $ man git add
+ $ man -l fr/git-add.1
and verify how your translated manpage is rendered.