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