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

[Junio C Hamano]

Jean-Noël AVILA  writes:

>> ...  Doesn't that workflow apply equally well for the
>> documentation l10n?
>
> Theoretically, this workflow should apply to the documentation, so that a 
> version of the documentation can be cut at each release of git. I still have 
> to convince po4a not to update the *.pot and *.po files each time it is run, 
> while at the same time allow translators to produce the output file for 
> proofreading.

Ahh, OK, that does sound like a meaningful difference that may make
the workflow we use for in-code strings not applicable for the
documentation l10n project.  As I said already, I am not married to
the "gitman-l10n at Documentation/po" approach at all, and if the
layout you brought up to turn the containment relationship the other
way around works better, that is perfectly fine by me.

Thanks.

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

[Jean-Noël AVILA]

Le dimanche 26 mars 2017, 15:56:55 CEST Junio C Hamano a écrit :
> Jean-Noël AVILA  writes:
> > ... So I would
> > think the other way around: for those interested in translated the
> > documentation, some script would allow to checkout the git project inside
> > the gitman-l10n project (like a kind of library).
> > 
> > This would be mainly transparent for the git developers.
> 
> As long as the resulting layout would help all groups (1) developers
> who do not worry about documentation l10n (2) documentation i18n
> coordinator and transltors (3) those who build and ship binary
> packages, I personally am OK either way.
> 
> Having said that, I am not sure if I understand your "translators do
> not have a fixed version of git.git to work with and po4a cannot
> work well" as a real concern.  Wouldn't the l10n of documentation
> use a similar workflow as used for the translation of in-code
> strings we do in po/?  Namely, *.pot files are *NOT* updated by
> individual translators by picking up a random version of git.git and
> running xgettext.  Instead, i18n coordinator is the only person who
> runs xgettext to update *.pot for the upcoming release of Git being
> prepared, and then translators work off of that *.pot file.  Which
> means they do not have to worry about in-code strings that gets
> updated in the meantime; instead they work on a stable known
> snapshot of *.pot and wait for the next sync with i18n coordinator
> whose running of xgettext would update *.pot files with updated
> in-code strings.  Doesn't that workflow apply equally well for the
> documentation l10n?

Theoretically, this workflow should apply to the documentation, so that a 
version of the documentation can be cut at each release of git. I still have 
to convince po4a not to update the *.pot and *.po files each time it is run, 
while at the same time allow translators to produce the output file for 
proofreading.

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

[Junio C Hamano]

Jean-Noël AVILA  writes:

> ... So I would 
> think the other way around: for those interested in translated the 
> documentation, some script would allow to checkout the git project inside the 
> gitman-l10n project (like a kind of library).
>
> This would be mainly transparent for the git developers.

As long as the resulting layout would help all groups (1) developers
who do not worry about documentation l10n (2) documentation i18n
coordinator and transltors (3) those who build and ship binary
packages, I personally am OK either way.

Having said that, I am not sure if I understand your "translators do
not have a fixed version of git.git to work with and po4a cannot
work well" as a real concern.  Wouldn't the l10n of documentation
use a similar workflow as used for the translation of in-code
strings we do in po/?  Namely, *.pot files are *NOT* updated by
individual translators by picking up a random version of git.git and
running xgettext.  Instead, i18n coordinator is the only person who
runs xgettext to update *.pot for the upcoming release of Git being
prepared, and then translators work off of that *.pot file.  Which
means they do not have to worry about in-code strings that gets
updated in the meantime; instead they work on a stable known
snapshot of *.pot and wait for the next sync with i18n coordinator
whose running of xgettext would update *.pot files with updated
in-code strings.  Doesn't that workflow apply equally well for the
documentation l10n?

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

[Jean-Noël AVILA]

Le mercredi 22 mars 2017 11:02:09 CET, vous avez écrit :
> Jean-Noël Avila  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).

There's one big downside of  this splitting. The gitman-l10n project would not 
be autonomous without the specific cloning at the particular place in the git 
project. po4a needs the original asciidoc files to perform the transclusion of 
the translated content into the structure of the documents. The setup that you 
are proposing would rule out simple CI checks and would make it complicated 
for the translators to set up their working copy and check the resulting man 
pages.

