||This function splits an input string by `,` delimiter, sanitizes the result
language tags and returns them to the caller.
||LocaleService is a manager of language negotiation in Gecko.
It's intended to be the core place for collecting available and
requested languages and negotiating them to produce a fallback
chain of locales for the application.
Client / Server
LocaleService may operate in one of two modes:
in the server mode, LocaleService is collecting and negotiating
languages. It also subscribes to relevant observers.
There should be at most one server per application instance.
in the client mode, LocaleService is not responsible for collecting
or reacting to any system changes. It still distributes information
about locales, but internally, it gets information from the server
instance instead of collecting it on its own. This prevents any data
desynchronization and minimizes the cost of running the service.
In both modes, all get* methods should work the same way and all
static methods are available.
In the server mode, other components may inform LocaleService about their
status either via calls to set* methods or via observer events.
In the client mode, only the process communication should provide data
to the LocaleService.
At the moment desktop apps use the parent process in the server mode, and
content processes in the client mode.
Locale / Language
The terms `Locale ID` and `Language ID` are used slightly differently
by different organizations. Mozilla uses the term `Language ID` to describe
a string that contains information about the language itself, script,
region and variant. For example "en-Latn-US-mac" is a correct Language ID.
Locale ID contains a Language ID plus a number of extension tags that
contain information that go beyond language inforamation such as
preferred currency, date/time formatting etc.
An example of a Locale ID is `en-Latn-US-x-hc-h12-ca-gregory`
At the moment we do not support full extension tag system, but we
try to be specific when naming APIs, so the service is for locales,
but we negotiate between languages etc.
||List of language negotiation strategies to use.
For an example list of requested and available locales:
Requested: ['es-MX', 'fr-FR']
Available: ['fr', 'fr-CA', 'es', 'es-MX', 'it']
each of those strategies will build a different result:
filtering (default) -
Matches as many of the available locales as possible.
Supported: ['es-MX', 'es', 'fr', 'fr-CA', 'en-US']
Matches the best match from the available locales for every requested
Supported: ['es-MX', 'fr', 'en-US']
Matches a single best locale. This strategy always returns a list
of the length 1 and requires a defaultLocale to be set.
||Returns a list of locales used by the host environment for UI
The result is a sorted list and we expect that the OS attempts to
use the top locale from the list for which it has data.
Each element of the list is a valid locale ID that can be passed to ICU
and ECMA402 Intl APIs,
At the same time each element is a valid BCP47 language tag that can be
used for language negotiation.
Example: ["en-US", "de", "pl", "sr-Cyrl", "zh-Hans-HK"]
||Note: The file name is `MozLocale` to avoid compilation problems on
case-insensitive Windows. The class name is `Locale`.
||Locale class is a core representation of a single locale.
A locale is a data object representing a combination of language, script,
region, variant and a set of regional extension preferences that may further
specify particular user choices like calendar, numbering system, etc.
A locale can be expressed as a language tag string, like a simple "fr" for
French, or a more specific "sr-Cyrl-RS-u-hc-h12" for Serbian in Russia with a
Cyrylic script, and hour cycle selected to be `h12`.
The format of the language tag follows BCP47 standard and implements a subset
of it. In the future we expect to extend this class to cover more subtags and
The aim of this class it aid in validation, parsing and canonicalization of
It allows the user to input any well-formed BCP47 language tag and operate
on its subtags in a canonicalized form.
It should be used for all operations on language tags, and together with
LocaleService::NegotiateLanguages for language negotiation.
Locale loc = Locale("de-at");
ASSERT_TRUE(loc.GetRegion().Equals("AT")); // canonicalized to upper case
Note: The file name is `MozLocale` to avoid compilation problems on
case-insensitive Windows. The class name is `Locale`.
||The nsILanguageAtomService provides a mapping from languages or charsets
to language groups, and access to the system locale language.
||Looks up a property by value.
the static property array
the key to look up
the return value (empty string if not found)
@return NS_OK if found or NS_ERROR_FAILURE if not found
||This is a shared part of the OSPreferences API implementation.
It defines helper methods and public methods that are calling
platform-specific private methods.
||OSPreferences API provides a set of methods for retrieving information from
the host environment on topics such as:
- Regional preferences
The API is meant to remain as simple as possible, relaying information from
the host environment to the user without too much logic.
Saying that, there are two exceptions to that paradigm.
First one is normalization. We do intend to translate host environment
concepts to unified Intl/L10n vocabulary used by Mozilla.
That means that we will format locale IDs, timezone names, currencies etc.
into a chosen format.
Second is caching. This API does cache values and where possible will
hook into the environment for some event-driven cache invalidation.
This means that on platforms that do not support a mechanism to
notify apps about changes, new OS-level settings may not be reflected
in the app until it is relaunched.
||This module provides the PluralForm object which contains a method to figure
out which plural form of a word to use for a given number based on the
current localization. There is also a makeGetter method that creates a get
function for the desired plural rule. This is useful for extensions that
specify their own plural rule instead of relying on the browser default.
(I.e., the extension hasn't been localized to the browser's locale.)
NOTE: any change to these plural forms need to be reflected in
List of methods:
get(int aNum, string aWords)
[string pluralForm get(int aNum, string aWords), int numForms numForms()]
Note: Basically, makeGetter returns 2 functions that do "get" and "numForm"
||Return a pointer to the Quotes record for the given locale (lang attribute),
or nullptr if none available.
The returned value points to a hashtable entry, but will remain valid until
shutdown begins, as the table is not modified after initialization.