Django Translator Comments and Multi-line Function Calls

This behavior is related to how xgettext processes translator comments in relation to multi-line function calls. The issue you're experiencing is a known limitation of the translation extraction tools.

The Issue

When using multi-line function calls with translation functions like npgettext_lazy(), the translator comments are not properly associated with the translatable strings if the function call spans multiple lines. This is because xgettext expects the translator comment to be directly above the line containing the translation function call.

Django's Documentation on Translator Comments

Django's documentation specifically mentions this limitation in templates, where translator comments need to be at the end of a line to be recognized properly. While your issue is in Python code rather than templates, the underlying mechanism is similar:

For templates, Django documentation states:

Comments for translators in templates specified using {# / #} need to be at the end of a line. If they are not, the comments are ignored and makemessages will generate a warning.

Solutions

1. Use single-line function calls (as you've discovered):

   PYTHONCopied
   # Translators: 'naturaltime-past' strings will be included in '%(delta)s ago'
   "year": npgettext_lazy("naturaltime-past", "%(num)d year", "%(num)d years", "num"),

2. Place the comment directly above the first line of the function call:

   PYTHONCopied
   # Translators: 'naturaltime-past' strings will be included in '%(delta)s ago'
   "year": npgettext_lazy(
       "naturaltime-past", "%(num)d year", "%(num)d years", "num"
   ),

3. Use Django's makemessages command which has some improvements over direct xgettext usage, though it may still have limitations with multi-line calls.

Technical Explanation

This behavior is related to how xgettext parses source files. It associates translator comments with the next translatable string it finds, but when function calls span multiple lines, the association can break. The first line of your multi-line function call doesn't contain the complete translatable string, so xgettext doesn't properly associate the comment with it.

The single-line version works because the entire translation function call is on the same line as (or immediately after) the translator comment.

This is a limitation of the GNU gettext tools rather than Django itself, though Django's makemessages command tries to handle some edge cases better than raw xgettext.