Difference between revisions of "Template:Engvar/doc"

From blackwiki
Jump to navigation Jump to search
imported>DePiep
imported>Wikisaurus
(Undid revision 863403503 by Wikisaurus (talk))
 
(84 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
{{Documentation subpage}}
 
{{Documentation subpage}}
<!-- Categories and interwikis go at the bottom of this page. -->
+
{{lua|module:Engvar}}
 +
This template can be used inside a template. It allows the template to show '''national variants of English''' ([[WP:ENGVAR]]), depending on the individual article preference.
  
== Usage ==
+
For example, the same template can show the word "football" text in en-UK articles, and "soccer" in en-US articles.
This template can be used in templates that are used on pages with different '''English language variants''' (see [[WP:ENGVAR|ENGVAR]]): articles in en-UK and articles in en-US. At the moment only UK and US English are recognised.
 
  
'''Article editor:''' When using the prepared template in an article, the editor can set its parameter  {{code|<nowiki>|engvar=en-UK</nowiki>}}. The template text now will use the provided en-UK variant of words. This parameter setting is only needed once in the template.
+
==Usage==
 +
;1. For the editors, add the parameter
 +
Add {{para|engvar|}} to the parameter list. To be used in an article. With this parameter an editor sets a variant Engvar language: {{para|engvar|en-US}}.
  
'''In the template:''' So your template takes ''input parameter'' {{code|<nowiki>{{{engvar}}}</nowiki>}} as the language id. Internally, your template should have this code construct:
+
;2. Inside the template code, add like
 
<pre>
 
<pre>
 
...
 
...
| label= {{engvar| engvar={{{engvar}}} | en-uk=Football | en-us=Soccer }}
+
|label3 = {{engvar |defaultWord=Colour |defaultLang=en-UK |en-US=Color |engvar={{{engvar|}}} }}
 +
| data3 = {{{color|}}}
 
...
 
...
 
</pre>
 
</pre>
Depending on the engvar input, it returns one of the words.
 
  
===Language id===
+
First, the {{para|defaultWord}} entered in the template will be shown. But when an article asks for a variant language, that alternative word &mdash;when found in the list&mdash;will be shown. The article editor has some freedom in words: {{para|engvar|en-US}}, {{para|engvar|United States}}, {{para|engvar|US}} all lead to the listed {{para|en-US|football}} variant.
At this moment, the next language ids are recognised.<br />
 
Used in article code (article editor; case insensitive):
 
* {{code|1=engvar= en-UK, UK, en-uk, uk}} &rarr; returns the en-UK word(s)
 
* {{code|1=engvar= en-US, US, en-us, us}} &rarr; returns the en-US word(s)
 
* {{code|1=engvar= en, EN}} &rarr; returns the plain English word(s) (more on this below)
 
  
Used in template code (template editor):
+
Note that the template parameter (user value) is passed through: <nowiki>|engvar={{{engvar|}}}</nowiki>
* Here, always use the lowercase language id for your word definition: {{code|1=uk-en=Football}} (NOT {{code|1=uk-EN=Football}})
 
* Recognised language id's: {{code|1=en-uk= OR uk=, en-us= OR us=, en=}}
 
  
===Unnamed parameters===
+
In the example, the template shows the ''default word'' being the en-UK one (without the article editor taking any action in this). In an ''en-US language'' article, the word can be changed.
In template code unnamed parameters can be used:
 
* Unnamed parameter 1=pass throught the {{code|<nowiki>{{{engvar}}}</nowiki>}} variable. Named: {{code|<nowiki>engvar={{{engvar}}}</nowiki>}}
 
* Unnamed parameter 2=en-UK word(s)
 
* Unnamed parameter 3=en-US word(s)
 
* Parameter "en=" cannot be unnamed.
 
  
 +
* This template can be '''reused''' in the template, with the same {{para|engvar}} choice taking effective:
 
<pre>
 
<pre>
<!-- The next four rows are equal in template code: -->
 
 
...
 
...
| label= {{engvar| engvar={{{engvar|}}} | en-uk=Football | en-us=Soccer }}
+
| label4 = {{engvar|defaultWord=Football |defaultLang=en-UK |en-US=Soccer |engvar=<nowiki>{{{engvar|}}}</nowiki> }} team
| label= {{engvar| 1={{{engvar|}}} | uk=Football | us=Soccer }}
+
| data4 = {{{team|}}}
| label= {{engvar| {{{engvar|}}} | Football | Soccer }}
 
| label= {{engvar| 1={{{engvar|}}} | 2=Football | 3=Soccer }}
 
 
...
 
...
 
</pre>
 
</pre>
  
===Plain "en" variant===
 
It is possible to define and use the plain English variant word(s) with id "en": {{code|1=en=Association football}}. From here, the article can ask for plain "en" by using {{code|1=engvar=en}}.
 
  
In the template code, this must ''always'' be a named parameter.
+
'''Note''': Parameter names like {{para|color}} vs. {{para|colour}} are not affected at all. Existing names do not change by this template in any way. (See programming option <code><nowiki>|data3 = {{{color|{{{colour|}}} }}}</nowiki></code>)
 +
 
 +
===Example===
 +
Below is an example template, a fictive {{tlf|infobox personal likes}}. The demo is encoded in {{tlx|Engvar/infobox demo}}.
 +
'''Template code'''
 
<pre>
 
<pre>
...
+
{{infobox
| label= {{engvar| {{{engvar|}}} | Football | Soccer | en=Association football }}
+
| title  = Personal likes
...
+
| headerstyle=background:lemonchiffon
 +
| label1  = Home country
 +
|  data1  = {{{home country|}}}
 +
| header2 = Favorite things
 +
| label3 = {{engvar|defaultWord=Colour |defaultLang=en-UK | engvar={{{engvar|}}}
 +
            |en-US=Color }}
 +
|  data3  = {{{color|}}}
 +
| label4  = {{engvar|defaultWord=Football |defaultLang=en-UK | engvar={{{engvar|}}}
 +
            |en-US=Soccer |en-AU=Association Football}} team
 +
|  data4  = {{{team|}}}}}
 
</pre>
 
</pre>
 
+
'''Three articles''':
===Default language id===
+
{{clear}}
'''Default behaviour 1:''' To force a default language id (a language that will be used when there is no input, or a blank input) use {{code|1=default=en-US}}.
+
{{Engvar/infobox demo
 +
| home country = Wales
 +
| color = Blue
 +
| team  = [[FC Kuusysi]]
 +
| engvar =<!-- not set; expect defaults -->
 +
}}
 
<pre>
 
<pre>
| label= {{engvar| {{{engvar}}} | Football | Soccer | default=en-US }}
+
{{Engvar/infobox demo
 +
| home country = Wales
 +
| color = Blue
 +
| team  = [[FC Kuusysi]]
 +
| engvar=<!-- not set; expect defaults -->
 +
}}
 
</pre>
 
</pre>
 +
{{clear}}
 +
{{Engvar/infobox demo
 +
| home country = Alaska
 +
| color = Blue
 +
| team  = [[FC Kuusysi]]
 +
| engvar= en-US
 +
}}
 +
<pre>
 +
{{Engvar/infobox demo
 +
| home country = Alaska
 +
| color = Blue
 +
| team  = [[FC Kuusysi]]
 +
| engvar = en-US
 +
}}
 +
</pre>{{clear}}
 +
{{clear}}
 +
{{Engvar/infobox demo
 +
| home country = Australia
 +
| color = Blue
 +
| team  = [[FC Kuusysi]]
 +
| engvar= Australian
 +
}}
 +
<pre>
 +
{{Engvar/infobox demo
 +
| home country = Australia
 +
| color = Blue
 +
| team  = [[FC Kuusysi]]
 +
| engvar = Australian
 +
}}
 +
</pre>{{clear}}
 +
 +
'''A live example'''
 +
Currently, {{tl|infobox element}} has five {{tlf|engvar}} words. Default is en-US, and [[Template:Phosphorus|Phosphorus]] shows its setting is {{para|engvar|en-UK}}.
  
'''Default behaviour 2:''' Another default-behaviour can be used: in your template, provide parameter {{code|engvar}} with a default language id:
+
==More details==
 
<pre>
 
<pre>
| label= {{engvar| {{{engvar| en-US }}} | Football | Soccer | en=Association football }}
+
| defaultWord =
 +
| defaultLang =
 +
| engvar = {{{engvar|}}}
 +
| en-XX = <!-- Add country code for XX, and the nation language word -->
 +
| en-YY = <!-- Add more variants as might be needed -->
 +
| engvarCat = {{{engvarCat|}}}<!-- '=no' will suppress message category in article page) -->
 
