nagai/fune
3
0
Fork 0
forked from mirrors/gecko-dev
Code Pull requests Activity

Bug 1467377 - Fix typos in Intl and L10n documentation r=gandalf

Browse source 
MozReview-Commit-ID: 9zP6j7COEiJ

--HG--
extra : rebase_source : 35b44964d38f53f62522d0709b18d7dfa1ca8a9a
This commit is contained in:
Francesco Lodolo (:flod) 2018-06-07 08:20:49 +02:00
parent 367e64f0d4
commit fe5f3fd914
7 changed files with 74 additions and 73 deletions
repo.diff.show_diff_stats Download patch file Download diff file Expand all files Collapse all files

21
intl/docs/dataintl.rst
View file

@ -61,7 +61,7 @@ It will do a good job at formatting the date to the user locale, but it will
only be able to use the customization bits that are exposed to the Web, based on
the locale the user broadcasts to the Web and any additional settings.
But that leaves out a lot of bits of information that could inform the formatting.
But that ignores bits of information that could inform the formatting.
Public API such as :js:`Intl.*` will not be able to look into the Operating System for
regional preferences. It will also respect settings such as `Resist Fingerprinting`
@ -93,7 +93,7 @@ to use the :js:`Services.intl` wrapper.
Additional APIs
================
On top of wrapping up `Intl` API, `mozIntl` provides a number of additional features
On top of wrapping up `Intl` API, `mozIntl` provides a number of features
in form of additional options to existing APIs as well as completely new APIs.
Many of those extensions are in the process of being standardized, but are
@ -105,19 +105,20 @@ mozIntl.DateTimeFormat
----------------------
`DateTimeFormat` in `mozIntl` gets additional options that provide greater
simplicy and consistency to the API.
simplicity and consistency to the API.
* :js:`timeStyle` and :js:`dateStyle` can take values :js:`short`, :js:`medium`,
:js:`long` and :js:`full`.
Those options can replace the manual listing of tokens like :js:`year`, :js:`day`, :js:`hour` etc.
These options can replace the manual listing of tokens like :js:`year`, :js:`day`, :js:`hour` etc.
and will compose the most natural date or time format of a given style for the selected
locale.
Using :js:`timeStyle` and :js:`dateStyle` is highly recommended over listing the tokens,
because different locales may use different default styles for displaying the same tokens.
Additional value is that using those styles allows `mozIntl` to look into Operating
System patterns which allow the user to customize those patterns to their liking.
Additional value is that using those styles allows `mozIntl` to look into
Operating System patterns, which gives users the ability to customize those
patterns to their liking.
Example use:
@ -130,7 +131,7 @@ Example use:
let value = dtf.format(new Date());
This will select the best locale to match the current Gecko application locale,
then potentially check for Operating System regional preferneces customizations,
then potentially check for Operating System regional preferences customizations,
produce the correct pattern for short date+time style and format the date into it.
@ -178,7 +179,7 @@ mozIntl.getDisplayNames(locales, options)
-----------------------------------------
:js:`getDisplayNames` API is useful to retrieve various terms available in the
internationalization API.
internationalization API.
The API takes a locale fallback chain list, and an options object which can contain
two keys:
@ -240,10 +241,10 @@ mozIntl.RelativeTimeFormat(locales, options)
--------------------------------------------
API which can be used to format an interval or a date into a textual
representation of a relative time such as **5 minutes ago** or **in 2 days**.
representation of a relative time, such as **5 minutes ago** or **in 2 days**.
This API is in the process of standardization and in its raw form will not handle
any calculations to select the best unit. It is inteded to just offer a way
any calculations to select the best unit. It is intended to just offer a way
to format a value.
`mozIntl` wrapper extends the functionality providing the calculations and

4
intl/docs/index.rst
View file

@ -6,12 +6,12 @@ Internationalization (`"i18n"`) is a domain of computer science focused on makin
software accessible across languages, regions and cultures.
A combination of those is called a `locale`.
On the most abstract level, Gecko internationalizaion is a set of algorithms,
On the most abstract level, Gecko internationalization is a set of algorithms,
data structures and APIs that aim to enable Gecko to work with all human scripts and
languages, both as a UI toolkit and as a web engine.
In order to achieve that, i18n has to hook into many components such as layout, gfx, dom,
widget, build, front-end, JS engine and accessiblity.
widget, build, front-end, JS engine and accessibility.
It also has to be available across programming languages and frameworks used in the
platform and front-end.

53
intl/docs/locale.rst
View file

