Re: [PATCH v3 2/2] l10n: Add git-add.txt to localized man pages

[Junio C Hamano <gitster@pobox.com>]

Jean-Noël Avila <jn.avila@free.fr> writes:

>> I am wondering if Documentation/po part should be a separate
>> repository, with a dedicated i18n/l10n coordinator.  Would it make
>> it easier for (1) those who write code and doc without knowing other
>> languages, (2) those who update .pot and coordinate the l10n effort
>> for the documentation and (3) those who translate them if we keep
>> them in a single repository?
>
> This is one of the points raised in the first RFC mail. Splitting this
> part would help a lot manage the translations with their own workflow,
> would not clutter the main repo with files not really needed for
> packaging and would simplify dealing with the interaction with crowd
> translation websites which can directly push translation content to a
> git repo.

As I was in favor of splitting it out, I was trying to gauge what
the downside of doing so would be, especially for those who are
doing the translation work (it is obvious that it would help
developers who are not translators, as nothing will change for them
if we keep this new thing as a separate project).

We may still want to fill in the details (and by doing so we may
discover it is not as easy as I make it sound to be here), but a
rough outline of what I think we could do is:

 * What you added to Documentation/po/ in these two patches becomes
   a separate project (let's call it "gitman-l10n") and they will be
   at the root level of the project, i.e. documentation.pot and
   documentation.$LANG.po will sit at the top level of the working
   tree of that project, without Documentation/po/ prefix.  

   The idea is for some of us to have a checkout of "gitman-l10n"
   project inside Documentation/po of the checkout of git.git
   project and achieve a layout similar to what these two patches
   from you create, but keep that optional.

 * In git.git, teach Documentation/Makefile to enable "make
   doc-l10n" and "make install-l10n" targets in "Documentation/" if
   and only if Documentation/po/Makefile exists, and delegate these
   two targets to it, i.e. something like:

   (in Documentation/Makefile)
   ifeq ($(wildcard po/Makefile),po/Makefile)
   doc-l10n install-l10n::
	$(MAKE) -C po $@
   endif

   Certain Makefile macros Documentation/Makefile knows aboute
   (e.g. location to install, list of pages in the man1 section) may
   have to be exported down to Documentation/po/Makefile.

 * Some other Makefile targets to help i18n coordinator, e.g.
   updating Documentation/po/documentation.pot by using the latest
   set of Documentation/*.txt files, may also have to be added to
   Documentation/Makefile and conditionally enabled the same way
   (i.e. keying off of the presence of po/Makefile).

 * Those who work on the documentation translation and those who
   want to build and install localized documentation will have a
   checkout of the "gitman-l10n" project at "Documentation/po".
   This will _eventually_ be done by making "gitman-l10n" a
   submodule that git.git project uses, but it can start as a manual
   "clone and checkout" without making it a submodule.  Those who do
   not deal with localized manpages can just work with git.git
   proper without even knowing anything about the gitman-l10n
   project.

I'd prefer to start with the "optional gitman-l10n repository is
checked out at Documentation/po only by convention" approach, before
committing to bind it as a submodule.  Once we got comfortable with
cooperating between these two projects, we do want to bind them
using the submodule mechanism, but not before.

Once git.git starts binding the "gitman-l10n" project as its
submodule at "Documentation/po", we may want to start using "git
archive --recurse-submodules" when cutting a release tarball, when
that option becomes usable.

I'd prefer to start with the "main tarball" with "optional language
pack tarball" approach for releases, which is more flexible to the
end users (and less change to the workflow).  Once we gain more
experience, we may want to produce a single ball of wax tarball as
well (or "only a single one").