intl/docs/locale_startup.rst

   1 Startup
   2 =======
   3
   4 There are cases where it may be important to understand how Gecko locale management
   5 acts during the startup.
   6
   7 Below is the description of the `server` mode, since the `client` mode is starting
   8 with no data and doesn't perform any operations waiting for the parent to fill
   9 basic locale lists (`requested` and `appLocales`) and then maintain them in a
  10 unidirectional way.
  11
  12 Data Types
  13 ----------
  14
  15 There are two primary data types involved in negotiating locales during startup:
  16 `requested` and `available`.
  17 Throughout the startup different sources for this lists become available, and
  18 in result the values for those lists change.
  19
  20 Data Sources
  21 ------------
  22
  23 There are three primary sources that become available during the bootstrap.
  24
  25 1) Packaged locale lists stored in files :js:`update.locale` and :js:`multilocale.txt`.
  26
  27 2) User preferences read from the profile.
  28
  29 3) Language packs installed in user profile or system wide.
  30
  31 Bootstrap
  32 ---------
  33
  34 1) Packaged Data
  35 ^^^^^^^^^^^^^^^^
  36
  37 In the `server` mode Gecko starts with no knowledge of `available` or `requested`
  38 locales.
  39
  40 Initially, all fields are resolved lazily, so no data for available, requested,
  41 default or resolved locales is retrieved.
  42
  43 If any code queries any of the APIs, it triggers the initial data fetching
  44 and language negotiation.
  45
  46 The initial request comes from the XPCLocale which is initializing
  47 the first JS context and needs to know which locale the JS context should use as
  48 the default.
  49
  50 At that moment :js:`LocaleService` fetches the list of available locales, using
  51 packaged locales which are retrieved via :js:`multilocale.txt` file in the toolkit's
  52 package.
  53 This gives LocaleService information about which locales are initially available.
  54
  55 Notice that this happens before any of the language packs gets registered, so
  56 at that point Gecko only knows about packaged locales.
  57
  58 For requested locales, the initial request comes before user profile preferences
  59 are being read, so the data is being fetched using packaged preferences.
  60
  61 In case of Desktop Firefox the :js:`intl.locale.requested` pref will be not set,
  62 which means Gecko will use the default locale which is retrieved from
  63 :js:`update.locale` file (also packaged).
  64
  65 This means that the initial result of language negotiation is between packaged
  66 locales as available and the default requested locale.
  67
  68 2) Profile Prefs Read
  69 ^^^^^^^^^^^^^^^^^^^^^
  70
  71 Next, the profile is being read and if the user set any requested locales,
  72 LocaleService updates its list of requested locales and broadcasts
  73 :js:`intl:requested-locales-changed` event.
  74
  75 This may lead to language renegotiation if the requested locale is one of the packaged
  76 ones. In that case, :js:`intl:app-locales-changed` will be broadcasted.
  77
  78 3) Language Packs Registered
  79 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  80
  81 Finally, the AddonManager registers all the language packs, they get added to
  82 :js:`L10nRegistry` and in result LocaleService's available locales get updated.
  83
  84 That triggers language negotiation and, if the language from the language pack
  85 is used in the requested list, final list of locales is being set.
  86
  87 All of that happens before any UI is being built, but there's no guarantee of this
  88 order being preserved, so it is important to understand that, depending on where the
  89 code is used during the startup, it may receive different list of locales.
  90
  91 In order to maintain the correct locale settings it is important to set an observer
  92 on :js:`intl:app-locales-changed` and update the code when the locale list changes.
  93
  94 That ensures the code always uses the best possible locale selection during startup,
  95 but also during runtime in case user changes their requested locale list, or
  96 language packs are updated/removed on the fly.