@ -30,7 +30,7 @@ Locale data structure consists of four primary fields.
`BCP 47`_ specifies the syntax for each of those fields (called subtags) when
represented as a string. The syntax defines the allowed selection of characters,
their capitalization and order in which the fields should be defined.
their capitalization, and the order in which the fields should be defined.
Most of the base subtags are valid ISO codes, such as `ISO 639`_ for
language subtag, or `ISO 3166-1`_ for region.
@ -38,7 +38,7 @@ language subtag, or `ISO 3166-1`_ for region.
The examples above present language tags with several fields omitted, which is allowed
by the standard.
On top of that a locale may contain:
On top of that, a locale may contain:
- extensions and private fields
These fields can be used to carry additional information about a locale.
@ -97,10 +97,10 @@ Language Negotiation
====================
Due to the imperfections in data matching, all operations on locales should always
use a language negotiation algorithm to resolve the best available set of locales
use a language negotiation algorithm to resolve the best available set of locales,
based on the list of all available locales and an ordered list of requested locales.
Such algorithms may vary in sophistication and number of used strategies. Mozilla's
Such algorithms may vary in sophistication and number of strategies. Mozilla's
solution is based on modified logic from `RFC 5656`_.
The three lists of locales used in negotiation:
@ -109,8 +109,9 @@ The three lists of locales used in negotiation:
- **Requested** - locales that the user selected in decreasing order of preference
- **Resolved** - result of the negotiation
The result of a negotiation is an ordered list of locales that are available to the system
and it is expected for the consumer to attempt using the locales in the resolved order.
The result of a negotiation is an ordered list of locales that are available to
the system, and the consumer is expected to attempt using the locales in the
resolved order.
Negotiation should be used in all scenarios like selecting language resources,
calendar, number formatting, etc.
@ -166,8 +167,8 @@ offers three language negotiation strategies:
Filtering
^^^^^^^^^
This is the most common scenario, where there is a benefit to creating a maximal
possible list of locales that the user may benefit from.
This is the most common scenario, where there is an advantage in creating a
maximal possible list of locales that the user may benefit from.
An example of a scenario:
@ -218,7 +219,7 @@ Lookup
^^^^^^
The third strategy should be used in cases where no matter what, only one locale
can be every used. Some third-party APIs don't support fallback and it doesn't make
can be ever used. Some third-party APIs don't support fallback and it doesn't make
sense to continue resolving after finding the first locale.
It is still advised to continue using this API as a fallback chain list, just in
@ -241,7 +242,7 @@ Default Locale
--------------
Besides *Available*, *Requested* and *Resolved* locale lists, there's also a concept
of *DefaultLocale* which is a single locale out of the list of available ones that
of *DefaultLocale*, which is a single locale out of the list of available ones that
should be used in case there is no match to be found between available and
requested locales.
@ -268,7 +269,7 @@ In some cases the user may want to link a language selection to another componen
For example, a Firefox extension may come with its own list of available locales, which
may have locales that Firefox doesn't.
In that case, negotiation between user requested locales and the addon's list may result
In that case, negotiation between user requested locales and the add-on's list may result
in a selection of locales superseding that of Firefox itself.
@ -284,36 +285,36 @@ in a selection of locales superseding that of Firefox itself.
Requested |
+----------------+
| es, fr, pl, ar |
+----------------+ Addon Locales
+----------------+ Add-on Locales
| +------------+
+--------------> | es, fr, ar |
Addon Available | +------------+
Add-on Available | +------------+
+-----------------+
| de, es, fr, ar |
+-----------------+
In that case, an addon may end up being displayed in Spanish, while Firefox UI will
use French. In most cases this is a bad UX.
In that case, an add-on may end up being displayed in Spanish, while Firefox UI will
use French. In most cases this results in a bad UX.
In order to avoid that, one can chain the addon negotiation and take Firefox's resolved
locales as a `requested` and negotiate that against the addons' `available` list.
In order to avoid that, one can chain the add-on negotiation and take Firefox's resolved
locales as a `requested`, and negotiate that against the add-ons' `available` list.
.. code-block:: none
Fx Available
+-------------+
| it, ar, fr |
+-------------+ Fx Locales (as Addon Requested)
+-------------+ Fx Locales (as Add-on Requested)
| +--------+
+--------------> | fr, ar |
| +--------+
Requested | | Addon Locales
Requested | | Add-on Locales
+----------------+ | +--------+
| es, fr, pl, ar | +-------------> | fr, ar |
+----------------+ | +--------+
|
Addon Available |
Add-on Available |
+-----------------+
| de, es, ar, fr |
+-----------------+
@ -396,8 +397,8 @@ UI Direction
Since the UI direction is so tightly coupled with the locale selection, the
main method of testing the directionality of the Gecko app lives in LocaleService.
:js:`LocaleService::IsAppLocaleRTL` returns a boolean indicating the current
direction of the app UI.
:js:`LocaleService::IsAppLocaleRTL` returns a boolean indicating if the current
direction of the app UI is right-to-left.
Default and Last Fallback Locales
=================================
@ -408,11 +409,11 @@ as the default locale in case language negotiation cannot find any match, and al
as the last locale to look for in a fallback chain.
If all else fails, Gecko also support a notion of last fallback locale, which is
currently hardcoded to *"en-US"* and is the very final locale to try in case
currently hardcoded to *"en-US"*, and is the very final locale to try in case
nothing else (including the default locale) works.
Notice that Unicode and ICU use *"en-GB"* in that role because more English speaking
people around the World recognize British regional preferences than American (metric vs.
imperial, fahrenheit vs celsius etc.).
imperial, Fahrenheit vs Celsius etc.).
Mozilla may switch to *"en-GB"* in the future.
Packaged Locales
@ -484,7 +485,7 @@ First, it is necessary to add a new locale to the available ones, then change
the requested, and only that will result in a new negotiation and language
change happening.
There are two primary ways to add locale to available ones.
There are two primary ways to add a locale to available ones.
Testing Localization
--------------------
@ -533,7 +534,7 @@ but it is also simpler:
let appLocales = Services.locale.getAppLocalesAsBCP47();
assert(appLocales[0], "ko-KR");
In the future, Mozilla plans to add a third way for addons (`bug 1440969`_)
In the future, Mozilla plans to add a third way for add-ons (`bug 1440969`_)
to allow for either manual or automated testing purposes disconnecting its locales
from the main application ones.

