From df67fd9200954b0f3ea570d4feb0027c595d3130 Mon Sep 17 00:00:00 2001
From: Oleh Gerus <73129739+olehgerus@users.noreply.github.com>
Date: Thu, 22 Oct 2026 23:43:40 +0300
Subject: [PATCH] Document how to report missing messages with the backend
 callbacks

Missing messages are returned silently. Show how to override
handle_missing_translation/5 and handle_missing_plural_translation/7 and
call super to log a warning.
---
 lib/gettext.ex | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/lib/gettext.ex b/lib/gettext.ex
index 6fd6238..07120ee 100644
--- a/lib/gettext.ex
+++ b/lib/gettext.ex
@@ -436,6 +436,42 @@ defmodule Gettext do
       ngettext("One error", "%{count} errors", 3)
       #=> "3 errors"
 
+  ### Reporting missing messages
+
+  Missing messages are returned silently, which can make untranslated messages
+  hard to find. To get notified, override `c:Gettext.Backend.handle_missing_translation/5`
+  and `c:Gettext.Backend.handle_missing_plural_translation/7` in your backend and
+  call `super` to keep the behaviour described above. For example, to log a
+  warning:
+
+      defmodule MyApp.Gettext do
+        use Gettext.Backend, otp_app: :my_app
+
+        require Logger
+
+        def handle_missing_translation(locale, domain, msgctxt, msgid, bindings) do
+          Logger.warning("Missing #{locale} message in #{domain}: #{inspect(msgid)}")
+          super(locale, domain, msgctxt, msgid, bindings)
+        end
+
+        def handle_missing_plural_translation(
+              locale,
+              domain,
+              msgctxt,
+              msgid,
+              msgid_plural,
+              n,
+              bindings
+            ) do
+          Logger.warning("Missing #{locale} message in #{domain}: #{inspect(msgid)}")
+          super(locale, domain, msgctxt, msgid, msgid_plural, n, bindings)
+        end
+      end
+
+  The callbacks run for every locale that lacks the message, including the one
+  your messages are written in, so you may want to skip the warning for that
+  locale. To fail instead of warning, raise from the callbacks.
+
   ### Empty messages
 
   When a `msgstr` is empty (`""`), the message is considered missing and the