Re: [PATCH v5] submodule merge: update conflict error message

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Jul 25, 2022, 12:31 UTC
Message-ID: <220725.86v8rlpdix.gmgdl@evledraar.gmail.com>
In-Reply-To: <20220718214349.3379328-1-calvinwan@google.com>

On Mon, Jul 18 2022, Calvin Wan wrote:

I'll have some more comments, but just on the output/i18n:

Show 6 quoted lines

> +		printf(_("Recursive merging with submodules currently only supports trivial cases.\n"
> +			"Please manually handle the merging of each conflicted submodule.\n"
> +			"This can be accomplished with the following steps:\n"));
> +		for (i = 0; i < csub->nr; i++) {
> +			printf(_(" - go to submodule (%s), and either merge commit %s\n"
> +				    "or update to an existing commit which has merged those changes\n"),

This seems to have some formatting issues, i.e. we'll emit things like:

 - one
one continued
 - tow
two continued

Whereas we want this, surely?;

 - one
   one continued
 - two
   two continued

I.e. we're using " - " to mark list items, but then not indenting the items.

> +					csub->items[i].path,
> +					csub->items[i].oid);
> +			if (csub->items[i].resolution_exists)
> +				printf(_("such as one listed above\n"));

	that people might read this backwards
	You need to consider

:)

I.e. this is "translation lego" that we try to avoid.

It's a bit more verbose (but it often is, unfortunately)

I think you can borrow a bit from ba5e8a0eb80 (object-name: make ambiguous object output translatable, 2022-01-27) here, i.e.:

 1. Just translate a message like "go to submodule ...\nor update to
    an", have another variant for the "resolution exists".

 2. As translators retain those \n split those lines and format them
    with e.g. _(" %s") (you could borrow the string used in
    object-name.c via ba5e8a0eb80), or _("- %s").

    This will give you list-itemized output, which will also format
    correctly in RTL languages, and takes the formatting concerns
    completely out of the hands of translators, and allows us to change
    it later ourselves.

    I.e. we can safely assume that for a \n-delimited translation we can
    take \n-delimited input from a translator and treat the first line
    specially as a "first line in new list item".

> +		}
> +		printf(_(" - come back to superproject, and `git add"));
> +		for (i = 0; i < csub->nr; i++)
> +			printf(_(" %s"), csub->items[i].path);

More inconsistent indentation, and per ba5e8a0eb80 you should explain any addition of magical formatting like " %s" with a TRANSLATORS comment.

> +		printf(_("` to record the above merge or update \n"
> +			" - resolve any other conflicts in the superproject\n"
> +			" - commit the resulting index in the superproject\n"));

A bit more odd formatting, i.e.:

 - A trailing  " " before a \n?

 - " " after `, what is that ` doing? At first I thought it was a typo,
   but looking again it's a continuation of `` from above

   It's quite odd to tell a user to run a command with the `` syntax,
   which is used for interpolation. Let's instead suggest:

        blah blah blah run:

		git add foo \
			bar \ [...]
	                baz

   I.e. use \ at the end of lines to note a multi-line command, not wrap
   the whole thing in ``-quotes.

 - If a message must always end in a \n just add it between _()'s,
   instead of making it part of the _() string.