intl/docs/localization.rst

   1 .. role:: js(code)
   2    :language: javascript
   3
   4 ============
   5 Localization
   6 ============
   7
   8 Localization – sometimes written as l10n, where 10 is the number of letters between `l` and `n` –
   9 is an aspect of internationalization focused on adapting software to
  10 different cultural and regional needs.
  11
  12 The boundary between internationalization and localization is fuzzy. At Mozilla
  13 we refer to localization when we talk about adapting the user interface
  14 and messages, while internationalization handles operations on raw data.
  15
  16 .. note::
  17
  18   Localization is a broader term than translation because it involves extensive research
  19   into the target culture, and in result touches not only text and UI translation but also
  20   cultural adaptation of icons, communication styles, colors, and UX.
  21
  22 Localization at Mozilla
  23 =======================
  24
  25 At Mozilla localizations are managed by locale communities around the world, who
  26 are responsible for maintaining high quality linguistic and cultural adaptation
  27 of Mozilla software into over 100 locales.
  28
  29 The exact process of localization management differs from project to project, but
  30 in the case of Gecko applications, the localization is primarily done via a web localization
  31 system called `Pontoon`_ and stored in HG repositories under
  32 `hg.mozilla.org/l10n-central`_.
  33
  34 Developers are expected to keep their code localizable using localization
  35 and internationalization systems, and also serve as localizers into the `en-US` locale
  36 which is used as the `source` locale.
  37
  38 In between the developers and localizers, there's a sophisticated ecosystem of tools,
  39 tests, automation, validators and other checks on one hand, and management, release,
  40 community and quality processes facilitated by the `L10n Drivers Team`_, on the other.
  41
  42 Content vs. UI
  43 ==============
  44
  45 The two main categories in localization are content localization vs UI localization.
  46
  47 The former is usually involved when dealing with large blocks of text such as
  48 documentation, help articles, marketing material and legal documents.
  49
  50 The latter is the primary type when handling user interfaces for applications such
  51 as Firefox.
  52
  53 This article will focus on UI localization.
  54
  55 Lifecycle & Workflow
  56 ====================
  57
  58 1) New feature
  59 --------------
  60
  61 The typical life cycle of a localizable UI starts with a UX/UI or new feature need which
  62 should be accompanied by the UX mockups involving so called `copy` - the original
  63 content to be used in the new piece of UI.
  64
  65 2) UX mockup + copy review
  66 --------------------------
  67
  68 The UX mockup with copy is the first step that should be reviewed by the L10n Drivers Team.
  69 Their aim is to identify potential cultural and localization challenges that may arise
  70 later and ensure that the UI is ready for localization on a linguistic, cultural,
  71 and technical level.
  72
  73 3) Patch l10n review
  74 --------------------
  75
  76 Once that is completed, the next stage is for front-end engineers to create patches
  77 which implement the new UI. Those patches should already contain the `copy` and
  78 place the strings in the localization resources for the source locale (`en-US`).
  79
  80 The developer uses the localization API by selecting a special identifier we call
  81 `L10n ID` and optionally a list of variables that will be passed to the translation.
  82
  83 We call this "a social contract" which binds the l10n-id/args combination to a particular
  84 source translation to use in the UI.
  85
  86 The localizer expects the developer to maintain the contract by ensuring that the
  87 translation will be used in the given location, and will correspond to the
  88 source translation. If that contract is to be changed, the developer will be expected
  89 to update it. More on that in part `6) String Updates`.
  90
  91 The next review comes from either L10n Drivers, or experienced front end engineers
  92 familiar with the internationalization and localization systems, making sure that
  93 the patches properly use the right APIs and the code is ready to be landed
  94 into `mozilla-central`.
  95
  96 4) Exposure in `gecko-strings`
  97 ------------------------------
  98
  99 Once the patch lands in `mozilla-central`, L10n Drivers will take a final look at
 100 the localizability of the introduced strings. In case of issues, developers might
 101 be asked to land a follow up, or the patch could be backed out with the help of sheriffs.
 102
 103 Every few days, strings are exported into a repository called `gecko-strings-quarantine`,
 104 a unified repository that includes strings for all shipping versions of Firefox
 105 (nightly, beta, release). This repository is used as a buffer to avoid exposing potential
 106 issues to over 100 locales.
 107
 108 As a last step, strings are pushed into `gecko-strings`, another unified repository that
 109 is exposed to localization tools, like Pontoon, and build automation.
 110
 111 5) Localization
 112 ---------------
 113
 114 From that moment localizers will work on providing translations for the new feature
 115 either while the new strings are only in Nightly or after they are merged to Beta.
 116 The goal is to have as much of the UI ready in as many locales as early as possible,
 117 but the process is continuous and we're capable of releasing Firefox with incomplete
 118 translations falling back on a backup locale in case of a missing string.
 119
 120 While Nightly products use the latest version of localization available in repositories,
 121 the L10n Drivers team is responsible for reviewing and signing off versions of each
 122 localization shipping in Beta and Release versions of Gecko products.
 123
 124 6) String updates
 125 -----------------
 126
 127 Later in the software life cycle some strings might need to be changed or removed.
 128 As a general rule, once the strings lands in `mozilla-central`, any further update
 129 to existing strings will need to follow these guidelines, independently from how much
 130 time has passed since previous changes.
 131
 132 If it's just a string removal, all the engineer has to do is to remove it from the UI
 133 and from the localization resource file in `mozilla-central`.
 134
 135 If it's an update, we currently have two "levels" of change severity:
 136
 137 1) If the change is minor, like fixing a spelling error or case, the developer should update
 138 the `en-US` translation without changing the l10n-id.
 139
 140 2) If the change is anyhow affecting the meaning or tone of the message, the developer
 141 is requested to update the l10n string ID.
 142
 143 The latter is considered a change in the social contract between the developer and
 144 the localizer and an update to the ID is expected.
 145
 146 In case of `Fluent`_, any changes to the structure of the message such as adding/removing
 147 attributes also requires an update of the ID.
 148
 149 The new ID will be recognized by the l10n tooling as untranslated, and the old one
 150 as obsolete. This will give the localizers an opportunity to find and update the
 151 translation, while the old string will be removed from the build process.
 152
 153 There is a gray area between the two severity levels. In case of doubt, don’t hesitate
 154 to request feedback of review from L10n Drivers to avoid issues once the strings land.
 155
 156 Selecting L10n Identifier
 157 =========================
 158
 159 Choosing an identifier for a localization message is tricky. It may seem similar
 160 to picking a variable name, but in reality, it's much closer to designing a public
 161 API.
 162
 163 An l10n identifier, once defined, is then getting associated to a translated
 164 message in every one of 100+ locales and it becomes very costly to attempt to
 165 migrate that string in all locales to a different identifier.
 166
 167 Additionally, in Fluent an identifier is used as a last resort string to be displayed in
 168 an error scenario when formatting the message fails, which makes selecting
 169 **meaningful** identifiers particularly valuable.
 170
 171 Lastly, l10n resources get mixed and matched into localization contexts where
 172 it becomes important to avoid identifier collision from two strings coming
 173 from two different files.
 174
 175 For all those reasons, a longer identifier such as :js:`privacy-exceptions-button-ok` is
 176 preferred over short identifiers like :js:`ok` or :js:`ok-button`.
 177
 178 Localization Systems
 179 ====================
 180
 181 Gecko has three main localization systems: two older ones (DTD and StringBundle) and
 182 a new system, called Fluent, that is progressively replacing them.
 183
 184 DTD & StringBundle
 185 ------------------
 186
 187 DTD is primarily used for XUL and XHTML file localization. It uses `.dtd` files
 188 and the only localization feature it provides is the ability to reference one
 189 string from another via entity reference.
 190
 191 StringBundle is a runtime API used primarily for localization of the JS code.
 192 The messages are stored in `.properties` files and loaded using the StringBundle API
 193 and then retrieved from there via imperative calls.
 194
 195 The system provides external arguments which can be placed into the string, and
 196 support basic plural categories via a proprietary API `PluralForms.jsm`.
 197
 198 Fluent
 199 ------
 200
 201 Fluent is a modern localization system designed by Mozilla to address the challenges
 202 and limitations of the previous systems.
 203
 204 It's well suited for modern web development cycle, provides a number of localization
 205 features including good internationalization model and strong bidirectionality support.
 206
 207 Fluent strictly supersedes the old systems and is currently being slowly introduced to
 208 Firefox and all other Mozilla products with the goal to become the only
 209 unified localization system at Mozilla and a foundation of the future localization
 210 standard.
 211
 212 To learn more about Fluent, follow the `Fluent for Firefox Developers`_ guide.
 213
 214 .. _Pontoon: https://pontoon.mozilla.org/
 215 .. _hg.mozilla.org/l10n-central: https://hg.mozilla.org/l10n-central/
 216 .. _L10n Drivers Team: https://wiki.mozilla.org/L10n:Mozilla_Team
 217 .. _Fluent For Firefox Developers: ./l10n/l10n/fluent_tutorial.html