As I see it, there's the need for the Documentation folder to be contained in 
both project (while remaining the property of the git project). So I would 
think the other way around: for those interested in translated the 
documentation, some script would allow to checkout the git project inside the 
gitman-l10n project (like a kind of library).

This would be mainly transparent for the git developers.

> 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.

Obviously, my proposition would not allow to evolve towards such a setup, but 
is it really needed anyway ?

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

[Junio C Hamano]

Ævar Arnfjörð Bjarmason  writes:

> On Mon, Mar 20, 2017 at 11:05 PM, Junio C Hamano  wrote:
>> But more importantly, aren't we essentially adding an equivalent of
>>
>> cd Documentation && cat git-*.txt
>>
>> to our codebase?
>>
>> Surely we cannot avoid having a copy of all messages that are to be
>> translated using msgid/msgstr based approach, and we already do so
>> for end-user-facing in-program strings, but it just feels a bit too
>> much having to carry a duplicate (and slightly a stale) copy of the
>> entire documentation set around.  For N languages, we'll have an
>> equivalent for N copies of the English text, in addition to the
>> translated documentation.
>
> As someone reading this thread from the sidelines you never elaborate
> on why this is a problem worth solving (other than "a bit too much")
> before everyone downthread jumped on trying to figure out how to solve
> this out-of tree somehow.

I do not particularly see the size as an issue that must be solved;
to me, it is "nice to solve".

But going back and finding this from Jean-Noel in an earlier
message:

... 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.

there may be other benefits we may be able to reap from such a
split.

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

[Ævar Arnfjörð Bjarmason]

On Mon, Mar 20, 2017 at 11:05 PM, Junio C Hamano  wrote:
> But more importantly, aren't we essentially adding an equivalent of
>
> cd Documentation && cat git-*.txt
>
> to our codebase?
>
> Surely we cannot avoid having a copy of all messages that are to be
> translated using msgid/msgstr based approach, and we already do so
> for end-user-facing in-program strings, but it just feels a bit too
> much having to carry a duplicate (and slightly a stale) copy of the
> entire documentation set around.  For N languages, we'll have an
> equivalent for N copies of the English text, in addition to the
> translated documentation.

As someone reading this thread from the sidelines you never elaborate
on why this is a problem worth solving (other than "a bit too much")
before everyone downthread jumped on trying to figure out how to solve
this out-of tree somehow.

So I thought I'd do a basic test of what it would mean to have this
in-tree. For every git version (every tag) since v1.0.0 I created a
parallel version of all our git-*.txt documentation, applied rot13 to
it, and dropped it in Documentation/po/rot13[1].

The end result after repack is:

$ du -sh git-*/.git
88M git-orig/.git
89M git-po4a/.git

Now of course this isn't equivalent to the *.po files we're talking
about, which'll also contain the original English version, so let's
say that's at least 2x the size, or just assume 2.5x for extra
overhead because the translation is longer / uses higher Unicode
characters or whatever.

That's still only an extra 2.5MB per-language for 10 years of history,
and an extra 3.75MB to the checkout.

Even if we had 10 languages with a 100% translation (a stretch, since
the core translations in po/ only have 12 languages) the .git
directory would grow from the current 88MB to 113MB, and the checkout
from 33MB to 70MB (for comparison the existing po/ directory is
5.3MB).

Maybe I've just become desensitized to bigger repos but that seems
like nothing to me. For comparison the linux.git repository has a
1.9GB .git and an 800MB checkout.

There's always going to be some inconvenience cost to pay when cloning
doesn't Just Work. Right now grabbing any tar'd up git.git from any
service it's on will give you something you can fully build. This'll
no longer be the case for the po4a assets.

If there's a good reason to break that kind of stuff fine, but the
growth in repo/checkout size noted above seems tiny to me compared to
disks & hardware these days.

1. rm -rfv Documentation/po; mkdir -p Documentation/po/rot13; for
version in $(git tag -l --contains v1.0.0 'v[0-9]*.[0-9]*.[0-9]'
--sort=version:refname); do for file in $(git ls-tree $version --
./Documentation/|awk '{print $4}'|grep '^Documentation/git-.*\.txt');
do git show $version:$file | perl -pe 'tr/A-Za-z/N-ZA-Mn-za-m/' >
${file/git-/po/rot13/git-}; done; git add Documentation/po && git
commit -m"Bump rot13 for $version"; done

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

