Set up searchplugins and protocol handlers

Set up searchplugins

Searchplugins configuration has become too complex and it’s constantly evolving, because of that a bug needs to be filed to let the Search Team set up new locales. This section is meant as an overall reference, with link to external documentation.

Given the complexity and external dependencies, it’s become common practice to set up searchplugins at a later phase, when the locale is ready to move from Nightly to Beta, and let Nightly rely on default settings.

Starting with Firefox 68, the XML OpenSearch format was dropped for built-in searchplugins, switching to WebExtensions. Each searchplugin has its own folder, with:

  • An icon, which can be either in PNG format (favicon.png) or ICO (favicon.ico).
  • A WebExtension manifest (manifest.json). If the searchplugin supports only one locale, the manifest includes the localized name (repeated twice) and description (leo-ende example).
  "name": "LEO Eng-Deu",
   "description": "Deutsch-Englisch Wörterbuch von LEO",
  "chrome_settings_overrides": {
    "search_provider": {
      "name": "LEO Eng-Deu",
  • A _locales folder if the searchplugins supports multiple locales. In this case, the manifest will only include placeholders for name and description, and they will be localized in a subfolder for the locale itself (Wikipedia example).
  "extensionName": {
    "message": "Wikipedia (it)"
  "extensionDescription": {
    "message": "Wikipedia, l'enciclopedia libera"

As of Firefox 77, the search configuration is still stored in-tree (list.json). More recent versions of Firefox will switch to a new configuration system (search-config.json), and use Remote Settings to be able to update the configuration independently from the release cycle. The new system, including the schema for search-config.json, is documented in Firefox Documentation - Search Service.

When filing a new bug, make sure to provide the following information:

  • The list of searchplugins to use for the locale.
  • If a new searchplugin needs to be added: name, description, icon, search parameters. The best way to make sure all information is included is to use existing searchplugins as reference.

Tips for icons and Wikipedia


These are some useful tips to deal with icons for brand new searchplugins:

  • If the image is a PNG, make sure to optimize it before encoding it to base64 (for example using
  • You can create an .ico file starting from separate 16px and 32px PNG icons. Create a 32px image in Gimp, add each icon to a separate layer, and export the file as .ico (make sure to select the option to compress each of the layers).
  • You can use online services (like this one) to quickly encode an image to base64.
  • You can test the image in the browser (copy and paste the data URI in the address bar). You will still have to download it to check that everything looks good, since only one image will be displayed for multilayer .ico files, and transparent files are displayed in a misleading way in Firefox preview.


URLs: Make sure to update all URLs. If the URL for English starts with en.wikipedia., for ur it should start with ur.wikipedia. (check if the domain actually exists).

Search template: There’s one special URL to keep in mind, in English it’s It’s particular because the last part changes according to the locale, just try replacing the domain first from en. to ur.: You’ll notice that it redirects toخاص:تلاش and that’s the URL you need to use in the webextension.

You can’t copy the full URL from the address bar since it will encode UTF-8 characters, e.g., so it’s faster to just copy only part of the URL and fix the rest by hand.

Description: You will need localizers to provide the translation for Wikipedia, the Free Encyclopedia.

Name: In the localization file there’s an attribute called extensionName. For English is:

"extensionName": {
  "message": "Wikipedia (en)"

To get the localized name, visit and press CTRL+U to view the source code of the page. At the beginning you will find a line looking like this:

<link rel="search" type="application/opensearchdescription+xml" href="/w/opensearch_desc.php" title="ویکیپیڈیا (ur)"/>

The Name to use in your localization is ویکیپیڈیا (ur). Copying and pasting RTL languages is particularly tricky.

Set up protocol handlers

You will be working on l10n-central to set up protocol handlers for a new locale, and you need this locale’s Mercurial repository on your computer.

l10n repositories for Firefox live in In this case, let’s assume that l10n clones will be stored in ~/mozilla/mercurial/l10n, with a subfolder for each locale. So, if the locale is ur, the repository will be stored in ~/mozilla/mercurial/l10n/ur.

$ mkdir -p ~/mozilla/mercurial/l10n
$ cd ~/mozilla/mercurial/l10n

The first command makes sure that the path for l10n repositories exists, the second moves into the folder.

If you don’t have a clone yet, you need to create it:

$ hg clone ssh://

The command uses ssh://, which means you need an active (and properly configured) SSH access to the repository.

Once the execution is completed, there should be a clone stored in ~/mozilla/mercurial/l10n/ur.

If you already have a clone on your computer, always make sure to update it before doing anything:

$ cd ~/mozilla/mercurial/l10n/ur
$ hg pull -r default -u is stored in /browser/chrome/browser-region for Firefox desktop, and it contains information about protocol handlers. You can use this model as a base.

If you’re updating an existing file, make sure to not reset the gecko.handlerService.defaultHandlersVersion key. If, on the other hand, you’re adding a new handler, you will have to increment the existing numeric value.

Creating a patch for review (locale repository)

Once files are ready, follow the instructions available in this document to create a patch, submit it for review, and land it.