[olehgerus]

Refs #410.

Following the discussion here, this is now docs only and the :on_missing_translation option is gone.

It adds a "Reporting missing messages" section to the "Missing messages" docs in Gettext. It shows how to override handle_missing_translation/5 and handle_missing_plural_translation/7 in a backend, log a warning and call super, and mentions that the callbacks run for every locale that lacks the message, including the source one.

I ran the example from the docs: it logs the warning and still returns the msgid.

[josevalim]

Perhaps I am missing something, but why not use the handle_missing_translation and handle_missing_plural_translation callbacks?

[olehgerus]

Not missing anything, the callbacks can do this, and I checked that overriding both and calling super covers the same cases (missing keys, empty msgstr, unknown domains and locales, plurals, split_module_by).

I went with the option because of the discussion in #410, where @maennchen and @whatyouhide were in favor of an on_missing_translation backend option. It saves people writing the same override, and gives one shared error and log format. But if you'd rather keep the API small, I understand.

The docs don't mention the callbacks in the "Missing messages" section, so that part is easy to miss. If you prefer, I can turn this PR into a docs-only change with an example of warning or raising from the override, plus the default-domain fallback from the issue. Just tell me which way you want to go.

[josevalim]

I'd prefer to use the callbacks but let's def er to @maennchen and @whatyouhide's decision.

[whatyouhide]

When I suggested that option I was not thinking of callbacks, which in general are a good approach here I think. I would personally go for this:

1. Improve docs around this instead of adding the option.
2. Update Phoenix template to generate a missing-translation callback that does warn (because I think it's a nice behavior, and easier to take it out?).

Thoughts?

[olehgerus]

Sounds good, I agree callbacks are the better fit here. I'll rework this PR into docs only and drop the option. The docs will show how to override handle_missing_translation/5 and handle_missing_plural_translation/7 to log a warning.

For the Phoenix template, I'm happy to open that PR in the Phoenix repo once the docs are in, if that works for you.

[whatyouhide]

Thank you @olehgerus 🫶