Adding upstream version 115.7.0esr.upstream/115.7.0esr

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

3 files changed, 1078 insertions, 0 deletions

diff --git a/intl/l10n/docs/fluent/index.rst b/intl/l10n/docs/fluent/index.rst
new file mode 100644
index 0000000000..84103db5e4
--- /dev/null
+++ b/intl/l10n/docs/fluent/index.rst
@@ -0,0 +1,25 @@
+======
+Fluent
+======
+
+`Fluent`_ is a localization system developed by Mozilla, which aims to replace
+all existing localization models currently used at Mozilla.
+
+In case of Firefox it directly supersedes DTD and StringBundle systems, providing
+a large number of features and improvements over both of them, for developers
+and localizers.
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorial
+   review
+
+Other resources:
+
+ * `Fluent Syntax Guide <http://projectfluent.org/fluent/guide/>`_
+ * `Fluent Wiki <https://github.com/projectfluent/fluent/wiki>`_
+ * `Fluent.js Wiki <https://github.com/projectfluent/fluent.js/wiki>`_
+ * `Fluent DOM L10n Tutorial <https://projectfluent.org/dom-l10n-documentation/>`_
+
+.. _Fluent: http://projectfluent.org/
diff --git a/intl/l10n/docs/fluent/review.rst b/intl/l10n/docs/fluent/review.rst
new file mode 100644
index 0000000000..83d65ebed9
--- /dev/null
+++ b/intl/l10n/docs/fluent/review.rst
@@ -0,0 +1,303 @@
+.. role:: bash(code)
+   :language: bash
+
+.. role:: js(code)
+   :language: javascript
+
+===============================
+Guidelines for Fluent Reviewers
+===============================
+
+This document is intended as a guideline for developers and reviewers when
+working with FTL (Fluent) files. As such, it’s not meant to replace the
+`existing extensive documentation`__ about Fluent.
+
+__ ./tutorial.html
+
+`Herald`_ is used to set the group `fluent-reviewers`_ as blocking reviewer for
+any patch modifying FTL files committed to Phabricator. The person from this
+group performing the review will have to manually set other reviewers as
+blocking, if the original developer didn’t originally do it.
+
+
+.. hint::
+
+  In case of doubt, you should always reach out to the l10n team for
+  clarifications.
+
+
+Message Identifiers
+===================
+
+While in Fluent it’s possible to use both lowercase and uppercase characters in
+message identifiers, the naming convention in Gecko is to use lowercase and
+hyphens (*kebab-case*), avoiding CamelCase and underscores. For example,
+:js:`allow-button` should be preferred to :js:`allow_button` or
+:js:`allowButton`, unless there are technically constraints – like identifiers
+generated at run-time from external sources – that make this impractical.
+
+When importing multiple FTL files, all messages share the same scope in the
+Fluent bundle. For that reason, it’s suggested to add scope to the message
+identifier itself: using :js:`cancel` as an identifier increases the chances of
+having a conflict, :js:`save-dialog-cancel-button` would make it less likely.
+
+Message identifiers are also used as the ultimate fall back in case of run-time
+errors. Having a descriptive message ID would make such fall back more useful
+for the user.
+
+Comments
+========
+
+When a message includes placeables (variables), there should always be a
+comment explaining the format of the variable, and what kind of content it will
+be replaced with. This is the format suggested for such comments:
+
+
+.. code-block:: fluent
+
+  # This string is used on a new line below the add-on name
+  # Variables:
+  #   $name (String) - Add-on author name
+  cfr-doorhanger-extension-author = by { $name }
+
+
+By default, a comment is bound to the message immediately following it. Fluent
+supports both `file-level and group-level comments`__. Be aware that a group
+comment will apply to all messages following that comment until the end of the
+file. If that shouldn’t be the case, you’ll need to “reset” the group comment,
+by adding an empty one (:js:`##`), or moving the section of messages at the end
+of the file.
+
+__ https://projectfluent.org/fluent/guide/comments.html
+
+Comments are fundamental for localizers, since they don’t see the file as a
+whole, or changes as a fragment of a larger patch. Their work happens on a
+message at a time, and the context is only provided by comments.
+
+License headers are standalone comments, that is, a single :js:`#` as prefix,
+and the comment is followed by at least one empty line.
+
+Changes to Existing Messages
+============================
+
+You must update the message identifier if:
+
+- The meaning of the sentence has changed.
+- You’re changing the morphology of the message, by adding or removing attributes.
+
+Messages are identified in the entire localization toolchain by their ID. For
+this reason, there’s no need to change attribute names.
+
+If your changes are relevant only for English — for example, to correct a
+typographical error or to make letter case consistent — then there is generally
+no need to update the message identifier.
+
+There is a grey area between needing a new ID or not. In some cases, it will be
+necessary to look at all the existing translations to determine if a new ID
+would be beneficial. You should always reach out to the l10n team in case of
+doubt.
+
+Changing the message ID will invalidate the existing translation, the new
+message will be reported as missing in all tools, and localizers will have to
+retranslate it. This is the only reliable method to ensure that localizers
+update existing localizations, and run-time stop using obsolete translations.
+
+You must also update all instances where that message identifier is used in the
+source code, including localization comments.
+
+Non-text Elements in Messages
+=============================
+
+When a message includes non text-elements – like anchors or images – make sure
+that they have a :js:`data-l10n-name` associated to them. Additional
+attributes, like the URL for an anchor or CSS classes, should not be exposed
+for localization in the FTL file. More details can be found in `this page`__
+dedicated to DOM overlays.
+
+__ https://github.com/projectfluent/fluent.js/wiki/DOM-Overlays#text-level-elements
+
+This information is not relevant if your code is using `fluent-react`_, where
+DOM overlays `work differently`__.
+
+__ https://github.com/projectfluent/fluent.js/wiki/React-Overlays
+
+Message References
+==================
+
+Consider the following example:
+
+
+.. code-block:: fluent
+
+  newtab-search-box-search-the-web-text = Search the Web
+  newtab-search-box-search-the-web-input =
+      .placeholder = { newtab-search-box-search-the-web-text }
+      .title = { newtab-search-box-search-the-web-text }
+
+
+This might seem to reduce the work for localizers, but it actually doesn’t
+help:
+
+- A change to the referenced message (:js:`newtab-search-box-search-the-web-text`)
+  would require a new ID also for all messages referencing it.
+- Translation memory can help with matching text, not with message references.
+
+On the other hand, this approach is helpful if, for example, you want to
+reference another element of the UI in your message:
+
+
+.. code-block:: fluent
+
+  help-button = Help
+  help-explanation = Click the { help-button} to access support
+
+
+This enforces consistency and, if :js:`help-button` changes, all other messages
+will need to be updated anyway.
+
+Terms
+=====
+
+Fluent supports a specific type of message, called `term`_. Terms are similar
+to regular messages but they can only be used as references in other messages.
+They are best used to define vocabulary and glossary items which can be used
+consistently across the localization of the entire product.
+
+Terms are typically used for brand names, like :js:`Firefox` or :js:`Mozilla`:
+it allows to have them in one easily identifiable place, and raise warnings
+when a localization is not using them. It helps enforcing consistency and brand
+protection. If you simply need to reference a message from another message, you
+don’t need a term: cross references between messages are allowed, but they
+should not be abused, as already described.
+
+Variants and plurals
+====================
+
+Consider the following example:
+
+
+.. code-block:: fluent
+
+  items-selected =
+      { $num ->
+          [0] Select items.
+          [one] One item selected.
+         *[other] { $num } items selected.
+      }
+
+
+In this example, there’s no guarantee that all localizations will have this
+variant covered, since variants are private by design. The correct approach for
+the example would be to have a separate message for the :js:`0` case:
+
+
+.. code-block:: fluent
+
+  # Separate messages which serve different purposes.
+  items-select = Select items
+  # The default variant works for all values of the selector.
+  items-selected =
+      { $num ->
+          [one] One item selected.
+         *[other] { $num } items selected.
+      }
+
+
+As a rule of thumb:
+
+- Use variants only if the default variant makes sense for all possible values
+  of the selector.
+- The code shouldn’t depend on the availability of a specific variant.
+
+More examples about selector and variant abuses can be found in `this wiki`__.
+
+__ https://github.com/projectfluent/fluent/wiki/Good-Practices-for-Developers#prefer-separate-messages-over-variants-for-ui-logic
+
+In general, also avoid putting a selector in the middle of a sentence, like in
+the example below:
+
+
+.. code-block:: fluent
+
+  items-selected =
+      { $num ->
+          [one] One item.
+         *[other] { $num } items
+      } selected.
+
+
+:js:`1` should only be used in case you want to cover the literal number. If
+it’s a standard plural, you should use the :js:`one` category for singular.
+Also make sure to always pass the variable to these messages as a number, not
+as a string.
+
+Access Keys
+===========
+
+The following is a simple potential example of an access key:
+
+.. code-block:: fluent
+
+  example-menu-item =
+      .label = Menu Item
+      .accesskey = M
+
+Access keys are used in menus in order to help provide easy keyboard shortcut access. They
+are useful for both power users, and for users who have accessibility needs. It is
+helpful to first read the `Access keys`__ guide in the Windows Developer documentation,
+as it outlines the best practices for Windows applications.
+
+__ https://docs.microsoft.com/en-us/windows/uwp/design/input/access-keys
+
+There are some differences between operating systems. Linux mostly follows the same
+practices as Windows. However, macOS in general does not have good support for accesskeys,
+especially in menus.
+
+When choosing an access key, it's important that it's unique relative to the current level
+of UI. It's preferable to avoid letters with descending parts, such as :code:`g`,
+:code:`j`, :code:`p`, and :code:`q` as these will not be underlined nicely in Windows or
+Linux. Other problematic characters are ones which are narrow, such as :code:`l`,
+:code:`i` and :code:`I`. The underline may not be as visible as other letters in
+sans-serif fonts.
+
+Linter
+======
+
+:bash:`mach lint` includes a :ref:`l10n linter <L10n>`, called :bash:`moz-l10n-lint`. It
+can be run locally by developers but also runs on Treeherder: in the Build
+Status section of the diff on Phabricator, open the Treeherder Jobs link and
+look for the :js:`l1nt` job.
+
+Besides displaying errors and warnings due to syntax errors, it’s particularly
+important because it also checks for message changes without new IDs, and
+conflicts with the cross-channel repository used to ship localized versions of
+Firefox.
+
+
+.. warning::
+
+  Currently, there’s an `issue`__ preventing warnings to be displayed in
+  Phabricator. Checks can be run locally using :bash:`./mach lint -l l10n -W`.
+
+  __ https://github.com/mozilla/code-review/issues/32
+
+
+Migrating Strings From Legacy or Fluent Files
+=============================================
+
+If a patch is moving legacy strings (.properties, .DTD) to Fluent, it should
+also include a recipe to migrate existing strings to FTL messages. The same is
+applicable if a patch moves existing Fluent messages to a different file, or
+changes the morphology of existing messages without actual changes to the
+content.
+
+Documentation on how to write and test migration recipes is available in `this
+page`__.
+
+__ ./fluent_migrations.html
+
+
+.. _Herald: https://phabricator.services.mozilla.com/herald/
+.. _fluent-reviewers: https://phabricator.services.mozilla.com/tag/fluent-reviewers/
+.. _fluent-react: https://github.com/projectfluent/fluent.js/wiki/React-Bindings
+.. _term: https://projectfluent.org/fluent/guide/terms.html
diff --git a/intl/l10n/docs/fluent/tutorial.rst b/intl/l10n/docs/fluent/tutorial.rst
new file mode 100644
index 0000000000..1312efd448
--- /dev/null
+++ b/intl/l10n/docs/fluent/tutorial.rst
@@ -0,0 +1,750 @@
+.. role:: html(code)
+   :language: html
+
+.. role:: js(code)
+   :language: javascript
+
+=============================
+Fluent for Firefox Developers
+=============================
+
+
+This tutorial is intended for Firefox engineers already familiar with the previous
+localization systems offered by Gecko - `DTD`_ and  `StringBundle`_ - and assumes
+prior experience with those systems.
+
+For a more hands-on tutorial of understanding Fluent from the ground up, try
+following the `Fluent DOMLocalization Tutorial`__, which provides some background on
+how Fluent works and walks you through creating a basic web project from scratch that
+uses Fluent for localization.
+
+__ https://projectfluent.org/dom-l10n-documentation/
+
+Using Fluent in Gecko
+=====================
+
+`Fluent`_ is a modern localization system introduced into
+the Gecko platform with a focus on quality, performance, maintenance and completeness.
+
+The legacy DTD system is deprecated, and Fluent should be used where possible.
+
+Getting a Review
+----------------
+
+If you work on any patch that touches FTL files, you'll need to get a review
+from `fluent-reviewers`__. There's a Herald hook that automatically sets
+that group as a blocking reviewer.
+
+__ https://phabricator.services.mozilla.com/tag/fluent-reviewers/
+
+Guidelines for the review process are available `here`__.
+
+__ ./fluent_review.html
+
+To lighten the burden on reviewers, please take a moment to review some
+best practices before submitting your patch for review.
+
+-  `ProjectFluent Good Practices for Developers`_
+-  `Mozilla Localization Best Practices For Developers`_
+
+.. _ProjectFluent Good Practices for Developers: https://github.com/projectfluent/fluent/wiki/Good-Practices-for-Developers
+.. _Mozilla Localization Best Practices For Developers: https://mozilla-l10n.github.io/documentation/localization/dev_best_practices.html
+
+Major Benefits
+==============
+
+Fluent `ties tightly`__ into the domain of internationalization
+through `Unicode`_, `CLDR`_ and `ICU`_.
+
+__ https://github.com/projectfluent/fluent/wiki/Fluent-and-Standards
+
+More specifically, the most observable benefits for each group of consumers are
+
+
+Developers
+----------
+
+ - Support for XUL, XHTML, HTML, Web Components, React, JS, Python and Rust
+ - Strings are available in a single, unified localization context available for both DOM and runtime code
+ - Full internationalization (i18n) support: date and time formatting, number formatting, plurals, genders etc.
+ - Strong focus on `declarative API via DOM attributes`__
+ - Extensible with custom formatters, Mozilla-specific APIs etc.
+ - `Separation of concerns`__: localization details, and the added complexity of some languages, don't leak onto the source code and are no concern for developers
+ - Compound messages link a single translation unit to a single UI element
+ - `DOM Overlays`__ allow for localization of DOM fragments
+ - Simplified build system model
+ - No need for pre-processing instructions
+ - Support for pseudolocalization
+
+__ https://github.com/projectfluent/fluent/wiki/Get-Started
+__ https://github.com/projectfluent/fluent/wiki/Design-Principles
+__ https://github.com/projectfluent/fluent.js/wiki/DOM-Overlays
+
+
+Product Quality
+------------------
+
+ - A robust, multilevel, `error fallback system`__ prevents XML errors and runtime errors
+ - Simplified l10n API reduces the amount of l10n specific code and resulting bugs
+ - Runtime localization allows for dynamic language changes and updates over-the-air
+ - DOM Overlays increase localization security
+
+__ https://github.com/projectfluent/fluent/wiki/Error-Handling
+
+
+Fluent Translation List - FTL
+=============================
+
+Fluent introduces a file format designed specifically for easy readability
+and the localization features offered by the system.
+
+At first glance the format is a simple key-value store. It may look like this:
+
+.. code-block:: fluent
+
+  home-page-header = Home Page
+
+  # The label of a button opening a new tab
+  new-tab-open = Open New Tab
+
+But the FTL file format is significantly more powerful and the additional features
+quickly add up. In order to familiarize yourself with the basic features,
+consider reading through the `Fluent Syntax Guide`_ to understand
+a more complex example like:
+
+.. code-block:: fluent
+
+  ### These messages correspond to security and privacy user interface.
+  ###
+  ### Please choose simple and non-threatening language when localizing
+  ### to help user feel in control when interacting with the UI.
+
+  ## General Section
+
+  -brand-short-name = Firefox
+      .gender = masculine
+
+  pref-pane =
+      .title =
+          { PLATFORM() ->
+              [windows] Options
+             *[other] Preferences
+          }
+      .accesskey = C
+
+  # Variables:
+  #   $tabCount (Number) - number of container tabs to be closed
+  containers-disable-alert-ok-button =
+      { $tabCount ->
+          [one] Close { $tabCount } Container Tab
+         *[other] Close { $tabCount } Container Tabs
+      }
+
+  update-application-info =
+      You are using { -brand-short-name } Version: { $version }.
+      Please read the <a>privacy policy</a>.
+
+The above, of course, is a particular selection of complex strings intended to exemplify
+the new features and concepts introduced by Fluent.
+
+.. important::
+
+  While in Fluent it’s possible to use both lowercase and uppercase characters in message
+  identifiers, the naming convention in Gecko is to use lowercase and hyphens, avoiding
+  CamelCase and underscores. For example, `allow-button` should be preferred to
+  `allow_button` or `allowButton`, unless there are technically constraints – like
+  identifiers generated at run-time from external sources – that make this impractical.
+
+In order to ensure the quality of the output, a lot of checks and tooling
+is part of the build system.
+`Pontoon`_, the main localization tool used to translate Firefox, also supports
+Fluent and its features to help localizers in their work.
+
+
+.. _fluent-tutorial-social-contract:
+
+Social Contract
+===============
+
+Fluent uses the concept of a `social contract` between developer and localizers.
+This contract is established by the selection of a unique identifier, called :js:`l10n-id`,
+which carries a promise of being used in a particular place to carry a particular meaning.
+
+The use of unique identifiers is shared with legacy localization systems in
+Firefox.
+
+.. important::
+
+  An important part of the contract is that the developer commits to treat the
+  localization output as `opaque`. That means that no concatenations, replacements
+  or splitting should happen after the translation is completed to generate the
+  desired output.
+
+In return, localizers enter the social contract by promising to provide an accurate
+and clean translation of the messages that match the request.
+
+In Fluent, the developer is not to be bothered with inner logic and complexity that the
+localization will use to construct the response. Whether `declensions`__ or other
+variant selection techniques are used is up to a localizer and their particular translation.
+From the developer perspective, Fluent returns a final string to be presented to
+the user, with no l10n logic required in the running code.
+
+__ https://en.wikipedia.org/wiki/Declension
+
+
+Markup Localization
+===================
+
+To localize an element in Fluent, the developer adds a new message to
+an FTL file and then has to associate an :js:`l10n-id` with the element
+by defining a :js:`data-l10n-id` attribute:
+
+.. code-block:: html
+
+  <h1 data-l10n-id="home-page-header" />
+
+  <button data-l10n-id="pref-pane" />
+
+Fluent will take care of the rest, populating the element with the message value
+in its content and all localizable attributes if defined.
+
+The developer provides only a single message to localize the whole element,
+including the value and selected attributes.
+
+The value can be a whole fragment of DOM:
+
+.. code-block:: html
+
+  <p data-l10n-id="update-application-info" data-l10n-args='{"version": "60.0"}'>
+    <a data-l10n-name="privacy-url" href="http://www.mozilla.org/privacy" />
+  </p>
+
+.. code-block:: fluent
+
+  -brand-short-name = Firefox
+  update-application-info =
+      You are using { -brand-short-name } Version: { $version }.
+      Please read the <a data-l10n-name="privacy-url">privacy policy</a>.
+
+
+Fluent will overlay the translation onto the source fragment preserving attributes like
+:code:`class` and :code:`href` from the source and adding translations for the elements
+inside. The resulting localized content will look like this:
+
+.. code-block::
+
+  <p data-l10n-id="update-application-info" data-l10n-args='{"version": "60.0"}'">
+    You are using Firefox Version: 60.0.
+    Please read the <a href="http://www.mozilla.org/privacy">privacy policy</a>.
+  </p>
+
+
+This operation is sanitized, and Fluent takes care of selecting which elements and
+attributes can be safely provided by the localization.
+The list of allowed elements and attributes is `maintained by the W3C`__, and if
+the developer needs to allow for localization of additional attributes, they can
+allow them using :code:`data-l10n-attrs` list:
+
+.. code-block:: html
+
+  <label data-l10n-id="search-input" data-l10n-attrs="style" />
+
+The above example adds an attribute :code:`style` to be allowed on this
+particular :code:`label` element.
+
+
+External Arguments
+------------------
+
+Notice in the previous example the attribute :code:`data-l10n-args`, which is
+a JSON object storing variables exposed by the developer to the localizer.
+
+This is the main channel for the developer to provide additional variables
+to be used in the localization.
+
+Arguments are rarely needed for situations where it’s currently possible to use
+DTD, since such variables would need to be computed from the code at runtime.
+It's worth noting that, when the :code:`l10n-args` are set in
+the runtime code, they are in fact encoded as JSON and stored together with
+:code:`l10n-id` as an attribute of the element.
+
+__ https://www.w3.org/TR/2011/WD-html5-20110525/text-level-semantics.html
+
+
+Runtime Localization
+====================
+
+In almost every case the JS runtime code will operate on a particular document, either
+XUL, XHTML or HTML.
+
+If the document has its markup already localized, then Fluent exposes a new
+attribute on the :js:`document` element - :js:`document.l10n`.
+
+This property is an object of type :js:`DOMLocalization` which maintains the main
+localization context for this document and exposes it to runtime code as well.
+
+With a focus on `declarative localization`__, the primary method of localization is
+to alter the localization attributes in the DOM. Fluent provides a method to facilitate this:
+
+.. code-block:: javascript
+
+  document.l10n.setAttributes(element, "new-panel-header");
+
+This will set the :code:`data-l10n-id` on the element and translate it before the next
+animation frame.
+
+This API can be used to set both the ID and the arguments at the same time.
+
+.. code-block:: javascript
+
+  document.l10n.setAttributes(element, "containers-disable-alert-ok-button", {
+    tabCount: 5
+  });
+
+If only the arguments need to be updated, then it's possible to use the :code:`setArgs`
+method.
+
+.. code-block:: javascript
+
+  document.l10n.setArgs(element, {
+    tabCount: 5
+  });
+
+On debug builds if the Fluent arguments are not provided, then Firefox will crash. This
+is done so that these errors are caught in CI. On rare occasions it may be necessary
+to work around this crash by providing a blank string as an argument value.
+
+__ https://github.com/projectfluent/fluent/wiki/Good-Practices-for-Developers
+
+
+Non-Markup Localization
+-----------------------
+
+In rare cases, when the runtime code needs to retrieve the translation and not
+apply it onto the DOM, Fluent provides an API to retrieve it:
+
+.. code-block:: javascript
+
+  let [ msg ] = await document.l10n.formatValues([
+    {id: "remove-containers-description"}
+  ]);
+
+  alert(msg);
+
+This model is heavily discouraged and should be used only in cases where the
+DOM annotation is not possible.
+
+.. note::
+
+  This API is available as asynchronous. In case of Firefox,
+  the only non-DOM localizable calls are used where the output goes to
+  a third-party like Bluetooth, Notifications etc.
+  All those cases should already be asynchronous. If you can't avoid synchronous
+  access, you can use ``mozILocalization.formatMessagesSync`` with synchronous IO.
+
+
+Internationalization
+====================
+
+The majority of internationalization issues are implicitly handled by Fluent without
+any additional requirement. Full Unicode support, `bidirectionality`__, and
+correct number formatting work without any action required from either
+developer or localizer.
+
+__ https://github.com/projectfluent/fluent/wiki/BiDi-in-Fluent
+
+.. code-block:: javascript
+
+  document.l10n.setAttributes(element, "welcome-message", {
+    userName: "اليسع",
+    count: 5
+  });
+
+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
+display the bidirectional text.
+
+On the other hand, the same message localized to Arabic will use the Eastern Arabic
+numeral for number "5".
+
+
+Plural Rules
+------------
+
+The most common localization feature is the ability to provide different variants
+of the same string depending on plural categories. Fluent ties into the Unicode CLDR
+standard called `Plural Rules`_.
+
+In order to allow localizers to use it, all the developer has to do is to pass
+an external argument number:
+
+.. code-block:: javascript
+
+  document.l10n.setAttributes(element, "unread-warning", { unreadCount: 5 });
+
+Localizers can use the argument to build a multi variant message if their
+language requires that:
+
+.. code-block:: fluent
+
+  unread-warning =
+      { $unreadCount ->
+          [one] You have { $unreadCount } unread message
+         *[other] You have { $unreadCount } unread messages
+      }
+
+If the variant selection is performed based on a number, Fluent matches that
+number against literal numbers as well as its `plural category`__.
+
+If the given translation doesn't need pluralization for the string (for example
+Japanese often will not), the localizer can replace it with:
+
+.. code-block:: fluent
+
+  unread-warning = You have { $unreadCount } unread messages
+
+and the message will preserve the social contract.
+
+One additional feature is that the localizer can further improve the message by
+specifying variants for particular values:
+
+.. code-block:: fluent
+
+  unread-warning =
+      { $unreadCount ->
+          [0] You have no unread messages
+          [1] You have one unread message
+         *[other] You have { $unreadCount } unread messages
+      }
+
+The advantage here is that per-locale choices don't leak onto the source code
+and the developer is not affected.
+
+
+.. note::
+
+  There is an important distinction between a variant keyed on plural category
+  `one` and digit `1`. Although in English the two are synonymous, in other
+  languages category `one` may be used for other numbers.
+  For example in `Bosnian`__, category `one` is used for numbers like `1`, `21`, `31`
+  and so on, and also for fractional numbers like `0.1`.
+
+__ https://unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html
+__ https://unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html#bs
+
+Partially-formatted variables
+-----------------------------
+
+When it comes to formatting data, Fluent allows the developer to provide
+a set of parameters for the formatter, and the localizer can fine tune some of them.
+This technique is called `partially-formatted variables`__.
+
+For example, when formatting a date, the developer can just pass a JS :js:`Date` object,
+but its default formatting will be pretty expressive. In most cases, the developer
+may want to use some of the :js:`Intl.DateTimeFormat` options to select the default
+representation of the date in string:
+
+.. code-block:: javascript
+
+  document.l10n.formatValue("welcome-message", {
+  startDate: FluentDateTime(new Date(), {
+      year: "numeric",
+      month: "long",
+      day: "numeric"
+    })
+  });
+
+.. code-block:: fluent
+
+  welcome-message = Your session will start date: { $startDate }
+
+In most cases, that will be enough and the date would get formatted in the current
+Firefox as `February 28, 2018`.
+
+But if in some other locale the string would get too long, the localizer can fine
+tune the options as well:
+
+.. code-block:: fluent
+
+  welcome-message = Początek Twojej sesji: { DATETIME($startDate, month: "short") }
+
+This will adjust the length of the month token in the message to short and get formatted
+in Polish as `28 lut 2018`.
+
+At the moment Fluent supports two formatters that match JS Intl API counterparts:
+
+ * **NUMBER**: `Intl.NumberFormat`__
+ * **DATETIME**: `Intl.DateTimeFormat`__
+
+With time more formatters will be added. Also, this feature is not exposed
+to ``setAttributes`` at this point, as that serializes to JSON.
+
+__ https://projectfluent.org/fluent/guide/functions.html#partially-formatted-variables
+__ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat
+__ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat
+
+Registering New L10n Files
+==========================
+
+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
+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 referenced.
+
+To make the document localized using Fluent, all the developer has to do is add
+localizable resources for Fluent API to use:
+
+.. code-block:: html
+
+  <link rel="localization" href="branding/brand.ftl"/>
+  <link rel="localization" href="browser/preferences/preferences.ftl"/>
+
+The URI provided to the :html:`<link/>` element are relative paths within the localization
+system.
+
+
+Custom Localizations
+====================
+
+The above method creates a single localization context per document.
+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
+Localization object manually using the `Localization` class:
+
+.. code-block:: javascript
+
+  const myL10n = new Localization([
+    "branding/brand.ftl",
+    "browser/preferences/preferences.ftl"
+  ]);
+
+
+  let [isDefaultMsg, isNotDefaultMsg] =
+    await myL10n.formatValues({id: "is-default"}, {id: "is-not-default"});
+
+
+.. admonition:: Example
+
+  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
+  in English, since a lot of documentation and online help exist only in English.
+
+  A developer may create manually a new context with the same resources as the main one,
+  but hardcode it to `en-US` and then build the search index using both contexts.
+
+
+By default, all `Localization` contexts are asynchronous. It is possible to create a synchronous
+one by passing an `sync = false` argument to the constructor, or calling the `SetIsSync(bool)` method
+on the class.
+
+
+.. code-block:: javascript
+
+  const myL10n = new Localization([
+    "branding/brand.ftl",
+    "browser/preferences/preferences.ftl"
+  ], false);
+
+
+  let [isDefaultMsg, isNotDefaultMsg] =
+    myL10n.formatValuesSync({id: "is-default"}, {id: "is-not-default"});
+
+
+Synchronous contexts should be always avoided as they require synchronous I/O. If you think your use case
+requires a synchronous localization context, please consult Gecko, Performance and L10n Drivers teams.
+
+
+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
+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.
+
+
+Testing
+=======
+
+When writing tests that involve both I18n and L10n, the general rule is that
+result strings are opaque. That means that the developer should not assume any particular
+value and should never test against it.
+
+In case of raw i18n the :js:`resolvedOptions` method on all :js:`Intl.*` formatters
+makes it relatively easy. In case of localization, the recommended way is to test that
+the code sets the right :code:`l10n-id`/:code:`l10n-args` attributes like this:
+
+.. code-block:: javascript
+
+  testedFunction();
+
+  const l10nAttrs = document.l10n.getAttributes(element);
+
+  deepEquals(l10nAttrs, {
+    id: "my-expected-id",
+    args: {
+      unreadCount: 5
+    }
+  });
+
+If the code really has to test for particular values in the localized UI, it is
+always better to scan for a variable:
+
+.. code-block:: javascript
+
+  testedFunction();
+
+  equals(element.textContent.contains("John"));
+
+.. important::
+
+  Testing against whole values is brittle and will break when we insert Unicode
+  bidirectionality marks into the result string or adapt the output in other ways.
+
+
+Manually Testing UI with 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 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 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 strings
+   may be 30% longer (or more). Turning on pseudolocalization is a quick way to
+   test how the layout handles such locales. Strings that don't fit the space
+   available are truncated and pseudolocalization can also help with detecting them.
+
+
+ - Bidi adaptation.
+
+   For many developers, testing the UI in right-to-left mode is hard.
+   Pseudolocalization shows how a right-to-left locale will look like.
+
+To turn on pseudolocalization, open the :doc:`Browser Toolbox <../../devtools-user/browser_toolbox/index>`,
+click the three dot menu in the top right corner, and choose one of the following:
+
+ - **Enable “accented” locale** - [Ȧȧƈƈḗḗƞŧḗḗḓ Ḗḗƞɠŀīīşħ]
+
+   This strategy replaces all Latin characters with their accented equivalents,
+   and duplicates some vowels to create roughly 30% longer strings. Strings are
+   wrapped in markers (square brackets), which help with detecting truncation.
+
+   This option sets the :js:`intl.l10n.pseudo` pref to :js:`accented`.
+
+
+ - **Enable bidi locale** - ɥsıʅƃuƎ ıpıԐ
+
+   This strategy replaces all Latin characters with their 180 degree rotated versions
+   and enforces right to left text flow using Unicode UAX#9 `Explicit Directional Embeddings`__.
+   In this mode, the UI directionality will also be set to right-to-left.
+
+   This option sets the :js:`intl.l10n.pseudo` pref to :js:`bidi`.
+
+__ https://www.unicode.org/reports/tr9/#Explicit_Directional_Embeddings
+
+Inner Structure of Fluent
+=========================
+
+The inner structure of Fluent in Gecko is out of scope of this tutorial, but
+since the class and file names may show up during debugging or profiling,
+below is a list of major components, each with a corresponding file in `/intl/l10n`
+modules in Gecko.
+
+For more hands-on experience with some of the concepts below, try
+following the `Fluent DOMLocalization Tutorial`__, which provides some
+background on how Fluent works and walks you through creating a basic
+web project from scratch that uses Fluent for localization.
+
+__ https://projectfluent.org/dom-l10n-documentation/overview.html
+
+FluentBundle
+--------------
+
+FluentBundle is the lowest level API. It's fully synchronous, contains a parser for the
+FTL file format and a resolver for the logic. It is not meant to be used by
+consumers directly.
+
+In the future we intend to offer this layer for standardization and it may become
+part of the :js:`mozIntl.*` or even :js:`Intl.*` API sets.
+
+That part of the codebase is also the first that we'll be looking to port to Rust.
+
+
+Localization
+------------
+
+Localization is a higher level API which uses :js:`FluentBundle` internally but
+provides a full layer of compound message formatting and robust error fall-backing.
+
+It is intended for use in runtime code and contains all fundamental localization
+methods.
+
+
+DOMLocalization
+---------------
+
+DOMLocalization extends :js:`Localization` with functionality to operate on HTML, XUL
+and the DOM directly including DOM Overlays and Mutation Observers.
+
+DocumentL10n
+------------
+
+DocumentL10n implements the DocumentL10n WebIDL API and allows Document to
+communicate with DOMLocalization.
+
+Events
+^^^^^^
+
+DOM translation is asynchronous (e.g., setting a `data-l10n-id` attribute won't
+immediately reflect the localized content in the DOM).
+
+We expose a :js:`Document.hasPendingL10nMutations` member that reflects whether
+there are any async operations pending. When they are finished, the
+`L10nMutationsFinished` event is fired on the document, so that chrome code can
+be certain all the async operations are done.
+
+L10nRegistry
+------------
+
+L10nRegistry is our resource management service. It
+maintains the state of resources packaged into the build and language packs,
+providing an asynchronous iterator of :js:`FluentBundle` objects for a given locale set
+and resources that the :js:`Localization` class uses.
+
+
+.. _Fluent: https://projectfluent.org/
+.. _DTD: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XUL/Tutorial/Localization
+.. _StringBundle: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XUL/Tutorial/Property_Files
+.. _Firefox Preferences: https://bugzilla.mozilla.org/show_bug.cgi?id=1415730
+.. _Unprivileged Contexts: https://bugzilla.mozilla.org/show_bug.cgi?id=1407418
+.. _System Add-ons: https://bugzilla.mozilla.org/show_bug.cgi?id=1425104
+.. _CLDR: http://cldr.unicode.org/
+.. _ICU: http://site.icu-project.org/
+.. _Unicode: https://www.unicode.org/
+.. _Fluent Syntax Guide: https://projectfluent.org/fluent/guide/
+.. _Pontoon: https://pontoon.mozilla.org/
+.. _Plural Rules: http://cldr.unicode.org/index/cldr-spec/plural-rules