L10n:Toolbox/Creating a search plugin

From MozillaWiki
Jump to: navigation, search

Patching a search plugin

Creating a patch for a search plugin is a specific task during the localization process that provides an excellent set of skills that can be applied to other aspects of the localization work flow. The follow document instructs a localizer on the "how-tos" for creating a search plugin in "mozsearch" format, testing that search plugin, creating a patch for review, and updating local repositories to reflect the new changes so that a localizer is ready to commit those changes to their public repository.

Cloning your repository locally

To begin working on editing the search plugins for a localization, the localizer must first clone the most recent version of the repository from the stable branch that corresponds with the current release cycle for Firefox. For example, at the time of Firefox 3.5, localizers work from the Mozilla 1.9.1 branch. From this branch, each team clones the public repository to their local environment by running the following commands:

Open the terminal prompt and navigate to a file folder on the local disk where localization work will take place.

From the command line of the terminal prompt, type:

 $ hg clone http://hg.mozilla.org/releases/l10n-mozilla-1.9.1/ab-CD

(where ab-CD should be replaced by a specific locale code)

The output will read something like

 destination directory: [ab-CD]
 requesting all changes
 adding changesets
 adding manifests
 adding file changes
 added 65 changesets with 354 changes to 254 files
 updating working directory
 205 files updated, 0 files merged, 0 files removed, 0 files unresolved

where the number of changesets with changes to files will be unique to each locale.

The next set of commands enable a localizer to open the files and begin working.

Oftentimes, it is wise to check the present "path" where the last task was executed. From here, one can begin to navigate to the next path where work will continue. A user can check the current path by typing the following:

 $ pwd

And the output should show something like


Now, navigate to the local repository that was created in the hg clone command above by typing

 $ cd [ab-CD]

Looking inside the searchplugin directory

Since we are now in the present directory in the path where we cloned our repository, you can now navigate all the way to the search plugin section of the browser code by typing the following

 $ cd browser/searchplugins/

To list what files are located in this directory, type

 $ ls

The output should show a list of search plugins in the present directory.

  • yahoo.xml
  • amazon.xml
  • eBay.xml
  • wikipedia.xml
  • creativecommons.xml
  • list.txt

As you can see, if no changes have been made, the en-US default search plugins will show like above.

Localizers work to customize these settings so that the local version of Firefox presents a set of plugins that are relevant to the end user. Localizers need to research the best choices, guided by the <a href:"">"productization"</a> process. Search plugins are categorized into three parts:

  1. General purpose
  2. e-Commerce
  3. Specific interest

Once the set has been determined and the search providers have responded with the information necessary, we can begin to create the search plugin files.

Creating a new search plugin file

After a localization team has selected the proper search plugins, it is time to create an .xml file in "mozsearch" format. Type the following command.

 $ open yahoo.xml 

The yahoo.xml file should open in a code editor or text editor. Popular text editors for Mac include Text Wrangler, Dashcode, and or TextEdit.

mozsearch format

Once the file is open, the following file should appear:

 <SearchPlugin xmlns="http://www.mozilla.org/2006/browser/search/">
 <Description>Yahoo Search</Description>
 <Image width="16" height="16">data:image/x-icon;base64,R0lGODlhEAAQAJECAP8AAAAAAP///wAAACH5BAEAAAIALAAAAAAQABAAAAIplI+py+0NogQuyBDEnEd2kHkfFWUamEzmpZSfmaIHPHrRguUm/fT+UwAAOw==</Image>
 <Url type="application/x-suggestions+json" method="GET" template="http://ff.search.yahoo.com/gossip?output=fxjson&command={searchTerms}" />
 <Url type="text/html" method="GET" template="http://search.yahoo.com/search">
   <Param name="p" value="{searchTerms}"/>
   <Param name="ei" value="UTF-8"/>
   <MozParam name="fr" condition="pref" pref="yahoo-fr" />

This is the standard "mozsearch" format. If we have received all the search parameters and plugin information from a provider, we can edit this document and save it in the searchplugins directory as a new file, named after the search provider.

...from a search provider

Providers typically give the following information:

  • ShortName -- the name that a provider chooses
  • Description -- the description that will show up in the search box
  • Favicon URI -- an image that will be displayed in the chrome of the browser
  • Search URL -- the URL that a user will follow if a search is initiated from the Firefox search box with no search terms entered
  • Parameters to specify the search results -- parameters often provided by a partner to help specify that a search is coming from Firefox
  • Search Form -- The search URL from the provider