</pre>
 
</pre>
This default last example will ''not'' use the default language when the engvar is a blank. Instead, the standard default word is returned (see below).This may occur in nested templates and pass-through variables.
 
  
===Default word(s)===
+
;{{para|1=defaultWord}}
'''Default behaviour 3:'''
+
:The word (or sentence) that will be shown by default. Pick the language one that is most often used (no preference involved).
When the {{code|engvar}} value is not recognised (or the {{code|default}} language alternative you might have provided), then the ''default word(s)'' will be returned.
+
 
 +
;{{para|engvar|}}
 +
:Add <code><nowiki>| engvar = {{{engvar|}}}</nowiki></code> to the template. This passes through the article's setting to the internal Engvar template for processing.
 +
 
 +
;{{para|1=en-XX}}, {{para|1=en-YY}}
 +
:Add the alternative language variant(s). Only those languages (words) that differ from the default are needed. Also, only list the languages that are likely to be used in the template. Will the template be used in Jamaican English language articles?
  
This default word(s) is determined as follows:
+
:In the template code, use the ''[[#List of Engvar codes|listed codes]]'' only: <code>en-UK=</code>, <code>en-AU=</code>, <code>en-OED=</code>, etcetera. So in the template code, write {{xt|1={{!}}en-US=soccer}}, ''not'' {{!xt|1={{!}}American English=soccer}} (the textual freedom is available for the article editor).
1st: the {{code|1=en=}} word(s) if entered<br />
 
2nd: the {{code|1=en-uk=}} (or uk) word(s) if entered<br />
 
3rd: the {{code|1=en-us=}} (or us) word(s) if entered<br />
 
4rd: a blank<br />
 
Clearly, this template tries to make a catch when possible. Blanks output avoided when possibble.
 
  
'''Default behaviour 4:''' From the above, it follows that entering {{code|1=engvar=en}} produces the default word(s) as described. This is intentionally and by definition. Still, it is preferred not to rely on this route, because it might not work as expected.
+
;{{para|1=defaultLang}}
 +
:Not required. Use an <code>=en-ZZ</code> code. Adding this helps documenting your {{tlf|engvar}} setting. See also [[#Maintenance category|Maintenance category]] below.
  
'''Notes on coding'''
+
;{{para|engvarCat}}
* On the template side provide at least both UK and US word(s), and maybe the en-word(s). Do not rely on the Default-behaviour, ''even when it tests OK today''.
+
:{{para|engvarCat|no}} will suppress (prevent) the ''maintenance category'' to be added to an article page. See [[#Maintenance category|Maintenance category]] below.
* Use named parameters for code clarity
 
* Do not rely on blank entries to return (do not use: {{code|1=<nowiki>en-UK=|...}}</nowiki>}}). It might be interpreted as absent, and so another word may be used.
 
  
===Full parameter list===
+
==Parameter list==
Parameter list:
+
In the
 
<pre>
 
<pre>
{{engvar
+
| defaultWord =
| engvar =
+
| defaultLang =
| en-uk  =
+
| engvar = {{{engvar|}}}<!-- Pass through the editor's choice -->
| en-us  =
+
| en-XX = <!-- add country code for XX, and the nation language word -->
| en    =
+
| en-YY = <!-- add more variants as might be needed -->
| default=
+
| engvarCat = {{{engvarCat|}}} <!-- '=no' will suppress message category in article page) -->
}}
 
 
</pre>
 
</pre>
  
Or, equivalent names:
+
In the parameter list, for the editor to see & use:
 
<pre>
 
<pre>
{{engvar
 
 
| engvar =
 
| engvar =
| uk    =
+
| engvarCat =
| us    =
 
| en    =
 
| default=
 
}}
 
 
</pre>
 
</pre>
  
Or, unnamed:
+
==<span id="List of Engvar codes" ></span> List of variant languages==
<pre>
+
In the template code, use the ''exact'' ISO-code as parameter name:
{{engvar
+
{{para|en-GB|vapour}}
|
+
(The need for precision it with the ''template encoder''. Then for the ''article editor'' are the leeways such as variant language names).
|
+
{| class="wikitable sortable collapsible uncollapsed" style="min-width:50%;"
|
+
! Language
| en     =
+
! ISO-code
| default=
+
|-
}}
+
| [[American English]]
</pre>
+
| en-US
 
+
|-
==Todo==
+
| [[Australian English]]
* Other English variants could be added
+
| en-AU
* Is there a definite list of English language variants, we should cover?
+
|-
* Maybe a fallback can exist: if en-GB does not exist then use en-UK
+
| [[British English]]
* Rewrite this doc. ;-) <!--self reference me DePiep -->
+
| en-GB
 
+
|-
==Examples==
+
| [[Canadian English]]
* See [[Template:Engvar/testcases]]
+
| en-CA
 
+
|-
{| class=wikitable
+
| [[Hiberno-English]] (Irish-English)
! en-UK
+
| en-EI
! en-US
+
|-
! en-CAN<br />en-OED (Oxford)
+
| [[Hong Kong English]]
! en-AUS<br />en-NZ
+
| en-HK
 +
|-
 +
| [[Indian English]]
 +
| en-IN
 +
|-
 +
| [[Jamaican English]]
 +
| en-JM
 +
|-
 +
| [[Malawian English]]
 +
| en-MW
 +
|-
 +
| [[New Zealand English]]
 +
| en-NZ
 +
|-
 +
| [[Nigerian English]]
 +
| en-NG
 +
|-
 +
| [[Pakistani English]]
 +
| en-PK
 +
|-
 +
| [[Philippine English]]
 +
| en-PH
 +
|-
 +
| [[Scottish English]]
 +
| en-SCO
 +
|-
 +
| [[Singapore English]]
 +
| en-SG
 
|-
 
|-
| centre || center || centre || centre
+
| [[South African English]]
 +
| en-ZA
 
|-
 
|-
| colour || color || colour || colour
+
| [[Trinidadian English]]
 +
| en-TT
 
|-
 
|-
| -isation || -ization || -ization || -isation
+
| data-sort-value="_Oxford" | British English [[Oxford spelling]]<br/>British (Oxford) English<br/>''[[Oxford English Dictionary]]'' (OED)
 +
| data-sort-value="_Oxford" | en-OED
 
|-
 
|-
| vapour || vapor || vapour || vapour
+
| data-sort-value="_IUPAC" | IUPAC spelling
 +
| data-sort-value="_IUPAC" | en-IUPAC
 
|}
 
|}
== See also ==
+
*[[HELP:ENGVAR]]
* [[WP:ENGVAR]] about using a single variant in an article
+
 
 +
*[[ISO 3166-1 alpha-2]] 2-letter country code
 +
 
 +
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||
 +
<!-- Categories go here and interwikis go in Wikidata. -->
 +
 
 +
}}</includeonly>
 +
 
 +
