forked from mirrors/gecko-dev
1da76eaf4a
Differential Revision: https://phabricator.services.mozilla.com/D19329 --HG-- extra : moz-landing-system : lando
217 lines
9.4 KiB
ReStructuredText
217 lines
9.4 KiB
ReStructuredText
.. role:: js(code)
|
||
:language: javascript
|
||
|
||
============
|
||
Localization
|
||
============
|
||
|
||
Localization – sometimes written as l10n, where 10 is the number of letters between `l` and `n` –
|
||
is an aspect of internationalization focused on adapting software to
|
||
different cultural and regional needs.
|
||
|
||
The boundary between internationalization and localization is fuzzy. At Mozilla
|
||
we refer to localization when we talk about adapting the user interface
|
||
and messages, while internationalization handles operations on raw data.
|
||
|
||
.. note::
|
||
|
||
Localization is a broader term than translation because it involves extensive research
|
||
into the target culture, and in result touches not only text and UI translation but also
|
||
cultural adaptation of icons, communication styles, colors, and UX.
|
||
|
||
Localization at Mozilla
|
||
=======================
|
||
|
||
At Mozilla localizations are managed by locale communities around the world, who
|
||
are responsible for maintaining high quality linguistic and cultural adaptation
|
||
of Mozilla software into over 100 locales.
|
||
|
||
The exact process of localization management differs from project to project, but
|
||
in the case of Gecko applications, the localization is primarily done via a web localization
|
||
system called `Pontoon`_ and stored in HG repositories under
|
||
`hg.mozilla.org/l10n-central`_.
|
||
|
||
Developers are expected to keep their code localizable using localization
|
||
and internationalization systems, and also serve as localizers into the `en-US` locale
|
||
which is used as the `source` locale.
|
||
|
||
In between the developers and localizers, there's a sophisticated ecosystem of tools,
|
||
tests, automation, validators and other checks on one hand, and management, release,
|
||
community and quality processes facilitated by the `L10n Drivers Team`_, on the other.
|
||
|
||
Content vs. UI
|
||
==============
|
||
|
||
The two main categories in localization are content localization vs UI localization.
|
||
|
||
The former is usually involved when dealing with large blocks of text such as
|
||
documentation, help articles, marketing material and legal documents.
|
||
|
||
The latter is the primary type when handling user interfaces for applications such
|
||
as Firefox.
|
||
|
||
This article will focus on UI localization.
|
||
|
||
Lifecycle & Workflow
|
||
====================
|
||
|
||
1) New feature
|
||
--------------
|
||
|
||
The typical life cycle of a localizable UI starts with a UX/UI or new feature need which
|
||
should be accompanied by the UX mockups involving so called `copy` - the original
|
||
content to be used in the new piece of UI.
|
||
|
||
2) UX mockup + copy review
|
||
--------------------------
|
||
|
||
The UX mockup with copy is the first step that should be reviewed by the L10n Drivers Team.
|
||
Their aim is to identify potential cultural and localization challenges that may arise
|
||
later and ensure that the UI is ready for localization on a linguistic, cultural,
|
||
and technical level.
|
||
|
||
3) Patch l10n review
|
||
--------------------
|
||
|
||
Once that is completed, the next stage is for front-end engineers to create patches
|
||
which implement the new UI. Those patches should already contain the `copy` and
|
||
place the strings in the localization resources for the source locale (`en-US`).
|
||
|
||
The developer uses the localization API by selecting a special identifier we call
|
||
`L10n ID` and optionally a list of variables that will be passed to the translation.
|
||
|
||
We call this "a social contract" which binds the l10n-id/args combination to a particular
|
||
source translation to use in the UI.
|
||
|
||
The localizer expects the developer to maintain the contract by ensuring that the
|
||
translation will be used in the given location, and will correspond to the
|
||
source translation. If that contract is to be changed, the developer will be expected
|
||
to update it. More on that in part `6) String Updates`.
|
||
|
||
The next review comes from either L10n Drivers, or experienced front end engineers
|
||
familiar with the internationalization and localization systems, making sure that
|
||
the patches properly use the right APIs and the code is ready to be landed
|
||
into `mozilla-central`.
|
||
|
||
4) Exposure in `gecko-strings`
|
||
------------------------------
|
||
|
||
Once the patch lands in `mozilla-central`, L10n Drivers will take a final look at
|
||
the localizability of the introduced strings. In case of issues, developers might
|
||
be asked to land a follow up, or the patch could be backed out with the help of sheriffs.
|
||
|
||
Every few days, strings are exported into a repository called `gecko-strings-quarantine`,
|
||
a unified repository that includes strings for all shipping versions of Firefox
|
||
(nightly, beta, release). This repository is used as a buffer to avoid exposing potential
|
||
issues to over 100 locales.
|
||
|
||
As a last step, strings are pushed into `gecko-strings`, another unified repository that
|
||
is exposed to localization tools, like Pontoon, and build automation.
|
||
|
||
5) Localization
|
||
---------------
|
||
|
||
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 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,
|
||
the L10n Drivers team is responsible for reviewing and signing off versions of each
|
||
localization shipping in Beta and Release versions of Gecko products.
|
||
|
||
6) String updates
|
||
-----------------
|
||
|
||
Later in the software life cycle some strings might need to be changed or removed.
|
||
As a general rule, once the strings lands in `mozilla-central`, any further update
|
||
to existing strings will need to follow these guidelines, independently from how much
|
||
time has passed since previous changes.
|
||
|
||
If it's just a string removal, all the engineer has to do is to remove it from the UI
|
||
and from the localization resource file in `mozilla-central`.
|
||
|
||
If it's an update, we currently have two "levels" of change severity:
|
||
|
||
1) If the change is minor, like fixing a spelling error or case, the developer should update
|
||
the `en-US` translation without changing the l10n-id.
|
||
|
||
2) If the change is anyhow affecting the meaning or tone of the message, the developer
|
||
is requested to update the l10n string ID.
|
||
|
||
The latter is considered a change in the social contract between the developer and
|
||
the localizer and an update to the ID is expected.
|
||
|
||
In case of `Fluent`_, any changes to the structure of the message such as adding/removing
|
||
attributes also requires an update of the ID.
|
||
|
||
The new ID will be recognized by the l10n tooling as untranslated, and the old one
|
||
as obsolete. This will give the localizers an opportunity to find and update the
|
||
translation, while the old string will be removed from the build process.
|
||
|
||
There is a gray area between the two severity levels. In case of doubt, don’t hesitate
|
||
to request feedback of review from L10n Drivers to avoid issues once the strings land.
|
||
|
||
Selecting L10n Identifier
|
||
=========================
|
||
|
||
Choosing an identifier for a localization message is tricky. It may seem similar
|
||
to picking a variable name, but in reality, it's much closer to designing a public
|
||
API.
|
||
|
||
An l10n identifier, once defined, is then getting associated to a translated
|
||
message in every one of 100+ locales and it becomes very costly to attempt to
|
||
migrate that string in all locales to a different identifier.
|
||
|
||
Additionally, in Fluent an identifier is used as a last resort string to be displayed in
|
||
an error scenario when formatting the message fails, which makes selecting
|
||
**meaningful** identifiers particularly valuable.
|
||
|
||
Lastly, l10n resources get mixed and matched into localization contexts where
|
||
it becomes important to avoid identifier collision from two strings coming
|
||
from two different files.
|
||
|
||
For all those reasons, a longer identifier such as :js:`privacy-exceptions-button-ok` is
|
||
preferred over short identifiers like :js:`ok` or :js:`ok-button`.
|
||
|
||
Localization Systems
|
||
====================
|
||
|
||
Gecko has three main localization systems: two older ones (DTD and StringBundle) and
|
||
a new system, called Fluent, that is progressively replacing them.
|
||
|
||
DTD & StringBundle
|
||
------------------
|
||
|
||
DTD is primarily used for XUL and XHTML file localization. It uses `.dtd` files
|
||
and the only localization feature it provides is the ability to reference one
|
||
string from another via entity reference.
|
||
|
||
StringBundle is a runtime API used primarily for localization of the JS code.
|
||
The messages are stored in `.properties` files and loaded using the StringBundle API
|
||
and then retrieved from there via imperative calls.
|
||
|
||
The system provides external arguments which can be placed into the string, and
|
||
support basic plural categories via a proprietary API `PluralForms.jsm`.
|
||
|
||
Fluent
|
||
------
|
||
|
||
Fluent is a modern localization system designed by Mozilla to address the challenges
|
||
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 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.
|
||
|
||
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/l10n/fluent_tutorial.html
|