Extension:WebFonts

Development on this extension is discontinued. Please use Universal Language Selector instead: WebFonts is integrated in it. Critical support requests and addition of new fonts will continue as long as this extension is in use on Wikimedia projects: bugs for #Adding a new language support should be filed against UniversalLanguageSelector, but new languages will then be separately added also to WebFonts.

This is technical documentation of the extension. There is also a user documentation

MediaWiki extensions manual - list

WebFonts Release status: stable
Implementation	User interface, Skin
Description	Embed fonts on pages
Author(s)	Localisation Team (Santhosh.thottingaltalk)
MediaWiki	1.17, 1.18
License	GNU General Public Licence 3.0 or later
Download	Download snapshot (Git master) Git [?]: repo summary tree code changes
Check usage and version matrix
Bugs: list open list all report

What can this extension do?

Many languages do not have proper fonts easily available to users. This may be because the operating systems do not ship these fonts, the script has fonts but users don't know from where they will get them or how to install them in their system, or even the user is reading the wiki from a shared computer without these fonts. Sometimes it may be because the user does not know how to configure the operating system for a language or the user does not have enough permissions to do this. Because of all these reasons, providing the content in certain languages is facing issues. This extension tries to solve this by embedding the fonts in the wiki itself. Fonts will be served from the server and the user's system would not need to have the fonts installed.

Supported skins

Vector, Monobook and Modern.

Usage

When the extension is installed and enabled, along with the login, preferences link in the wiki page, a menu will appear to select a font for the page. By default, the first font in that menu will be applied to the wiki. A user can change the font and it will be remembered across the pages. Optionally user can disable the font embedding too, this choice will also remembered across pages, even for next visits, for 30 days.

If the font is available in user's local system, font will not be downloaded from the mediawiki server. It will be taken from the user's computer. Otherwise, font will be downloaded from the server only once. ie when the user selects the font first time. Next time onwards, font will be taken from the local cache.

Alternate ways to load fonts

By specifying font-family

Inside the wiki text <span style="font-family:'YourFontName';">YourText</span>, webfonts extension will check whether the font is available with the extension, if so it will download it to the client. So the reader will not face any difficulty in reading the text even if the font specified is not available in their computer.

By specifying language

Inside the wiki text <span lang="my">YourText</span>, webfonts extension will check whether any font is available for the given language with the extension, if so it will download it to the client. So the reader will not face any difficulty in reading the text even if the font specified is not available in their computer. If there are multiple fonts for the language, the default font will be used. If default font is not preferred, use the font-family approach to specify the font. If the tag has both lang and font-family definitions, font-family get precedence.

Supported languages

Language	Fonts	Upstream
Ahirani	Lohit Devanagari	Lohit Project, Red Hat
Akkadian	Akkadian	Unicode Fonts for Ancient Scripts
Amharic	Abyssinica SIL	SIL
Assamese	Lohit Assamese	Lohit Project, Red Hat
Avestan	Ahuramzda	Ahuramzda
Bengali	Lohit Bengali,Siyam Rupali	Lohit Project, Red Hat
Bhojpuri	Lohit Devanagari	Lohit Project, Red Hat
Bishnupria Manipuri	Lohit Bengali	Lohit Project, Red Hat
Buginese	Saweri (for Lontara script)	Saweri
Gujarati	Lohit Gujarati	Lohit Project, Red Hat
Hebrew	Miriam CLM	Culmus
	Javanese	Tuladha Jejeg	Tuladha Jejeg
Taamey Frank CLM		Culmus
Gothic	Cardo	Cardo
Hebrew-Old	Taamey Frank CLM	Culmus
Hindi	Lohit Devanagari	Lohit Project, Red Hat
	Samyak Devanagari	Samyak
Kannada	Lohit Kannada	Lohit Project, Red Hat
	Kedage	Sanchaya