Let's take an example from a search provider called Webdunia from India.

Webdunia provides general purpose search services for Malayalam speakers. The localization team received the following email with all information necessary to create the Wedunia search plugin.

Please pass on the below information to Mozilla.
Presently we are following all open search standards for using instant search box. They can find details of parameters for Webdunia search at
Referral Tracking: I wish if they can return FF-SearchBox for Searches done through Search Box and FF-Address if the serach is done through the address bar.
Webdunia team

In this example, all basic information is contained in the feed:


Cut and paste that feed into a browser to see the following:

 <ShortName>Webdunia Search</ShortName>
  Webdunia Search : A Multilingual Search Engine for Indian Content
 <Tags>Webdunia Multilingual Search</Tags>
 <Url type="text/html" template="http://search.webdunia.com/search.aspx?q={searchTerms}"/>
 <Url type="application/x-suggestions+json" template="http://search.webdunia.com/suggestions.aspx?q={searchTerms}&stype=json"/>
 <LongName>search.webdunia.com Multilingual Search</LongName>
 <Image height="16" width="16" type="image/x-icon">http://search.webdunia.com/favicon.ico</Image>
 <Query role="request" searchTerms=""/>

Making a favicon for the search plugin

First off, let's convert the favicon URI to something that we can use for our plugin.

Copy the favicon URI to your clipboard. In this case, it is


Visit the "URI Kitchen" website


Paste the URI into the HTTP URI box on the site and be sure to click the base 64 box at the top and then click "Generate". Copy the entire string in the URL Location bar. For this example, it should be


Copy and paste this *entire* into our search plugin file that we are editing so that <Image width="16" height="16">[your new URI]</image> reads


Special parameters requested by the provider

Next we have to specify any parameters that the search plugin provided. In the Webdunia example, they have defined parameters of their search template and we need to amend our search plugin to account for this format. We do this by changing

 <Url type="text/html" method="GET" template="http://search.yahoo.com/search">
   <Param name="p" value="{searchTerms}"/>


 <Url type="text/html" template="http://search.webdunia.com/search.aspx">
   <Param name="q" value="{searchTerms}"/>

As is often the case, Webdunia is also asking for an additional parameter to track the percentage of searches are coming from Firefox. We honor these requests and modify the Param settings in the mozsearch form. You can see exactly how the mozsearch form is edited to satisfy their request by adding a new line,

 <Param name="FF-SearchBox" value="1" />

after the parameter

 <Param name="q" value="{searchTerms}"/>

When you are ready to test, when searching for the term "Banglore", this parameter will return a URL :


Lastly, be sure to amend each of the following as instructed by the search provider:

<ShortName> <Description> <SearchForm>

Search providers will often provide more information, but you only need to make sure the mozsearch template is complete. Nothing else, with the exception of specific search parameter requests as shown above, is necessary.

Final format

The final search plugin file should looks like this

 <SearchPlugin xmlns="http://www.mozilla.org/2006/browser/search/">
 <ShortName>Webdunia Search</ShortName>
 <Description>Webdunia Search : A Multilingual Search Engine for Indian Content</Description>
 <Url type="text/html" template="http://search.webdunia.com/search.aspx">
   <Param name="q" value="{searchTerms}"/>
   <Param name="FF-SearchBox" value="1" />
 <Url type="application/x-suggestions+json" template="http://search.webdunia.com/suggestions.aspx">  
   <Param name="q" value="{searchTerms}"/>
   <Param name="stype" value="json"/>

Amending list.txt file

Localizers have to amend the "list.txt" file in your repository to account for the new search plugin. Type the following: $ open list.txt

Add the name of your search plugin to the list. In the above example, it is


Save your list.txt document.


One quick way to test your plugin is to copy the .xml file you just created an paste that file into an existing Firefox profile. You can do this by copying the file in the repository (right click --> copy file) and then navigating to your Firefox profile. On a Mac, you would do this by navigating

 ~Library/Application Support/Firefox/Profiles/[Your profile]/searchplugins/

and pasting the .xml file into that folder.

Restart Firefox and check the upper right search plugin drop down box to see if the new plugin is there. Type "Bangalore" and you should see results in the browser window. The URL in the location bar should


Removing other search plugins

If in your work, you would like to remove the en-US default plugins so that you can add more relevant local providers, you simply need to navigate to the path of your local repository's searchplugin directory from your home state.

Remember the cd command.

 $cd /Users/../../../ab-CD/browser/searchplugins/

