Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Documentation for Mozilla localizers

Table of contents

Community

Products

How to localize and test Mozilla products:

Tools

Web Projects

Other topics

How to contribute to documentation

Please see the README file in our GitHub repository.

Localization community in Mozilla

Roles and guidelines in the localization community

Volunteer communities are the backbone of the localization (l10n) efforts at Mozilla. They are designed to be self-regulating and self-managing with minimal intervention from staff. For example, the responsibility of reviewing suggestions falls on the Translators and Managers within the community; they not only ensure quality and consistency but also keep an eye out for potential new volunteers to promote. And when Managers plan to step down, it’s crucial they develop succession plans to maintain continuity.

The role of staff is to intervene only when necessary. The main reasons for staff to be involved is when self-regulation fails or there are violations of the Community Participation Guidelines (CPG). The goal is to empower the communities to thrive independently while maintaining the high standards that Mozilla is known for.

The localization team can occasionally take a more hands-on approach, proactively engaging with locales that are facing challenges. For example, it can happen when a member (or members) of a locale reaches out directly to localization staff to express concerns about their community. Other times, the team may receive product requests for specific locales, which prompts initiatives to ensure that these communities are capable of supporting the product expansion.

In the following sections, we’ll review the current roles and expectations and suggest guidelines for when role criteria are not met — and how the localization staff can get involved and help in these different scenarios.

Roles: responsibilities and expectations

Managers

Responsibilities

On top of the responsibilities associated with the Translator role:

  • Establish mentorship practices for new localizers that foster growth and lead to impactful participation.
  • Identify and train community mentors in their role.
  • Coordinate translation and l10n testing of projects within the l10n community.
  • Provide input and consultation with localizers, evaluate candidates for advanced roles within the community.
  • Coordinate and facilitate internal community discussions.
  • Create and maintain language resources for the community (e.g., terminology, style guides, etc.).

Expectations

  • Open and frequent communication (liaison between l10n-drivers and l10n community) concerning new projects, new deadlines, and community issues.
  • Create and secure a safe space for people to participate in l10n in an impactful way.
  • Recruit and mentor new localizers.
  • Give timely feedback to community mentors and translators.

Translators

Responsibilities

  • Submit translations for new content.
  • Review pending translation suggestions from contributors and provide them with timely feedback that focuses on developing skills.
  • Testing of all submitted translations in product.
  • Work with Managers to create and maintain language resources for the community.
  • Report issues concerning source language content issues.

Expectations

  • Ensure consistent quality of the project they’re localizing.
  • Give detailed feedback to contributors in a timely manner.
  • Translate new content regularly.
  • Ensure that community style guidelines are being followed in translations that make it to the repositories.
  • Keep pending translation suggestion queue to a low number.
  • Gracefully accept feedback on their translations from other Translators and Managers.

Contributors

Responsibilities

  • Submit translation suggestions to Pontoon projects for the target language.
  • Request and accept feedback from Translators and Managers in the community.
  • In-context review (l10n testing) of translation suggestions that have been approved by Translators and Managers.

Expectations

  • Gracefully accept feedback on their translations from Translators and Managers.
  • Avoid relying exclusively on machine translation, especially when unsure about the source string or the language.
  • Proactively request feedback from Translators and Managers.
  • Network and form relationships with others in the community.

Guidelines

Promotions

Promotions apply to Translators and Contributors. Managers and localization staff can directly promote/demote users to Translator or Manager roles.

Efforts to revive an inactive community

A community is considered inactive when there are no other active Translators or Managers, which can make it difficult for Contributors to participate effectively. If a Contributor has attempted to reach out to the Managers or Translators but has not received a satisfactory response (or any response) within a few weeks, it’s advisable to contact the localization staff for assistance. Each situation is unique, and staff can help investigate further, for example reviewing a localizer’s contribution history across external localization projects outside of Mozilla. The localization team will also reach out to former Managers and Translators for their input. If there is still no response, the localization team will consider promoting active localizers who have expressed interest in taking on an active role.

Community engagement

Localizers who actively participate in community discussions, provide feedback and reviews, mentor new members, and engage in localization events and workshops should be recognized and promoted for their dedication and leadership within the community​. They often transition from direct translation work to more managerial roles, focusing on building and enabling the locale community.

How do you recognize and promote them? Existing locale Managers are typically in charge of updating the permissions on Pontoon. Staff will step in if there are reasons preventing a person from reaching the next role (for example, if there are no active Managers, or if there is gatekeeping).

In the case there is no existing community, a localizer requesting a new locale will be appointed to the Manager role.

High-quality contributions

A localizer who consistently provides high-quality translations that meet the community’s standards should be considered for promotion. This includes accuracy, adherence to style guides, and timely contributions and reviews​. Contribution data on Pontoon can be used to help guide these decisions.

Demotions

Demotions should come as a last resort when a localizer’s actions significantly impact the project’s quality, collaboration, or community. In practice demotions are extremely rare and historically have occurred when a Manager or Translator voluntarily expresses a desire to step back from their roles and expectations.

Here are some examples of reasons for demotion.

A localizer wants to take a step back

As explained, a request for demotion can come from localizers themselves, when they want to delegate certain responsibilities. This is a straightforward scenario, in which a localizer typically will reach out to the manager — or localization staff — to express their desire to step down. Managers have the permissions to do so themselves, but localization staff can also assist.

A localizer is failing to meet role expectations

A localizer might notice that a Manager or Translator is abusing their role, especially in ways that may be considered gatekeeping. After the community has tried to get in touch with the Managers or Translators, but has not received a satisfactory response (or any response) after a few weeks, reaching out to the localization staff is a good first step for the team to help investigate and find solutions, as each situation is unique. Note that the localization team rarely demotes anyone unless it’s a grave situation, but they can help promote or unblock users.

Prolonged inactivity

Typically there isn’t a need to demote a Manager or Translator due to inactivity, unless gatekeeping or retaliation disrupt the work of others.

Community guidelines enforcement

CPG violation

A CPG violation is taken very seriously and will be addressed immediately. The process for reporting a violation is detailed under the “Reporting” section of the CPG.

Gatekeeping

Gatekeeping can show up in different ways in localization communities/localizers:

  • Not reviewing new Contributors’ work, which prevents them from joining and contributing.
  • Self-reviewing their own work and ignoring the work done by others — or constantly rejecting others’ contributions as not good enough to maintain control over the locale.
  • Creating unnecessary barriers to participation, like setting very strict standards without offering guidance or feedback, holding onto knowledge or resources instead of sharing with the community, and resisting changes or improvements suggested by others without explanation.
  • Being inactive for a long period of time, but nonetheless never wanting to give permissions to others actively participating. These actions limit the growth and diversity of the community, making it less welcoming and inclusive.

How does the localization team know someone is gatekeeping? This can happen through direct feedback, or through the localization team’s own investigations.

If a localizer has attempted to reach out to Managers or Translators but has not received a satisfactory response (or any response) within 2 weeks, it’s advisable to contact the localization staff for assistance.

Common issues and references

How can I contact the localization staff?

If you have contacted members of your team and received no responses, have questions about these guidelines or want to suggest improvements, don’t hesitate to get in touch with the localization staff:

  1. You can use email and Matrix to reach out to the entire team.
  2. You can also find the member of staff in charge of each project directly in Pontoon.

I am a Translator and want to become a Manager, what do I do?

Try to get in touch with the current Managers and Translators from your locale, to surface your request (you can find them under the Contributor view in your team page on Pontoon). Check also the Promotions section. You can also reach out to the localization team directly.

No one is reviewing my suggestions, what do I do?

Try to get in touch with the current Managers and Translators from your locale, to surface your request (you can find them under the Contributor view in your team page on Pontoon). You can also reach out to the localization team directly.

I’m a new Contributor and am interested in becoming a Translator for only one project.

Get in touch with the locale Managers first, to ask them to appoint you to only one project. If there is no response within a few weeks, reach out to the localization team.

How can I delete my Pontoon account?

Currently users cannot remove their account directly from Pontoon. Reach out to the localization team.

Reviewing translations within your community

Mozilla encourages a three-stage review process:

  1. Linguistic review in Pontoon by community.
  2. Technical review by l10n-drivers.
  3. In-context localization testing by community and users.

This document explains how to perform the first stage of the review process: review the work of another member of your community and provide constructive feedback.

Attitudes around reviewing translations

Reviewing the translation contributions of another localizer can be controversial. Many attach strong feelings to their contributions, making it very difficult for them to receive feedback and make adjustments to the way they contribute. Reviews are opportunities to ensure high quality contributions while mentoring someone to improve their translation skill set. Reviewers should approach their work with these things in mind:

  1. Everyone is volunteering their time and looking to have a positive impact in their community.
  2. Reviews are an opportunity to give clear, actionable feedback about another localizer’s contributions.
  3. Reviews should be based on objective standards agreed upon by the community and made explicit through the community’s style guide and terminology resources rather than personal preferences. This eliminates the potential for subjective feedback or manipulation through reviews, and thus eliminates potential conflicts within the community.
  4. Reviewers should avoid using vague, potentially inflammatory language in their reviews (e.g., “This translation is terrible, fix it“).

Localizers should approach receiving feedback with these things in mind:

  1. Everyone is volunteering their time and looking to have a positive impact in their community.
  2. Reviews are an opportunity to develop and improve your translation skills. They should be welcomed with an open mind.
  3. Reviews are a natural and required part of the localization process.

Giving constructive feedback

When reviewing someone else’s translations, feedback should be actionable and based on objective standards. Style guides and terminology resources developed within the community with agreement from its members contain those objective standards. Feedback should include the following elements:

  1. Actionable criticism.
  2. Reference to where the translation violates the objective standards.

For example, if a translation contains a spelling error, a constructive piece of feedback would look like this: “There’s a spelling mistake in moniter. The correct spelling can be found in either our official terminology or this section of the community style guide.“

Tools available for giving feedback

Pontoon currently allows reviewers to do the following:

  1. Approve or reject suggestions.
  2. Make edits to existing translation submissions.

A more robust feedback loop will be implemented in Pontoon during the beginning of 2018.

Localization of Mozilla products

Documentation regarding testing and localization of the following products:

Documentation about testing localization of Mozilla projects, as well as a list of localization team project managers.

Localization team project managers

You can find the project manager for any project hosted in Pontoon directly in the header of the project page.

Bryan

Francesco (flod)

  • Email: flodolo(at)mozilla.com
  • GitHub profile
  • Bugzilla profile
  • Localization team manager
  • Products: Android and iOS browsers (Focus, Firefox), Mozilla VPN projects

Peiying

L10n and Firefox for desktop

Some documentation specific for common tasks regarding Firefox desktop and l10n:

Testing Firefox Desktop

Which build should I test?

As a localizer you will work against Nightly, which means you should be testing a localized build of Firefox Nightly provided directly by Mozilla.

You can download the build from the pre-release download page, the download page for all systems and locales, or directly via FTP (search for your locale code and operative system).

Why Nightly? Because it’s updated twice every day, which means that you can fix an error and verify if the correction was effective within a few hours. It’s definitely a good approach to use this version as your main browser.

At the same time, you, or someone in your team, should be testing also Beta and Release, to make sure updates don’t introduce issues.

Building a localized version of Firefox

If you’re interested in building a localized version of Firefox from source code, please follow the official instructions available in Mozilla Source Tree Docs. Note that you will need to set up the build environment on your system.

How to test

Here are some tips on how to test Firefox once installed in your computer.

Create a new profile

From time to time create a new profile:

  • To test that the default searchplugins are still relevant and work as expected.
  • To check messages and pages displayed on first run.
  • To test dialogs and preferences at the default size.