Khmer	KhmerOSbattambang, KhmerOSsiemreap, KhmerOS, KhmerOSbokor, KhmerOSmuollight, KhmerOSmuol, KhmerOSmuolpali, KhmerOSfreehand	KhmerOS
Konkani	Lohit Devanagari	Lohit Project, Red Hat
Lepcha	Mingzat	SIL
Makassarese	Saweri (for Lontara script)	Saweri
Malayalam	AnjaliOldLipi	Varamozhi Project
	Meera	SMC
	RaghuMalayalam	SMC
Maithili	Lohit Devanagari	Lohit Project, Red Hat
Marathi	Lohit Marathi	Lohit Project, Red Hat
	Samyak Devanagari	Samyak
Min Dong Chinese	Charis SIL	SIL
Myanmar	Masterpiece Uni Sans	Prahita
	Padauk-Regular	SIL
	Myanmar3	Myanmar Unicode & NLP Research Center
Parthian	ZH Mono	SourceForge
Yunghkio		Yunghkio
Odia	Lohit Oriya	Lohit Project, Red Hat
	Utkal	Oriya, Sarovar
Punjabi	Lohit Punjabi	Lohit Project, Red Hat
	Saab	GUCA
Persian	IranianSans	Iranian National Initiative for FOSS
Sourashtra	Pagul	Pagul
Sanskrit	Lohit Devanagari, Samyak Devanagari	Lohit Project, Red Hat
Tamil	Lohit Tamil, Lohit Tamil Classical	Lohit Project, Red Hat
	Thendral	Thamizha
	Thenee	Thamizha
Telugu	Lohit Telugu	Lohit Project, Red Hat
	Pothana2000	K.Desikachary
	Vemana2000	K.Desikachary
Tai Lü	Dai Banna SIL	SIL
Tigrinya	Abyssinica SIL	SIL
Yi	Nuosu SIL	SIL

Adding a new language support

Supporting more languages is only a matter of including the proper fonts in the code. However, please note that we will add support only for freely licensed fonts, for example fonts licensed under GNU GPL, SIL OFL, etc. An example directory of such free fonts is Google Web Fonts [1] (not yet fully examined/exploited by the authors of this extension).

First of all, you need to find or produce such a free font (this is the most important part and you have to do it yourself); then, it has to be converted to the required formats, which are eot, ttf, woff; finally, you can file a request in bugzilla for the font to be added to the extension.

#Preparing webfonts below explains how to convert the fonts: basic knowledge about GNU/Linux based operating system is required; if you have difficulty in doing this, you can skip this step and ask someone else to do it for you on the same bugzilla request (of course this will slow down the process).

#Adding fonts contains instructions for the wiki's system administrator.

Preparing webfonts

Fontforge can be used and also has a graphical interface; it probably is on your GNU/Linux distribution's repositories.

• You can generate a truetype font from its source file (sfd file). SFD is not mandatory.
• If you have a truetype font (.ttf) you can convert it to woff:
  1. open it with fontforge,
  2. File->Generate Fonts,
  3. select "Web Open Font" and save.

You still have to create the eot font, but you can't use fontforge for that. Use ttf2eot for converting it. Install the tool and run

 ttf2eot yourfont.ttf > yourfont.eot

Now, if you want you can try to reduce the size of the EOT font, Google has a MicroTypeExpress compression implementation which is more efficient. The tool is part of Google sfntly project. To use this, you need to build the java based tool from source. Refer the project documentation for more information.

Bulk conversion

The font conversion can also be scripted using fontforge's scripting feature. See fontforge.sourceforge.net/scripting-tutorial.html.

For example, to convert a truetype font to svg, use the following fontforge script

#!/usr/bin/fontforge -lang=ff
Open($1)
Generate($1:r + ".svg")

You may save this script to a file named say, ttf2svg.pe, give execution permission and execute like this

./ttf2svg.pe yourfont.ttf

Similarly, for creating a WOFF font:

#!/usr/bin/fontforge -lang=ff
Open($1)
Generate($1:r + ".woff")

Adding fonts

• Place the eot, ttf, woff font files inside the matching folder. The fonts are sorted under WebFonts/fonts folder in folders named according to ISO 15924 script codes. If a folder for your script doesn't exist, create it.
• Preferably set svn:mime-type to "application/vnd.ms-fontobject" for eot, "application/x-font-ttf" for ttf, "application/x-font-woff" for woff.
• Open js/webfonts.fontlist.js and add an entry for the font. You may refer the existing fonts or use the following syntax