Let's say you want to remove the Yahoo! search plugin. From the termina in the searchplugin directory, type

 $ rm yahoo.xml 

Be sure to also remove the search plugin from the list.txt file by opening that file, removing the name of the plugin and saving it.

Check the status of your repository

 $ hg stat

You'll see

 R browser/searchplugins/yahoo.xml

You now need to update your repository with the

 $ hg addremove

Check status

 $ hg stat

And you see

 R browser/searchplugins/yahoo.xml

Create a new patch that removes the plugin

 $ hg diff > ~/Desktop/abCD.searchplugin.patch

And then follow the steps above to upload that patch.

Editing Region.properties

If you have removed a search plugin and replaced it with a local provider, you will need to edit the order of your region.properties file.

Navigate to the region.properties file with a path like


Using the Webdunia example from above, open the region.properties file in this directory using the following command

 $open region.properties

In the text editor, change the line that reads

 browser.search.order.2 = [default Search Provider, typically Yahoo]


 browser.search.order.2 = Webdunia Search

Save your file.

Updating your local repository and creating a patch

After the file has been tested, we need to add and remove any changes we may have made to the local repository. Be sure that the current path leads to the ab-CD directory where all edits occurred. Remember, check the path by typing:


the path should say something like


Once there, type

 $ hg addremove

To get an output like

 adding browser/searchplugins/webdunia.xml

This shows that Webdunia has been added.

Check the status of your hg repository by typing

 $ hg stat

This yields

 M browser/searchplugins/list.txt
 M browser/chrome/browser-region/region.properties
 A browser/searchplugins/webdunia.xml

which tells that we (M) modified the list.txt document and region.properties and (A) added an xml file called webdunia.xml


Now you are ready to look at the differences between the repository before and after all this work.


 $ hg diff

And the output reflects the "diff" (difference) of all changes you have made.

 diff -r c924c77b0bfd browser/chrome/browser-region/region.properties
 --- a/browser/chrome/browser-region/region.properties	Wed Jul 22 16:58:37 2009 +0530
 +++ b/browser/chrome/browser-region/region.properties	Wed Aug 12 18:19:58 2009 +0200
 @@ -5,7 +5,7 @@

 browser.search.defaultenginename = Google
 browser.search.order.1 = Google
 -browser.search.order.2 = Yahoo
 +browser.search.order.2 = Webdunia Search
 browser.contentHandlers.types.0.title = Bloglines
 browser.contentHandlers.types.0.uri = http://www.bloglines.com/login?r=/sub/%s
 browser.contentHandlers.types.1.title = My Yahoo
 diff -r 567ef2c90f0f browser/searchplugins/list.txt
 --- a/browser/searchplugins/list.txt	Mon Jan 12 13:21:09 2009 +0530
 +++ b/browser/searchplugins/list.txt	Wed Aug 12 16:08:36 2009 +0200
 @@ -2,3 +2,4 @@
 diff -r 567ef2c90f0f browser/searchplugins/webdunia.xml
 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
 +++ b/browser/searchplugins/webdunia.xml	Wed Aug 12 16:08:36 2009 +0200
 @@ -0,0 +1,14 @@
 +<SearchPlugin xmlns="http://www.mozilla.org/2006/browser/search/">
 +<ShortName>Webdunia Search</ShortName>
 +<Description>Webdunia Search : A Multilingual Search Engine for Indian Content</Description>
 +<Url type="text/html" template="http://search.webdunia.com/search.aspx">
 +  <Param name="q" value="{searchTerms}"/>
 +<Url type="application/x-suggestions+json" template="http://search.webdunia.com/suggestions.aspx">  
 +  <Param name="q" value="{searchTerms}"/>	
 +  <Param name="stype" value="json"/>

Creating the patch

To create the patch for upload to Bugzilla, type the following command

 $ hg diff > ~/Desktop/searchplugins.patch

You have now created a patch that reflects these changes and is saved on your desktop.

Upload your patch

Most of the work has been done so that you can upload changes to a bug that was filed by Mozilla's l10n-drivers team to track the completion of your localization.

  1. Log into Bugzilla and find the bug that was filed to track changes to search plugins
  2. The "Attachments" section of the bug has a link that allows you to add an attachment
  3. Click this link and upload your file
  4. Add a quick description for the attachment, click the "patch" box, and request a review by one Mozilla's l10n-drivers listed in the bug
  5. Enter the bugzilla ID/email of the person you want to review the patch.
  6. Add a comment describing the patch
  7. Commit

Your patch will now wait for review from one of the l10n-drivers.