Help users of the metric system by converting and replacing Imperial and US units of measure with metric (SI) units directly within a web page. A hotspot will popup with the original value, conversion workings and potential ambiguities.
Update 5-July-2022
After many years without incident, Google sent me an email saying that I was effectively a spammer and that my Chrome extension would be removed. I tried to update the description (the source of the spamming allegations) but Google have locked me out of my account and I can't recover it so I can’t update the offending description.
I’m sorry, but if Google ends up withdrawing Metrication, I’m not going to do anything about it. They’re just making things way too hard. It still works fine on Firefox so just try that instead.
Overview
Metrication is an add-on for Firefox and Chrome that identifies Imperial/US units and converts them to appropriate metric units.
This add-on is still under development and should be considered experimental.
When an Imperial/US unit is identified, Metrication removes it totally from the document and replaces it with the appropriate metric value and unit so that the document reads as if it were written for a metric audience.
The replacement metric value and unit are embedded within a hotspot that will popup a small window containing: 1) the original text; 2) the working involved in the conversion to a higher number of decimal places; and 3) any other conversions that may have been possible due to cultural or other ambiguities.
If the user deems the default conversion to be inappropriate, a popup menu will also allow the selection of an alternate conversion or reversion to the original text.
Output Unit Scaling
The Metrication add-on attempts to provide "appropriate metric units" by varying the output unit on the scale of the output value and not be fixed to the input unit. For example, "40 miles" will be represented as "64.4 kilometres" whereas "⅛ miles" will be represented as "201 metres". This scaling can also be limited so that values like "30,000 feet" will be represented as "9,144 metres" (not 9.1 kilometres) in line with convention.
Scaling is also applied to decimal places as output values increase. As previously stated, "40 miles" will be represented as "64.4 kilometres" however, "200 miles" will be represented as "322 kilometres" and not as "321.868 kilometres".
Abbreviations
The Metrication add-on will detect both full unit names like "feet" and abbreviated unit names like "ft" or '"'. The add-on will use full names or abbreviated names in its output depending upon which is detected in the input. For example: "40 mi." will be converted to "64.4 km.". This can lead to some false positives: for example, the abbreviation for "font point size" is "pt" however, this could also be seen as an attempt to abbreviate "pint". The popup will explain the conversion used and hopefully the context will reveal that there is no such text size as "5.7 l" (litres).
Fractions
The Metrication add-on recognises fractions in two distinct ways: 1) Unicode characters expressing fractions, for example "⅘" is Unicode character 8536 (decimal, 2158 in hexadecimal); and 2) textual representation of fractions using numerals, spaces and slashes, for example "4 1/2". There are also Unicode representations of superscript and subscript numerals, for example "⁶" (Unicode 8310 decimal) and "₆" (Unicode 8326 decimal) that are interpreted as numerators and denominators accordingly when separated by a slash.
Ambiguities and Variants
An "Ambiguity" occurs when the unit used may result in multiple conversion results. There are two types of ambiguity: 1) Ambiguities that arise from cultural difference (sometimes referred to as "variants"), for example "Imperial Gallon" and "US Gallon" both being referred to as "gallon"; and 2) Ambiguities that arise from context, for example "Add 2 ounces of sugar to 20 ounces of lemon juice" where "20 ounces" can be inferred by a human reader to mean "20 fluid ounces".
Ambiguity may arise as the unit "Gallon" may actually refer the traditional gallon used within the United Kingdom (and formerly some commonwealth nations), sometimes referred to as the "Imperial Gallon" or the "U.S. Gallon" as used in the United States. The Metrication add-on attempts to resolve cultural ambiguity by detecting the language of the webpage in 3 ways: 1) the explicit language defined in the web page, for example "<html lang="en-GB">"; 2) the implied language derived from the domain name, for example "domain.co.uk"; and 3) the presence of English/US spelling variants such as "neighbour" and "neighbor" on the web page. As none of these methods are 100% reliable, the Metrication add-on will assume "U.S." variants where none of the above methods are definitive.
Ambiguity may also arise as the unit "ounce" may actually refer to the unit of mass or as shorthand for "fluid ounce" where context could be used to determine which one was meant. Consider the sentence "add 2 ounces of sugar to 20 ounces of lemon juice": from the context, a human reader would understand that as "lemon juice" is a liquid, "fluid ounces" in the most likely unit to apply. When encountering "ounces" the Metrication add-on will always convert based on mass, however, it will provide an alternate volume conversion in the popup. When encountering "fluid ounces", however, the Metrication add-on will always convert to volume only.
Compound Values and Compound Units
A "Unit" is an Imperial unit of measurement such as "foot", "pound", "gallon", etc. Each unit is normally associated with a numerical value describing the magnitude.
A "Value" is the quantity associated with a unit. Measurements are normally expressed as a value/unit pair. For example, with "20 Miles", "20" is the value and "Miles" is the unit.
The Metrication add-on can also cater for what it refers to as "compound values". A "compound value" is a value such as "5 feet 11¾ inches" containing 2 sub-values of independent sub-units. Both feet and inches are valid individual units that could be converted to metres and centimetres independently, but would make little sense in a metric context. Instead, the above example is taken as a single value that is converted to "1.8 metres". The Metrication add-on will show its working as " (5 feet = 1.524 metres) + (11.75 inches = 0.29845 metres) = 1.82245 metres".
The Metrication add-on also caters for what it refers to as "compound units". A "compound unit" is a single value that references multiple sub-units, for example "21 miles per gallon". There is a single value "21" but the unit that it refers to is comprised of 2 sub-units, "miles" and "gallons". A simple conversion would yield a non-sensical phrase like "33.8 kilometres per gallon". The Metrication add-on can recognise compound units and provide a more appropriate "11.2 litres/100 kilometres" as the output value.
Implied Units
A "Unit" is an Imperial unit of measurement such as "foot", "pound", "gallon", etc. Each unit is normally associated with a numerical value describing the magnitude.
The Metrication add-on attempt to cater for compound values with implied units. An "Implied Unit" is a compound value where the name of one of the units (normally the last) is omitted because it can be implied from the name of the previous unit. For example: "5 feet 7" where the unit "inches" is implied for the value "7" because it immediately follows the unit "feet".
Range Values and List Values
For a large number of conversion, but not all, the Metrication add-on will detect where an single unit can be applied to multiple values. "Range values" occur where a single unit is provided with two values separated by a range indicator. Examples of range values are as follows: "from 4 to 9 feet" and "between 7 and 8 miles".
List values are similar to range values, however, more than 2 values may be present and they can be separated by punctuation such as commas, semi colons, etc. For example: "The product is available in lengths of 10, 15, 20 & 50 feet" or "Overall dimensions are 2 x 3 x 4 inches".
Value Follows Unit
As well as writing "20 miles", it is also grammatically permissible to write "mile 20" under certain circumstances. For example: "We had 50 miles to cover today and we stopped at mile 30 for lunch". Where the singular form of the unit is used, in this case "mile" and the value is not 1, the output unit name will also use the singular form. For example: "We had 80.5 kilometres to cover today and we stopped at kilometre 48.3 for lunch".
Informational Conversions
Commencing with version 0.0.2, conversions can be performed that still perform the conversion and add the popup, but do not replace the detected value within the web page. This is handy for units such as 'teaspoon' where precision is not always needed, but sometime handy to have.
Automatic Conversions
Any Web page that contains an element that has a class "metrication-auto-convert" assigned to it will be automatically converted to metric.
Conversion Rules JSON Documentation
It is planned that future versions of the Metrication add-on will allow users to easily modify the conversion rules directly within the add-on and to also provide a mechanism for applying different conversion rule sets under different circumstances. For example, the degree of accuracy required by a hiker reading a trail report (elevation gain is OK to the nearest metre) may be very different to that required by an engineer building a precision instrument (fractions of a millimetre).
Unfortunately, for now at least, you will need to provide your own rules in JSON format. If you go into the add-on's "Options" page, you can copy the existing conversion rules, modify them in your text editor of choice, paste your modified rules back into the options page and then save them. It should be easy enough to follow the existing JSON file, however, the documentation below is designed to help you modify the rules in the required JSON format.
Main Section
Entries in the main section defines global configuration items.
Example:
{
"alwaysRenderAsInformational": false,
"enableAutoConversions": true,
"adjustRoundingVariance": true,
"enableIframeProcessing": false
"preservedUnitEndings": ",.;:",
"dashes": ["\u002d", "\u2010", … "\u2013", "\u2014"],
"spaces": ["\u0020", "\u00a0", … "\u2009", "\u200a"],
"numberMap": {" ":" ", "/":"/", "0":"0", "1":"1", … "⅞":"⅞"},
"numberMultipliers": {"k":"000", "m":"000000", "b":"000000000"},
"fractionMap": {"¼":0.25, "½":0.5, "¾":0.75, "⅐":0.142857142857143, … "⅝":0.625, "⅞":0.875},
"defaultVariant": "us",
"activeVariant": "us",
"activeVariantOrder": ["us_", "uk_"],
"activeVariantReason": "default",
"localeMap": {"en-gb":"uk", "en-us":"us", … "en-ei":"uk", "en-jm":"uk"},
"domainMap": {"uk":"uk", "us":"us", "au":"uk", "nz":"uk", "ca":"uk", "za":"uk", "ei":"uk", "jm":"uk", "in":"uk"},
"spellingMap": [{"variant":"uk", "searchText":"(colours|colourful|…)"}, {"variant":"us", "searchText":"(colors|colorful|…)"}],
"variantOrder": {"uk":["uk_","us_"], "us":["us_", "uk_"]}
"defaultDetector": "<regular expression>",
"permittedRoundingVariance": 0.01,
| Property | Description. |
|---|---|
| defaultOptions | Introduced in v0.0.2, these items represent default values for user options. |
| +alwaysRenderAbbreviations | Introduced in v0.0.2, if 'true' ignore input unit format ('feet' vs 'ft') and always use abbreviations for output units. |
| +alwaysRenderAsInformational | Introduced in v0.0.3, if 'true' all conversions are informational, not page text is replaced. |
| +enableAutoConversionss | Introduced in v0.0.3, if 'true' pages set to "Auto-Convert" will be converted automatically when loaded. |
| +adjustRoundingVariance | Introduced in v0.0.5, if 'true' the rounded converted output will be compared to the actual converted output and if the variance is greater than the global 'permittedRoundingVariance' setting, additional decimal places will be added. (|(n - ⌊n⌉)| ÷ n) > permittedRoundingVariance |
| +enableIframeProcessing | Introduced in v0.0.7, if 'true' Metrication will recurse into <iframe> elements and convert contents. |
| preservedUnitEndings | These characters are removed from the end of a 'unit' before testing for singular/plural and replacement by the SI unit name. For example, 'n feet:' would be converted to 'n metres:'. |
| dashes | Introduced in v0.0.2, these characters are converted into standard dashes during the detection stage. |
| spaces | Introduced in v0.0.2, these characters are converted into standard spaces during the detection stage. |
| numberMap | This array maps characters to their numeric value. For example a superscript ² (2) is mapped to a normal '2' This is handy when dealing with constructed fractions such as: 1 ⁷⁄₈ constructed from '1' + '(space)' + '⁷' + '⁄' + '₈'. |
| numberMultipliers | Introduced in v0.0.8, this array maps characters to their multiplier value. For example: '20k' is expanded to "20000" prior to conversion using basic string substitution. |
| fractionMap | This array maps the unicode fraction characters into numeric values. For example: '⅑' = '0.111111111111111'. |
| defaultVariant | If a cultural variant can not be determined, this one is used. |
| activeVariant | Each page to be converted has its own copy of the conversion rules. One the 'locale' for a page has been determined, this value is updated internally by the add-on. |
| activeVariantOrder | This property is set to one of the values in the 'variantOrder' matching the page locale of the current page. |
| activeVariantReason | For internal debugging use, a text reason describing why a certain locale was selected. |
| localeMap | This array maps the HTML 'lang' tags to a locale used for determining variant order |
| domainMap | This array maps country domain suffixes to a locale used for determining variant order. |
| spellingMap | This array use used to search a web page for key words that are spelt differently in English and American and used to determine variant order. |
| variantOrder | This array maps page local to variant order. |
| defaultDetector | Introduced in v0.0.5, this mandatory property is used to define the 'default detector' that can be used as a substitution within the 'input' field of a 'detector' rule. The value '%%DEFAULTDETECTOR%%' in the detector rule will be replaced by the contents of this property. |
| permittedRoundingVariance | Introduced in v0.0.5, this mandatory property defines the maximum permissible variance, as a proportion, between the calculated conversion and the rounded conversion to be used in the web page replacement. If this variance is exceeded, more decimal places will be added until the rounded value comes within this permissible variance, or, 20 decimal places are reached. Setting this value to 'null' will disable this feature. For example: to ensure that the rounded conversion is within 1% of the calculated conversion, set this property to '0.01'. |
'detection' Section
Entries in the detection section define the regular expression used to detect an imperial character string, what metric value to convert to and render as.
Example:
"convert": "conversion_rule",
"convertCompound": ["conversion_rule_1","conversion_rule_2"],
"variants": true,
"excludeAmbiguities": true,
"scaledBelow": null,
"render": "rendering_rule",
"compound": true,
"priority": 100,
"ignore": false,
"singularForm": "word",
"concatenateUnits": true,
"impliedFinalUnit": true,
"splitter": "splitting_rule",
"informational": false,
"numberWords": false,
"abbreviate": false
| Property | Description. |
|---|---|
| description | Introduced in v0.0.2, this mandatory property will be used in the future to identify detection rules for editing. |
| category | Introduced in v0.0.2, this mandatory property will be used in the future to group detection rules for editing. |
| input | This mandatory property contains the regular expression to be matched in order to detect that a conversion is required. For example, to match "20 miles" a grossly simplified regular expression could look something like "(\\d){1,}(\\s)*miles". Note, backslashes need to be 'escaped'. Commencing v0.0.5, the string "%%DEFAULTDETECTOR%%" will be replaced by the value of the global 'defaultDetector' property. |
| convert | This mandatory property points to the conversion rule defined in the 'conversion' section. |
| convertCompound | This optional property contains an array of conversion rules to be applied if the input values are 'compound values'. |
| variants | This optional property indicates if variants (cultural ambiguities) should be used in the conversion process. For example, 'gallon' could mean 'imperial gallon' or 'US gallon', the 'convert' property will be prepended to the variant names to determine the final conversion rules to apply. The default value if this property if omitted is 'false'. |
| excludeAmbiguities | This optional property indicates if ambiguities defined in the 'conversion' section should be used in the conversion process. For example, 'ounce' could mean 'ounce' or 'fluid ounce' depending on the context. The default value if this property is omitted is 'false'. |
| scaleBelow | This mandatory property determines how scaling will be applied to the output value. If the input value is lower than the property value, then the output value will be scaled, however, if the input value is equal to or exceeds the property value, the unscaled output value will be used. This can be used where the convention is to use a smaller unit where a larger unit exists. For example, an altitude may be expressed as '35,000 feet' and should be converted to '10,668 metres' not '10.7 kilometres'. |
| render | This mandatory property determines which rendering rule to use. Rendering rules control unit selection and scaling. |
| compound | This mandatory property determines if the detected expression should be converted as a compound value. The default value if this property if omitted is 'false'. |
| priority | This mandatory property determines which matched 'detection' rule should be processed when multiple rules are matched to the same text. For example, '20 Miles Per Gallon' will match both 'Miles' and 'Miles Per Gallon', however, if 'Miles Per Gallon' has a higher 'priority' then 'Miles' will be ignored. |
| ignore | Used with 'priority' when set to 'true' the match will not be converted. This option is used to emulate a negative lookbehind regular expression. An example of this is preventing a false positive when the abbreviated form of 'degrees/minutes/seconds' with 'minutes/seconds' using the same abbreviation as 'feet/inches'. |
| singularForm | This optional property determines the singular form of a matched unit. This is used where 'unit before value' matches have been made. For example 'Mile 20'. Commencing v0.0.5, this property can contain either a string or an array of strings. |
| concatenateUnits | This optional property determines if the output unit and value are replaced individually or as a single block of text. |
| impliedFinalUnit | This optional property determines if the final unit in a 'compound value' can be skipped. For example, '5 feet 7 inches' can be expressed as '5 feet 7' and the 'inches' implied. |
| splitter | This optional property determines which regular expression should be used to split values from units. If omitted, the 'default' splitter will be used. |
| informational | Introduced in v0.0.2, this optional property indicates that the detected imperial value should NOT be replaced. Only the popup will be provided with the conversion workings. This is useful for terms like 'Mach 3' for example. |
| numberWords | Introduced in v0.0.2, this optional property indicates that the detected input value should be converted from words to numbers prior to conversion. |
| abbreviate | This optional property determines if the output unit should be abbreviated. For example, 'm' instead of 'metres'. |
'splitters' Section
Entries in the splitters section define the regular expressions used to separate the values from the units in a detected imperial phrase.
Example:
{
"addSpaceBeforeUnit": false,
"unitAtFront": false
| Property | Description. |
|---|---|
| string | This mandatory property contains the regular expression used to split values from units. |
| addSpaceBeforeUnit | Commencing v0.0.7, when set to 'true' this optional property determines if a single space character is added before the unit's text. This only applies with the unit follows the value. For example, "20mm" will become "20 mm" |
| unitAtFront | This mandatory property determines if the values follow the units or the units follow the value. For example "20 miles" and "mile 20". |
'conversion' Section
Entries in the conversion section define how the input value is to be converted to the output value. There should be a matching value in the 'convert' property in the 'detection' section.
Example:
{
"multiplier": 123.456789,
"popupScientificOutputAbove": 999999999,
"popupScientificDecimals": 3,
"evaluator": "(100 * 4.54609) / (1.609344 * INPUT)",
"ambiguities": ["conversion_rule_1", "conversion_rule_2"]
"ambiguitiesRender": "render_rule"
| Property | Description. |
|---|---|
| description | This mandatory property contains clarifying text added to the hotspot text describing the conversion process. For example, 'miles' may be described as 'statute miles' to differentiate itself from 'nautical miles'. |
| multiplier | The input value is multiplied by this mandatory property to produce the output value. Note: This property must be set to '1' when a 'evaluator' property is present. |
| popupScientificOutputAbove | Commencing v0.0.3, if the output value exceeds this limit, the popup value will shoe in scientific notation. |
| popupScientificDecimals | Commencing v0.0.3, the number of decimal places to use with the significand. |
| evaluator | This optional property represents the formula to be applied to the input value to produce the output value. It may only contain numerals and characters '+-/*()'. The word 'INPUT' is replaced by the input value prior to the conversion calculation being made. Only the 4 elementary maths functions (addition, subtraction, multiplication and division) can be used with parenthesis available to enforce order-of-operation. |
| ambiguities | This optional array represents other conversion rules that should be used as well as this one with converting an input value. For example 'ounce' may have ambiguities of 'uk fluid ounces' and 'us fluid ounces' Results from conversion resulting from these ambiguity calculation will be shown in the information hotspot and are also available to be selected from the popup menu. |
| ambiguitiesRender | If this optional property is present, it will override the 'render' property from the 'detection' rule. This should only be necessary when an 'ambiguity' is not from the same detection category (mass, volume, etc) as the 'detection' rule. |
A note about conversions: The default conversion rules provided with the add-on will normally convert from an imperial unit to the base SI unit, for example, inches, feet and yards are all converted to metres, however, miles are actually converted directly to kilometres. With separate rendering rules, inches/feet/yards can be scaled to millimetres, centimetres, etc whereas miles can be scaled to metres and kilometres.
'rendering' Section
Entries in the rendering section define how the output value is to be presented in the web page. There should be a matching value in the 'render' property in the 'detection' section.
Example:
{
"unscaled":
"decimals": 0,
"labels": "metres"
[
"divisor": 0.001,
"decimals": 1,
"labels": "millimetres"
{
"divisor": 0.01,
"decimals": 2,
"labels": "centimetres"
{
"divisor": 1,
"decimals": 1,
"labels": "metres"
{
"divisor": 1,
"decimals": 0,
"labels": "metres"
{
"divisor": 1000,
"decimals": 0,
"labels": "kilometres"
{
"divisor": 1000,
"decimals": 3,
"scientific": true,
"labels": "kilometres"
| Property | Description. |
|---|---|
| description | This mandatory property describes the output unit as received from the conversion rule. |
| unscaled | If the output is not to be scaled, the rendering rules in this mandatory group are used. Also see the 'scaleBelow' property in the 'detection' section. |
| scaled | This mandatory group contains an array of rendering rules for various magnitudes of output values. |
upperLimit | If the output value is less than this mandatory property, or this property is null, this rendering rule will be applied. |
divisor | This mandatory property is used to scale the output have is a different unit is to be used than that produced by the conversion rule. |
decimals | This mandatory property is used to determine the number of decimal places to be displayed for the output value. |
scientific | Commencing v0.0.3, this optional property signifies that the output should be in scientific notation. eg: '1.432×10¹¹' The 'decimals' property above is used to determine the number of decimal places in the significand. |
labels | This mandatory property points to the 'unitNames' rule to be used in the final output. |
'unitNames' Section
Entries in the unitsNames section determinewhat unit name will be applied to the final output value.
Example:
[
{"upperLimit": 1, "label": "metre", "abbreviation": "m", "template": "%%VALUE%% metre", "abbreviationTemplate": "%%VALUE%% m"},
{"upperLimit": null, "label": "metres", "abbreviation": "m", "template": "%%VALUE%% metres", "abbreviationTemplate": "%%VALUE%% m"}
| Property | Description. |
|---|---|
| upperLimit | If the output value is less than or equal to this mandatory property, or this property is null, this label rule will be applied. |
| label | The unit name to use if the 'abbreviation' property is 'false' in the 'detection' rule. |
| abbreviation | The abbreviated unit name to use if the 'abbreviation' property is 'true' in the 'detection' rule. |
| template | This property contains a template to be used replacing '%%VALUE%%' with the output value. The output of this is displayed in the popup menu. |
| abbreviationTemplate | This property contains a template to be used for abbreviated units replacing '%%VALUE%%' with the output value. The output of this is displayed in the popup menu. |
