D8351: API dox: add note about calling setApplicationDomain after QApp creation

[Friedrich W . H . Kossebau]

This revision was automatically updated to reflect the committed changes.
Closed by commit R249:9ae1a9b2e923: API dox: add note about calling 
setApplicationDomain after QApp creation (authored by kossebau).

CHANGED PRIOR TO COMMIT
  https://phabricator.kde.org/D8351?vs=20928=26851#toc

REPOSITORY
  R249 KI18n

CHANGES SINCE LAST UPDATE
  https://phabricator.kde.org/D8351?vs=20928=26851

REVISION DETAIL
  https://phabricator.kde.org/D8351

AFFECTED FILES
  docs/programmers-guide.md
  src/klocalizedstring.h

To: kossebau, #frameworks, ilic, ltoscano, dfaure
Cc: dfaure, michaelh, ngraham

D8351: API dox: add note about calling setApplicationDomain after QApp creation

[Friedrich W . H . Kossebau]

kossebau added a comment.


  In https://phabricator.kde.org/D8351#201926, @ilic wrote:
  
  > Yes, I guess in the end it's the simplest way to look at it.
  >
  > One thing though: I'd add at least another sentence claryfing that unlike 
an i18n* call, a ki18n* can happen at any time, and only its toString method 
should be called after Q*App instance creation (because that's when translation 
happens and locale is queried).
  
  
  Makes sense to me, will see to add that (with some post-commit review ;) ). 
If you have some phrasing proposal, would be happy to have something to copy 
(lazy me).

REPOSITORY
  R249 KI18n

BRANCH
  addNoteAboutCallingSetAppDomainAfterQApp

REVISION DETAIL
  https://phabricator.kde.org/D8351

To: kossebau, #frameworks, ilic, ltoscano, dfaure
Cc: dfaure, michaelh, ngraham

D8351: API dox: add note about calling setApplicationDomain after QApp creation

[Chusslove Illich]

ilic added a comment.


  Yes, I guess in the end it's the simplest way to look at it.
  
  One thing though: I'd add at least another sentence claryfing that unlike an 
i18n* call, a ki18n* can happen at any time, and only its toString method 
should be called after Q*App instance creation (because that's when translation 
happens and locale is queried).

REPOSITORY
  R249 KI18n

BRANCH
  addNoteAboutCallingSetAppDomainAfterQApp

REVISION DETAIL
  https://phabricator.kde.org/D8351

To: kossebau, #frameworks, ilic, ltoscano, dfaure
Cc: dfaure, michaelh, ngraham

D8351: API dox: add note about calling setApplicationDomain after QApp creation

[Friedrich W . H . Kossebau]

kossebau added a comment.


  In https://phabricator.kde.org/D8351#161562, @ilic wrote:
  
  > Well... it's a tough situation. It is not by design that `i18n` calls 
should in any way depend on creation of `QApplication`, and also any library 
may place an `i18n` call before the main program creates `QApplication`. The 
only solution I see is that environment is rechecked at every `i18n` call. This 
would be easy to do (just replacing every `s->languages` with a newly 
implemented `s->getLanguages()`), but I've no idea what would be the 
performance hit of that.
  
  
  Thanks for reply, @ilic, sorry for not having picked up immediately, as I 
agree it's tough and I set the topic aside a little to have some thoughts 
develop in the back of my mind.
  
  One problem that i see with rechecking the environment at every i18n call is 