[Michael J Gruber]

Stefan Beller venit, vidit, dixit 22.03.2017 19:59:
> On Wed, Mar 22, 2017 at 11:56 AM, Junio C Hamano  wrote:
>>> So we'd want to be able to say:
>>>   "get a tarball including all submodules except the superproject"
>>>   (This would produce the "optional language pack tarball")
>>
>> You do not need that.  Just go to the gitman-l10n project and grab a
>> tarball out of it.
> 
> Oh, I misunderstood your proposal.
> You said: We have *one* submodule for all languages, but I understood
> we'd have a submodule for *each* language.

In general, submodules would remove the major gripe that I have with the
current organization, that is carrying out-of-date translations in tree.
submodules make it clear that git.git refers to a specific revision of
the translations.

Now, since not even git.pot is insync with the l10n mark-up in the code
base, I'm afraid everything in po qualifies for being externalized.
Junio's current "pull l10n" would be substituted by updating the l10n
submodule version that git.git references.

In turn, the l10n coordinator may want to update submodule versions for
each language rather than pulling updates. That would allow the space
savings for the common uni- or bilingual developper that we are after.
Recursive submodules, yeah ;)

I'm unsure whether we should/can treat translations of git and the man
pages the same. I tend to say yes (being unsure about the consequences),
as I would hope that translators would be the same so that we keep
consistency across several tranlations in one language.

Michael

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

[Stefan Beller]

On Wed, Mar 22, 2017 at 11:56 AM, Junio C Hamano  wrote:
>> So we'd want to be able to say:
>>   "get a tarball including all submodules except the superproject"
>>   (This would produce the "optional language pack tarball")
>
> You do not need that.  Just go to the gitman-l10n project and grab a
> tarball out of it.

Oh, I misunderstood your proposal.
You said: We have *one* submodule for all languages, but I understood
we'd have a submodule for *each* language.

Thanks,
Stefan

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

[Junio C Hamano]

Stefan Beller  writes:

> I wonder if we could have partial functionality for these "clone and checkout"
> fake submodules, by having e.g. the .gitmodules file telling you the URL
> and path, but no recorded gitlink in the tree.

You can have such a comment in any file including .gitmodules but
would that even be a feature?  

A comment in the INSTALL file was what I had in mind, at least while
we are getting more familiar with the proposed two project structure
and before we commit to use the submodule mechanism to bind them
together.

> So we'd want to be able to say:
>   "get a tarball including all submodules except the superproject"
>   (This would produce the "optional language pack tarball")

You do not need that.  Just go to the gitman-l10n project and grab a
tarball out of it.

