ਫਰਮਾ:Convert/Transwiki guide/translate

This page explains how the convert template and module can be adapted for use at any Wikipedia. It is likely that some details will need further explanation—please ask at Module talk:Convert for assistance. For an overview of how the template is used, see Help:Convert.

Overview

Template:Convert • Invokes the module; some parameters can be used to configure the module.
Module:Convert • Should not be changed. If a change appears desirable, please discuss first.
Module:Convert/data • Unit definitions—must not be changed (see below).
Module:Convert/text • Text for options and messages—should be changed.

Copying the above is sufficient for convert to work, but more is needed to translate unit names (see below).

When translations to unit names and convert options are performed, it would be desirable to keep the enwiki text so that if an article is copied from enwiki, any converts would work. For example, the unit code acre should not be changed—instead, add an entry defining the local name for acre as an alias for the existing unit, then translate the symbol, name and link for acre. Similarly, range words such as "to" should not be translated. An example of a range is {{convert|4|to|5|ft}} (4 to 5 feet)—the output produced by "to" should be translated, but the input "to" should be retained, and the local name for "to" should be added as an alias for "to".

Nothing in Module:Convert needs to be changed. The module contains some messages that would only appear if a bug were introduced to the program. It is best to not translate those messages so updates will be easier in the future. The bug messages have never been displayed and would be meaningless to general editors even if translated.

Module:Convert/data must not be changed because it is generated by running a script which reads the data from a master list of units. See below.

The messages in Module:Convert/text should be translated.

Convert/text

The following items are in Module:Convert/text. It is not necessary to translate all items because some features will probably not be used. If they are used, translations can be added later.

translation_table
This table is not used at enwiki and will be provided on request. Please specify:

What characters are used for the digits 0123456789.
How numbers are formatted: for example, a number at enwiki may be written as "12,345,678.12345" with a comma as the thousands separator and a dot as the decimal mark.
The "per" word used in units like "liters per kilometer"; see per units.
Whether there is a rule for how plural names of units are usually formed (such as adding "s" to "meter" to form "meters")—most wikis will have no such rule, or plurals may not be used.
The name of the page which will contain the master list of units—see below.

translation_table can define the following items.

