How to localize strings from the help.html file of an extension
If you are reading this, you are a developer that deserves consideration, because you have documented your extension, which is a pretty good idea to make it more user-friendly. So you have a help.html or howto.html file shipped with your extension. Let's suppose you have it in the locale folder, so that translators may do their work and spread it worldwide.
Then the problem is:
- a help.html file in each language subfolder makes your extension bigger in size (consider we have several extensions on BabelZilla that include more than 25 locales)
- translators are not developers, they are generally uncomfortable at the idea of sneaking inside html code, slaloming between tags and attributes to get strings to translate. Moreover, encoding errors may happen when editing an html document.
The solution can be:
- Transform your html file into a help.xhtml one and move it into the content folder
- Entitize all the strings of the xhtml file and drop them in a locale/help.dtd file
Let's see how to do that. We shall take outliner extension by Roman Mashirov as a test case.
First, create a help.dtd file or use an already existing .dtd in the locale folder, and move the .html to the content folder. Then follow these simple steps:
Make a xhtml file out of a html one
You have to delete everything before the <head> tag and paste this piece of code instead:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd" [ <!ENTITY % helpDTD SYSTEM "chrome://outliner/locale/help.dtd" > %helpDTD; ]> <html xmlns="http://www.w3.org/1999/xhtml"> | of course, you can put your extension name and the dtd name you wish.
The ENTITY part is important because it tells the extension where to find strings | Check the validity of your new xhtml fileXhtml syntax seems to be more demanding than plain html in terms of tags correctness. Check every closing tag especially, else you will encounter a parsing error. To check your xhtml file, just open it with Firefox and if there is anything wrong, your favourite browser will display a useful debugging message such as : error on line x, found <span>, expected </br>. You will also take a special care about html entities that must be replaced with their decimal equivalent. Examples: & copy; --> ©
& amp; --->&
& nbsp; ---> 
Transform the strings in localizable entities Now it is just the same process as when moving strings from content/*.xul to locale/*.dtd. Each time you encounter a message for the user interface :
1. Use an entity instead.
| For example if you have this: | |
just write that: | <h1>Outliner Help</h1>
<p>This is Outliner extension for Mozilla, or at least some day it will be.
For now this is just notekeeper with notes arranged in tree.</p>
| | <h1>&page.title;</h1>
<p>&this.is.outliner;</p> |
2. Drop the entity and the message in the dtd file <!ENTITY page.title "Outliner Help">
<!ENTITY this.is.outliner "This is Outliner extension for Mozilla, or at least some day it will be.
For now this is just notekeeper with notes arranged in tree."> |
Make some adjustments - remember to modify the path of your help file where it is invoked (usually in a .js file)
chrome://outliner/locale/help.html ---> chrome://outliner/content/help.xhtml
- if you have linked images, javascript or css in your document, check their new path too.
- you may have to add some non-breaking spaces here and there for a better layout.
- In case you need more here are the original outliner extension and the modified one
...And you have done with it. Congratulations!  a Goofy mini-howto
|
Working...
