mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-12-07 05:15:09 +00:00
fe5f3fd914
MozReview-Commit-ID: 9zP6j7COEiJ --HG-- extra : rebase_source : 35b44964d38f53f62522d0709b18d7dfa1ca8a9a
97 lines
3.6 KiB
ReStructuredText
97 lines
3.6 KiB
ReStructuredText
Startup
|
|
=======
|
|
|
|
There are cases where it may be important to understand how Gecko locale management
|
|
acts during the startup.
|
|
|
|
Below is the description of the `server` mode, since the `client` mode is starting
|
|
with no data and doesn't perform any operations waiting for the parent to fill
|
|
basic locale lists (`requested` and `appLocales`) and then maintain them in a
|
|
unidirectional way.
|
|
|
|
Data Types
|
|
----------
|
|
|
|
There are two primary data types involved in negotiating locales during startup:
|
|
`requested` and `available`.
|
|
Throughout the startup different sources for this lists become available, and
|
|
in result the values for those lists change.
|
|
|
|
Data Sources
|
|
------------
|
|
|
|
There are three primary sources that become available during the bootstrap.
|
|
|
|
1) Packaged locale lists stored in files :js:`update.locale` and :js:`multilocale.txt`.
|
|
|
|
2) User preferences read from the profile.
|
|
|
|
3) Language packs installed in user profile or system wide.
|
|
|
|
Bootstrap
|
|
---------
|
|
|
|
1) Packaged Data
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
In the `server` mode Gecko starts with no knowledge of `available` or `requested`
|
|
locales.
|
|
|
|
Initially, all fields are resolved lazily, so no data for available, requested,
|
|
default or resolved locales is retrieved.
|
|
|
|
If any code queries any of the APIs, it triggers the initial data fetching
|
|
and language negotiation.
|
|
|
|
The initial request comes from the XPCLocale which is initializing
|
|
the first JS context and needs to know which locale the JS context should use as
|
|
the default.
|
|
|
|
At that moment :js:`LocaleService` fetches the list of available locales, using
|
|
packaged locales which are retrieved via :js:`multilocale.txt` file in the toolkit's
|
|
package.
|
|
This gives LocaleService information about which locales are initially available.
|
|
|
|
Notice that this happens before any of the language packs gets registered, so
|
|
at that point Gecko only knows about packaged locales.
|
|
|
|
For requested locales, the initial request comes before user profile preferences
|
|
are being read, so the data is being fetched using packaged preferences.
|
|
|
|
In case of Desktop Firefox the :js:`intl.locale.requested` pref will be not set,
|
|
which means Gecko will use the default locale which is retrieved from
|
|
:js:`update.locale` file (also packaged).
|
|
|
|
This means that the initial result of language negotiation is between packaged
|
|
locales as available and the default requested locale.
|
|
|
|
2) Profile Prefs Read
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Next, the profile is being read and if the user set any requested locales,
|
|
LocaleService updates its list of requested locales and broadcasts
|
|
:js:`intl:requested-locales-changed` event.
|
|
|
|
This may lead to language renegotiation if the requested locale is one of the packaged
|
|
ones. In that case, :js:`intl:app-locales-changed` will be broadcasted.
|
|
|
|
3) Language Packs Registered
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Finally, the AddonManager registers all the language packs, they get added to
|
|
:js:`L10nRegistry` and in result LocaleService's available locales get updated.
|
|
|
|
That triggers language negotiation and, if the language from the language pack
|
|
is used in the requested list, final list of locales is being set.
|
|
|
|
All of that happens before any UI is being built, but there's no guarantee of this
|
|
order being preserved, so it is important to understand that, depending on where the
|
|
code is used during the startup, it may receive different list of locales.
|
|
|
|
In order to maintain the correct locale settings it is important to set an observer
|
|
on :js:`intl:app-locales-changed` and update the code when the locale list changes.
|
|
|
|
That ensures the code always uses the best possible locale selection during startup,
|
|
but also during runtime in case user changes their requested locale list, or
|
|
language packs are updated/removed on the fly.
|