Difference between revisions of "Template:Lang/doc"

From blackwiki
Jump to navigation Jump to search
imported>Nnemo
(Notably — Restoring “these” in plural. Corr. Typography. Section, not “§”. Details. Links.)
imported>Sardanaphalus
(some rephrasings, replaced <tt>, ref ... to do: size option)
Line 1: Line 1:
{{documentation subpage}}
+
{{Documentation subpage}}
  
The purpose of this template is to indicate that a given span of text belongs to a particular language (see [[language code]]). It often makes no visible changes to the text, but can help web browsers choose the right font, screen readers use the right pronunciation, and more. (See [[#Rationale|section ''Rationale'']] for further information.)
+
The purpose of this template is to indicate, via [[Language code|a code]], that a span of text belongs to a particular language. It often makes no visible changes to the text, but can prompt web browsers to use a more appropriate font, or screen readers to use a particular kind of pronunciation; and so on. The [[#Rationale|"Rationale" section below]] provides more information.
  
<nowiki>{{</nowiki>lang|''Language tag''|''Text''}}
+
===Syntax and usage===
 +
: {{tlx|lang|''[[List of ISO 639 codes|ISO 639 language code]]''|''text''}}
  
Use [[List of ISO 639 codes|ISO 639 language codes]]. Example (where <tt>fr</tt> is the code for [[French language|French]]):  
+
The [[ISO 639]] code is usually a two or three-letter abbreviation, in lowercase, of the language's name. [[French language|French]], for example, has the code "fr":
 +
: {{plaincode|<nowiki>She said: "''{{lang|fr|Je suis française.}}''"</nowiki>
 +
produces:
 +
: She said: "''{{lang|fr|Je suis française.}}''"
  
<pre>
+
By default, this template will place articles into the relevant subcategory of {{cl|Articles containing non-English-language text}}. To suppress this{{aside|e.g. when using {{braces|lang}} within a [[Help:Link#Wikilinks|wikilink]] or the ''title'' parameter of a citation}} add the parameter {{para|nocat|true}}. If {{braces|lang}} is used to identify a language read from right to left, e.g. [[Arabic language|Arabic]], the template {{tl|rtl-lang}} may be used afterward to ensure the standard (English) left-to-right formatting is resumed. It also supports the {{para|nocat}} parameter.
* She said: "''{{lang|fr|Je suis française.}}''"
 
</pre>
 
 
 
Results in your browser:
 
* She said: "''{{lang|fr|Je suis française.}}''"
 
 
 
By default, this template will place articles into the relevant subcategory of {{cl|Articles containing non-English-language text}}. To suppress this, for example when using the template inside a wikilink or the "title" parameter of a citation, add the parameter {{para|nocat|true}}. To reset the direction of text immediately following a string of right-to-left text, the {{tl|rtl-lang}} template may be used, which also supports the {{para|nocat}} parameter.
 
 
 
If appropriate, the entire wikilink may be fed to the template instead:
 
  
;Good
+
It is usually better to incorporate an entire wikilink within {{braces|lang}} rather than a label, i.e. {{plaincode|<nowiki>{{lang|grc|[[Ancient Greek|Ἑλληνική]]}}</nowiki>,}} for example, rather than [[File:Symbol declined.svg|16px|alt=|link=]]{{plaincode|<nowiki>[[Ancient Greek|{{lang|grc|Ἑλληνική}}]]</nowiki>}}.
:<code><nowiki>{{lang|ar|[[Arabic language|العربية]]}}</nowiki></code>
 
;Bad
 
:<code><nowiki>[[Arabic language|{{lang|ar|العربية}}]]</nowiki></code>
 
  
There are also versions of this template for specific languages that also print the language's name, intended to be used the first time that language is used in the article. For example, {{j|"{{tlx|lang-es|español}}"}} and {{j|"{{tlx|lang-ru|русский язык}}"}} give "{{lang-es|español}}" and "{{lang-ru|русский язык}}".
+
There are also versions of this template for specific languages, intended for use the first time one of those languages appears in an article, that print the language's name. {{nowrap|"{{tlxpl|lang-es|español}}"}} and {{nowrap|"{{tlxpl|lang-ru|русский язык}}"}}, for example, yield "{{lang-es|español}}" and "{{lang-ru|русский язык}}".
  
Language subtags can also be used to indicate the writing script or regional variant of a language. According to the [[World Wide Web Consortium|W3C]], "the golden rule when creating language tags is to keep the tag as short as possible", [http://www.w3.org/International/articles/language-tags/Overview.en.php] so such subtags should only be added if there is an important reason to use them. [[ISO 639‑1]] is preferred over [[ISO 639‑2]] and [[ISO 639‑3]].
+
Language subtags can be used to indicate a regional variant of and/or a particular script used for a language. According to the [[World Wide Web Consortium]], "the golden rule when creating language tags is to keep the tag as short as possible",<ref>http://www.w3.org/International/articles/language-tags/Overview.en.php</ref> so such subtags should only be added if there is good reason to use them. [[ISO 639‑1]] is preferred over [[ISO 639‑2]] and [[ISO 639‑3]].
  
 
== Italics ==
 
== Italics ==
  
{{tlx|lang|xx}} outputs plain text by default. In {{tlx|lang-xx}}, the foreign-language text is italicised by default. If plain text is required, e.g. for proper names, {{tlx|noitalics}} may be used:
+
By default, {{tlp|lang|[language code]|…}} outputs plain text, while {{tnf|lang-[language code]|…}} templates (e.g. {{tl|lang-de}}) output text in italics. If, with the latter, plain text is required (e.g. for proper names), {{tl|noitalics}} may be used. For example,
 
+
: {{plaincode|… the border town of Ventimiglia (<nowiki>{{lang-fr|{{noitalics|Vintimille}}}}</nowiki>)}}
<pre>
+
produces:
* ... the border town of Ventimiglia ({{lang-fr|{{noitalics|Vintimille}}}})
+
: the border town of Ventimiglia ({{lang-fr|{{noitalics|Vintimille}}}})
</pre>
 
 
 
Gives:
 
* ... the border town of Ventimiglia ({{lang-fr|{{noitalics|Vintimille}}}})
 
  
 
== Indicating writing script ==
 
== Indicating writing script ==
  
If necessary, add the [[List of ISO 15924 codes|ISO 15924]] code to indicate the script.  
+
If necessary, add the [[List of ISO 15924 codes|ISO 15924]] code to indicate the script.  
  
For example, [[Russian language|Russian]] is usually written in the [[Cyrillic script]], therefore the <tt>Cyrl</tt> script code is superfluous and the language code will be <tt>ru</tt> instead of <tt>ru-Cyrl</tt>. However, when that text is [[transliteration|transliterated]] the <tt>transl</tt> code (transliteration) should be used because it isn't the default script for Russian: <tt>ru-Latn</tt>.  Example:
+
For example, [[Russian language|Russian]] is usually written in the [[Cyrillic script]], therefore the {{plaincode|Cyrl}} script code is superfluous and the language code will be {{plaincode|ru}} instead of {{plaincode|ru-Cyrl}}. However, when that text is [[transliteration|transliterated]] the {{plaincode|transl}} code (transliteration) should be used because it isn't the default script for Russian: {{plaincode|ru-Latn}}.  Example:
  
 
<pre>
 
<pre>
Line 55: Line 43:
 
* Moscow ({{lang-ru|Москва́}}, {{transl|ru|''Moskva''}})
 
* Moscow ({{lang-ru|Москва́}}, {{transl|ru|''Moskva''}})
  
Instead of using <code><nowiki>{{transl|ru|''Moskva''}}</nowiki></code> the <code><nowiki>{{lang|ru-Latn|''Moskva''}}</nowiki></code> can be used, but if you specified a font and a size for the target language in your [[Special:Mypage/vector.css|custom CSS]] (see [[Help:User style]]), the transliteration will appear in that specified style. To specify a transliteration scheme, for example, you are using the [[ISO 9]] transliteration of Cyrillic, use <code><nowiki>{{transl|ru|ISO|''Moskva''}}</nowiki></code>:
+
Instead of using <code><nowiki>{{transl|ru|''Moskva''}}</nowiki></code> the <code><nowiki>{{lang|ru-Latn|''Moskva''}}</nowiki></code> can be used, but if you specified a font and a size for the target language in your [[Special:Mypage/vector.css|custom CSS]] (see [[Help:User style]]), the transliteration will appear in that specified style. To specify a transliteration scheme, for example, you are using the [[ISO 9]] transliteration of Cyrillic, use <code><nowiki>{{transl|ru|ISO|''Moskva''}}</nowiki></code>:
 
* Moscow ({{lang-ru|Москва́}}; [[ISO 9]]: {{transl|ru|ISO|''Moskva''}})
 
* Moscow ({{lang-ru|Москва́}}; [[ISO 9]]: {{transl|ru|ISO|''Moskva''}})
  
Line 66: Line 54:
 
Note the use of {{tl|rtl-lang}} instead of {{tl|lang}} when using the Arabic script (see hereafter section [[#Writing direction|''Writing direction'']]).
 
Note the use of {{tl|rtl-lang}} instead of {{tl|lang}} when using the Arabic script (see hereafter section [[#Writing direction|''Writing direction'']]).
  
=== Undetermined language ===
+
===Undetermined language===
 
+
The <nowiki>{{</nowiki>lang}} template is not only used to specify the language of foreign words, but also to specify a single symbol or character in a specific script, for example when discussing about a specific writing system. Many times the character / symbol is used in several languages, but when the article refers to the [[grapheme]] itself the [[ISO 639‑2]] and [[ISO 639‑3]] language code {{plaincode|und}} for Undetermined language should be used. For example:
The <nowiki>{{</nowiki>lang}} template is not only used to specify the language of foreign words, but also to specify a single symbol or character in a specific script, for example when discussing about a specific writing system. Many times the character / symbol is used in several languages, but when the article refers to the [[grapheme]] itself the [[ISO 639‑2]] and [[ISO 639‑3]] language code <tt>und</tt> for Undetermined language should be used. For example:
 
  
 
<pre>
 
<pre>
The {{lang|und-Hani|字}} Han character has 6 strokes.
+
The {{lang|und-Hani|字}} Han character has 6 strokes.
 
</pre>
 
</pre>
:The {{lang|und-Hani|字}} Han character has 6 strokes.
+
:The {{lang|und-Hani|字}} Han character has 6 strokes.
  
Han characters are used in Chinese, Japanese, sometimes Korean, and formerly Vietnamese, and in this case the character is not used for any specific language. Note that the script code used is <tt>Hani</tt>, which specifies generic Han characters (Hanzi, Kanji, Hanja).
+
Han characters are used in Chinese, Japanese, sometimes Korean, and formerly Vietnamese, and in this case the character is not used for any specific language. Note that the script code used is {{plaincode|Hani}}, which specifies generic Han characters (Hanzi, Kanji, Hanja).
  
 
Compare {{tl|script}}
 
Compare {{tl|script}}
 
<pre>
 
<pre>
The {{script|Hani|字}} Han character has 6 strokes.
+
The {{script|Hani|字}} Han character has 6 strokes.
 
</pre>
 
</pre>
:The {{script|Hani|字}} Han character has 6 strokes.
+
:The {{script|Hani|字}} Han character has 6 strokes.
  
 
== Indicating regional variant ==
 
== Indicating regional variant ==
  
In some cases, maybe it will be needed to add [[ISO 3166-1 alpha-2]] country codes (specific usage of that country). Of course the three codes can appear in the same tag, for example the code <tt>zh-Hant-TW</tt> will be used for [[Chinese language|Chinese]] text written with [[Traditional Chinese characters|Traditional Han characters]], containing words or expressions specific to [[Taiwan]]. <tt>zh-Hans</tt> is for simplified. Examples:
+
In some cases, maybe it will be needed to add [[ISO 3166-1 alpha-2]] country codes (specific usage of that country). Of course the three codes can appear in the same tag, for example the code {{plaincode|zh-Hant-TW}} will be used for [[Chinese language|Chinese]] text written with [[Traditional Chinese characters|Traditional Han characters]], containing words or expressions specific to [[Taiwan]]. {{plaincode|zh-Hans}} is for simplified. Examples:
  
 
<pre>
 
<pre>
Line 100: Line 87:
 
== Rationale ==
 
== Rationale ==
  
* [[WWW|Web]] [[Web browser|browsers]] can use the information in such [[:Category:multilingual support templates|multilingual support templates]] to choose an appropriate font.
+
* [[WWW|Web]] [[Web browser|browsers]] can use the information in such [[:Category:multilingual support templates|multilingual support templates]] to choose an appropriate font.
 
** This is great for [[CJK characters|CJK]] where a character can be given its language-specific shape but will fall back to another form if no appropriate font is found or if the preferred font lacks that character, for example because the language does not make use of that character: see [[Han Unification#Examples of language dependent characters]] and [[User:Wikipeditor/CJK|these comparison table and screen photo]].
 
** This is great for [[CJK characters|CJK]] where a character can be given its language-specific shape but will fall back to another form if no appropriate font is found or if the preferred font lacks that character, for example because the language does not make use of that character: see [[Han Unification#Examples of language dependent characters]] and [[User:Wikipeditor/CJK|these comparison table and screen photo]].
 
* For [[web accessibility|accessibility]] – [[screen reader]]s need language info to speak text in the correct language – and to satisfy [[Wikipedia:Accessibility#Text|Wikipedia accessibility guidelines]].  
 
* For [[web accessibility|accessibility]] – [[screen reader]]s need language info to speak text in the correct language – and to satisfy [[Wikipedia:Accessibility#Text|Wikipedia accessibility guidelines]].  
Line 115: Line 102:
 
You can apply [[Cascading Style Sheets|CSS]] styles in your user style sheet. Registered users can put styles into User:XXX/monobook.css, where ''XXX'' is the user name.   
 
You can apply [[Cascading Style Sheets|CSS]] styles in your user style sheet. Registered users can put styles into User:XXX/monobook.css, where ''XXX'' is the user name.   
  
These examples may work in [[Internet Explorer 8]]; prior versions do not support attribute selectors. Alternatively, try [[List of web browsers|another browser]] such as [[Firefox]].
+
These examples may work in [[Internet Explorer 8]]; prior versions do not support attribute selectors. Alternatively, try [[List of web browsers|another browser]] such as [[Firefox]].
  
 
Example: to apply a font to Russian-language text:
 
Example: to apply a font to Russian-language text:
Line 128: Line 115:
  
 
== TemplateData ==
 
== TemplateData ==
 +
 
{{TemplateDataHeader}}
 
{{TemplateDataHeader}}
 
<templatedata>{
 
<templatedata>{
Line 134: Line 122:
 
   "1": {
 
   "1": {
 
     "label": "Language code",
 
     "label": "Language code",
     "description": "A language tag or an ISO 639 language code, e.g. fr (the code for French).",
+
     "description": "A language tag or an ISO 639 language code, e.g. fr (the code for French).",
 
     "type": "string",
 
     "type": "string",
 
     "required": true
 
     "required": true
Line 157: Line 145:
 
* {{tl|Language}}
 
* {{tl|Language}}
  
== References ==
+
== Further information ==
 
* [[World Wide Web Consortium|W3C]]
 
* [[World Wide Web Consortium|W3C]]
 
** [http://www.w3.org/International/articles/language-tags/Overview.en.php Language tags in HTML and XML] – Overview
 
** [http://www.w3.org/International/articles/language-tags/Overview.en.php Language tags in HTML and XML] – Overview
** [http://www.w3.org/TR/i18n-html-tech-lang/ Internationalization Best Practices: Specifying Language in XHTML & HTML Content] – W3C Working Draft 21 July 2006
+
** [http://www.w3.org/TR/i18n-html-tech-lang/ Internationalization Best Practices: Specifying Language in XHTML & HTML Content] – W3C Working Draft 21 July 2006
 
** [http://www.w3.org/International/articles/bcp47/ Understanding the New Language Tags]
 
** [http://www.w3.org/International/articles/bcp47/ Understanding the New Language Tags]
 
** [http://www.w3.org/International/questions/qa-css-lang FAQ: Styling using the lang attribute]
 
** [http://www.w3.org/International/questions/qa-css-lang FAQ: Styling using the lang attribute]
 
* [[Internet Assigned Numbers Authority|IANA]]
 
* [[Internet Assigned Numbers Authority|IANA]]
 
** [http://www.iana.org/assignments/language-subtag-registry IANA Language Subtag Registry]
 
** [http://www.iana.org/assignments/language-subtag-registry IANA Language Subtag Registry]
** [http://www.rfc-editor.org/rfc/rfc4646.txt Tags for Identifying Languages] (RFC 4646)
+
** [http://www.rfc-editor.org/rfc/rfc4646.txt Tags for Identifying Languages] (RFC 4646)
** [http://www.rfc-editor.org/rfc/rfc4647.txt Matching of Language Tags] (RFC 4647)
+
** [http://www.rfc-editor.org/rfc/rfc4647.txt Matching of Language Tags] (RFC 4647)
** [http://www.iana.org/assignments/language-tags Language tags] (obsolete per RFC 4646)
+
** [http://www.iana.org/assignments/language-tags Language tags] (obsolete per RFC 4646)
 
* [[Mozilla Firefox]]
 
* [[Mozilla Firefox]]
 
** [https://bugzilla.mozilla.org/show_bug.cgi?id=192636 Bug with script selection]
 
** [https://bugzilla.mozilla.org/show_bug.cgi?id=192636 Bug with script selection]
  
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
+
== References ==
<!---- ADD CATEGORIES HERE: ---->
+
{{reflist}}
 +
 
 +
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox |
 +
| <!---- PLEASE ADD CATEGORIES BELOW THIS LINE: ---->
 
[[Category:Multilingual support templates]]
 
[[Category:Multilingual support templates]]
 
}}</includeonly>
 
}}</includeonly>

Revision as of 11:43, 19 September 2014

The purpose of this template is to indicate, via a code, that a span of text belongs to a particular language. It often makes no visible changes to the text, but can prompt web browsers to use a more appropriate font, or screen readers to use a particular kind of pronunciation; and so on. The "Rationale" section below provides more information.

Syntax and usage

{{lang|ISO 639 language code|text}}

The ISO 639 code is usually a two or three-letter abbreviation, in lowercase, of the language's name. French, for example, has the code "fr":

Template:Plaincode template is not only used to specify the language of foreign words, but also to specify a single symbol or character in a specific script, for example when discussing about a specific writing system. Many times the character / symbol is used in several languages, but when the article refers to the grapheme itself the ISO 639‑2 and ISO 639‑3 language code Template:Plaincode for Undetermined language should be used. For example:
The {{lang|und-Hani|字}} Han character has 6 strokes.
The Han character has 6 strokes.

Han characters are used in Chinese, Japanese, sometimes Korean, and formerly Vietnamese, and in this case the character is not used for any specific language. Note that the script code used is Template:Plaincode, which specifies generic Han characters (Hanzi, Kanji, Hanja).

Compare {{script}}

The {{script|Hani|字}} Han character has 6 strokes.
The Template:Script Han character has 6 strokes.

Indicating regional variant

In some cases, maybe it will be needed to add ISO 3166-1 alpha-2 country codes (specific usage of that country). Of course the three codes can appear in the same tag, for example the code Template:Plaincode will be used for Chinese text written with Traditional Han characters, containing words or expressions specific to Taiwan. Template:Plaincode is for simplified. Examples:

* {{lang|zh-Hant-TW|臺灣}}

Results in your browser:

  • 臺灣

Writing direction

{{rtl-lang}} is used to wrap strings of right-to-left text (from languages like Arabic or Hebrew) embedded in left-to-right text, and resets text direction to left-to-right at its conclusion. For whole paragraphs of right-to-left text, use {{rtl-para}}. The rtl- prefix is not needed in the {{lang-xx}} form, as this is implied by the language: there is no {{rtl-lang-ar}}, for instance: just use {{lang-ar}}.

Rationale

Applying styles

You can apply CSS styles in your user style sheet. Registered users can put styles into User:XXX/monobook.css, where XXX is the user name.

These examples may work in Internet Explorer 8; prior versions do not support attribute selectors. Alternatively, try another browser such as Firefox.

Example: to apply a font to Russian-language text:

 span[lang|=ru] { font-family: fonteskaya; }

Example: to apply a colour to text marked with any language:

 span[lang] { color: green; }

Do not use quotation marks in your user style sheet; wikitext would screw them up. They are recommended in CSS, but not required other than for font families containing generic-family keywords ('inherit', 'serif', 'sans-serif', 'monospace', 'fantasy', and 'cursive'). See http://www.w3.org/TR/CSS21/fonts.html#font-family-prop for details.

TemplateData

This is the TemplateData documentation for this template used by VisualEditor and other tools; see the monthly parameter usage report for this template.

TemplateData for Lang

Indicate that a given span of text belongs to a particular language. Use by browsers which use different styles for different languages.

Template parameters

ParameterDescriptionTypeStatus
Language code1

A language tag or an ISO 639 language code, e.g. fr (the code for French).

Stringrequired
Text2

The text e.g. Je suis française.

Stringrequired

See also

Further information

References