git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH] C style: use standard style for "TRANSLATORS" comments

From
Jonathan Nieder <jrnieder@gmail.com>
Date
May 11, 2017, 21:41 UTC
Message-ID
<20170511214125.GB21723@aiede.svl.corp.google.com>
In-Reply-To
<20170511212012.6782-1-avarab@gmail.com>
Hi,
Ævar Arnfjörð Bjarmason wrote:
> Change all the "TRANSLATORS: [...]" comments in the C code to use the
> regular Git coding style, and amend the style guide so that the
> example there uses that style.
Hooray!
[...]
Show 5 quoted lines
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -256,12 +256,12 @@ For C programs:
>  
>     Note however that a comment that explains a translatable string to

The "Note however" isn't needed since it's not contradicting the previous point any more. This can be an entirely separate item:

 - A comment that explains a translatable string to translators
   uses a convention of starting with a magic token "TRANSLATORS: "
   [etc]

It might even make sense to remove the explanation of TRANSLATORS comments from this file altogether, since they're intuitive to use. A more common place to want to learn about them is po/README, which already explains them.

[...]
Show 12 quoted lines
> --- a/bisect.c
> +++ b/bisect.c
> @@ -995,8 +995,10 @@ int bisect_next_all(const char *prefix, int no_checkout)
>  
>  	steps_msg = xstrfmt(Q_("(roughly %d step)", "(roughly %d steps)",
>  		  steps), steps);
> -	/* TRANSLATORS: the last %s will be replaced with
> -	   "(roughly %d steps)" translation */
> +	/*
> +	 * TRANSLATORS: the last %s will be replaced with "(roughly %d
> +	 * steps)" translation.
> +	 */
Nice.
[...]
Show 11 quoted lines
> +++ b/ref-filter.c
> @@ -1251,13 +1251,17 @@ char *get_head_description(void)
>  			    state.branch);
>  	else if (state.detached_from) {
>  		if (state.detached_at)
> -			/* TRANSLATORS: make sure this matches
> -			   "HEAD detached at " in wt-status.c */
> +			/*
> +			 * TRANSLATORS: make sure this matches "HEAD
> +			 * detached at " in wt-status.c
> +			 */

optional: could treat "HEAD detached at " as an unbreakable phrase for the sake of line-breaking, for easier grepping.

But what's here is also perfectly fine.
[...]
Show 6 quoted lines
> -			/* TRANSLATORS: make sure this matches
> -			   "HEAD detached from " in wt-status.c */
> +			/*
> +			 * TRANSLATORS: make sure this matches "HEAD
> +			 * detached from " in wt-status.c
> +			 */
Likewise.
The rest also look good. This is great.

Thanks, Jonathan

Previous: Ævar Arnfjörð BjarmasonNext: Brandon Williams
Message 55 of 61 in “Easy to review grep & pre-PCRE changes”
  1. 00/29 Easy to review grep & pre-PCRE changesÆvar Arnfjörð Bjarmason, May 11, 2017
  2. 02/29 grep & rev-list doc: stop promising libpcre for --perl-regexpÆvar Arnfjörð Bjarmason, May 11, 2017
  3. 03/29 test-lib: rename the LIBPCRE prerequisite to PCREÆvar Arnfjörð Bjarmason, May 11, 2017
  4. 01/29 Makefile & configure: reword inaccurate comment about PCREÆvar Arnfjörð Bjarmason, May 11, 2017
  5. 04/29 log: add exhaustive tests for pattern style options & configÆvar Arnfjörð Bjarmason, May 11, 2017
  6. Junio C HamanoMay 12, 2017
  7. Ævar Arnfjörð BjarmasonMay 13, 2017
  8. 06/29 grep: add a test for backreferences in PCRE patternsÆvar Arnfjörð Bjarmason, May 11, 2017
  9. 05/29 grep: add a test asserting that --perl-regexp dies when !PCREÆvar Arnfjörð Bjarmason, May 11, 2017
  10. 08/29 grep: add tests for --threads=N and grep.threadsÆvar Arnfjörð Bjarmason, May 11, 2017
  11. Brandon WilliamsMay 11, 2017
  12. Ævar Arnfjörð BjarmasonMay 11, 2017
  13. 09/29 grep: amend submodule recursion test for regex engine testingÆvar Arnfjörð Bjarmason, May 11, 2017
  14. Junio C HamanoMay 12, 2017
  15. Ævar Arnfjörð BjarmasonMay 13, 2017
  16. 10/29 grep: add tests for grep pattern types being passed to submodulesÆvar Arnfjörð Bjarmason, May 11, 2017
  17. 07/29 grep: change non-ASCII -i test to stop using --debugÆvar Arnfjörð Bjarmason, May 11, 2017
  18. Brandon WilliamsMay 11, 2017
  19. Ævar Arnfjörð BjarmasonMay 11, 2017
  20. Brandon WilliamsMay 11, 2017
  21. 12/29 grep: prepare for testing binary regexes containing rx metacharactersÆvar Arnfjörð Bjarmason, May 11, 2017
  22. 13/29 grep: add tests to fix blind spots with \0 patternsÆvar Arnfjörð Bjarmason, May 11, 2017
  23. 14/29 perf: add a GIT_PERF_MAKE_COMMAND for when *_MAKE_OPTS won't doÆvar Arnfjörð Bjarmason, May 11, 2017
  24. 11/29 grep: add a test helper function for less verbose -f \0 testsÆvar Arnfjörð Bjarmason, May 11, 2017
  25. Junio C HamanoMay 12, 2017
  26. Ævar Arnfjörð BjarmasonMay 13, 2017
  27. Junio C HamanoMay 15, 2017
  28. 15/29 perf: emit progress output when unpacking & buildingÆvar Arnfjörð Bjarmason, May 11, 2017
  29. 16/29 perf: add a performance comparison test of grep -G, -E and -PÆvar Arnfjörð Bjarmason, May 11, 2017
  30. 18/29 grep: catch a missing enum in switch statementÆvar Arnfjörð Bjarmason, May 11, 2017
  31. Brandon WilliamsMay 11, 2017
  32. Stefan BellerMay 11, 2017
  33. Ævar Arnfjörð BjarmasonMay 11, 2017
  34. 17/29 perf: add a performance comparison of fixed-string grepÆvar Arnfjörð Bjarmason, May 11, 2017
  35. 19/29 grep: remove redundant regflags assignment under PCREÆvar Arnfjörð Bjarmason, May 11, 2017
  36. 20/29 grep: remove redundant `regflags &= ~REG_EXTENDED` assignmentsÆvar Arnfjörð Bjarmason, May 11, 2017
  37. 21/29 grep: factor test for \0 in grep patterns into a functionÆvar Arnfjörð Bjarmason, May 11, 2017
  38. Brandon WilliamsMay 11, 2017
  39. Ævar Arnfjörð BjarmasonMay 11, 2017
  40. 22/29 grep: change the internal PCRE macro names to be PCRE1Ævar Arnfjörð Bjarmason, May 11, 2017
  41. Brandon WilliamsMay 11, 2017
  42. 23/29 grep: change internal *pcre* variable & function names to be *pcre1*Ævar Arnfjörð Bjarmason, May 11, 2017
  43. 24/29 grep: move two functions to avoid forward declarationÆvar Arnfjörð Bjarmason, May 11, 2017
  44. Brandon WilliamsMay 11, 2017
  45. Ævar Arnfjörð BjarmasonMay 11, 2017
  46. 25/29 test-lib: add a PTHREADS prerequisiteÆvar Arnfjörð Bjarmason, May 11, 2017
  47. 26/29 pack-objects & index-pack: add test for --threads warningÆvar Arnfjörð Bjarmason, May 11, 2017
  48. Brandon WilliamsMay 11, 2017
  49. Ævar Arnfjörð BjarmasonMay 11, 2017
  50. 28/29 grep: given --threads with NO_PTHREADS=YesPlease, warnÆvar Arnfjörð Bjarmason, May 11, 2017
  51. Brandon WilliamsMay 11, 2017
  52. Ævar Arnfjörð BjarmasonMay 11, 2017
  53. Brandon WilliamsMay 11, 2017
  54. C style: use standard style for "TRANSLATORS" commentsÆvar Arnfjörð Bjarmason, May 11, 2017
  55. Jonathan NiederMay 11, 2017
  56. Brandon WilliamsMay 11, 2017
  57. Johannes SixtMay 12, 2017
  58. Jiang XinMay 30, 2017
  59. Junio C HamanoMay 30, 2017
  60. 27/29 pack-objects: fix buggy warning about threadsÆvar Arnfjörð Bjarmason, May 11, 2017
  61. 29/29 grep: assert that threading is enabled when calling grep_{lock,unlock}Ævar Arnfjörð Bjarmason, May 11, 2017

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.