[l10n] date: Note for translators not included in .po files

[l10n] date: Note for translators not included in .po files

[Brian Gesiak]

A note for translators in date.c is not included in git.pot.
Namely, the following note from date.c:147 is not included
(https://github.com/git/git/blob/v1.9.2/date.c#L147):

/* TRANSLATORS: "%s" is "<n> years" */

This is a very useful note for translators (in fact, I think
the zh_CN translation for date.c:149 might be a little off
because this note was not included. My Mandarin is rusty,
but I believe "<n> years, <m> months ago" should be expressed
without a comma).

According to po/README, the l10n coordinator is responsible
for updating the git.pot file. Would it be possible to update it based
on v1.9.2 and include the above comment?

By the way, I am trying to organize contributors to produce a Japanese
localization for Core Git. Currently we have plenty of interest but
only two contributors. If you or anyone you know would like to contribute
please visit the repository here: https://github.com/modocache/git-po-ja

Thanks!

- Brian Gesiak

Re: [l10n] date: Note for translators not included in .po files

[Jiang Xin]

2014-04-17 6:51 GMT+08:00 Brian Gesiak <modocache@gmail.com>:
> A note for translators in date.c is not included in git.pot.
> Namely, the following note from date.c:147 is not included
> (https://github.com/git/git/blob/v1.9.2/date.c#L147):
>
> /* TRANSLATORS: "%s" is "<n> years" */
>

Comments for translators will be extracted to pot file automatically,
when run xgettext with "--add-comments" option.

       -c, --add-comments
              place all comment blocks preceding keyword lines in output file

For example, the comments in the following code blocks will
be extracted.

       /* TRANSLATORS: "will be extracted." */
       strbuf_addf(&sb, Q_("%lu year", "%lu years", years), years);

        strbuf_addf(&sb,
               /* TRANSLATORS: "will be extracted." */
               Q_("%lu year", "%lu years", years), years);

But if the comment is not right before the l10n markers, such
comments will not be extracted. E.g.

        /* TRANSLATORS: "WARNING: will NOT be extracted." */
        strbuf_addf(&sb,
                Q_("%lu year", "%lu years", years), years);

        /* TRANSLATORS: "WARNING: will NOT be extracted." */
        strbuf_addf(&sb, Q_(
                "%lu year", "%lu years", years), years);


I will scan all the codes and make a fix.

> This is a very useful note for translators (in fact, I think
> the zh_CN translation for date.c:149 might be a little off
> because this note was not included. My Mandarin is rusty,
> but I believe "<n> years, <m> months ago" should be expressed
> without a comma).
>
> According to po/README, the l10n coordinator is responsible
> for updating the git.pot file. Would it be possible to update it based
> on v1.9.2 and include the above comment?
>

I could generate a new git.pot for "maint" branch, but fixes for codes
may only contribute to "master" branch.


-- 
Jiang Xin

[PATCH 0/3] extract proper comments for l10n translators

[Jiang Xin]

When generate git.pot, many irrelevant comments are extracted as references
for translators, but one useful comment is lost.  This series patches will
fix this issue.

Jiang Xin (3):
  i18n: Fixes uncatchable comments for translators
  i18n: Only extract comments marked by special tag
  i18n: Remove obsolete comments for translators

 Makefile          | 2 +-
 builtin/init-db.c | 8 +++-----
 date.c            | 2 +-
 diff.c            | 8 --------
 4 files changed, 5 insertions(+), 15 deletions(-)

-- 
1.9.2.461.g942803f

[PATCH 1/3] i18n: Fixes uncatchable comments for translators

[Jiang Xin]

Comment for l10n translators can not be extracted by xgettext if it is
not right above the l10n tag.  Moving the comment right before the l10n
tag will fix this issue.

Reported-by: Brian Gesiak <modocache@gmail.com>
Signed-off-by: Jiang Xin <worldhello.net@gmail.com>
---
 date.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/date.c b/date.c
index e1a2cee..782de95 100644
--- a/date.c
+++ b/date.c
@@ -144,8 +144,8 @@ void show_date_relative(unsigned long time, int tz,
 		if (months) {
 			struct strbuf sb = STRBUF_INIT;
 			strbuf_addf(&sb, Q_("%lu year", "%lu years", years), years);
-			/* TRANSLATORS: "%s" is "<n> years" */
 			strbuf_addf(timebuf,
+				 /* TRANSLATORS: "%s" is "<n> years" */
 				 Q_("%s, %lu month ago", "%s, %lu months ago", months),
 				 sb.buf, months);
 			strbuf_release(&sb);
-- 
1.9.2.461.g942803f

[PATCH 2/3] i18n: Only extract comments marked by special tag

[Jiang Xin]

When extract l10n messages, we use "--add-comments" option to keep
comments right above the l10n messages for references.  But sometimes
irrelevant comments are also extracted.  For example in the following
code block, the comment in line 2 will be extracted as comment for the
l10n message in line 3, but obviously it's wrong.

        { OPTION_CALLBACK, 0, "ignore-removal", &addremove_explicit,
          NULL /* takes no arguments */,
          N_("ignore paths removed in the working tree (same as
          --no-all)"),
          PARSE_OPT_NOARG, ignore_removal_cb },

Since almost all comments for l10n translators are marked with the same
prefix (tag): "TRANSLATORS:", it's safe to only extract comments with
this special tag.  I.E. it's better to call xgettext as:

        xgettext --add-comments=TRANSLATORS: ...

Also tweaks the multi-line comment in "init-db.c", to make it start with
the proper tag, not "* TRANSLATORS:" (which has a star before the tag).

Signed-off-by: Jiang Xin <worldhello.net@gmail.com>
---
 Makefile          | 2 +-
 builtin/init-db.c | 8 +++-----
 2 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/Makefile b/Makefile
index 2128ce3..a53f3a8 100644
--- a/Makefile
+++ b/Makefile
@@ -2102,7 +2102,7 @@ pdf:
 
 XGETTEXT_FLAGS = \
 	--force-po \
-	--add-comments \
+	--add-comments=TRANSLATORS: \
 	--msgid-bugs-address="Git Mailing List <git@vger.kernel.org>" \
 	--from-code=UTF-8
 XGETTEXT_FLAGS_C = $(XGETTEXT_FLAGS) --language=C \
diff --git a/builtin/init-db.c b/builtin/init-db.c
index c7c76bb..56f85e2 100644
--- a/builtin/init-db.c
+++ b/builtin/init-db.c
@@ -412,11 +412,9 @@ int init_db(const char *template_dir, unsigned int flags)
 	if (!(flags & INIT_DB_QUIET)) {
 		int len = strlen(git_dir);
 
-		/*
-		 * TRANSLATORS: The first '%s' is either "Reinitialized
-		 * existing" or "Initialized empty", the second " shared" or
-		 * "", and the last '%s%s' is the verbatim directory name.
-		 */
+		/* TRANSLATORS: The first '%s' is either "Reinitialized
+		   existing" or "Initialized empty", the second " shared" or
+		   "", and the last '%s%s' is the verbatim directory name. */
 		printf(_("%s%s Git repository in %s%s\n"),
 		       reinit ? _("Reinitialized existing") : _("Initialized empty"),
 		       shared_repository ? _(" shared") : "",
-- 
1.9.2.461.g942803f

[PATCH 3/3] i18n: Remove obsolete comments for translators

[Jiang Xin]

Since we do not translate diffstat any more, remove the obsolete comments.

Signed-off-by: Jiang Xin <worldhello.net@gmail.com>
---
 diff.c | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/diff.c b/diff.c
index 539997f..54d5308 100644
--- a/diff.c
+++ b/diff.c
@@ -1461,20 +1461,12 @@ int print_stat_summary(FILE *fp, int files, int insertions, int deletions)
 	 * but nothing about added/removed lines? Is this a bug in Git?").
 	 */
 	if (insertions || deletions == 0) {
-		/*
-		 * TRANSLATORS: "+" in (+) is a line addition marker;
-		 * do not translate it.
-		 */
 		strbuf_addf(&sb,
 			    (insertions == 1) ? ", %d insertion(+)" : ", %d insertions(+)",
 			    insertions);
 	}
 
 	if (deletions || insertions == 0) {
-		/*
-		 * TRANSLATORS: "-" in (-) is a line removal marker;
-		 * do not translate it.
-		 */
 		strbuf_addf(&sb,
 			    (deletions == 1) ? ", %d deletion(-)" : ", %d deletions(-)",
 			    deletions);
-- 
1.9.2.461.g942803f

Re: [PATCH 0/3] extract proper comments for l10n translators

[Jiang Xin]

2014-04-17 13:37 GMT+08:00 Jiang Xin <worldhello.net@gmail.com>:
> When generate git.pot, many irrelevant comments are extracted as references
> for translators, but one useful comment is lost.  This series patches will
> fix this issue.

Brief changes of po/git.pot after applied these patches:

diff --git a/po/git.pot b/po/git.pot
index f70b46b..9e474f3 100644
--- a/po/git.pot
+++ b/po/git.pot
@@ -23,10 +23,6 @@ msgstr ""
 msgid "hint: %.*s\n"
 msgstr ""

-#.
-#. * Message used both when 'git commit' fails and when
-#. * other commands doing a merge do.
-#.
 #: advice.c:85
 msgid ""
 "Fix them up in the work tree,\n"
@@ -399,6 +395,7 @@ msgid_plural "%lu years"
 msgstr[0] ""
 msgstr[1] ""

+#. TRANSLATORS: "%s" is "<n> years"
 #: date.c:149
 #, c-format
 msgid "%s, %lu month ago"
@@ -582,8 +579,6 @@ msgstr ""
 msgid "Removing %s to make room for subdirectory\n"
 msgstr ""

-#. something else exists
-#. .. but not some other error (who really cares what?)
 #: merge-recursive.c:700 merge-recursive.c:721
 msgid ": perhaps a D/F conflict?"
 msgstr ""
@@ -899,11 +894,6 @@ msgstr ""
 msgid "Pathspec '%s' is in submodule '%.*s'"
 msgstr ""

-#.
-#. * We may want to substitute "this command" with a command
-#. * name. E.g. when add--interactive dies when running
-#. * "checkout -p"
-#.
 #: pathspec.c:353
 #, c-format
 msgid "%s: pathspec magic not supported by this command: %s"
@@ -953,11 +943,6 @@ msgstr ""
 msgid "%s tracks both %s and %s"
 msgstr ""

-#.
-#. * This last possibility doesn't occur because
-#. * FETCH_HEAD_IGNORE entries always appear at
-#. * the end of the list.
-#.
 #: remote.c:774
 msgid "Internal error"
 msgstr ""
@@ -1306,13 +1291,11 @@ msgstr ""
 msgid "Could not find section in .gitmodules where path=%s"
 msgstr ""

-#. Maybe the user already did that, don't error out here
 #: submodule.c:76
 #, c-format
 msgid "Could not update .gitmodules entry %s"
 msgstr ""

-#. Maybe the user already did that, don't error out here
 #: submodule.c:109
 #, c-format
 msgid "Could not remove .gitmodules entry for %s"
@@ -1884,7 +1867,6 @@ msgstr ""
 msgid "add changes from all tracked and untracked files"
 msgstr ""

-#. takes no arguments
 #: builtin/add.c:260
 msgid "ignore paths removed in the working tree (same as --no-all)"
 msgstr ""
@@ -2044,7 +2026,6 @@ msgstr ""
 msgid "corrupt binary patch at line %d: %.*s"
 msgstr ""

-#. there has to be one hunk (forward hunk)
 #: builtin/apply.c:1900
 #, c-format
 msgid "unrecognized binary patch at line %d"
@@ -2232,7 +2213,6 @@ msgstr ""
 msgid "internal error"
 msgstr ""

-#. Say this even without --verbose
 #: builtin/apply.c:4043
 #, c-format
 msgid "Applying patch %%s with %d reject..."
@@ -3232,7 +3212,6 @@ msgstr ""
 msgid " ... and %d more.\n"
 msgstr ""

-#. The singular version
 #: builtin/checkout.c:711
 #, c-format
 msgid ""
@@ -3280,7 +3259,6 @@ msgstr ""
 msgid "invalid reference: %s"
 msgstr ""

-#. case (1): want a tree
 #: builtin/checkout.c:1002
 #, c-format
 msgid "reference is not a tree: %s"
@@ -4276,7 +4254,6 @@ msgstr ""
 msgid "GPG sign commit"
 msgstr ""

-#. end commit message options
 #: builtin/commit.c:1508
 msgid "Commit contents options"
 msgstr ""
@@ -5140,7 +5117,6 @@ msgstr ""
 msgid "See \"git help gc\" for manual housekeeping.\n"
 msgstr ""

-#. be quiet on --auto
 #: builtin/gc.c:336
 #, c-format
 msgid ""
@@ -5894,12 +5870,10 @@ msgstr ""
 msgid "unable to move %s to %s"
 msgstr ""

-#.
-#. * TRANSLATORS: The first '%s' is either "Reinitialized
-#. * existing" or "Initialized empty", the second " shared" or
-#. * "", and the last '%s%s' is the verbatim directory name.
-#.
-#: builtin/init-db.c:420
+#. TRANSLATORS: The first '%s' is either "Reinitialized
+#. existing" or "Initialized empty", the second " shared" or
+#. "", and the last '%s%s' is the verbatim directory name.
+#: builtin/init-db.c:418
 #, c-format
 msgid "%s%s Git repository in %s%s\n"
 msgstr ""
@@ -6627,7 +6601,6 @@ msgstr ""
 msgid "Commit %s has a bad GPG signature allegedly by %s."
 msgstr ""

-#. 'N'
 #: builtin/merge.c:1279
 #, c-format
 msgid "Commit %s does not have a GPG signature."
@@ -9593,8 +9566,6 @@ msgstr ""
 msgid "'git bisect bad' can take only one argument."
 msgstr ""

-#. have bad but not good.  we could bisect although
-#. this is less optimum.
 #: git-bisect.sh:273
 msgid "Warning: bisecting only with a bad commit."
 msgstr ""
@@ -9690,10 +9661,6 @@ msgstr ""
 msgid "updating an unborn branch with changes added to the index"
 msgstr ""

-#. The fetch involved updating the current branch.
-#. The working tree and the index file is still based on the
-#. $orig_head commit, but we are merging into $curr_head.
-#. First update the working tree to match $curr_head.
 #: git-pull.sh:271
 #, sh-format
 msgid ""
@@ -9835,7 +9802,6 @@ msgstr ""
 msgid "Changes from $mb to $onto:"
 msgstr ""

-#. Detach HEAD and reset the tree
 #: git-rebase.sh:609
 msgid "First, rewinding head to replay your work on top of it..."
 msgstr ""
@@ -10218,7 +10184,6 @@ msgstr ""
 msgid "The --cached option cannot be used with the --files option"
 msgstr ""

-#. unexpected type
 #: git-submodule.sh:1097
 #, sh-format
 msgid "unexpected mode $mod_dst"


-- 
Jiang Xin

Re: [l10n] date: Note for translators not included in .po files

[Jiang Xin]

2014-04-17 6:51 GMT+08:00 Brian Gesiak <modocache@gmail.com>:
> According to po/README, the l10n coordinator is responsible
> for updating the git.pot file. Would it be possible to update it based
> on v1.9.2 and include the above comment?
>

I have pushed a polished "git.pot" to the maint branch of git-l10n/git-po.
It's based on Git v1.9.2, and you can get it from:

    https://github.com/git-l10n/git-po/blob/maint/po/git.pot

But if you want to translate for the upcoming Git v2.0.0, you can use
"git.pot" in the "pu" branch as a template. See:

    https://github.com/git-l10n/git-po/blob/pu/po/git.pot

> By the way, I am trying to organize contributors to produce a Japanese
> localization for Core Git. Currently we have plenty of interest but
> only two contributors. If you or anyone you know would like to contribute
> please visit the repository here: https://github.com/modocache/git-po-ja
>
> Thanks!
>
> - Brian Gesiak
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html



-- 
蒋鑫

北京群英汇信息技术有限公司
邮件: worldhello.net@gmail.com
网址: http://www.ossxp.com/
博客: http://www.worldhello.net/
微博: http://weibo.com/gotgit/
电话: 18601196889

Re: [PATCH 2/3] i18n: Only extract comments marked by special tag

[Junio C Hamano]

Jiang Xin <worldhello.net@gmail.com> writes:

> When extract l10n messages, we use "--add-comments" option to keep
> comments right above the l10n messages for references.  But sometimes
> irrelevant comments are also extracted.  For example in the following
> code block, the comment in line 2 will be extracted as comment for the
> l10n message in line 3, but obviously it's wrong.
>
>         { OPTION_CALLBACK, 0, "ignore-removal", &addremove_explicit,
>           NULL /* takes no arguments */,
>           N_("ignore paths removed in the working tree (same as
>           --no-all)"),
>           PARSE_OPT_NOARG, ignore_removal_cb },
>
> Since almost all comments for l10n translators are marked with the same
> prefix (tag): "TRANSLATORS:", it's safe to only extract comments with
> this special tag.  I.E. it's better to call xgettext as:
>
>         xgettext --add-comments=TRANSLATORS: ...
>
> Also tweaks the multi-line comment in "init-db.c", to make it start with
> the proper tag, not "* TRANSLATORS:" (which has a star before the tag).

Hmph.

I am not very happy with this change, as it would force us to
special case "Translators" comment to follow a non-standard
multi-line comment formatting convention.  Is there a way to tell
xgettext to accept both of these forms?

        /* TRANSLATORS: this is a short comment to help you */
        _("foo bar");

        /*
         * TRANSLATORS: this comment is to help you, but it is
         * a lot longer to fit on just a single line.
         */
        _("bar baz");


>
> Signed-off-by: Jiang Xin <worldhello.net@gmail.com>
> ---
>  Makefile          | 2 +-
>  builtin/init-db.c | 8 +++-----
>  2 files changed, 4 insertions(+), 6 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index 2128ce3..a53f3a8 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -2102,7 +2102,7 @@ pdf:
>  
>  XGETTEXT_FLAGS = \
>  	--force-po \
> -	--add-comments \
> +	--add-comments=TRANSLATORS: \
>  	--msgid-bugs-address="Git Mailing List <git@vger.kernel.org>" \
>  	--from-code=UTF-8
>  XGETTEXT_FLAGS_C = $(XGETTEXT_FLAGS) --language=C \
> diff --git a/builtin/init-db.c b/builtin/init-db.c
> index c7c76bb..56f85e2 100644
> --- a/builtin/init-db.c
> +++ b/builtin/init-db.c
> @@ -412,11 +412,9 @@ int init_db(const char *template_dir, unsigned int flags)
>  	if (!(flags & INIT_DB_QUIET)) {
>  		int len = strlen(git_dir);
>  
> -		/*
> -		 * TRANSLATORS: The first '%s' is either "Reinitialized
> -		 * existing" or "Initialized empty", the second " shared" or
> -		 * "", and the last '%s%s' is the verbatim directory name.
> -		 */
> +		/* TRANSLATORS: The first '%s' is either "Reinitialized
> +		   existing" or "Initialized empty", the second " shared" or
> +		   "", and the last '%s%s' is the verbatim directory name. */
>  		printf(_("%s%s Git repository in %s%s\n"),
>  		       reinit ? _("Reinitialized existing") : _("Initialized empty"),
>  		       shared_repository ? _(" shared") : "",

Re: [PATCH 0/3] extract proper comments for l10n translators

[Junio C Hamano]

Jiang Xin <worldhello.net@gmail.com> writes:

> 2014-04-17 13:37 GMT+08:00 Jiang Xin <worldhello.net@gmail.com>:
>> When generate git.pot, many irrelevant comments are extracted as references
>> for translators, but one useful comment is lost.  This series patches will
>> fix this issue.
>
> Brief changes of po/git.pot after applied these patches:

This is a very good way to make sure that 2/3 does not lose helpful
comments.

Thanks, but my complaint regarding the multi-line comment format
still stands.

>
> diff --git a/po/git.pot b/po/git.pot
> index f70b46b..9e474f3 100644
> --- a/po/git.pot
> +++ b/po/git.pot
> @@ -23,10 +23,6 @@ msgstr ""
>  msgid "hint: %.*s\n"
>  msgstr ""
>
> -#.
> -#. * Message used both when 'git commit' fails and when
> -#. * other commands doing a merge do.
> -#.
>  #: advice.c:85
>  msgid ""
>  "Fix them up in the work tree,\n"
> @@ -399,6 +395,7 @@ msgid_plural "%lu years"
>  msgstr[0] ""
>  msgstr[1] ""
>
> +#. TRANSLATORS: "%s" is "<n> years"
>  #: date.c:149
>  #, c-format
>  msgid "%s, %lu month ago"
> @@ -582,8 +579,6 @@ msgstr ""
>  msgid "Removing %s to make room for subdirectory\n"
>  msgstr ""
>
> -#. something else exists
> -#. .. but not some other error (who really cares what?)
>  #: merge-recursive.c:700 merge-recursive.c:721
>  msgid ": perhaps a D/F conflict?"
>  msgstr ""
> @@ -899,11 +894,6 @@ msgstr ""
>  msgid "Pathspec '%s' is in submodule '%.*s'"
>  msgstr ""
>
> -#.
> -#. * We may want to substitute "this command" with a command
> -#. * name. E.g. when add--interactive dies when running
> -#. * "checkout -p"
> -#.
>  #: pathspec.c:353
>  #, c-format
>  msgid "%s: pathspec magic not supported by this command: %s"
> @@ -953,11 +943,6 @@ msgstr ""
>  msgid "%s tracks both %s and %s"
>  msgstr ""
>
> -#.
> -#. * This last possibility doesn't occur because
> -#. * FETCH_HEAD_IGNORE entries always appear at
> -#. * the end of the list.
> -#.
>  #: remote.c:774
>  msgid "Internal error"
>  msgstr ""
> @@ -1306,13 +1291,11 @@ msgstr ""
>  msgid "Could not find section in .gitmodules where path=%s"
>  msgstr ""
>
> -#. Maybe the user already did that, don't error out here
>  #: submodule.c:76
>  #, c-format
>  msgid "Could not update .gitmodules entry %s"
>  msgstr ""
>
> -#. Maybe the user already did that, don't error out here
>  #: submodule.c:109
>  #, c-format
>  msgid "Could not remove .gitmodules entry for %s"
> @@ -1884,7 +1867,6 @@ msgstr ""
>  msgid "add changes from all tracked and untracked files"
>  msgstr ""
>
> -#. takes no arguments
>  #: builtin/add.c:260
>  msgid "ignore paths removed in the working tree (same as --no-all)"
>  msgstr ""
> @@ -2044,7 +2026,6 @@ msgstr ""
>  msgid "corrupt binary patch at line %d: %.*s"
>  msgstr ""
>
> -#. there has to be one hunk (forward hunk)
>  #: builtin/apply.c:1900
>  #, c-format
>  msgid "unrecognized binary patch at line %d"
> @@ -2232,7 +2213,6 @@ msgstr ""
>  msgid "internal error"
>  msgstr ""
>
> -#. Say this even without --verbose
>  #: builtin/apply.c:4043
>  #, c-format
>  msgid "Applying patch %%s with %d reject..."
> @@ -3232,7 +3212,6 @@ msgstr ""
>  msgid " ... and %d more.\n"
>  msgstr ""
>
> -#. The singular version
>  #: builtin/checkout.c:711
>  #, c-format
>  msgid ""
> @@ -3280,7 +3259,6 @@ msgstr ""
>  msgid "invalid reference: %s"
>  msgstr ""
>
> -#. case (1): want a tree
>  #: builtin/checkout.c:1002
>  #, c-format
>  msgid "reference is not a tree: %s"
> @@ -4276,7 +4254,6 @@ msgstr ""
>  msgid "GPG sign commit"
>  msgstr ""
>
> -#. end commit message options
>  #: builtin/commit.c:1508
>  msgid "Commit contents options"
>  msgstr ""
> @@ -5140,7 +5117,6 @@ msgstr ""
>  msgid "See \"git help gc\" for manual housekeeping.\n"
>  msgstr ""
>
> -#. be quiet on --auto
>  #: builtin/gc.c:336
>  #, c-format
>  msgid ""
> @@ -5894,12 +5870,10 @@ msgstr ""
>  msgid "unable to move %s to %s"
>  msgstr ""
>
> -#.
> -#. * TRANSLATORS: The first '%s' is either "Reinitialized
> -#. * existing" or "Initialized empty", the second " shared" or
> -#. * "", and the last '%s%s' is the verbatim directory name.
> -#.
> -#: builtin/init-db.c:420
> +#. TRANSLATORS: The first '%s' is either "Reinitialized
> +#. existing" or "Initialized empty", the second " shared" or
> +#. "", and the last '%s%s' is the verbatim directory name.
> +#: builtin/init-db.c:418
>  #, c-format
>  msgid "%s%s Git repository in %s%s\n"
>  msgstr ""
> @@ -6627,7 +6601,6 @@ msgstr ""
>  msgid "Commit %s has a bad GPG signature allegedly by %s."
>  msgstr ""
>
> -#. 'N'
>  #: builtin/merge.c:1279
>  #, c-format
>  msgid "Commit %s does not have a GPG signature."
> @@ -9593,8 +9566,6 @@ msgstr ""
>  msgid "'git bisect bad' can take only one argument."
>  msgstr ""
>
> -#. have bad but not good.  we could bisect although
> -#. this is less optimum.
>  #: git-bisect.sh:273
>  msgid "Warning: bisecting only with a bad commit."
>  msgstr ""
> @@ -9690,10 +9661,6 @@ msgstr ""
>  msgid "updating an unborn branch with changes added to the index"
>  msgstr ""
>
> -#. The fetch involved updating the current branch.
> -#. The working tree and the index file is still based on the
> -#. $orig_head commit, but we are merging into $curr_head.
> -#. First update the working tree to match $curr_head.
>  #: git-pull.sh:271
>  #, sh-format
>  msgid ""
> @@ -9835,7 +9802,6 @@ msgstr ""
>  msgid "Changes from $mb to $onto:"
>  msgstr ""
>
> -#. Detach HEAD and reset the tree
>  #: git-rebase.sh:609
>  msgid "First, rewinding head to replay your work on top of it..."
>  msgstr ""
> @@ -10218,7 +10184,6 @@ msgstr ""
>  msgid "The --cached option cannot be used with the --files option"
>  msgstr ""
>
> -#. unexpected type
>  #: git-submodule.sh:1097
>  #, sh-format
>  msgid "unexpected mode $mod_dst"

Re: [PATCH 2/3] i18n: Only extract comments marked by special tag

[Jiang Xin]

2014-04-18 2:08 GMT+08:00 Junio C Hamano <gitster@pobox.com>:
> Jiang Xin <worldhello.net@gmail.com> writes:
>
>> When extract l10n messages, we use "--add-comments" option to keep
>> comments right above the l10n messages for references.  But sometimes
>> irrelevant comments are also extracted.  For example in the following
>> code block, the comment in line 2 will be extracted as comment for the
>> l10n message in line 3, but obviously it's wrong.
>>
>>         { OPTION_CALLBACK, 0, "ignore-removal", &addremove_explicit,
>>           NULL /* takes no arguments */,
>>           N_("ignore paths removed in the working tree (same as
>>           --no-all)"),
>>           PARSE_OPT_NOARG, ignore_removal_cb },
>>
>> Since almost all comments for l10n translators are marked with the same
>> prefix (tag): "TRANSLATORS:", it's safe to only extract comments with
>> this special tag.  I.E. it's better to call xgettext as:
>>
>>         xgettext --add-comments=TRANSLATORS: ...
>>
>> Also tweaks the multi-line comment in "init-db.c", to make it start with
>> the proper tag, not "* TRANSLATORS:" (which has a star before the tag).
>
> Hmph.
>
> I am not very happy with this change, as it would force us to
> special case "Translators" comment to follow a non-standard
> multi-line comment formatting convention.  Is there a way to tell
> xgettext to accept both of these forms?
>
>         /* TRANSLATORS: this is a short comment to help you */
>         _("foo bar");
>
>         /*
>          * TRANSLATORS: this comment is to help you, but it is
>          * a lot longer to fit on just a single line.
>          */
>         _("bar baz");
>

We can not provide multiple `--add-comments=TAG` options to xgettext,
because xgettext holds the tag in one string, not in a list:

        /* Tag used in comment of prevailing domain.  */
        static char *comment_tag;

So if we won't change our multi-line comments for translators, must
hack gettext in some ways.

There maybe 3 ways to hack gettext:

1. When matching comments against TAG, using strstr not strncmp.

        2360         /* When the comment tag is seen, it drags in not
only the line
        2361            which it starts, but all remaining comment lines.  */
        2362         if (add_all_remaining_comments
        2363             || (add_all_remaining_comments =
        2364                   (comment_tag != NULL
        2365                    && strncmp (s, comment_tag, strlen
(comment_tag)) == 0)))

2. Add a extension to in-comment xgettext instructions.

    There is a undocumented feature in xgettext: User can provide
    instructions (prefixed by xgettext:) in comments, such as:

        /*
         * xgettext: fuzzy possible-c-format no-wrap
         * other comments...
         */

    But it does not help much, unless we hack xgettext to extend this
    hidden feature. I.E. Add an additional flag to support unconditionally
    reference to the commit block. Like:

        /*
         * xgettext: comments
         * TRANSLATORS: this comment is to help you, but it is
         * a lot longer to fit on just a single line.
         */
         _("bar baz");

3. Hack the parser for comments in "gettext-tools/src/x-c.c" (maybe
    function phase4_getc()) to support various multi-line comments style,
    such as:

        /*
         * TRANSLATORS: this comment is to help you, but it is
         * a lot longer to fit on just a single line.
         */

        /*
        ** TRANSLATORS: this comment is to help you, but it is
        ** a lot longer to fit on just a single line.
        */

        /********************************************************
         * TRANSLATORS: this comment is to help you, but it is  *
         * a lot longer to fit on just a single line.           *
         ********************************************************/


I CC this mail to the gettext mailing list. Full thread see:

 * http://thread.gmane.org/gmane.comp.version-control.git/246390/focus=246431

-- 
Jiang Xin

Re: [PATCH 2/3] i18n: Only extract comments marked by special tag

[Junio C Hamano]

Jiang Xin <worldhello.net@gmail.com> writes:

>> I am not very happy with this change, as it would force us to
>> special case "Translators" comment to follow a non-standard
>> multi-line comment formatting convention.  Is there a way to tell
>> xgettext to accept both of these forms?
>>
>>         /* TRANSLATORS: this is a short comment to help you */
>>         _("foo bar");
>>
>>         /*
>>          * TRANSLATORS: this comment is to help you, but it is
>>          * a lot longer to fit on just a single line.
>>          */
>>         _("bar baz");
>>
>
> We can not provide multiple `--add-comments=TAG` options to xgettext,
> because xgettext holds the tag in one string, not in a list:
>
>         /* Tag used in comment of prevailing domain.  */
>         static char *comment_tag;
>
> So if we won't change our multi-line comments for translators, must
> hack gettext in some ways.
>
> There maybe 3 ways to hack gettext:
> ...
> I CC this mail to the gettext mailing list. Full thread see:
>
>  * http://thread.gmane.org/gmane.comp.version-control.git/246390/focus=246431

This is one of these times when I find myself very fortunate for
being surrounded by competent contributors with good tastes, which I
may not deserve ;-)

Thanks for being thorough.

Having said that, it is only just a single comment, and it is too
much hassle to even think about what to do in the meantime while we
wait until such a change happens and an updated version of gettext
reaches everybody.  Let's take 2/3 as-is.

Documentation/CodingGuidelines may want to have a sentence of two to
explain this, though.

 Documentation/CodingGuidelines | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index dab5c61..b367a85 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -159,10 +159,19 @@ For C programs:
  - Multi-line comments include their delimiters on separate lines from
    the text.  E.g.
 
 	/*
 	 * A very long
 	 * multi-line comment.
 	 */
 
+   Note however that a multi-line comment that explains a translatable
+   string to translators uses a different convention of starting with a
+   magic token "TRANSLATORS: " immediately after the opening delimiter,
+   and without an asterisk at the beginning of each line.  E.g.
+
+	/* TRANSLATORS: here is a comment that explains the string
+	   to be translated, that follows immediately after it */
+	_("Here is a translatable string explained by the above.");
+
  - Double negation is often harder to understand than no negation
    at all.

Re: [PATCH 2/3] i18n: Only extract comments marked by special tag

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Documentation/CodingGuidelines may want to have a sentence of two to
> explain this, though.

After re-reading what I sent out, I realized that the way I singled
out multi-line comments was misleading.  Here is an updated version.

-- >8 --
Subject: [PATCH] i18n: mention "TRANSLATORS:" marker in Documentation/CodingGuidelines

These comments have to have "TRANSLATORS: " at the very beginning
and have to deviate from the usual multi-line comment formatting
convention.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/CodingGuidelines | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index dab5c61..f9b8bff 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -164,6 +164,16 @@ For C programs:
 	 * multi-line comment.
 	 */
 
+   Note however that a comment that explains a translatable string to
+   translators uses a convention of starting with a magic token
+   "TRANSLATORS: " immediately after the opening delimiter, even when
+   it spans multiple lines.  We do not add an asterisk at the beginning
+   of each line, either.  E.g.
+
+	/* TRANSLATORS: here is a comment that explains the string
+	   to be translated, that follows immediately after it */
+	_("Here is a translatable string explained by the above.");
+
  - Double negation is often harder to understand than no negation
    at all.
 
-- 
1.9.2-651-g78816bc