'FontName' : {
    eot: "Script_code/FontName.eot",
    ttf: "Script_code/FontName.ttf",
    woff: "Script_code/FontName.woff",
}

• (Optional) If you want to do some normalization on the page content when you display it the font, such are replacing certain characters with other characters, you can specify it as normalization rules.

normalization : {
    "searchString1": "replaceString1",
    "searchString2": "replaceString2",
}

• Add a entry to the languages section of the file. The following example maps two fonts to Hindi (hi is Hindi's ISO 639 language code). The first font will be used as default font. The font names should match with the font name we used above.

    hi: [ 'Samyak Devanagari', 'Lohit Hindi' ]

Download instructions

Download WebFonts and put it in to a directory named WebFonts under $IP/extensions/ Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php.

Installation

To install this extension, add the following to LocalSettings.php:

require_once( "$IP/extensions/WebFonts/WebFonts.php" );

Configuration parameters

• Whether the web fonts should be active as default or not

 $wgWebFontsEnabledByDefault = true;

• To enable or disable the web fonts, the user can go to My Preferences -> Appearance -> Enable font embedding (WebFonts)

By default, the preference page option to enable web fonts is set based on the value of $wgWebFontsEnabledByDefault

Caching configuration

To ensure that the web fonts files are cached on the clients' machines, font file types must be added to the web server configuration. In Apache2 this consists of:

• Adding font file extensions to the FileTimes regex at FilesMatch for the relevant directory, example: <FilesMatch "\.(gif|jpe?g|png|css|js|woff|svg|eot|ttf)$">
• Adding ExpiresByType values to the relevant MIME types, similarly to image MIME types.
  • Note that there's no standard MIME type for TTF. application/x-font-ttf is used for Wikimedia.
• Adding the MIME types:
  • AddType application/x-woff .woff
  • AddType application/vnd.ms-fontobject .eot
  • AddType application/x-font-ttf .ttf

For a full example see the caching configuration update done for the Wikimedia cluster.

Known issues

• IE 6 is not capable of doing font-fallback properly. Because of this, if the page contains text within elements having no lang information, squares are getting displayed. The extension is disabled in IE 6 browser. See bug report.
• IE 8 sometimes shows junk characters on the screen instead of the actual text in the specified font. The issue is not always reproducible and disappears upon page refresh. The junk characters may be because of a partially downloaded font. See Bug 32775.
• Google chrome (chromium too) upto version 15 has a bug that cause some complex script webfont being rejected by the browser. This issue is observed only for Meera font of Malayalam. The OTS tool does not show any errors in the font. But the issue is not present in Chrome 17. See Bug report.
• In Mac OS X 10.7, Opera browser is not capable of rendering complex scripts like Malayalam. See our detailed test report about various OS-browser combinations. Also see Bug 31823 - Opera 11.51 does not display saz font.
• Google Chrome on Windows XP dispays gibberish - Observed very rarely on a page on Wikimedia Incubator, and we have not been able to reproduce this observation, let alone reproduce it reliably. A screenshot is present in the bug report. Except for reporting upstream, no action is being taken on this issue at this point in time.
• OSX 10.7.2/Opera 11.60 has no fallback for Latin characters.

Reporting issues

While we are constantly trying to improve the quality of fonts and scripts coverage, it is quite possible that you notice issues with the provided fonts in terms of missing glyphs, wrong rendering, low quality rendering etc. Please report that issues to us using Bugzilla and we will work with upstream font maintainers to resolve such bugs.

More information

• Writing systems - information on writing systems in MediaWiki
• Fonts on the Web -W3C- http://www.w3.org/Fonts/
• CSS3 WebFonts specification - http://www.w3.org/TR/css3-fonts/
• @font-face performance
• translatewiki:WebFonts assessment
• m:Fonts, a 2011 list of fonts
• The Free Software Foundation's page about free licenses for fonts
• Code review of this extension
• Help:Extension:WebFonts