locale_startup.rst (3734B)
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:`default.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:`default.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.