Discourage releasers from editing .po files by hand

Django Internals Internationalization
1

During the life of a feature release, a releaser makes about 5 interactions with Transifex. Each time, the releaser is asked(*) to skim the changes in incoming/outgoing PO files to revert possibly-noisy changes, for the sake of a smaller diff.

Going through this exercise recently, I had the feeling that this is actually harmful, and I’m hoping those who have been around before will be able to help me see what I’m missing.

The classes of changes that could be considered “noisy”:

The algorithm we’ve been applying has been to:

  • revert any changes to Plural-Forms, on the assumption that translators are not entering values for esoteric/dubious plural forms recently added by a language authority
  • scan for whether a file contains SOME substantial change to a string
  • if so, stage the entire file, including any line number and line break changes that might tag along
  • if not (i.e. the only changes were line number and line break changes), do not commit the file

I think this has some negative effects:

  • Line numbers aren’t accurate, becoming correct later, if ever
    – Strings are only unique within a single catalog. “Feature” means something different in contrib.gis versus contrib.admindocs. If a translator wants to compare the translations for “Feature” in other languages, one might prefer to search by file and line number rather than msgid to avoid getting hits on other strings. You can’t if the line numbers are wrong.
    – This information also flows through to the Transifex UI. Editing a string there labeled with a wrong line number, jumping to Django’s GitHub, and looking up the wrong line number doesn’t sound like a good experience.
  • As a releaser, it’s error-prone to look at hundreds of strings and attempt to determine whether the change is only a white-space change, especially in non-Latin scripts. I felt uncomfortable doing this.
  • Reverting "Plural-Forms" from the *.po headers without regenerating the *.mo files means the *.po headers are describing a false state of affairs.
    • Hebrew’s "Plural-Forms" decreased from 4 to 3, although we still have the 4th plural form for some strings on Transifex & our *.po files. I don’t see the point of maintaining 4 in the header if the 4th form is always going to be ignored. That’s a meaningful git diff on the header if it now says 3, and more importantly, it saves translators from wasted work.
    • Portuguese’s "Plural-Forms" increased from 2 to 3, and translators are potentially entering these values on Transifex. If I revert this back to 2 manually, I can either choose to leave the entries as is, resulting in a broken .po file that will not compile to *.mo, or I can also remove the strings that were entered for that plural form, but that’s no good, since they’ll appear in the app anyway, making this even harder to debug for a translator. (Django’s gettext calls, of course, do not select which plural form to use; they delegate to the plural form rule in the compiled .mo.)
    • In main, we have some broken *.po files that do not compile to *.mo because of a discrepancy in the plural-forms:
    django % msgfmt -c -o django/contrib/postgres/locale/pt_BR/LC_MESSAGES/django.mo django/contrib/postgres/locale/pt_BR/LC_MESSAGES/django.po
django/contrib/postgres/locale/pt_BR/LC_MESSAGES/django.po:14: nplurals = 2...
django/contrib/postgres/locale/pt_BR/LC_MESSAGES/django.po:76: ...but some messages have 3 plural forms
msgfmt: found 1 fatal error

My thought: manually editing .po files to make them incorrect or broken for the sake of having smaller diffs is not a good tradeoff.

The line wrapping problem could likely by alleviated by changing the fetch script to be more deterministic by using the --width argument to msgcat. This could be done once and git-ignored.

If the use case for small diffs isn’t very concrete, my recommendation is for the releasers to be discouraged from applying any manual edits to *.po files.

Those of you who have used the git diffs, what do you say? In what debugging scenarios are line number changes too noisy?

(*) search for “avoid”

1 Like
Django Fellow Report - Jacob - 2026
2

Thanks for the detailed post. I understand your general feeling, and share it.

If I were to decide things and have unlimited time, I would:

  • remove compiled .mo file from the .git repo (to address the diffs size)
  • use a platform (e.g. Weblate) where we can decide the plural strings ourselves.

This would avoid most if not all workarounds you describe in your post. However, I can understand your suggestion to give up with this and for the time being simply commit what we obtain from Transifex.

2 Likes
3

@claudep Thank you for your response. Would you have any further (historical?) rationale on why the process is how it is today? why do we revert the plural forms? why do we not ingest the .po files as given by Transifex?

4

why do we revert the plural forms?

Because the choices in Transifex doesn’t always suit our needs in my opinion (even if they use the CLDR reference). For example, in French, they set 3 plural forms. I find this totally unneeded, as I didn’t the see the need for the 3rd one in all my translator career. These are for real, real (theoretical) corner cases. And I know that’s the same for several languages. But if we stick with Transifex, it may be we should simply forget it and call it a day.

why do we not ingest the .po files as given by Transifex?

It is often related to some habits of mine, probably. So as I’m a bit less involved, it may be a good time to revisit and follow Jacob’s suggestions.

2 Likes