==The maintenance category==
 +
Articles that can not resolve the Engvar request (The {{para|engvar|}} for the template can not be resolved), will be placed in the hidden maintenance category:
 +
:[[:Category:Articles using an unknown Template:Engvar option]]
 +
Articles listed here can indicate that the may need adjustment (or the article needs a correction).
 +
 
 +
The editors Engvar request may not be available in your template code. For example, an {{para|engvar|South African English}} is asked for, but is not in the variants list you entered, so can not be honored (the <code>defaultWord</code> is shown). You can check the ''maintenance category'' for those requests, and maybe improve the template.
 +
:When this categorization is not wanted desired for a page or a whole tempalte, parameter {{para|engvarCat|no}} can be set in code for the whole of the template ( = the template will never add this category).
 +
:The template can also pass-through this setting from the article: {{para|engvarCat|<nowiki>{{{engvarCat|yes}}}</nowiki>}}. This allows the editor to switch categorization off per article.
 +
 
 +
Articles are sorted by {{para|engvarCatSort}} (or pagename by default). Note that all templates will be filling this category. Set this parameter to group all template reports (e.g. {{para|engvarCatSort|Personal prefs}} will group ''this'' templates listings under "P").
 +
 
 +
* The module has a debugging option <code><nowiki>{{#invoke:Engvar|explain|...}}</nowiki></code> to give feedback on the arguments entered.
 +
 
 +
==See also==
 +
*[[HELP:ENGVAR]]
 +
*[[:Category:Articles using an unknown Template:Engvar option]]
 +
*[[ISO 3166-1 alpha-2]] -- The 2-letter country code<!--
  
<includeonly>
+
--><includeonly>{{sandbox other| |
<!-- Categories and interwikis go here: -->
+
[[Category:Engvar]]
  
</includeonly>
+
}}</includeonly>

Latest revision as of 15:39, 10 October 2018

This template can be used inside a template. It allows the template to show national variants of English (WP:ENGVAR), depending on the individual article preference.

For example, the same template can show the word "football" text in en-UK articles, and "soccer" in en-US articles.

Usage

1. For the editors, add the parameter

Add |engvar= to the parameter list. To be used in an article. With this parameter an editor sets a variant Engvar language: |engvar=en-US.

2. Inside the template code, add like
...
|label3 = {{engvar |defaultWord=Colour |defaultLang=en-UK |en-US=Color |engvar={{{engvar|}}} }}
| data3 = {{{color|}}}
...

First, the |defaultWord= entered in the template will be shown. But when an article asks for a variant language, that alternative word —when found in the list—will be shown. The article editor has some freedom in words: |engvar=en-US, |engvar=United States, |engvar=US all lead to the listed |en-US=football variant.

Note that the template parameter (user value) is passed through: |engvar={{{engvar|}}}

In the example, the template shows the default word being the en-UK one (without the article editor taking any action in this). In an en-US language article, the word can be changed.

  • This template can be reused in the template, with the same |engvar= choice taking effective:
...
| label4 = {{engvar|defaultWord=Football |defaultLang=en-UK |en-US=Soccer |engvar={{{engvar|}}} }} team
|  data4 = {{{team|}}}
...


Note: Parameter names like |color= vs. |colour= are not affected at all. Existing names do not change by this template in any way. (See programming option |data3 = {{{color|{{{colour|}}} }}})

Example

Below is an example template, a fictive {{infobox personal likes}}. The demo is encoded in {{Engvar/infobox demo}}. Template code

{{infobox
| title   = Personal likes
| headerstyle=background:lemonchiffon
| label1  = Home country
|  data1  = {{{home country|}}}
| header2 = Favorite things
|  label3 = {{engvar|defaultWord=Colour |defaultLang=en-UK | engvar={{{engvar|}}}
            |en-US=Color }}
|  data3  = {{{color|}}}
| label4  = {{engvar|defaultWord=Football |defaultLang=en-UK | engvar={{{engvar|}}}
            |en-US=Soccer |en-AU=Association Football}} team
|  data4  = {{{team|}}}}}

Three articles:

Personal likes
Demo: using WP:Engvar in templates
Home countryWales
Favorite things
ColourBlue
Football teamFC Kuusysi
In this demo 'article', template parameter is set: |engvar=
{{Engvar/infobox demo
| home country = Wales
| color = Blue
| team  = [[FC Kuusysi]]
| engvar=<!-- not set; expect defaults -->
}}
Personal likes
Demo: using WP:Engvar in templates
Home countryAlaska
Favorite things
ColorBlue
Soccer teamFC Kuusysi
In this demo 'article', template parameter is set: |engvar=en-US
{{Engvar/infobox demo
| home country = Alaska
| color = Blue
| team  = [[FC Kuusysi]]
| engvar = en-US
}}
Personal likes
Demo: using WP:Engvar in templates
Home countryAustralia
Favorite things
ColourBlue
Association Football teamFC Kuusysi
In this demo 'article', template parameter is set: |engvar=Australian
{{Engvar/infobox demo
| home country = Australia
| color = Blue
| team  = [[FC Kuusysi]]
| engvar = Australian
}}

A live example Currently, {{infobox element}} has five {{engvar}} words. Default is en-US, and Phosphorus shows its setting is |engvar=en-UK.

More details

| defaultWord =
| defaultLang =
| engvar = {{{engvar|}}}
| en-XX = <!-- Add country code for XX, and the nation language word -->
| en-YY = <!-- Add more variants as might be needed -->
| engvarCat = {{{engvarCat|}}}<!-- '=no' will suppress message category in article page) -->
|defaultWord=
The word (or sentence) that will be shown by default. Pick the language one that is most often used (no preference involved).
|engvar=
Add | engvar = {{{engvar|}}} to the template. This passes through the article's setting to the internal Engvar template for processing.
|en-XX=, |en-YY=
Add the alternative language variant(s). Only those languages (words) that differ from the default are needed. Also, only list the languages that are likely to be used in the template. Will the template be used in Jamaican English language articles?
In the template code, use the listed codes only: en-UK=, en-AU=, en-OED=, etcetera. So in the template code, write |en-US=soccer, not |American English=soccer (the textual freedom is available for the article editor).
|defaultLang=
Not required. Use an =en-ZZ code. Adding this helps documenting your {{engvar}} setting. See also Maintenance category below.
|engvarCat=
|engvarCat=no will suppress (prevent) the maintenance category to be added to an article page. See Maintenance category below.

Parameter list

In the

| defaultWord =
| defaultLang =
| engvar = {{{engvar|}}}<!-- Pass through the editor's choice -->
| en-XX = <!-- add country code for XX, and the nation language word -->
| en-YY = <!-- add more variants as might be needed -->
| engvarCat = {{{engvarCat|}}} <!-- '=no' will suppress message category in article page) -->