21
intl/docs/locale_startup.rst
View file

@ -15,7 +15,7 @@ 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 changes.
in result the values for those lists change.
Data Sources
------------
@ -34,8 +34,8 @@ Bootstrap
1) Packaged Data
^^^^^^^^^^^^^^^^
In the `server` mode Gecko starts with no knowledge of available locales, nor of
`requested`.
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.
@ -44,10 +44,10 @@ 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 what locale the JS context should use as
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
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.
@ -78,15 +78,15 @@ ones. In that case, :js:`intl:app-locales-changed` will be broadcasted.
3) Language Packs Registered
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Finally, the AddonManager registers all the language packs and they get added to
:js:`L10nRegistry` and in result update LocaleService's available locales.
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
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.
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.
@ -94,4 +94,3 @@ on :js:`intl:app-locales-changed` and update the code when the locale list chang
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.

6
intl/docs/localization.rst
View file

@ -114,7 +114,7 @@ is exposed to localization tools, like Pontoon, and build automation.
From that moment localizers will work on providing translations for the new feature
either while the new strings are only in Nightly or after they are merged to Beta.
The goal is to have as much of the UI ready in as many locales as early as possible,
but the process is continous and we're capable of releasing Firefox with incomplete
but the process is continuous and we're capable of releasing Firefox with incomplete
translations falling back on a backup locale in case of a missing string.
While Nightly products use the latest version of localization available in repositories,
@ -204,7 +204,7 @@ and limitations of the previous systems.
It's well suited for modern web development cycle, provides a number of localization
features including good internationalization model and strong bidirectionality support.
Fluent strictly superseeds the old systems and is currently being slowly introduced to
Fluent strictly supersedes the old systems and is currently being slowly introduced to
Firefox and all other Mozilla products with the goal to become the only
unified localization system at Mozilla and a foundation of the future localization
standard.
@ -214,4 +214,4 @@ To learn more about Fluent, follow the `Fluent for Firefox Developers`_ guide.
.. _Pontoon: https://pontoon.mozilla.org/
.. _hg.mozilla.org/l10n-central: https://hg.mozilla.org/l10n-central/
.. _L10n Drivers Team: https://wiki.mozilla.org/L10n:Mozilla_Team
.. _Fluent For Firefox Developers: ./l10n/docs/l10n/index.html
.. _Fluent For Firefox Developers: ./l10n/docs/l10n/index.html

38
intl/l10n/docs/fluent_tutorial.rst
View file

