diff --git a/docs/programmers-guide.md b/docs/programmers-guide.md
--- a/docs/programmers-guide.md
+++ b/docs/programmers-guide.md
@@ -1053,9 +1053,10 @@
 }
 ~~~
 
-This call can be made at any place in the code
-(e.g. there is no need to have `QApplication` constructed beforehand),
-but of course before any `i18n` call takes place.
+This call must be made in the code before any `i18n` call takes place,
+and right after creating the instance of `QCoreApplication` or one
+of its subclasses. `ki18n` calls can still be made before, but the
+respective `KLocalizedString::toString()` has to be delayed to after that.
 
 This is all there is to connecting calls and catalogs application's
 C++ source files. However, there may also be some non-code files
diff --git a/src/klocalizedstring.h b/src/klocalizedstring.h
--- a/src/klocalizedstring.h
+++ b/src/klocalizedstring.h
@@ -448,6 +448,12 @@
      * This prevents mixing of translated and untranslated text
      * in the user interface.
      *
+     * This function should be called right after creating the instance
+     * of QCoreApplication or one of its subclasses. At that time the locale
+     * setup has been made, including what is hooked into the
+     * QCoreApplication startup, like KXMLGUI's language switching support.
+     * So the initialisation done by this function sees all the data it should.
+     *
      * \param domain the translation domain of the application
      */
     static void setApplicationDomain(const char *domain);