Search for untranslated strings

  • Open all the items available in the main menu and check that they’re properly localized. If you opted to keep Developer Tools in English, the language should be consistent across all the developer tools.
  • Check the “hamburger” menu, making sure to inspect subpanels for items displaying the > symbol.
  • Open Preferences/Options and navigate through all panels, try to open all dialogs like Exceptions…. Make also sure to select the Custom settings option for History in the Privacy panel.
  • Log in with you Firefox Account and make sure that all preferences and dialogs are properly localized.
  • Check for untranslated strings and errors in the Library (Bookmarks->View all bookmarks…).
  • Open a new Private Window and check the content of the page.
  • Type about:support in the address bar, press Enter, and check for errors or missing translations.
  • Check the error pages for malware, unwanted software, deceptive website, harmful website. All strings are also visible in about:blocked.
  • Check permissions dialogs on this test website.
  • Visit secure and unsecure websites, and check the panel displayed when clicking the lock icon.
  • Check the Protections panel displayed when clicking the shield icon in the address bar, and the about:protections page for the Protections Report.
  • Right click on a page and verify all panels in the View Page Info dialog.
  • Enable login saving in Logins & Passwords, make sure that about:logins is correctly localized and works as expected.

Test the New Tab page and Contextual Feature Recommendations

First of all, make sure that everything is correctly translated in about:newtab. That’s the default page displayed when opening a new tab in Firefox.

In order to test other features available for New Tab, it’s necessary to enable a devtools option: open about:config, search for browser.newtabpage.activity-stream.asrouter.devtoolsEnabled and set it to true. After that, in the top right corner of the New Tab page a small wrench icon will be displayed.

For example, the AS Router Admin page can be used to test contextual feature recommendations (CFR):

  • In the Messages section, select to show message for cfr.
  • Click the Show button in one of the available options.

The suggestions is displayed at the end of the address bar (first as a bulb icon, then as a “suggestion” tag). Clicking the blue tag will display a doorhanger.

Test webextension permissions dialog

Create a new profile and open about:config in your browser:

  • Right click on the list of available keys and create a new boolean key extensions.webextPermissionPrompts set to true.
  • Search for the key xpinstall.signatures.required and set it to false. This will allow installing unsigned add-ons.
  • Open this link, select Download and save the file on your computer.
  • Extract the archive.
  • Drag each (one by one) of the .xpi files on your browser’s window to display the dialog (you don’t need to actually install it).

Test accesskeys and shortcuts

You can test accesskeys only on Windows and Linux, since they’re not available in OS X.

If your locale uses a non Latin alphabet and opted to keep the English accesskeys, you don’t have anything to check. If you’re localizing accesskeys, you should check that:

  • Accesskeys use letters available in the associated label, and are not displayed between parenthesis at the end of the label itself.
  • There are no conflicts, which means there are no items in the same menu or preference panel using the same letter. Starting from Firefox 56, it’s not possible to avoid conflicts in preferences: the guideline in that case is to reduce to a minimum the number of times the same letter is used within a panel.