>   "get a tarball including the superproject and only one submodule"
>   (This would produce the "I can distribute this in locally as everyone
>   speaks the same language in the organisation" tarball)

We don't need that, either, even though some other project would.
"git archive --recurse-submodules" with properly implemented
pathspec support will solve that.

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

[Stefan Beller]

On Wed, Mar 22, 2017 at 11:02 AM, Junio C Hamano  wrote:
> Jean-Noël Avila  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 wonder if we could have partial functionality for these "clone and checkout"
fake submodules, by having e.g. the .gitmodules file telling you the URL
and path, but no recorded gitlink in the tree.

> 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.

Yay, submodules in git.git!  Another aspect besides the git-archive
command supporting submodules is the URL management.

The URL for the canonical git.git ought to not change in the near future,
but for proper support we'd need to have a mechanism to have the URL
default and configuration outside the tracked content. The configuration
is already outside the tracked content, but the default is not.

IIUC Jonathan Nieder has a proposal for that (though not in written
form, easy to point at), which consists of having an additional" .gitmodules"
file stored in another ref, e.g. "refs/superproject/master" (Maybe we do not
need it to be branch specific? then a refs/meta/superproject would do).

That branch can be changed
* over time
  This is useful when the canonical URL where to obtain the submodules
  changes. Also when going back in history and then getting the submodules
  would be covered with this as the new ref would not go back in history.
* across people
  Some people prefer the submodules to be fetched 

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

[Junio C Hamano]

Jean-Noël Avila  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").

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

[Jean-Noël Avila]

Le 20/03/2017 à 23:05, Junio C Hamano a écrit :
> Jean-Noel Avila  writes:
>
>> Signed-off-by: Jean-Noel Avila 
>> ---
>>  Documentation/po/documentation.fr.po | 1095 
>> ++
>>  Documentation/po/documentation.pot   |  787 
>>  2 files changed, 1882 insertions(+)
>>  create mode 100644 Documentation/po/documentation.fr.po
>>  create mode 100644 Documentation/po/documentation.pot
> This sounds more like
>
> Subject: l10n: add fr localization for git-add manual pages
>
> to me.  The actual part of this patch that adds "git-add" is the
> addition of Documentation/po/documentation.pot, and from that point
> of view, this patch may want to be further split into two.

The generation of the documentation.pot and the documentation.fr.po is
already "virtually" done because that's what the po4a.conf file
describes in the previous patch. The point is that the po4a.conf file
for a minimum viable run of make implies that at least a language and a
file be described.

For documentation.po.fr, what is indeed added is the effective
translation. So I guess we could probably split the series differently,
with a po4a.conf and empty files, then the translation.

>
> But more importantly, aren't we essentially adding an equivalent of
>
>   cd Documentation && cat git-*.txt
>
> to our codebase?
>
> Surely we cannot avoid having a copy of all messages that are to be
> translated using msgid/msgstr based approach, and we already do so
> for end-user-facing in-program strings, but it just feels a bit too
> much having to carry a duplicate (and slightly a stale) copy of the
> entire documentation set around.  For N languages, we'll have an
> equivalent for N copies of the English text, in addition to the
> translated documentation.

True. The documentation source roughly weight 2.3MB, so each full
translation would add up 5MB to the working copy. More , that would also
generate another source of traffic for updates and questions from
readers, which may not be of interest for most developpers.

>
> 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.

There's still the question whether the secondary repo would copy the
original asciidocs and from there would manage them with po4a and then
the translated asciidoc sources would be pushed back to the main repo,
or if the main repo would still run the po4a, and only the translated po
files would be pushed back.

The first way would decouple the workflow and the tools used for
translating from the main repo. If po4a turns out to be too adventurous
for asciidoc (latest version tested with all the man pages, no visible
problem), that would not impact the main repo which could still benefit
from the job already done.

The later way would allow the main repo to keep an eye on how the
translation are up to date and decide to include them or not.

In any case, there would be a copy of the original asciidoc files to the
secondary repo, to be able to provide the source reference in the po
files and give context to the translators.

My personal preference would still go to the integration of po4a in the
main repo, but it isn't ready yet.

Thanks,

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

[Junio C Hamano]

Jean-Noel Avila  writes:

> Signed-off-by: Jean-Noel Avila 
> ---
>  Documentation/po/documentation.fr.po | 1095 
> ++
>  Documentation/po/documentation.pot   |  787 
>  2 files changed, 1882 insertions(+)
>  create mode 100644 Documentation/po/documentation.fr.po
>  create mode 100644 Documentation/po/documentation.pot

This sounds more like

Subject: l10n: add fr localization for git-add manual pages

to me.  The actual part of this patch that adds "git-add" is the
addition of Documentation/po/documentation.pot, and from that point
of view, this patch may want to be further split into two.

But more importantly, aren't we essentially adding an equivalent of

cd Documentation && cat git-*.txt

to our codebase?

Surely we cannot avoid having a copy of all messages that are to be
translated using msgid/msgstr based approach, and we already do so
for end-user-facing in-program strings, but it just feels a bit too
much having to carry a duplicate (and slightly a stale) copy of the
entire documentation set around.  For N languages, we'll have an
equivalent for N copies of the English text, in addition to the
translated documentation.

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?

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

[Jean-Noel Avila]

Signed-off-by: Jean-Noel Avila 
---
 Documentation/po/documentation.fr.po | 1095 ++
 Documentation/po/documentation.pot   |  787 
 2 files changed, 1882 insertions(+)
 create mode 100644 Documentation/po/documentation.fr.po
 create mode 100644 Documentation/po/documentation.pot

diff --git a/Documentation/po/documentation.fr.po 
b/Documentation/po/documentation.fr.po
new file mode 100644
index 0..3017da0c9
--- /dev/null
+++ b/Documentation/po/documentation.fr.po
@@ -0,0 +1,1095 @@
+# French translations for Git Manual Pages.
+# Copyright (C) 2017 Jean-Noël Avila 
+# This file is distributed under the same license as the Git package.
+# Jean-Noël Avila , 2016.
+msgid ""
+msgstr ""
+"Project-Id-Version: git documentation\n"
+"POT-Creation-Date: 2017-03-03 21:18+0100\n"
+"PO-Revision-Date: 2017-03-15 21:42+0100\n"
+"Last-Translator: Jean-Noël Avila \n"
+"Language-Team: Jean-Noël Avila \n"
+"Language: fr\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. type: Title =
+#: git-add.txt:2
+#, no-wrap
+msgid "git-add(1)"
+msgstr "git-add(1)"
+
+#. type: Title -
+#: git-add.txt:5
+#, no-wrap
+msgid "NAME"
+msgstr "NOM"
+
+#
+#. type: Plain text
+#: git-add.txt:7
+msgid "git-add - Add file contents to the index"
+msgstr "git-add - Ajoute le contenu de fichiers à l'index"
+
+#. type: Title -
+#: git-add.txt:9
+#, no-wrap
+msgid "SYNOPSIS"
+msgstr "SYNOPSIS"
+
+#. type: Plain text
+#: git-add.txt:15
+#, no-wrap
+msgid ""
+"'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | 
-i] [--patch | -p]\n"
+"\t  [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]]\n"
+"\t  [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing]\n"
+"\t  [--chmod=(+|-)x] [--] [...]\n"
+msgstr ""
+"'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | 
-i] [--patch | -p]\n"
+"\t  [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]]\n"
+"\t  [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing]\n"
+"\t  [--chmod=(+|-)x] [--] [...]\n"
+
+#. type: Title -
+#: git-add.txt:17
+#, no-wrap
+msgid "DESCRIPTION"
+msgstr "DESCRIPTION"
+
+#
+#. type: Plain text
+#: git-add.txt:24
+msgid ""
+"This command updates the index using the current content found in the "
+"working tree, to prepare the content staged for the next commit.  It "
+"typically adds the current content of existing paths as a whole, but with "
+"some options it can also be used to add content with only part of the "
+"changes made to the working tree files applied, or remove paths that do not "
+"exist in the working tree anymore."
+msgstr ""
+"Cette commande met à jour l'index en utilisant le contenu actuel trouvé dans "
+"la copie de travail, pour préparer le contenu de la prochaine validation. "
+"Typiquement, elle ajoute intégralement le contenu actuel des chemins "
+"existant, mais peut aussi n'ajouter que certaines parties des modifications "
+"au moyen d'options ou soustraire certains chemins qui n'existent plus dans "
+"la copie de travail."
+
+#
+#. type: Plain text
+#: git-add.txt:30
+msgid ""
+"The \"index\" holds a snapshot of the content of the working tree, and it is "
+"this snapshot that is taken as the contents of the next commit.  Thus after "
+"making any changes to the working tree, and before running the commit "
+"command, you must use the `add` command to add any new or modified files to "
+"the index."
+msgstr ""
+"L'« index » contient un instantané du contenu de la copie de travail et "
+"c'est cet instantané qui sera utilisé comme contenu du prochain commit.  "
+"Ainsi, après avoir réalisé des modifications dans la copie de travail, et "
+"avant de lancer la commande commit, vous devez utiliser la commande `add` "
+"pour ajouter tout fichier nouveau ou modifié à l'index."
+
+#
+#. type: Plain text
+#: git-add.txt:35
+msgid ""
+"This command can be performed multiple times before a commit.  It only adds "
+"the content of the specified file(s) at the time the add command is run; if "
+"you want subsequent changes included in the next commit, then you must run "
+"`git add` again to add the new content to the index."
+msgstr ""
+"Cette commande peut être effectuée plusieurs fois avant la validation.  Elle "
+"n'ajoute que le contenu des fichiers spécifiés au moment où la commande "
+"`add` est lancée ; si vous souhaitez inclure des modifications postérieures "
+"à un `add` dans la prochaine validation, vous devez alors lancer `git add` à "
+"nouveau pour ajouter le nouveau contenu à l'index."
+
+#
+#. type: Plain text
+#: git-add.txt:38
+msgid ""
+"The `git status` command can be used to obtain a summary of which files have "
+"changes that are staged for the next commit."
+msgstr ""
+"La commande `git status` permet