that this potentially could result in inconsistent UI. Because the average 
applications using KI18n is not written to support switching UI localization on 
the fly. Incl. KXMLGUI's language switching support, which only injects its 
settings at a roughly defined point in time, as part of the post-handlers of 
the Q*App instance creation.
  
  So I would agree with @dfaure that for the current KI18n usage (which is 
somewhat coupled with KXMLGUI's language switching support) we should just 
stick formally to what technically is needed right now: only doing UI 
locale-based things after the Q*App instance is created and thus after 
everything related to localization is setup and prepared (and will stay to the 
end of the Q*App instance lifetime.
  
  So would push this change upcoming WE, Feb 10/11, finally, unless someone 
objects.
  
  ((In time for Qt6/KF6 we should perhaps revisit this and hopefully have some 
people work on adding proper infrastructure and usage patterns to allow such 
switching UI localization on the fly. It's pretty sad that Web apps, which are 
younger, are better here))

REPOSITORY
  R249 KI18n

BRANCH
  addNoteAboutCallingSetAppDomainAfterQApp

REVISION DETAIL
  https://phabricator.kde.org/D8351

To: kossebau, #frameworks, ilic, ltoscano, dfaure
Cc: dfaure, michaelh, ngraham

D8351: API dox: add note about calling setApplicationDomain after QApp creation

[David Faure]

dfaure accepted this revision.
dfaure added a comment.
This revision is now accepted and ready to land.


  Yes.
  
  >   any library may place an i18n call before the main program creates 
QApplication
  
  No, that's invalid.
  Before QApp is created, many things are not initialized, including the 
locale. The translation support can have the same requirement, then.

REPOSITORY
  R249 KI18n

BRANCH
  addNoteAboutCallingSetAppDomainAfterQApp

REVISION DETAIL
  https://phabricator.kde.org/D8351

To: kossebau, #frameworks, ilic, ltoscano, dfaure
Cc: dfaure

D8351: API dox: add note about calling setApplicationDomain after QApp creation

[Chusslove Illich]

ilic added a comment.


  Well... it's a tough situation. It is not by design that `i18n` calls should 
in any way depend on creation of `QApplication`, and also any library may place 
an `i18n` call before the main program creates `QApplication`. The only 
solution I see is that environment is rechecked at every `i18n` call. This 
would be easy to do (just replacing every `s->languages` with a newly 
implemented `s->getLanguages()`), but I've no idea what would be the 
performance hit of that.

REPOSITORY
  R249 KI18n

REVISION DETAIL
  https://phabricator.kde.org/D8351

To: kossebau, #frameworks, ilic, ltoscano

D8351: API dox: add note about calling setApplicationDomain after QApp creation

[Friedrich W . H . Kossebau]

kossebau added a comment.


  @ilic ping? Can you confirm this is correct and by design?
  
  Motivation is:
  `KLocalizedString::setApplicationDomain()` 
 triggers 
the creation of the `KLocalizedStringPrivateStatics` instance, which then also 
reads the currently set env vars to collect the set locales/languages 
. 
  Now KXMLGUI's language switching support for programs injects the override 
language via `Q_COREAPP_STARTUP_FUNCTION(initializeLanguages)` (see 
kswitchlanguagedialog_p.cpp 
 
lines 44ff) by twisting the `LANGUAGE` env var.
  So for that to work, the `KLocalizedStringPrivateStatics` instance has to be 
created only _after_ the QCoreApplication constructor is run.
  
  A few programs had the order reversed, due to calling 
`KLocalizedString::setApplicationDomain()` before QApp creation, resulting in 
the language switching override being ignored and thus broken.

REPOSITORY
  R249 KI18n

REVISION DETAIL
  https://phabricator.kde.org/D8351

To: kossebau, #frameworks, ilic, ltoscano

D8351: API dox: add note about calling setApplicationDomain after QApp creation

[Friedrich W . H . Kossebau]

kossebau added a comment.


  Another option might be to split off a data structure where the application 
domain string is stored separately, and thus delay the initialization of the 
KLocalizedStringPrivateStatics instance to the first i18n call. Though given 
that the initialisation sets global values which then are const for the rest of 
the runtime based on the environment at the time, that would be slightly random.
  Having straight control about the time when the init is done feels better to 
me. Possibly that should be even more emphasized in the API dox?

REPOSITORY
  R249 KI18n

REVISION DETAIL
  https://phabricator.kde.org/D8351

To: kossebau, #frameworks, ilic, ltoscano

D8351: API dox: add note about calling setApplicationDomain after QApp creation

[Friedrich W . H . Kossebau]

kossebau created this revision.
kossebau added reviewers: Frameworks, ilic, ltoscano.
Restricted Application added a project: Frameworks.

REVISION SUMMARY
  The current implementation of KLocalizedString::setApplicationDomain()
  will trigger the creation of the KLocalizedStringPrivateStatics instance and
  thus also the calculation of the locale languanges from the env vars
  as set at that time, and QLocale::system() on some platforms.
  So the claim that "This call can be made at any place in the code" does not
  hold, instead API consumers should be instructed about when to call
  the method ideally.

REPOSITORY
  R249 KI18n

BRANCH
  addNoteAboutCallingSetAppDomainAfterQApp

REVISION DETAIL
  https://phabricator.kde.org/D8351

AFFECTED FILES
  docs/programmers-guide.md
  src/klocalizedstring.h

To: kossebau, #frameworks, ilic, ltoscano