For shortcuts, you should test at least the most common ones. You should never change a shortcut, unless that combination of keys is not available in the keyboard layout commonly used for your locale. For example, in the Italian keyboard the character [ is available pressing Alt and è. A shortcut based on Shift + [ would never work, because it would be read as Alt + Shift + è.

Transvision has a QA view to check both accesskeys and keyboard shortcuts for each locale.

Test certificate error pages

There are several certificate error pages in Firefox, the message displayed can vary depending on the error being bypassable or not:

Other test pages for certificates, both valid and invalid, are available at https://badssl.com.

Test the installer on Windows

Download the installer version and make sure that everything is working correctly. In the FTP folder you have both the Full Installer and the Stub Installer (downloading the package from Internet). You should test both at least once.,

L10n and Firefox for Android

Some documentation specific for common tasks regarding Firefox for Android and l10n:

Firefox for Android - How to localize

Firefox for Android is on a four week rapid release cycle. This means that usually there is a new release going out every four weeks.

Within this timeframe, localizers will usually have approximately four weeks to localize and test their strings for a given release: strings land continuously on Nightly during the first four weeks, and then these strings ride the train to the Beta version. The deadline in Pontoon is an indicator of when the next localization cut-off date is for the upcoming release - in other words, the last day to get localization updates into that release.

Note that all files contained in the project should be localized in order for Firefox for Android to be complete.

Localize Firefox for Android in Pontoon

Localizers should go to the Firefox for Android page on Pontoon, and click “Request New Language”. They will be notified by email once the locale is set up and the project is ready to be localized.

When the locale has been set up, localizers can choose it from the list of locales on Pontoon, and start localizing the product from there.

Once localization starts, the locale should become available in Nightly builds within the next few days, which will enable localizers to check and test their work (see this section for more information about testing).

When the locale reaches 70% completion (and given that active testing has taken place), it can be added to the release version.

Testing Firefox for Android

Note: UI elements change over time. As a result some terms or element locations might differ from what’s described here. If you notice that something is significantly out of date, please open an issue so we can update this page.

This document provides an overview of frequent localization issues, recommended fixes, and specific Firefox for Android testing scenarios to help identify them. Depending on the issue, either a direct correction in Pontoon can be made, or you will need to file a bug as described below.

Fixes in Pontoon

When issues can be fixed in Pontoon, open the Firefox for Android project and pick your locale to find the specific string in Pontoon. Click on the top right of the page, where it says All Strings. Type the string into the search bar and press Enter, and click the magnifying glass icon to open filters and refine your search. Read more about search here.

Note that while users with Translator or Manager permissions can edit strings directly, contributors can only submit a suggestion. For more information, see this section on translating in Pontoon.

Fixes in Bugzilla

If an issue cannot be fixed in Pontoon, you will have to open a bug in Bugzilla in Firefox for Android here (under the L10N Component) Note that you will need to log in or create a Bugzilla account to file a bug.

Whenever in doubt, contact the project manager for Firefox for Android.

Pre-requisites for testing

Download Nightly

If you have an Android device, it’s best to test Firefox with Nightly builds (download), as they are updated each day with the latest translations. Change the device’s system language in Android settings, or switch the in-app language from Firefox Nightly’s Settings (three dot menu → Settings → Language).

Install Android Studio Code

If you do not have an Android device, or if your Nightly build contains data you do not want to lose, you can use Android Studio Code on your PC to test the browser, including localized onboarding screens. Here are the instructions to set it up:

  1. Download Android Studio Code (it’s free).
  2. Install and run. Create an empty project (File → New → New Project → Empty activity).
  3. On the right-hand side of the Android Studio interface, look for the Device Manager icon (hover over icons to find it). If you don’t see it, open it from the top menu: View -> Tool Windows -> Device Manager.
  4. Then, you can add a virtual device (such as Pixel 9a) by clicking on the “+” icon to the top-right corner of where the code shows. Then choose Create Virtual Device.
  5. Now you can run a new virtual device: click the play icon next to your virtual device name. After a few moments, an Android phone window should appear.
  6. Log into your Google account and install Firefox Nightly from the Google Play Store.
  7. You can then change Firefox for Android languages just like you would in a regular device: either change the device’s system language in Android settings, or switch in-app language from Firefox Nightly’s settings.

Common localization issues

Here is a non-exhaustive list of common localization issues a localizer can encounter, along with ways to resolve them. Please keep these common issues in mind while performing localization testing.

Truncation/Overlap

Truncation happens when text is cut off because it doesn’t fit within the space allowed in the user interface. This is common on mobile devices, where space is limited.

Overlap occurs when text expands and pushes parts of the user interface, causing them to overlap with other UI elements.

There are two ways that this can be fixed:

  • The localizer can try shortening the translation in Pontoon, but this doesn’t always solve the issue. If that’s the case, the best solution is to file a bug as explained in the point above.
  • A developer can expand the UI to accommodate longer translations or enable text wrapping. Here again, a bug needs to be filed as explained above.

Language quality

Language quality issues happen when a translation sounds unnatural or includes grammatical errors, incorrect terminology, awkward phrasing, or inconsistent tone.

These issues can be fixed in Pontoon directly (see this section for more info).

Untranslated content

If anything appears untranslated, but you know the string has been translated in Pontoon, file a bug. This may be due to strings being hardcoded, or an issue with importing translations back into the Firefox for Android repository.

However, untranslated content can also appear because of the delay between when strings land in Nightly and when translations are imported back into the app. Before filing a bug, wait until the next day as the following Nightly build should include the updated translations.

Font support

Font support issues happen when a font used in the app doesn’t display certain characters or glyphs correctly. This can include missing letters, broken accents, or symbols that appear as boxes or question marks.

This will need an engineering fix. Follow the steps to file a bug as described in the section above.

Testing key UI elements

Onboarding flows

The onboarding flow is typically displayed with a fresh profile, but it can be triggered from the Debug settings hidden menu. First, you need to enable this menu:

  • Tap on the three-dot button in the toolbar.
  • Tap on Settings.
  • Scroll down and select About Firefox Nightly.
  • Tap the Firefox logo multiple times (at least 4), until you see a message Debug menu enabled at the bottom of the screen. Before that, the message will show the number of taps remaining, e.g. Debug menu: 3 click(s) left to enable.

After this, go back into the main Settings menu, tap Secret Settings, then enable Show onboarding on each app cold open. At this point, closing and reopening the app will show the onboarding flow.

Note that the hidden menu will be automatically disabled when restarting the app.

Home screen

This is the page you see right after completing the onboarding flow, when opening a new tab, or when no tabs are open. It usually shows Shortcuts, Jump back in (tabs), Recently visited (websites), Collections and Stories (note that Stories are enabled only for a subset of locales). Some sections only appear after you’ve visited a few websites — the more you browse, the more content you’ll see here. Please note that certain parts of the interface may appear in English because they display actual page titles from visited websites, and the language shown depends on the content source.

Be sure to tap Show all wherever it appears. Try saving tabs to collections, and review each element displayed there. Note that the mask icon at the top of the screen can be tapped and will take you to Private Browsing mode.

Always verify every interactive element in the UI you’re viewing — and do this throughout the app.

Address bar

Tap the search plugin logo, and check that everything in the interface is localized. Note the names displayed near each icon in the list will reflect the name of the search engine, so they will be in English unless it’s a local search engine.

Check that the text inside the address bar is localized. When you have tabs open, you’ll see the number of tabs displayed next to the address bar — tap it too. Move through the interface and tap all elements that can be tapped, including those in the three-dot menu at the bottom of the screen.

Navigate to a website, and tap everywhere you can within the address bar, including any submenus that appear.

Settings menu

Tap the three dot menu located either on the top right of the UI, or the bottom right of the UI, depending on the preference selected (note that for Right-to-Left languages, elements appear to the left). Check the menu displayed.

Then tap on Settings and scroll through the menu all the way down, checking that all text appears correctly translated.

Check all subsections within the Settings menu, including any areas you can open inside it. If you can change preferences or tap different options, do so — it may trigger notifications you’ll need to review.

Extensions

Tap the three dot menu → Extensions. Install an extension. Check the Extension menus and sub-menus. While extensions themselves are not necessarily translated, any other elements or text that appear there should be.

Tap to install an extension, and observe the notification that briefly appears before leading you to a more permanent one. Everything except the extension name should be localized. After adding the extension, note the confirmation notification that appears, then return to the Extensions menu and check that the Enabled string for the new extension(s) is localized.

Snackbars, notifications, error messages

For the purposes of this document, snackbars, notifications, and error messages are grouped together, as they often appear in similar ways. Note that this list is not exhaustive. If you come across other scenarios, file an issue.

Note: Snackbars are in-app and temporary (e.g. Tab closed or Bookmark added), while notifications are persistent and visible until a user clicks on an action such as OK or Back (e.g. Download complete).

Pay attention to messages displayed when you perform the following actions:

  • add/delete bookmarks
  • delete items from history
  • create/rename a Collection
  • add items to a Collection
  • download a file
  • open a private tab
  • close a tab
  • choose to move tabs to “inactive” from the Tabs menu in Settings. Check back in two weeks as the “inactive tabs” tray will appear (accessed via the tab icon beside the address bar)
  • long-press an image to download it
  • tap the Share button beneath an image
  • sign in to an account, such as Google
  • tap Save under an image, once you are logged into a Google account
  • long-press a link within a webpage
  • disable Wi-Fi and try using the app
  • crash the browser: type about:crashcontent in the address bar

L10n and Firefox for iOS

Some documentation specific for common tasks regarding Firefox for iOS and l10n:

Testing on iOS for a new release

Localizers currently mostly rely on screenshots for testing. Latest information and updates about Firefox for iOS are generally announced in the Localization Reports, which you should follow if you are working on localization for any of the existing Mozilla products.

Testing with screenshots

Screenshots are currently generated by the iOS team every two weeks. The most recent set is available in this page. Locales are listed in alphabetical order by locale code. Select your locale to open a gallery of screenshots. Each locale page also shows when the screenshots were last updated and includes a link to the corresponding commit in GitHub, which provides a visual diff of the changes.

Test builds

The beta version used for testing can be found here. In case the registration does not work from there, localizers can also reach out to the project manager for Firefox for iOS in order to be added to these builds. Please note you will need an iOS device running v15 or above.

Aspects to review

Here is a list of issues you should try to identify when testing the build:

  • Language quality.
  • Truncated words (cut-off from screen).
  • Anything that appears broken on the UI.
  • Check out at all the main screens, UI, menus, tabs, new features, etc. Make sure these all look good, that everything is properly translated and appears as expected.
  • Font support.
  • Untranslated content.

Concerning untranslated content: iOS provides two tiers of language support. Tier 1 locales are fully supported, while Tier 2 locales have more limited support. For Tier 2 locales, some UI elements supplied by the operating system may not be localizable and will appear in the UI in the OS language. To check whether a locale is supported, open Language Settings on an iOS device: Tier 1 locales are listed under iPhone Languages, while Tier 2 locales appear under Other Languages. If a locale does not appear in either list, it is currently not supported by iOS.

Shipping a brand new locale

Please note this section about prerequisites for adding a new locale to Firefox for iOS, as we are limited by the system settings.

As soon as you begin working on Firefox for iOS in Pontoon, we automatically ship whatever translations are available and the work will appear in the next Beta build.

L10n and Focus for iOS and Android

Some documentation specific for common tasks regarding Focus for iOS and Android:

Focus - How to localize

Focus for Android and Focus for iOS are both on a four week rapid release cycle. This means that usually there are new releases going out every four weeks.

Within this timeframe, localizers will have approximately four weeks to localize and test their strings for a given release: strings land continuously on Nightly during the first four weeks, and then these strings ride the train to the Beta version.

It is important to use the Nightly versions for both products, in order to test localization work regularly (see more details about testing here).

Localizing Focus for Android and Focus for iOS in Pontoon

Localizers should go to the Focus for Android page on Pontoon - or the Focus for iOS page on Pontoon - and click Request New Language. They will be notified by email once the locale is set up and the project is ready to be localized.

When the locale has been set up, localizers can choose it from the list of locales on Pontoon, in the same page from which they made the locale request (links above).

Once localization starts, the locale should become available in Nightly builds within the next few days, which will enable localizers to check and test their work. For Nightly builds and testing instructions, please refer again here.

Once the locale starts work and reaches even 1% completion in Pontoon (and assuming that active testing has taken place), it will be added to the release version either in the Google Play Store or the iOS App Store.

Note that Focus for Android strings share common strings with android-components, just like Fenix (Firefox for Android) does. At the moment, android-components strings all live in the Firefox for Android project in Pontoon - these are all the files in your locale folder that start with mozilla-mobile/android-components/. If Firefox for Android is not yet enabled for your locale, you will be asked to complete that work first.

Localization deadlines for projects are noted as Resources in each project page in Pontoon, and the main Project Manager’s contact information can be found there as well.

Testing Focus for iOS and Focus for Android for a new release

Given Focus for iOS and Focus for Android have very similar test procedures, this document will cover both at once. Please note that in certain markets, the app is named “Klar”. For the sake of simplicity, we will only call out the name “Focus” in this document.

Localizers currently mostly rely on screenshots for testing Focus for iOS. Latest information and updates about testing are provided on the l10n Discourse Channel, which you should follow if you are working on localizing any of the existing Mozilla products. Links to iOS screenshots are also provided under the Resources section in Pontoon, at the top of the project page. For Focus for Android and iOS, there are also links to testing builds, if they are currently available.

Testing with screenshots (currently available for Focus for iOS only)

Screenshots are provided by the mobile teams for iOS and appear under the Resources section in Pontoon or in the l10n Discourse channel (see above point for more details).

Test builds

  • For Focus for Android testing of either Nightly or Beta, you will first have to join this google group. Please note that you must use the same Google account you use on your device to download apps from Google Play.

For Beta releases: After you have joined the group, opt-in to receive Beta builds, (again with the same Google account) here. Then, download Firefox Focus (Beta) from Google Play here.

For Nightly releases: After you have joined the group opt-in, to receive Nightly builds, (again with the same Google account) here. Then, download Firefox Focus (Nightly) from Google Play here.

  • For Focus for iOS Nightly builds, check as well under the Resources section in Pontoon, at the top of the project page - or reach out directly to the project manager for Focus for iOS of localization project managers) to be added to the TestFlight system.

For Focus for iOS, please note an iOS device running v13.6 or above is needed. For Focus for Android, an Android device running v5.0 or above is needed.

Aspects to review

Here is a list of issues you should try to identify when testing the build:

  • Language quality.
  • Truncated words (cut-off from screen).
  • Anything that appears broken on the UI.
  • Check out all the main screens, UI, menus, tabs, new features, etc. Make sure these all look good, that everything is properly translated and appears as expected.
  • Font support: once you start translating, you should check against the screenshots provided that the fonts used appear correctly.
  • Untranslated content.

Concerning untranslated content on Focus for iOS: please note that we currently have two tiers of support in iOS. If your locale is only in the Tier 2 support (which corresponds to the languages under Other Languages in the iOS system settings), then it sometimes happens that menu items and dialogs, which are part of the OS itself, may not be localizable - and will therefore unfortunately appear in the primary OS language on the final UI.

Locale sign-offs

Unless there are visible l10n errors upon review of the locale’s screenshots (e.g., significant truncation, text overflow, encoding, etc.) - and besides what may have already been reported to the mobile team to correct - we will ship any locale that has started to localize (this applies to both Focus products).

Focus for Android issues can be filed here.
Focus for iOS issues can be filed here.

Details about any major updates concerning these products are always announced on the [l10n Discourse Channel - and are reflected in this document as well.

Working on mozilla.org

Some documentation specific for common tasks on mozilla.org and firefox.com

Testing Mozilla.org & Firefox.com

In mid-2025, firefox.com was spun off from mozilla.org. While mozilla.org continues to serve as the umbrella site for all Mozilla products — highlighting the organization’s mission, vision, and values, and promoting initiatives and campaigns, firefox.com is evolving into a product-centric site focused on the Firefox browsers, featuring download links, product highlights, and enterprise information. Both sites are highly visible, and their localized versions reach more than 60% of Mozilla users globally. It’s therefore critical that not only the main pages are localized, but that they are also thoroughly tested before going live in production. This document primarily focuses on mozilla.org. There will be a designated page for firefox.com once the site is fully transformed into its new design.

It’s highly advised you to ask other community members to conduct peer review not only on Pontoon, but on staging and production. While not all the languages are required for certain projects, each community can opt in the projects at a later time.

For Mozilla.org:

  • Production: https://www.mozilla.org/{locale_code}/
  • Staging: https://www-dev.allizom.org/{locale_code}/
  • Repository: https://github.com/mozilla-l10n/www-l10n
  • Pontoon: https://pontoon.mozilla.org/projects/mozillaorg/

For Firefox.com:

  • Production: https://www.firefox.com/{locale_code}/
  • Staging: https://www-dev.springfield.moz.works/{locale_code}/
  • Repository: https://github.com/mozilla-l10n/www-firefox-l10n
  • Pontoon: https://pontoon.mozilla.org/projects/firefoxcom/

What to test

Pre-l10n test

  • Have your glossary available as a reference, select mozilla.org or firefox.com as Repository, your language as your Target Locale.
  • For terminology consistency, reference the product or site that the page is for, assuming the product or site is localized (e.g.: Firefox, Monitor).
  • Have the matching US page up as reference, though some strings may not be identical due to A/B testing.
  • Have the project you just localized available for editing in Pontoon.

Linguistic testing

  • Translation quality in context.
  • Grammar correctness in context.
  • Truncation: button text should remain inside the button.
  • Header line break wraps at proper place.
  • Text not overlapping graphic.
  • Terminology consistent with product across web pages.
  • Brand names remain in English, with a few exceptions due to declension. Check out these detailed guidelines when working with brands and trademarks.
  • Product names comply to Mozilla guideline and adhere to what the community has agreed to.
  • No corrupted characters.
  • Click the links on the page to navigate to localized pages in the same language. If a page is not localized, you will be redirected based on your language preference settings (e.g., Fulah > French > English). If no preferences are set, the default is en-US.
  • Navigation terms consistent with the page titles they are linked to (except when the navigation term is shortened due to space limitation).
  • Footer links don’t overlap with one another.

You can make linguistic changes directly in both mozilla.org and firefox.com projects in Pontoon.

Functionality testing

  • Click the download link, you should be able to download the product in your language, if it is localized, such as Firefox.
  • Font support and readability.
  • Footer: verify that the translation of the link is coherent and the link is functional.
  • Language list: is your language listed as one of the options? Check https://www-dev.allizom.org/firefox/all/ (redirects to https://www.firefox.com/download/all/) to confirm. See detailed steps below to get to the language list.
  • Error page: deliberately type a broken link, such as https://www-dev.allizom.org/firefox/neu/, check whether 404 page is localized.
  • If your language is RTL, make sure that the page layout and text flow in the correct directions.

Compatibility testing:

  • Test the page layout in other major browsers and on other platforms.
  • Test the page layout on the leading locally developed browser if available.
  • Test the page layout on mobile devices of major platforms.

How to test localized pages on the production server

Updated translations are pushed to the production server regularly throughout the day.

  • New page: When a brand new page is available for localization, it will be enabled on production when it’s 80% complete. At that point, if it doesn’t reach 100% completion level, the page will be available on production with English content mixed with translation. Before the page is activated in production, use the staging server for testing.
  • Activated page with added strings: The strings will appear in English on production right away. Localized content will be pushed to production as soon as translations are available in the repository.
  • Activated page with string updates: The switch to the updated content happens when the replacements of obsolete strings are fully localized. In some cases, there is a defined time frame to show the new strings on production, so test the updates on staging server. The obsolete string will be removed three months after the introduction of the replacement strings.
  • Activated page with template change: In some cases, a page receives a major update that requires a complete rewrite of the template. If this happens, the old template is kept online only for a defined period of time. When removed, it will cause the URL to redirect users to the English version if the intended localized version is not ready, or other user preferred localized versions are not available either.
  • Activated page missing too many updates: An activated page falling far behind with multiple updates will create poor user experience. They may be subjected to removal.

Sync and update frequencies

Updated translations are pushed to the production server regularly throughout the day.

  • Pontoon syncs every 10 minutes to the repository.
  • GitHub update is pushed to production every 5 minutes.

It is safe to say that it will take less than an hour to see your changes reflected on the production server.

When a project has a firm deadline to meet, it will be indicated at the top left corner of the project page in Pontoon and at the page level. When necessary, it will be communicated through the l10n-community room on Matrix.

Testing content in Fluent

Reviewing and updating brands.ftl

File: brands.ftl

This file captures all the brand and product names that appear in all the pages on mozilla.org. As a general rule, brands and product names remain unchanged. The exceptions are:

  • Account/accounts in Mozilla account/accounts: Mozilla should be treated as a brand, but account and accounts should be translated. Both the singular and plural forms are used in lower cases. Uppercase is reserved for special use cases where headline case is necessary, for example legal document names and references.
  • Browser/Browsers in Firefox Browser/Browsers.

If your community decides to translate any of these products or feature names, translate it once and translate it in this file. Be sure to have a consensus among active contributors what the translation should be before updating this file. This practice will ensure term use consistency across all pages.  

Please refer to the guidelines for brands and trademarks when reviewing and updating this file.

Reporting technical issues

Report issues that can’t be resolved in Pontoon by:

  • Filing a bug in Bugzilla and selecting your locale.
  • Adding the l10n project manager in charge for Need Info. You can find the project manager for any project hosted in Pontoon directly in the header of the project page.
  • Including the file name plus a screenshot and/or URL.
  • If an extra tag is added to a string in order for it make sense in your language, the string will generate an error report. The l10n project manager for the project will consult you whether to make this an exception so it will not generate an error report in the future.

Reporting vendor translation errors

If the mozilla.org project is not in your Pontoon dashboard, but the site is localized into your locale, it is likely being translated by a translation vendor. Report any translation errors by:

Testing dynamic pages

This section focuses on instructions for testing pages with dynamically generated content. Each page or topic is different in terms of steps or flow. These instructions could change over time to reflect product design updates. Linguistic testing is the main focus. The instructions below are detailed steps to get to the localized content so it can be reviewed in context.

Accounts

File: firefox/accounts.ftl

On the landing page of the Mozilla account page, click on the links under each of the following products which take you to product specific pages:

  • Firefox Browser
  • Firefox Monitor
  • Firefox Relay
  • Mozilla VPN

If you already have an account, click on the Manage your account link on the right side of the landing page, which will take you to the subscription page. If you do not have an account, you will be invited to create an account by providing an email address in the Sign In box.

Note: You may see different languages between mozilla.org, the login window, and the products above. If any of these products is not localized in your locale, it will fall back to other languages set as preferred for content language negotiation, assuming any of them is available for the project, or English.

Download pages

File: firefox/all.ftl

To the right side of the page on firefox.com, there is a four-step process to go through in order to download Firefox.

  • Browsers: choose one of the options either for desktop or mobile. Click on the ? next to the Browsers category, a popup window shows the descriptions of different versions of Firefox browsers available for download. Select one browser to proceed to the next step.
  • Platforms: Click on the ?, a popup window shows the descriptions of different versions of installers available for download.
  • Languages: A list of languages available in the build depending on what is selected in the above two categories. Check whether your current preferred language is shown by default. Change to a different language, check whether the download summary above the Download Now button corresponds to your new selection.
  • Download: The Download Now button appears.

On the lower left side of each page, you will see these links:

File: firefox/download/home.ftl

This is the landing page on firefox.com:

  • Click the Download Firefox button to check the thank you page that triggers an automatic download.
  • The Firefox Privacy Notice (redirects to mozilla.org) document is localized in limited number of languages.
  • Click on the Download options and other languages link, you will be directed to the firefox/all page.
  • Click on the Firefox browser support link, you will be directed to the SUMO site featuring various topics on Firefox.
  • navigation_v2.ftl on mozilla.org: The strings in this file are shared content and are activated on production whether they are localized or not. When clicking on any of these topics on the navigation bar, Firefox browsers, Products, and About us, you will see a drop-down panel with subcategory topics.
  • navigation-firefox.ftl on firefox.com: The strings in this file are shared content and are activated on production whether they are localized or not. When clicking on any of these topics on the navigation bar, Features and Resources, you will see a drop-down panel with subcategory topics.

Within each of the topics, there is a description and a few links to help you dive deeper further into a topic which takes you to a different page. When reviewing the content, keep in mind the following:

  • Not all links take you to a site that’s localizable for all locales.
  • Not all products are offered in your locale.
  • Brand and product names must remain unchanged.

Testing localization of Mozilla projects

Mozilla encourages a three-stage review process:

  1. Linguistic review in Pontoon by community.
  2. Technical review by l10n-drivers.
  3. In-context localization testing by community and users.

Other documents will cover how the Mozilla approach to the first two stages of the review process. This document covers what to look for when performing in-context localization testing for a Mozilla product or Web project.

Localization testing process

Each Mozilla project has its own process for taking your translations and making them available for you to test. Generally speaking, the process moves like this:

  1. You submit a translation through Pontoon or directly to version control (Mercurial, GitHub).
  2. The translation goes through a linguistic review and a technical review.
  3. Once approved, the translation is automatically pushed into the project’s repository.
  4. Depending on the project, you’ll need to wait anywhere from 30 minutes to 24 hours to look for your translation in the Mozilla project.
  5. Once you’ve found your translation, if you see a problem with it, you return to Pontoon to make any necessary corrections.

Pontoon simplifies these steps for some Web projects by enabling the in-context editor (aka WYSIWYG editor). This allows you to see your translations in-context the moment you create them in Pontoon, cutting out the 30 minutes to 24 hours waiting period to test. Most projects do not have this enabled, however, so it is still important to know the typical testing process for your projects.

You might be wondering, “what sort of problems am I supposed to be looking for when I test?” Good question :-) Here’s a list of common localization bugs with screenshots that illustrate the problems in context.

Common localization bugs

Encoding and fonts

Character encoding errors occur when the browser can’t find the correct symbol to display for a character. Normally, you will recognize these errors when you see Unicode replacement characters (�), or strange glyphs, instead of letters or radicals in your language. In some cases the problem can be resolved by changing your browser’s default encoding, in other cases the problem is due to the website not serving content with the right encoding and can be fixed only by the website’s owner.

Encoding bug

Encoding bug

Fonts that do not include full support for a language’s set of glyphs can present similar issues, for example showing incorrect line spacing (leading), character spacing (kerning), or missing ligatures between characters. In the example below, the kerning of the Cherokee letters is too wide. This may be fixed by using a different font on the site.

Font bug

Truncation

Truncation happens when a translation is too long to fit in its corresponding space in the user interface. This error can cause problems with transmitting the right meaning to the user by hiding part of the translation from view. It can be corrected in one of two ways:

  • The developer increases the UI space to accommodate longer translations.
  • The localizer creates a shorter translation that captures the primary message but may not capture secondary or tertiary messages.

Truncation bug

String reuse

String reuse occurs when the same string is used in different contexts, and it represents a poor approach to localization.

Consider for example a string like Add to bookmarks: developers might consider a good idea to reuse the same string for both a button label and button tooltip, since it works fine for English. On the other hand, other languages might have completely different needs for these two contexts: while the button indicates an action (imperative verb), the tooltip is used to describe the action associated to the UI element and might need a sentence using a verb with the third person, and the element itself as implicit subject.

String concatenation and empty strings

String concatenation occurs when a developer takes one string, splits it into multiple strings, and tells the code to display these strings one after another.

This is often used to overcome technical limitations, like including a link in the middle of a sentence without exposing HTML tags to localization and injecting unsafe HTML in the UI.

Empty strings are also common when creating a sentence with a link. Typically 3 strings are used: before_link + link + after_link. English doesn’t need the part before or after the link, but that’s useful for other languages, so they’re kept empty in English. It’s expected for some locales to have a completely different behavior than English.

UI layout

Translated text often requires more space than the same text in the source language. For example, when translating between English and German, it’s common practice to expect a length increase of 30%. This can cause problems as wrapping text elements cause different parts of the user interface move around to accommodate a longer string. To fix this, the translator often needs to create a new, shorter translation that captures the primary meaning, but might lose some of the secondary or tertiary meaning.

UI layout bug

Mistranslation

Mistranslation occurs when meaning is lost between the source language and the target language. This can be caused accidentally by a lack of context for where a translation will be placed within a user interface (very common in software localization), a translator’s lack of subject matter expertise, or intentionally due to user interface text constraints (e.g., truncation).

Mistranslation bug

Untranslated strings

Untranslated strings appear in a user interface when developers don’t include that string in the string resource files available for localization, but instead in their code. It’s a practice called hardcoding. The best way to correct this error is to make sure that Pontoon does not contain the string for translation (or that it’s not in the string resource files) and then contact developers using Bugzilla to make the string available for localization.

Untranslated string bug

Style bugs

Mozilla’s official style guide serves as a primer to help communities create their own style guides. Style errors are when the tone or appearance of a translation does not match the tone or appearance described in a style guide. These can be corrected by making sure that localizers understand the style guide rules and follow them when translating.

Style bug

Numbers, date, currency

Every language and region displays numbers, dates, and currency differently. These errors occur when the user sees an incorrect number format, date format, or currency for the language and region of their localized Firefox. This can be fixed by filing a bug in Bugzilla.

Number bug

XML parsing errors

XML parsing errors (aka “the yellow screen of death”) cause Firefox to display a yellow error page. This is often due to a broken translated string in that localization of Firefox which causes the Firefox build to break. With Fluent, these errors will no longer be relevant.

XML parsing bug

Exposed variables and placeholders

Variables and placeholders become exposed in the user interface when the translated string has a typo within the variable or placeholder. Because it is not exactly the variable that the software or website expected to find, the system simply displays the variable rather than its value. A very common example of this is with the variable &brandShortName. If that variable is typed correctly in the translation, it will return the variable’s value (in this case, it’s Firefox). If it contains a typo, the user will see the variable instead (e.g., &brandshortname). These are discoverable in the Mozilla localization dashboards and can be corrected in Pontoon.

Variable bug

Broken access keys

Access keys are less effective when the same key is assigned to multiple functions within the same scope (menu, preference panel, etc.). Additionally, if the access key uses a letter not available in the label, it’s displayed near the label between parentheses. Multiple identical access keys in the same context (preference menu, toolbar menu) will require the user to press the letter twice to use it. Ideally, repetitions should be avoided, but that’s not possible in some places, e.g. the reorganized preferences shipping with Firefox 56 and later.

It’s possible to see a list of access keys using letters not available in the associated label in your Firefox localization by looking at this page in Transvision for your locale.

Access key bug

Broken language preferences

Users experience broken website language preferences in Firefox when the accept-lang preferences are left unchanged from the en-US default set of language preferences. This can lead to the user receiving web pages in a language they’re unfamiliar with by default, even when the web page is localized into their native language. It can be fixed in toolkit/chrome/global/intl.properties in the accept-lang setting.

Broken searchplugins

Users experiencing a broken searchplugin will receive a “website unreachable” message when they attempt to perform a search from their awesome bar or search bar. If you discover that a searchplugin is broken, please file a bug with the l10n-drivers.

Broken hyperlinks occur in a couple of different ways:

  1. When there are typos in the hyperlink markup, the markup is then exposed to users.
  2. When the hyperlink links to a site that is not obvious by the text it’s linked to (e.g., linking to the wrong support article according to the link’s context). These can only be discovered by using the website or software regularly and clicking each hyperlink available to ensure that they take the user to the intended website.

What to do when you find an error while testing

Congratulations! You’ve found a bug! No software is perfect and you’re very likely to find bugs while you test your localization. Once you’ve found a bug, you can either attempt to find the affected string in your community’s Pontoon projects or you can file a bug in Bugzilla for that language in Mozilla Localizations :: [your_locale]. Once a fix for that bug is landed, it’s important to test again to be sure that the issue has been resolved.

For project-specific testing guides, please see these pages:

Localization tools in Mozilla

These documents cover how to work with our tools from the user’s perspective, and use them to localize Mozilla projects.

Pretranslation

What is pretranslation?

Pretranslation is a feature in Pontoon that allows strings to be translated automatically using a combination of machine translation and translation memory. If pretranslation is enabled for a locale and project, when a new string is added to a project managed through Pontoon:

  • It will be translated (pretranslated) using a 100% match from translation memory or, should that not be available, using the Google AutoML Translation engine with a custom model.
  • The string will be stored in Pontoon with a special pretranslated status. The pretranslated status can be used in filters within the translation interface, allowing localizers to easily review pretranslated strings, and either approve or reject them.
  • The string will also be saved in the repository (e.g. GitHub), and eventually ship in the product.

While this comes with a potential compromise on quality, pretranslation brings the turn-around time to get a first translation to normally under 30 minutes.

Pretranslation uses Google AutoML Translation as its machine translation engine, selected based on reliability, quality of results, and range of supported locales. The engine is fine-tuned by training it on our own existing translation memories, which increases the chances of matching existing style and terminology.

Opt-in guidelines

To request pretranslation for your locale or a specific project, see Requesting pretranslation.

It’s important to note that these are not strict criteria: members of staff will evaluate each request to opt in individually, based on their knowledge of the project and direct experience with the locale.

Criteria for a new locale

  • Request needs to come from translators or managers active within the last month (translating or reviewing).
  • There is an active manager for the locale (last activity within 2 months).

Criteria for a new project

  • Less than 400 missing strings, except for projects or locales where existing pretranslation statistics provide high confidence.
  • Average review time for pretranslations in existing projects is less than 3 weeks.

Criteria for disabling pretranslation

  • Approval rate drops below 40%.
  • Average review time for pretranslations is longer than 6 weeks.

Note that disabling a project would always involve a conversation with reviewers for the locale.

Monitoring quality and time to review

Insights Chart - Pretranslation quality

When pretranslation is enabled and actively used, the Insights tab on a locale page (e.g. https://pontoon.mozilla.org/fr/) or a localization page (e.g. https://pontoon.mozilla.org/fr/firefox) includes a Pretranslation quality chart with monthly data:

  • Approved: number of pretranslated strings approved as-is.
  • Rejected: number of pretranslated strings rejected.
  • Approval rate: percentage of pretranslated strings accepted.
  • New pretranslations: total number of strings pretranslated that month.
  • chrF++ score: an automatic quality metric computed on rejected strings — the closer to 100, the better. A high score means the rejected strings were close to correct and only needed minor edits.

Insights Chart - Time to review pretranslations

The same Insights tab also includes a Time to review pretranslations chart, showing two lines of monthly data:

  • Average time that month: average number of days between a string being pretranslated and it being reviewed that month.
  • 12-month average: rolling average of review time over the 12 months up to that month, useful for identifying longer-term trends.

Fluent for localizers

Fluent is a localization system, previously known as L20n, designed at Mozilla to unleash the expressive power of the natural language. The format used to describe translation resources used by Fluent is called FTL.

This section of documentation includes a brief introduction to Fluent’s syntax for localizers and covers specific details regarding Mozilla’s implementation (branding rules, additional functions available in Gecko, etc.). For a detailed overview of Fluent, consult the official documentation.

Introduction to Fluent syntax

Basic syntax

A Message represents the basic unit of translation in Fluent. This is the simplest form messages can take:

welcome-msg = Hello, World!

welcome-msg is the message identifier (or message ID), and Hello, World! is the value of this message.

Messages can contain variables, for example:

welcome-msg = Welcome { $user }

$user is the name of the variable, and should never be translated. The fragment included between curly braces is called a placeable, and can be moved within the text. For example, the message above would be translated in Italian as follows, leaving the placeable unchanged:

welcome-msg = Benvenuto { $user }

Messages can also reference other messages. In this case, the placeable won’t include the $ sign, simply the message identifier:

menu-settings = Settings
help-menu-settings = Click { menu-settings } to save the file.

A Term is a special category of Message:

  • Terms have identifiers starting with a dash, e.g. -brand-short-name.
  • They can’t be called directly in the source code, but only referenced within other messages.
  • Each localization can add or remove attributes, regardless of the reference language (typically en-US).

For example, a term is used to define the Firefox brand name. For more details, see this document.

-brand-short-name = Firefox
close-msg = Close { -brand-short-name }

Attributes

For a single HTML object there might be multiple messages to localize: for example, a button could have a label and an accesskey, a link could have a text but also a tooltip. Such objects can be localized defining multiple attributes within a single message. For example, in the case of a button:

login-button =
    .label = Login
    .accesskey = L

The message login-button doesn’t have a value, but has 2 attributes defined: label and accesskey. There are a few things to highlight in this FTL fragment:

  • Attribute definitions must be indented and start with a period.
  • There is an equal sign following the message identifier, even if there is no value (i.e. the value is Null).
  • All attributes of messages found in the reference language – typically en-US – must be present in the localization. This will be enforced by tools like compare-locales, which will warn on missing or obsolete (only available in the localization) attributes.
instructions-link = Log out
    .tooltip = Disconnect from this account

In this case, instructions-link has a value (Log out) and a tooltip attribute (Disconnect from this account).

It’s important to note that, in FTL files, indentation is part of the syntax; indenting elements incorrectly will lead to parsing errors.

Selectors and plurals

With the select expression, a single message can provide several alternatives. The selected value will depend on the value of a variable, another message attribute, or a function.

The most common use of select expressions is for plural forms:

emails = { $unreadEmails ->
        [one] You have one unread email.
       *[other] You have { $unreadEmails } unread emails.
    }

Notice that both the variants and the closing curly brace are indented. The same message can also be written as:

emails =
    { $unreadEmails ->
        [one] You have one unread email.
       *[other] You have { $unreadEmails } unread emails.
    }

One of the variants starts with a *: that indicates the default option, and it must always be defined in a select expression. The part before -> is called the selector.

In this case, the message displayed will change based on the numeric value of $unreadEmails. For plurals, the variant key can either be a perfect match to a number or one of the CLDR plural categories. This allows to define special cases, beyond the number of plurals expected for a language:

emails = { $unreadEmails ->
        [one] You have one unread email.
        [42] You have { $unreadEmails } unread emails. So Long, and Thanks for All the Fish.
       *[other] You have { $unreadEmails } unread emails.
    }

Note how the [one] form in English doesn’t explicitly use the variable, in order to display the word one instead of the digit 1.

In plural messages is always possible to expose the number, even if the reference language doesn’t; the name of the variable is defined at the beginning of the select expression (in the selector), in this case $unreadEmails. The first example in this section can be translated in Italian using $unreadEmails in both forms:

emails = { $unreadEmails ->
        [one] C’è { $unreadEmails } messaggio non letto.
       *[other] Ci sono { $unreadEmails } messaggi non letti.
    }

Terms and parameterized terms

As described at the beginning of the document, terms are a special type of messages. They are used to define translations of common words and phrases, which can then be used inside of other messages. They can be recognized because of the identifier starting with a dash, e.g. -brand-short-name. Terms can also define additional language-specific attributes which are not present in the reference language (typically en-US).

While in most cases terms will have a single value, it’s also possible to define multiple values associated controlled by a parameter. These parameterized values can be used to define grammatical cases or any other language-specific modifications of the value required by the grammar of the spelling rules. When referencing a term from another message, you can optionally specify a parameter and its value with the -term-identifier(parameter: "value") syntax.

Consider the following example in English:

-fxaccount-brand-name = Firefox Account

sync-signedout-account-title = Connect with a { -fxaccount-brand-name }

In Italian this can become:

-fxaccount-brand-name =
    { $capitalization ->
        [lowercase] account Firefox
       *[uppercase] Account Firefox
    }

sync-signedout-account-title =
  Connetti il tuo { -fxaccount-brand-name(capitalization: "lowercase") }

Similar to select expressions, you must define a default value, identified by *. Also notice that parameter names are arbitrary, and don’t need to be in English. To get the default value (uppercase in the example), the term can be called without any parameter ({ -fxaccount-brand-name } or { -fxaccount-brand-name() }).

Parameters can also be nested for more complex situations, for example:

-sync-brand-short-name =
    { $case ->
        *[nom] { $capitalization ->
           *[upper] Синхронізація
            [lower] синхронізація
        }
        [gen] { $capitalization ->
           *[upper] Синхронізації
            [lower] синхронізації
        }
        [dat] { $capitalization ->
           *[upper] Синхронізації
            [lower] синхронізації
        }
        [acc] { $capitalization ->
           *[upper] Синхронізацію
            [lower] синхронізацію
        }
        [abl] { $capitalization ->
           *[upper] Синхронізацією
            [lower] синхронізацією
        }
    }

use-firefox-sync =
    Підказка: При цьому використовуються окремі профілі. Скористайтеся
    { -sync-brand-short-name(case: "abl", capitalization: "lower") }
    для обміну даними між ними.

Again, not all parameters need to be specified at all times when referencing a term. If some (or all) parameters are omitted, the corresponding default values will be used. In the example above, { -sync-brand-short-name(case: "abl") } will result in the uppercase Синхронізацією translation because upper is defined as the default value of the ablative case.

Functions

Functions can be used in Fluent to format data according to the current language’s rules, or can provide additional data to fine tune the translation.

Fluent includes some generic built-in functions, like NUMBER and DATETIME, for number and date formatting, respectively. Such functions can be used in placeables and selectors. For example:

dpi-ratio = Your DPI ratio is { NUMBER($ratio, minimumFractionDigits: 2) }

your-score = { NUMBER($score, minimumFractionDigits: 1) ->
        [0.0]   You scored zero points. What happened?
       *[other] You scored { NUMBER($score, minimumFractionDigits: 1) } points.
    }

This document describes additional functions available in Gecko products. Please refer to this document for references about the terminology used.

PLATFORM

PLATFORM is a function that allows localizers to tailor messages to the current platform. Allowed variant keys are: windows, macos, linux, android, other.

For example, Firefox settings are currently called Options in Windows, Preferences in macOS and Linux. Strings can be differentiated in Fluent by defining a message as follows:

pref-page =
    .title = { PLATFORM() ->
        [windows] Options
       *[other] Preferences
    }

PLATFORM() is used to determine the variant to use in the select expression, other is defined as default. If a variant isn’t defined, for example for linux, it will fall back to the default value.

The following example uses the PLATFORM() function for each attribute:

download-choose-folder =
    .label =
        { PLATFORM() ->
            [macos] Choose…
           *[other] Browse…
        }
    .accesskey =
        { PLATFORM() ->
            [macos] e
           *[other] o
        }

Brand names

Brand names, like Firefox or Sync, are stored as Terms in dedicated files, and shared across the application.

Unless indicated otherwise in comments, the policy is that brand names can’t be:

  • Translated.
  • Transliterated.

They need to be kept in English, and sentences adapted as needed to fit the undeclined name.

For example, a term -brand-short-name is provided in browser/branding/official/brand.ftl

-brand-short-name = Firefox

And it can be referenced in other messages as follows:


close-msg = Do you want to close { -brand-short-name }?

-brand-short-name is defined as a term to allow localizers to define custom attributes, for example to store grammatical properties. Mozilla tools like compare-locales won’t report those attributes as obsolete if the reference language (en-US) doesn’t have them. Each language is then free to put information about genders, animacy, the first letter being a vowel or not, and any more into attributes of terms.

Here’s an example in English:

-brand-name = Firefox

has-been-updated = { -brand-name } has been updated.

And how Polish can adapt its translation depending on the gender of the brand. To understand this example, consider a scenario where -brand-name would be defined in a separate file, and could change depending on the version (e.g. Firefox vs Aurora).

-brand-name = Firefox
    .gender = masculine

has-been-updated =
    { -brand-name.gender ->
        [masculine] { -brand-name } został zaktualizowany.
        [feminine] { -brand-name } została zaktualizowana.
        [neuter] { -brand-name } zostało zaktualizowane.
       *[other] Program { -brand-name } został zaktualizowany.
    }

Bugzilla for localizers

Bugzilla is the system used to track issues for most of Mozilla’s projects. For this reason, every localizer should have an account on Bugzilla, and check incoming emails and notifications. Since bugs need to be read and understood by several people, including developers, English is the language commonly used in Bugzilla.

Bugs are filed in a Product, each product has multiple Components. For localization, there are two main products:

  • Mozilla Localizations: this product has several components, including one for each locale.
  • www.mozilla.org: there is one specific component used for localization (L10N).

Bugzilla components are often referenced in the form of product :: component, e.g. Mozilla Localizations :: it / Italian or www.mozilla.org :: L10N. For some components, there is also a Locale field, that allows selecting one or more languages affected.

Locale field

A bug has a status, the most common ones are:

  • UNCONFIRMED: the bug was reported but it’s not confirmed yet. By default, a new user can only submit bugs as unconfirmed.
  • NEW: the bug has been confirmed, but it still requires action.
  • RESOLVED: the bug has been resolved.

When a bug is marked as RESOLVED, there is an additional information that describes the type of resolution:

  • FIXED: the bug was fixed by a specific action.
  • INVALID: the problem described is not a bug.
  • WONTFIX: the problem described is a bug which will never be fixed.
  • DUPLICATE: the problem is a duplicate of an existing bug.
  • WORKSFORME: it wasn’t possible to reproduce the bug.
  • INCOMPLETE: the bug doesn’t contain enough information to reproduce it, or a clear description of the issue.

When filing new bugs, the rule of thumb is:

  • If the issue can be fixed by the localization team, e.g. it’s about a typo or mistranslation, it should be filed in Mozilla Localizations :: Language or www.mozilla.org :: L10N.
  • If the issue needs work from a developer, e.g. a window is too narrow or a string is hardcoded, it’s a product bug, and should be filed accordingly. In case of doubt on which product or component to pick, Firefox :: Untriaged is usually a good starting point for Firefox bugs. If you’re reporting a bug for a specific string, you should trace back that string to a bug, and file your report in the same product and component.

More information about Bugzilla are available in this guide.

Triage localization bugs

Each localization team should keep an eye on bugs filed for their languages. The simplest way to do it is to use the BUGS tab on their team page in Pontoon.

Follow the Bugzilla component for your locale

The simplest way to keep your bugs under control is to follow your locale in Mozilla Localizations:

  • Open your account preferences on Bugzilla.
  • Select Component Watching in the left sidebar.
  • In the right section, select Mozilla Localizations as product, then your locale in the Component list.
  • Click Add.

Watch a component

The product will appear in the section You are currently watching: right below. From this moment, you will receive an email for all bugs filed in – or moved to – that component.

There are a few limitations to this approach:

  • It’s not possible to follow a single locale within a component, for example for www.mozilla.org :: L10N.
  • By default, bugs marked as UNCONFIRMED won’t send any notification. In order to receive emails for unconfirmed bugs, you need to update the Email Preferences in your profile, removing the flag from the Component column in the line The bug is in the UNCONFIRMED state.

Email Preferences

Saved searches

In Bugzilla, it’s possible to perform searches, and save them as templates. For example, let’s create a search for bugs reported against Italian in www.mozilla.org :: L10N.

Start from the Advanced Search page:

  • Leave the search field empty.
  • Select www.mozilla.org as Product.
  • Select L10N as Component.
  • Expand the Custom Search section at the bottom, and set it to Locale + contains the string + it.

Custom Search

When the results appear, you can use the Remember search button and input field to save this search.

Remember search

The list of your saved searches can be displayed by clicking in the search field at the top of the page: you simply need to click one of the items to perform the search.

Remember search

At the bottom of the page displaying search results, there’s a link to delete the saved search just performed (Forget Search “NAME”).

Note that you can select multiple products and multiple statuses (including UNCONFIRMED) to refine or expand the search criteria.

Confirm and close bugs

As already explained, each locale should address the bugs reported for their language in a timely manner. Bugs filed as UNCONFIRMED should be triaged, marked as NEW if they’re actual bugs or closed, and marked as fixed once the problem is solved.

By default, users can’t confirm or close bugs filed by other users. In order to do that, you need a permission called editbugs, which is normally assigned to localizers only after they demonstrated a clear understanding of how Bugzilla works and its etiquette. The reason for this is that this permission is assigned across the entire Bugzilla, not on single products or components. If you need to upgrade your permissions, get in touch with l10n-drivers.

Documentation for Mercurial

How to identify Bugzilla bugs that introduced a string

Sometimes it’s helpful to identify which bug on Bugzilla introduced a specific string, for example to check if an issue was already reported, or find out more information on a feature.

Note: These instructions apply only to projects that make use of Bugzilla, which currenly are Firefox projects for desktop and Android.

Find the string

The first step is to identify where the string is within the Mercurial repository by using Searchfox.

For example, if you want to know which bug introduced the string Password quality meter, you can search for the string. This may return multiples strings with the same text, so to find the exact string you can use the the identifier (which can be found from CONTEXT in Pontoon).

The results may look something like this:

Searchfox

You can further refine results to only localization files by using specific localization file extensions in the Path filter field in the top right:

  • For Firefox: limit the search to .ftl or .properties files. You can find information on the file from its CONTEXT. Or you can use {.ftl,.properties} to only show files with those extensions.
  • For Android: limit the search to .xml files.

Searchfox

Clicking on the string will open the file in Searchfox and highlight the string.

Find the bug

Searchfox shows details on the revision in which each line of code was introduced to the file, represented on the left hand sign as a bar with alternating shades of gray. Hovering over the bar next to the highlighted line containing your string will show you the revision details. The first line of the revision details contains a bug reference, a number represented as a link. Clicking the link will take you to Bugzilla where you can then check things like dependencies and comments.

Searchfox

Examining the changeset in Mercurial

You can also access the changeset in Mercurial. To view that, click full diff on the third line that says Show annotated diff or full diff.

This will show the full commit message and all the changes made as part of the bug.

Changeset info

Looking at older revisions

The above method doesn’t always work: sometimes a changeset only moves strings around, so you would need to repeat the process for an older revision of the file.

If a string was moved, the changeset for the earliest version will show the bug that moved it. In Searchfox, from the bar on the lefthand side next to your string, you can click Show earliest version with this line. From the page that follows, hover over the left bar next to the string and click full diff to show the changeset for that revision in Mercurial.

Near the top of the changeset, there’s a list of the modified files. Near each file there’s a revisions link.

Changeset info

After clicking revisions, you can pick an older changeset of a file by clicking the diff link next to the changeset you’re interested in, or repeat the process by selecting annotate. This will display the revision associated to each line of that changeset.

How to localize web projects

This set of documentation contains basic information on localizing and testing web based projects.

Firefox Accounts (FxA): how to localize and test

Firefox Accounts (or FxA) refers to https://accounts.firefox.com. There are three components in Pontoon that make up FxA:

  • LC_MESSAGES/client.po: the content server for UI and frontend.
  • LC_MESSAGES/server.po: strings for emails and backend templates.
  • Main.ftl: payments for both frontend and backend.
  • Settings.ftl: pages for account settings.

The above could change over time as the team is planning to migrate .po files to .ftl, which may involve restructuring the files.

Localizing the strings

FxA lives in two file formats: .po and .ftl, both contain variable or placeable in the strings. The shorter the string, the more context you need to make sure you get the translation right. Look for clues or get clarifications through the following methods:

  • String comments: Pay attention to the comment or string ID. In Pontoon, the comments are displayed above the area where you can enter your translation for a string.
  • Matrix channel: Ping the L10n PM in charge with any issues you may have.
  • Localization on Discourse: Follow announcement and discussions, and raise questions you have.

Errors in translations can break the build for all languages

During translation, do not alter code in a string, such as variables and HTML markup.

For .po file format, a few FxA contacts would be notified when code in a localized string is broken. Any subsequent commits by other localizers in other languages will trigger this warning until the broken string is fixed by one of the people notified. Here are a few common errors seen in localized content:

Example: Alter the code by omitting or inserting space breaks the build.

  • Source: The recipient’s consent is required. <a %(escapedLearnMoreAttributes)s>Learn more</a>
  • Target:
    • ❌ A címzett hozzájárulása szükséges. <a%(escapedLearnMoreAttributes)s >Tudjon meg többet</a>.
    • ✅ A címzett hozzájárulása szükséges. <a% (escapedLearnMoreAttributes)s>Tudjon meg többet</a>.
    • What changed in the broken translation (❌): space is removed from <a% ( to <a%(; extra space was added from )s> to )s >.

Example: Attributes should remain unchanged.

  • Source: <span class="number">2</span>Point the camera at the QR code and tap the link that appears
  • Target:
    • ❌ <span classe="numero">2</span>Puncta le camera al codice QR e tocca le ligamine que appare
    • ✅ <span class="number">2</span>Puncta le camera al codice QR e tocca le ligamine que appare
    • What changed in the broken translation (❌): both the attribute’s name class and value number were localized.

Example: Markup elements often come in pairs, one opens and one closes.

  • Source: Thank you for reaching out to Mozilla Support about <b>%(escapedLowercaseTopic)s</b> for <b>%(escapedSelectedProduct)s</b>.
  • Target:
    • ❌ Köszönjük, hogy felkereste a Mozilla támogatást a következő témában: <b>%(escapedLowercaseTopic)s</b (<b>%(escapedSelectedProduct)s</b.
    • ✅ Köszönjük, hogy felkereste a Mozilla támogatást a következő témában: <b>%(escapedLowercaseTopic)s</b><b>%(escapedSelectedProduct)s</b>.
    • What changed in the broken translation (❌): the closing element </b> was replaced by </b, leaving the tag open.

For .ftl file format, such error checking mechanism is not in place either in Pontoon or GitHub: Pontoon doesn’t have a warning, and the FxA repository doesn’t send out notifications. Before a script is developed to catch the errors, please use the above examples as general guidelines to avoid making these common mistakes.

Testing

Product updates are deployed to Pontoon on Fridays. Localized content is pushed to production on Tuesdays. Localized strings in Pontoon syncs with the l10n repository in GitHub every 10 minutes, making the repository the source of truth.

You can test on either staging and production, both involve having an account in order to access the environment. The payment feature will be rolling out to international markets through wave releases. It’s best to review localization work on the staging environment before the feature is launched to the market.

Firefox Accounts can be tested through Firefox browsers for desktop and mobile. In addition to following the general localization testing guidelines, there are features unique to the product that need special attention. Make sure you test them thoroughly.

Testing account setup

Linguistic testing

  • Login screen.
  • Email notification.
  • Check all the setting configuration buttons and the page or expanded window each page leads to.
  • Translation is of good quality and makes sense in context.
  • No broken UI, especially in a mobile environment. Text wraps or line breaks correctly.
  • Terms are consistent between pages.
  • Basic font support.
  • Error and warning messages.

Functionality testing

  • Configure the Settings. Go through all of the categories.
  • Check for email notifications with each of the initial setups.
  • Make changes to some of the settings, check for possible error messages or warnings; check for followup confirmation emails.

Testing the subscription platform

The subscription platform consists of a few features. Right now only the Payment and subscription creation is available for testing:

  • Payment and subscription creation: The initial payment funnel where users enter their credit card information to subscribe to a product. Mozilla partners with Stripe to handle this.
  • Billing: Ongoing billing and receipt emails once a subscription is entered.
  • Subscription management UI: Settings that allow the user to update their payment information.

Payment testing is tied to the language of user preference and location. Payment service is market specific. For instance, the product is available in German, but the service is available in Germany and not in Switzerland.

Before testing

  • Tips: Feeling not having enough test accounts to use for testing? You are not alone. Here are some tips you can consider.

    • Add number(s) or letter(s) to your existing account to create more accounts by adding a + in your email address. For example, if your main email is name@xyz.com, your expanded accounts could be name+1@xyz.com and name+m@xyz.com. You will receive email notifications in your name@xyz.com inbox. You can add anything you want, several digits and/or letters. Note that this works with Gmail and Google Apps domains.
    • Keep your password simple so you can log in and log out easily. Keep track of which account is connected with which password. Of course, there is Lockwise for the rescue!

  • Create a new Firefox account for testing purposes. Your existing account may or may not work.

  • Choose a Firefox browser for desktop, Android, or iOS.

  • Set the language you are testing in. Find out how to configure the correct display language by following the steps detailed in this SUMO article.

  • Have the link ready for the subscription testing server. Note, this link is for testing subscription only, different from the FxA staging server.

Testing payment and subscription creation

  • Go to the subscription testing server
  • Click on the Subscribe button which takes you to a subscription form. If you don’t have a Firefox account at this point or if your existing account doesn’t work, you will need to create one.
  • Fill out all the required fields in the form.
  • Key in credit card number 4242 4242 4242 4242. The mandatory fields for Expiration date, CCV and postal code can be filled with random values.
  • Verify formatting accuracy for date, currency and postal code. Check the box on usage agreement.
  • Click on Pay Now
  • A Thank You payment confirmation message appears with the subscription summary on your browser page with an invitation to download.
  • An email confirmation arrives in your inbox. The content should match the summary on the page where you just completed your subscription.

Note: the Privacy Notice and Terms of Use documents are not localized in all the languages where the product is offered. When not available, you will be redirected to the English versions.

Reporting technical issues

There are a few ways to report non-linguistic related bugs:

  • File an issue here.
  • Ping in the Matrix channel to the l10n PM responsible for the project.
  • Through Pontoon, click the REQUEST CONTEXT or REPORT ISSUE button next to the string and make a comment. This will notify the l10n PM in charge.
  • Send a direct email to the l10n PM responsible for the project. The email address can be found in the profile in Pontoon.

Addons.mozilla.org (AMO): how to localize and test

Product at a glance

AMO refers to https://addons.mozilla.org/. It is one of Mozilla’s biggest web properties, with 12 million users per month. The product consists of three key components that require localization:

  • AMO server is the backend component of AMO.
  • AMO frontend covers the top page of about:addons and the user-facing pages of addons.mozilla.org on Firefox for Android.
  • Discovery Pane is home of curated add-ons available on about:addons.

Product updates are deployed every Thursday to production. Localizable strings can be extracted on Tuesdays, strings localized by 5pm UTC each Tuesday go live on Thursday. To report a problem, you can use GitHub issues.

Now let’s take a look of these components in greater details.

AMO and AMO frontend

addons-server

Addons-server is the default front-end for desktop users of AMO. It is also the API backend and home to the developer hub and reviewer tools.

addons-frontend

Addons-frontend is the default frontend for mobile user-agents, and it will eventually replace the addons-server frontend for user-pages.

Test the server and the frontend

The strings will be available on Dev or Staging server at different times. See this section for details.

  • Dev: https://addons-dev.allizom.org/
  • Staging: https://addons.allizom.org/
  • Production: https://addons.mozilla.org/

The hosts for the new frontend are the same as addons-server, except to display the new frontend, you either need:

  • Click View mobile site in the footer (this will set a mamo cookie with the value on on your system).
  • A Mobile user-agent string.

Disco Pane app and editorial content

The AMO Frontend (addons-frontend) repository is also home to the Disco Pane, short for Discovery Pane. This is the site that contains curated add-ons available by typing about:addons in the address bar. Another way to reach it is by clicking Tools in the menu bar, select Add-ons in the dropdown menu, and click Get Add-ons on the left panel. While this looks like it’s part of Firefox, it’s actually a remote web page.

The content for the Disco Pane is available for translation in the AMO (addons-server) project.

Test the Discovery Pane

The strings will be available on Dev or Staging server depending on when they were committed. See this section for details.

The hosts for the Disco Pane are:

  • Dev: https://discovery.addons-dev.allizom.org/.
  • Staging: https://discovery.addons.allizom.org/.
  • Production: https://discovery.addons.mozilla.org/.

The actual link is automatically generated and depends on the locale, operative system and version of Firefox. To get the correct production link for your system, you can open the Browser Console from Tools > Web Developer, copy and paste this code snippet in the input area at the bottom of the window, and press enter:

Services.urlFormatter.formatURL(Services.prefs.getCharPref("extensions.webservice.discoverURL").replace("%COMPATIBILITY_MODE%", "normal"))

This code reads the preference extensions.webservice.discoverURL from about:config, and replaces placeholders with the correct data for your system. For example:

  • The original value of extensions.webservice.discoverURL is https://discovery.addons.mozilla.org/%LOCALE%/firefox/discovery/pane/%VERSION%/%OS%/%COMPATIBILITY_MODE%.
  • If you’re using Firefox 57.0 in Italian on macOS, the resulting URL will be https://discovery.addons.mozilla.org/it/firefox/discovery/pane/57.0a1/Darwin/normal.
  • To reach the Dev server, replace addons.mozilla in the domain with addons-dev.allizom, resulting in https://discovery.addons-dev.allizom.org/it/firefox/discovery/pane/57.0a1/Darwin/normal.

Frequency of strings extraction and push schedule

Newly added strings are extracted every week after tagging, which happens at 9am PST on Tuesdays. The strings will be on the dev server and ready for localization.

For localized content:

  • Dev server: once translations are committed into the repositories, they are visible on the dev server within 30 minutes (or as long as it takes to push the code).
  • Staging server: master is tagged and pushed to staging weekly on Tuesday at around 9am PST.
  • Production: the push usually starts at 9am PST every Thursday.

Developer.mozilla.org (MDN): how to localize and test

MDN is the acronym for Mozilla Developer Network. It hosts references and guides to Web technologies as well as Firefox at Mozilla. It attracts users around the globe. The localization communities are a key part of the Mozilla project. Their work in translating and localizing the MDN documentations helps people around the world develop for the open Web.

MDN consists of three parts:

  • The site user interface (or UI) strings that appear on almost all MDN pages to frame the main article content and provide navigation and user controls.
  • The main body of MDN pages consists of references, guides, and tutorial articles. Localization is done directly on the web.
  • Macro strings are the output by macro templates that construct certain kinds of navigation, messages, or generated structures. The strings currently live on GitHub, and changes can be done through pull requests.

This document only covers the UI portion localizable in Pontoon.

Localizing the strings

The UI strings for MDN product live in Pontoon. The string changes are extracted and sent to Pontoon as part of the production push process. You can translate directly in Pontoon or download it as .po files and upload them back to Pontoon when done. Newly localized strings will be included in production updates.

There is no sprint cycles. The staging and production sites are updated 1 - 3 times a week depending on product development. You should expect to see your new translations on production in 3-7 days.

Pontoon will be synced up with MDN repository every 20 minutes. Updating localization strings is preferably done in Pontoon, and not through pull requests in the repository.

Testing and reporting issues

Staging and production pushes take place at the same time. Localized sites will have English strings for a few days before localization is caught up. There is no public developer server at the moment.

Bugzilla is the best way to report localization issues.

Communication channels

  • For live communication, use IRC channels: #mdndev or #mdn.
  • MDN Discussion Forum has recently moved away from mailing list to Discourse. Though there is no l10n category, MDN category is for discussing topics related to the MDN site. If you have a question, you can post it in the general MDN category.
  • If you want to be notified for string changes, one way is to check Pontoon project dashboard for pending task. Another way is by subscribing to the notification list: click the Watch icon on the top of MDN GitHub repository page and be notified about pull requests and code changes.

Mozilla Donate website: how to localize and test

donate.mozilla.org is our platform to collect donations. The main instance is for donations to the Mozilla Foundation, but there is also a separate instance for donations to Thunderbird.

Testing

Submitted translations are automatically deployed to the staging server, so you can test them a few minutes after they have been translated.

  • Staging server: https://donate-wagtail.mofostaging.net/​.
  • Production server: https://donate.mozilla.org/.

Testing the payment flow

You may want to test the complete user journey on the website, but you don’t have to make an actual donation for that. Braintree (our payment processor for debit/credit cards) has a test mode that is enabled on the staging server only. Simply use the payment info from this page on the staging server and you should be able to simulate a payment. For instance, you can select an amount of money, click on donate by credit/debit card then fill out the form with the testing info. Make sure errors, as well as the page displayed when the donation has been successful, are properly localized.

Testing currency settings

The first thing to check is that the website supports all the relevant currencies for your locale.

You also want to make sure the default currency selected for your locale is the one that makes the most sense. Only one default currency can be set per locale and it’s not possible to rely on geolocation to determine the best one.

If your language is relevant in more than one country, make sure the other currencies are also available in the drop down.

Check that the currency formatting on the page is correct for your language. If it’s not correct, please file an issue.

How to report an issue

The preferred way is to file an issue on the donate.mozilla.org GitHub repository.

Support.mozilla.org(SUMO): how to localize and test

SUMO, short for SUpport.MOzilla.org, is a knowledge base site, providing support to Mozilla product users. More than half of all Firefox users speak a language other than English. Mozilla depends on contributors to make support available to people around the globe.

SUMO consists of two parts:

  • User interface (or UI), such as navigation and buttons.
  • Support articles, either used to troubleshoot issue or as knowledge base for Mozilla products.

This document only covers the UI portion localizable in Pontoon.

Localizing the strings

There are two active components in Pontoon that make up the product:

  • LC_MESSAGES/djangojs.po contains strings for the JS bits of the platform.
  • LC_MESSAGES/django.po contains the majority of strings in the SUMO product.

SUMO is made up by several file types. In order to minimize revision and get translation right the first time, the key is to get the context right. Look for clues or ask others for help:

  • String comments: in Pontoon they’re displayed above the area where you can enter your translation for a string. They always include a reference to the code where the string is used, and you can use this information to search for context in the Kitsune GitHub repository.
  • The SUMO l10n forum. But first thing first, you need to create a Firefox account in order to participate in the discussions in the forum.

Localized strings in Pontoon will be synced up with sumo-l10n on GitHub every 20 minutes, making the repository the source of truth.

Ignore these legacy components:

  • LC_MESSAGES/buddyup.po contains strings for mobile-centric 1-to-1 support project.
  • LC_MESSAGES/yaocho.po contains strings for the mobile version of the support knowledge base.

Testing

On Wednesdays, SUMO developers extract new strings from code and database edits. These strings are merged into the sumo-l10n repository and become available in Pontoon for translation.

Translated strings from Pontoon are pushed automatically to the staging and production when there is a release to the respected environment. Usually this happens once a week.

There are three ways to test the product:

  • Staging server: https://support.allizom.org​.
  • Production server: http://support.mozilla.org/.

Testing on production/staging

Localization updates are pushed to the staging and production environments usually once a week. More often for staging. Either way, the SUMO team relies on contributors to find issues and report bugs that are usually fixed at a timely manner.

FAQ

For any additional questions not covered here, you can reach out to the #sumo room in Matrix to discuss it.

How often are new strings added? Is there a sprint?

No, there are no sprints. Strings are added at as needed basis. Whenever a release or change is required, new strings will be added to both Pontoon and Kitsune on Mondays.

How do I participate in the SUMO l10n forum?

To be part of the SUMO community, you need to create a Firefox account, which allows you to write in the community l10n forum and localize SUMO articles. This is separate from the account used to log into Pontoon in order to localize SUMO product.

Are there email communications when new strings are added?

Only when there is a release or a major change will there be communications to localizers through mailing list (sumo-locale-leaders@), private messages, and the SUMO l10n forum. The Pontoon dashboard is the best way to check for pending tasks.

What are the ways to report an issue?

  • File a bug for SUMO. This is the quickest way to have a problem resolved.
  • Discuss it in the SUMO l10n forum.
  • Ping in the Matrix channel the l10n PM responsible for the project.
  • Through Pontoon, click the REQUEST CONTEXT or REPORT ISSUE button next to the string and make a comment. This will notify the l10n PM in charge.
  • Send a direct email to the l10n PM responsible for the project. The email address can be found in the profile in Pontoon.

It is not recommended to file issues on GitHub sumo-l10n.

Use of paid services for product localization

Mozilla’s localization model has always been community-first. Volunteer contributors and community managers are the foundation of how our products are translated, reviewed, and maintained across the world.

As Mozilla grows in new markets and launches new initiatives, there are occasional situations where release timelines and business requirements call for additional support. To improve transparency and reduce ambiguity, this page documents when and how paid localization services may be temporarily used.

This documentation does not represent a change in our current workflow. It clarifies a structured and limited approach to ensure product availability in priority markets while preserving long-term community ownership.

When is paid localization service used?

Temporary localization service by a Language Service Provider (LSP) may be considered only when both of the following conditions apply:

  • Business priority: A locale is required for market expansion, product launch, or another defined strategic initiative.
  • Community bandwidth gap: The current community does not have sufficient active capacity to meet required timelines or completion levels.

Paid localization service is not used to replace active communities or override community decisions. If either condition is not met, paid localization service is not necessary.

What does paid localization service include?

Depending on the situation, paid localization service may include:

  • Translating and reviewing missing strings.
  • Reviewing pending suggestions.
  • In-context linguistic QA (LQA).
  • Terminology alignment within the defined scope.

The scope is defined in advance and limited to specific products and timeframes. Community-developed terminology and style guidelines will be adhered to during paid engagements.

How does this affect community ownership?

Paid localization service is temporary, scoped to specific products or releases, used to meet defined timelines, and designed to transition back to community ownership.

After the defined work is completed, normal community contribution and review activities resume. Communities may review, refine, and improve translations after initial delivery.

How are communities informed?

Communication is intended to ensure transparency and avoid overlapping work. Before paid localization service begins:

  • Notify community managers and active translators
  • Explain the business rationale
  • Share the scope and expected duration

Frequently Asked Questions

Does this mean the community is being replaced?

No. Paid localization service is short-term, temporary, and limited to specific deliverables. Community ownership remains the long-term model.

Will paid translators override community decisions?

No. Paid localization service focuses on meeting delivery timelines within a defined scope. Community defined terminology and style will continue to guide localization, and ultimate ownership by the community will remain unchanged. Communities can review and refine translations after the scoped work is completed.

What if the community disagrees with the decision to implement temporary paid localization service?

Decisions are based on documented business priorities and delivery timelines. While we aim to communicate in advance and welcome feedback, some initiatives may require action within defined release schedules. Paid localization service remains limited and time-bound.

Why not wait for volunteers instead of using paid translators?

Volunteer contributions are central to Mozilla localization. However, when product launches or market initiatives have defined timelines, missing them may affect user experience and strategic goals. Paid localization service is used only when timelines cannot be met through available volunteer capacity.

Will paid translators maintain the product afterward?

No. Paid localization service is structured around specific scopes and timelines. Long-term ownership and maintenance remain community-driven.

Can communities request paid localization service?

Paid localization service is implemented when both business priorities and community capacity gaps are present.

Is paid localization becoming the default model?

No. Mozilla remains committed to community-driven localization. Paid localization service is used selectively and only when a business need encounters a capacity gap.

Couldn’t Mozilla pay community members instead?

No. Mozilla cannot engage individual contributors through direct payment for localization work. When paid support is needed, we are required to work with vetted language service providers that meet legal and procurement requirements. Community contribution is the heart of Mozilla localization and vital to our mission. We continue to invest in and advocate for resources that support contributors, such as events and community engagement initiatives.

Using l10n resources while translating

What are l10n resources

The different levels l10n resources help ensure quality and consistency. L10n resources are used to ensure consistency of translation and localization at specific levels of a document or set of documents. These levels are:

  1. Word or phrase level (terminology).
  2. Sentence or string level (translation memory).
  3. Whole document or project level (style guides).

Terminology

Terminology resources define specific words or phrases and their translated equivalents to be used in the translation process. These resources often go beyond providing one-to-one bilingual equivalents. They can include metadata about a particular term, including a monolingual definition, part of speech, context, images, and other relevant metadata that helps the translator understand the concept behind the term. A term belongs in the approved term base (terminology database) when it appears regularly, has a singular meaning in a particular context, or is specialized in nature.

Term bases are useful in helping translators to maintain meaning and consistent terms across multiple projects. They’re especially useful in collaborative translation environments that involve multiple projects with similar content and audiences. Term bases also help to ensure that any new collaborators can translate effectively in a shorter period of time.

Using term bases ensures that a user’s experience is consistent across platforms, products, and content types. For example, terminology used in the Firefox desktop UI also appears in Firefox for Android, Firefox for iOS, and SUMO documentation. If a user encounters a problem in Firefox, they will expect to find a solution by searching SUMO with the text from the Firefox desktop user interface. Consistent terminology use ensures a holistically consistent user experience for such cases.

Translation memory

Translation memory is a mechanism that reuses previously translated segments (i.e., strings, sentences, etc.). These segments are stored in a database as a key-value pair, with the source language segment as key and the target language segment as its value. Algorithms like the Levenshtein Distance are then used to compare an untranslated segment to the database of source language segments. If there’s a perfect match, the target language segment is returned for the translator to reuse. If there are partial matches (i.e., fuzzy match), they are returned as suggestions. Translators can then post-edit the closest matching suggestion without needing to repeat fully translating the segment.

Translation memory is useful in helping translators to translate more in a shorter amount of time. For example, it allows source content authors to make regular updates to source content without causing translators to treat these updates as untranslated segments. As with term bases, translation memory also ensures consistency between similar projects and collaborative translation projects with rotating contributors.

Style guides

Style guides establish the norms for translating a full document or project. It establishes norms for many of the following topics:

  1. Style.
  2. Tone.
  3. Grammar and spelling resources.
  4. Instructions on handling cultural references.
  5. Word forms (e.g., plurals, abbreviations).
  6. Language and culture-specific units (e.g., dates, numerals, currency).
  7. Criteria for identifying “Do-Not-Translate” content in a project.

Style guides help translators to know to address their audience (or users) in the target language when translating. They ensure consistency between translators in all of the above-mentioned topics. In a collaborative translation environment, they serve as the standard against which peers can review and correct translations from both new and old translators.

When are they used in the l10n process

Term bases and translation memory are best used within the translation environment (e.g., Pontoon). These computer-assisted translation (CAT) tools are designed to make use of these resources as a translator is in the process of translating a project.

Style guides are used primarily as a point of reference. A new translator should always begin their contributions by studying the style guide and refer back to it regularly while translating when they have questions. Reviewers use style guides to ensure that new translations meet the quality standards established in the style guide.

Glossary

Explanation of common terms and concepts used across documentation.

Comment

Comments can be used, for example, to discuss possible translations with other team members or request more information from project managers.

Pontoon supports two types of user comments:

  • Source string comments are associated with the source string and displayed in the COMMENTS tab in the right column.
  • Translation comments are associated with a specific translation and displayed under the editor in the translation list.

Comment authors can edit or delete their own comments. Project managers can also delete any comment for moderation purposes.

User comments should not be confused with Resource comments, which developers can add directly to the resource file. This type of comment is displayed in the editing area, along with other information like the resource path and context.

Fuzzy

fuzzy is an internal state available only if the source file is a gettext (.po) file. A string can be marked as such in a few cases:

  • The reference text changed after the string was already translated.
  • The string has been manually marked by translators because it needs review.
  • New strings were merged in the localized files, enabling the option to match existing translations (also called “fuzzy matching”).

In all these cases a translation exists in the file, but is marked as fuzzy (equivalent to “need review”) and not used by the website or application. For more information, read the documentation about Fuzzy Entries in gettext.

Locale

A locale is the combination of a language and a region, represented in Pontoon by a locale code. For example, American English is referred to as en-US, where en stands for the language (English), and US for the region (United States). In some cases, the region is omitted, because the language is mostly spoken in one region.

In Pontoon, each locale maps to a team.

Machine Translation

Machine Translation (MT) is the translation of text from one language to another, performed by software without human involvement. There are different types of machine translation solutions (or “engines”), but all modern systems are based on a neural network approach (vs statistical or rule-based).

In Pontoon, machine translation is used as part of the pretranslation feature, powered by Google AutoML Translation with custom models trained on existing translation memories.

Permission

Users in Pontoon can have different permissions depending on their role:

  • Translators can either submit approved translations directly or review suggestions from other users. Unlike in some other Translation Management Systems, this is a single permission in Pontoon, and it’s referred to as Translator permission.
  • Team managers have translator permissions, but can also change permissions assigned to other users (i.e., promote or demote them).

Pretranslation

Pretranslation is a feature in Pontoon that relies on machine translation (Google AutoML Translation) and translation memory to automatically translate strings and save them in localized files.

If pretranslation is enabled for a combination of a locale and a project, when a new string is added in Pontoon:

  • It will be translated (pretranslated) using a 100% match from translation memory or, should that not be available, using the Google AutoML Translation engine with a custom model.
  • The string will be stored in Pontoon with the pretranslated status.
  • For projects using version control systems, the translation will be stored in localized files outside of Pontoon.

Resource

Resources are localization files within a repository (see version control system) used to store source content and translations. They can be in different file formats but generally follow the same key-value structure, where the key (displayed as Context in the Source string panel) is a unique identifier and the value is a text snippet that needs to be translated.

Terminology

Terminology — sometimes also referred to as a Glossary — is a list of terms and their definitions. Pontoon will highlight any terms in the source string and show their definitions as well as translations into the target language.

TBX, or TermBase eXchange, is a standard file format used in the translation industry to represent and exchange terminological information. Pontoon Terminology can be downloaded in the TBX format.

Translation

A translation is any submission of the target content. There are several types of translations:

  • Approved translations: translations submitted directly or approved by users with translator permissions.
  • Suggestions: translations that have not been reviewed yet (pending).
  • Pretranslations: translations that have been authored by the pretranslation feature.

Translation memory

Translation memory is a list of all approved translations for any string. It can be leveraged to provide suggestions when translating new content.

TMX, or Translation Memory eXchange, is a standard file format used in the translation industry to represent and exchange translation memories. Pontoon Translation memory can be downloaded in the TMX format.

Translation mode

Depending on their settings and permissions, users will be able to submit translations directly (Translation Mode), or only submit suggestions (Suggestion Mode).

Contributors — users without translator permissions — can only access Suggestion Mode, while translators and team managers can manually switch between the modes.

Version Control System

Most projects store source content and translations outside of Pontoon, in repositories that use version control systems (VCS). The most popular are git and Mercurial (hg).

Pontoon periodically (usually every 10 minutes) imports source content and translations from these repositories and writes translations back. This process is referred to as Sync.

Pontoon also supports the so-called DB projects, where source content and translations are stored in Pontoon’s internal database (DB).