`group`	Code for how numbers are grouped (3 is the default; can also be 2).
`numdot`	Decimal mark ('`.`' is the default).
`numsep`	Separator for number grouping ('`,`" is the default; can use ` ` for spaces).
`per_word`	For units like "liters per kilometer" ("`per`" is the default); see per units.
`plural_suffix`	Use `''` (empty string) to disable appending "`s`" for plural unit names.
`from_en`	Table to translate digits 0 to 9 to local characters for output.
`to_en`	Table to translate local characters used for input digits to 0 to 9.
`varname`	Variable names (name of unit depends on the quantity); used at slwiki.
`specials`	Exceptions for how some units are handled.
`mtext`	Text used by Module:Convert/makeunits; can be used to specify the title of the master list of units.

SIprefixes
The symbol and name for each SI prefix can be modified. The text "name_us = 'deka'" should be deleted because it only applies if |sp=us is used, and that only makes sense at enwiki (for example, the unit name "metre" is changed to "meter" if |sp=us is used in a convert).

customary_units
Can be edited if wanted, but rarely used and could be ignored until needed.

eng_scales
May need edits, particularly for the "link" text. For example, 1000000000 (number) is linked at enwiki if the |lk=on option is used with certain units such as e9J (billion joules).

all_categories
Articles with a convert error are added to a tracking category (by default, that applies only to articles and not to talk or other pages). Two categories are used at enwiki, but it would probably be better to use only one tracking category because not many problems occur. If that is wanted, the one category name can be used for each of two categories.

all_messages
All the text can be edited to control what is displayed if an error occurs. Part of the text is "Help:Convert messages" and that is used as a link in an error message so the editor can get further information. To start, that can be changed to ":en:Help:Convert messages" (errors will then link to en:Help:Convert messages). Later, the convert messages page can be copied to the local wiki and translated, and the link can then be changed to point to the help page at the local wiki.

disp_joins
If wanted, the text on the right-hand side can be translated; the only text that might be changed is " or ". In addition, new lines can be added with wanted text on the left-hand side. Examples on request.

range_types and range_aliases
Can be modified in a manner similar to disp_joins.

en_option_name and en_option_value
Can be modified to define new options in the local language.

At enwiki, the "adjectival" options (|adj=on and |adj=mid) are sometimes used in converts, for example:

{{convert|240|ft}} → 240 feet (73 m)
{{convert|240|ft|adj=on}} → 240-foot (73 m)
{{convert|240|ft||adj=mid|-long}} → 240-foot-long (73 m)

In en_option_value, the adj entries can be changed to prevent the insertion of a hyphen, for example:

    ["mid"] = "opt_adj_mid",  -- adj=on with user-specified text after input unit (between input and output)
    ["on"] = "",              -- disable hyphenation

Unit names

In an article using the convert template, one of the following options can be entered in the template.

|abbr=on • Input and output are abbreviated (unit symbols are shown).
|abbr=off • Input and output are not abbreviated (unit names are shown).
|abbr=out • Input is not abbreviated; output is abbreviated (this is the default).
|abbr=in • Input is abbreviated; output is not abbreviated.

If needed, one of the following options can be added to Template:Convert to change how abbr works.

|abbr=off always • Abbreviations are always off.
|abbr=off default • The default is |abbr=off.
|abbr=on always • Abbreviations are always on.
|abbr=on default • The default is |abbr=on.

Unit definitions

Units are defined in a table which can be at any page. At enwiki, these pages are used:

Module:Convert/documentation/conversion data/doc • Master list of units.
Module:Convert/makeunits • Program: input is the master list of units; output is the wikitext to be pasted into Module:Convert/data.

The program is run by clicking "purge" at Module talk:Convert/makeunits. That talk page contains:

To see the current data, it may be necessary to purge this page.

{{#invoke:convert/makeunits|makeunits}}

At enwiki, the title of the master list of units was chosen to be a "doc" page in the module namespace. The "doc" should be replaced with the local name. The "documentation" part was used for a trick to prevent display of the "This is the module documentation" message—see MediaWiki:Scribunto-doc-page-header.

Redundant information can be omitted from the master list. For example, if a unit has the same singular and plural name (or if plural names are not used), the plural name can be omitted. It is likely that US unit names are only useful at enwiki, so they can all be empty. Redundant information does not have to be omitted—makeunits omits anything it considers is not needed.

Before makeunits can be successfully used, Convert/text has to be correctly configured. Ask for assistance.

Hundreds of unused units are defined at enwiki. In addition, there are many entries for default exceptions and link exceptions that are probably only useful at enwiki. To simplify working with the units, many rarely or never-used items could be removed. If a removed item is needed in the future, it can be re-added.

At enwiki, Module:Convert/documentation/conversion data/doc transcludes Module:Convert/documentation/conversion data introduction/doc to show some explanations at the top. Rather than copying and translating that technical documentation, it may be better to use a short message as in the following example.

Example of an introduction

Following is the master list of conversion data used by Module:Convert.

This page is read by a script (makeunits). The script extracts information from the wikitext, and outputs text that can be copied into Module:Convert/data.

Information about the format of tables used on this page is available at enwiki.

Making units

When adding new units, it may be better to add them to Module:Convert/extra as it involves very little risk—even if the "extra" module is damaged, converts should still function. By contrast, a mistaken edit in Module:Convert/data could break all converts, and that may not be immediately apparent—you would need to purge a page with a convert template to test if it still works.

The procedure to change an existing unit is:

Edit Module:Convert/documentation/conversion data/doc and save changes.
At Module talk:Convert/makeunits, click "purge this page" in the first line.
If no errors are displayed, copy the text to replace the contents of Module:Convert/data (it may be useful to "Show changes" to confirm what is being changed).

A sandbox should be used to preview some convert templates to check that they still work. The changes will be immediately available, but a page using the convert template may need to be purged to see the effect.

Help:Convert messages

When there is a problem with a convert, the module outputs a message to alert editors. Extra information is shown on mouseover (pop-up text appears when the mouse is held above the error message). The message links to Help:Convert messages—that page should be copied and translated. As explained above, a simple way to get started would be to link to the enwiki page; translation could occur later.

To demonstrate all possible messages, another template is needed, namely Template:Convert/warning which has |warnings=2 to enable all warnings. For general use, |warnings=1 is probably better as it will only display a warning if a convert uses invalid options. Setting warnings to level 2 also reports empty options, and that may cause a problem with templates that use convert because such templates often pass empty options.