In the parameter list, for the editor to see & use:

| engvar =
| engvarCat =

List of variant languages

In the template code, use the exact ISO-code as parameter name: |en-GB=vapour (The need for precision it with the template encoder. Then for the article editor are the leeways such as variant language names).

Language ISO-code
American English en-US
Australian English en-AU
British English en-GB
Canadian English en-CA
Hiberno-English (Irish-English) en-EI
Hong Kong English en-HK
Indian English en-IN
Jamaican English en-JM
Malawian English en-MW
New Zealand English en-NZ
Nigerian English en-NG
Pakistani English en-PK
Philippine English en-PH
Scottish English en-SCO
Singapore English en-SG
South African English en-ZA
Trinidadian English en-TT
British English Oxford spelling
British (Oxford) English
Oxford English Dictionary (OED)
en-OED
IUPAC spelling en-IUPAC


The maintenance category

Articles that can not resolve the Engvar request (The |engvar= for the template can not be resolved), will be placed in the hidden maintenance category:

Category:Articles using an unknown Template:Engvar option

Articles listed here can indicate that the may need adjustment (or the article needs a correction).

The editors Engvar request may not be available in your template code. For example, an |engvar=South African English is asked for, but is not in the variants list you entered, so can not be honored (the defaultWord is shown). You can check the maintenance category for those requests, and maybe improve the template.

When this categorization is not wanted desired for a page or a whole tempalte, parameter |engvarCat=no can be set in code for the whole of the template ( = the template will never add this category).
The template can also pass-through this setting from the article: |engvarCat={{{engvarCat|yes}}}. This allows the editor to switch categorization off per article.

Articles are sorted by |engvarCatSort= (or pagename by default). Note that all templates will be filling this category. Set this parameter to group all template reports (e.g. |engvarCatSort=Personal prefs will group this templates listings under "P").

  • The module has a debugging option {{#invoke:Engvar|explain|...}} to give feedback on the arguments entered.

See also