@ -25,7 +25,7 @@ migrations are performed manually with a lot of oversight from the involved
stakeholders.
In this initial phase, `Firefox Preferences`_ is being migrated as the first target
and as a result, the first bindings to be stabilized are for chrome-privileged
and, as a result, the first bindings to be stabilized are for chrome-privileged
XUL context.
From there we plan to focus on two areas:
@ -35,7 +35,7 @@ From there we plan to focus on two areas:
The end goal is replacing all uses of DTD and StringBundle within Firefox's codebase.
If you want to use Fluent and your code involves one of the areas currently unsupported,
If you want to use Fluent, and your code involves one of the areas currently unsupported,
we'd like to work with you on getting Fluent ready for your code.
@ -363,7 +363,7 @@ __ https://github.com/projectfluent/fluent/wiki/BiDi-in-Fluent
});
A message like this localized to American English will correctly wrap the user
name in directionality marks allowing the layout engine to determine how to
name in directionality marks, allowing the layout engine to determine how to
display the bidirectional text.
On the other hand, the same message localized to Arabic will use the Eastern Arabic
@ -397,7 +397,7 @@ language requires that:
*[other] You have { $unreadCount } unread messages
}
Fluent guesses that since the variant selection is performed based on a number,
Fluent guesses that, since the variant selection is performed based on a number,
its `plural category`__ should be retrieved.
If the given translation doesn't need pluralization for the string (for example
@ -492,17 +492,17 @@ Registering New L10n Files
In the previous system, a new localization file had to be registered in order to
add it in the `jar.mn` file for packaging.
Fluent uses a wildcard statement packaging all localization resources into
Fluent uses a wildcard statement, packaging all localization resources into
their component's `/localization/` directory.
That means that, if a new file is added to a component of Firefox already
covered by Fluent like `browser`, it's enough to add the new file to the
repository in a path like `browser/locales/en-US/browser/component/file.ftl` and
repository in a path like `browser/locales/en-US/browser/component/file.ftl`, and
the toolchain will package it into `browser/localization/browser/component/file.ftl`.
At runtime Firefox uses a special registry for all localization data. It will
register the browser's `/localization/` directory and make all files inside it
available to be references.
available to be referenced.
To make the document localized using Fluent, all the developer has to do is add
a single polyfill for the Fluent API to the source and list the resources
@ -515,7 +515,7 @@ that will be used:
<script src="chrome://global/content/l10n.js"></script>
For performance reasons the :html:`<link/>` elements have to be specified above the
:html:`<script/>` and the :html:`<script/>` itself has to be synchronous in order to ensure
:html:`<script/>`, and the :html:`<script/>` itself has to be synchronous in order to ensure
that the localization happens before first paint.
This allows Fluent to trigger asynchronous resource loading early enough to
@ -536,7 +536,7 @@ In almost all scenarios that's sufficient.
In rare edge cases where the developer needs to fetch additional resources, or
the same resources in another language, it is possible to create additional
contexts manually using `Localization` class:
contexts manually using the `Localization` class:
.. code-block:: javascript
@ -556,7 +556,7 @@ contexts manually using `Localization` class:
.. admonition:: Example
An example of a use case is the Preferences UI in Firefox which uses the
An example of a use case is the Preferences UI in Firefox, which uses the
main context to localize the UI but also to build a search index.
It is common to build such search index both in a current language and additionally
@ -570,7 +570,7 @@ Designing Localizable APIs
When designing localizable APIs, the most important rule is to resolve localization as
late as possible. That means that instead of resolving strings somewhere deep in the
codebase and then passing them on or even caching, it is highly recommended to pass
codebase and then passing them on, or even caching, it is highly recommended to pass
around :code:`l10n-id` or :code:`[l10n-id, l10n-args]` pairs until the top-most code
resolves them or applies them onto the DOM element.
@ -620,22 +620,22 @@ Pseudolocalization
When working with a Fluent-backed UI, the developer gets a new tool to test their UI
against several classes of problems.
Pseudolocalization is a mechanism which transforms messages on-fly, using specific
logic to help emulate how the UI will look once it gets localized.
Pseudolocalization is a mechanism which transforms messages on the fly, using
specific logic to help emulate how the UI will look once it gets localized.
The three classes of potential problems that this can help with are:
- Hardcoded strings.
Turning on pseudolocalization should expose any string that were left
hardcoded in the source, since they won't get transfomed.
Turning on pseudolocalization should expose any strings that were left
hardcoded in the source, since they won't get transformed.
- UI space not adapting to longer text.
Many languages use longer strings than English. For example, German string
may be 30% longer. Turning on pseudolocalization is a quick way to test how
the layout handles such locales.
Many languages use longer strings than English. For example, German strings
may be 30% longer (or more). Turning on pseudolocalization is a quick way to
test how the layout handles such locales.
- Bidi adaptation.
@ -651,7 +651,7 @@ select the strategy to be used:
- :js:`accented` - Ȧȧƈƈḗḗƞŧḗḗḓ Ḗḗƞɠŀīīşħ
This strategy replaces all Latin characters with their accented equivalents,
and duplicates some vovels to create roughly 30% longer strings.
and duplicates some vowels to create roughly 30% longer strings.
- :js:`bidi` - ɥsıʅƃuƎ ıpıԐ

4
intl/l10n/docs/index.rst
View file

@ -5,8 +5,8 @@ Fluent
`Fluent`_ is a new localization system, developed by Mozilla, which aims to replace
all existing localization models currently used at Mozilla.
In case of Firefox it directly superseeds DTD and StringBundle systems providing
a large number of new features and improvements over them both, for developers
In case of Firefox it directly supersedes DTD and StringBundle systems, providing
a large number of new features and improvements over both of them, for developers
and localizers.
.. toctree::