View source for Template:ISO 639 name/doc

{{Documentation subpage}}
{{not to be confused|Template:Tone}}
{{tsh|Iso2lang|Langname|Language|Lname|Lcode}}
{{May be substituted}}
{{High-use}}
{{Lua|Module:ISO 639 name}}
{{Language templates}}

This template may be used to convert an [[ISO 639]] language code (e.g. 'es' or 'de') to a language name ('Spanish' or 'German', respectively) and vice-versa, or to determine if a given code or language is valid in ISO 639.

== Usage ==

* {{tnull | ISO 639 name | ''ISO code''}}
* {{tnull | ISO 639 name | fn{{=}}iso_639_code_to_name | ''ISO code''}}
* {{tnull | Iso 639 name | fn{{=}}iso_639_name_to_code | ''Language name''}}
* {{tnull | ISO 639 name | fn{{=}}iso_639 | ''ISO code or language name'' | link{{=}}yes| hide-err{{=}}yes }}
* {{tnull | iso 639 name | fn{{=}}iso_639_code_exists | ''ISO code''}}

== Parameters ==

There is one required parameter and four optional parameters:

* {{para|1}} – unnamed (positional) param: either an ISO 639 language code, or an ISO 639 language name (required)
* {{para|fn}} – function name: identifies what to do with the code or name in param 1 (convert it, check if it exists; etc.) (optional). These are the most commonly used values:
*:* {{pval|iso_639_code_to_name}} – convert the ISO 639 code in param 1 to a language name. (This is the default if {{kbd|fn}} is omitted.)
*:* {{pval|iso_639_name_to_code}} – convert the language name in param 1 to an ISO 639 code 
*:* {{pval|iso_639_code_exists}} – return {{kbd|true}} if the value in param 1 is an ISO 639 code, otherwise empty
*:* {{pval|iso_639_name_exists}} – return {{kbd|true}} if the value in param 1 is an ISO 639 language name, otherwise empty
*:* {{pval|iso_639}} – try to convert the value in param 1 from a language name to an ISO 639 code, and if that fails then try the other way (code to language)
*: (For more values of {{para|fn}}, see {{slink||Additional function values}} below).
* {{para|link|yes}} – if a language name is returned, links it to the Wikipedia article about the language (optional, default=no)
* {{para|label|''any string''}} – if a language name is returned, and linked with {{para|link|yes}}, then you can alter the link text by setting this param
* {{para|hide-err|yes}} – blocks the error message returned upon failure of any of the three conversion functions ({{hairspace}}{{pval|iso_639_code_to_name}}, {{pval|iso_639_name_to_code}}, {{pval|iso_639}}{{hairspace}}) (optional; default=no)

=== Additional function values ===

The following function values are also available for parameter {{para|fn}}:

* {{pval|iso_639_code_1_to_name}} – same as {{pval|iso_639_code_to_name}} except constrained to the [[ISO 639-1]] data table
* {{pval|iso_639_code_2_to_name}} – same as {{pval|iso_639_code_to_name}} except constrained to the [[ISO 639-2]] data table
* {{pval|iso_639_code_2B_to_name}} – same as {{pval|iso_639_code_to_name}} except constrained to the [[ISO 639-2B]] data table
* {{pval|iso_639_code_3_to_name}} – same as {{pval|iso_639_code_to_name}} except constrained to the [[ISO 639-3]] data table
* {{pval|iso_639_code_5_to_name}} – same as {{pval|iso_639_code_to_name}} except constrained to the [[ISO 639-5]] data table

== Language names and codes ==

For a list of language names and ISO-639 codes, see:
* [[List of Wikipedias]]
* [[Special:SiteMatrix]]
* [[Lists of ISO 639 codes]]<!--DAB page linking five ISO-639 pages-->

== Examples ==

=== One parameter ===
* {{demo-inline|<nowiki>{{ISO 639 name|en}}</nowiki>}}
* {{demo-inline|<nowiki>{{ISO 639 name|fr}}</nowiki>}}

=== With |fn=iso_639_name_to_code ===
* {{demo-inline|<nowiki>{{ISO 639 name|English|fn=iso_639_name_to_code}}</nowiki>}}
* {{demo-inline|<nowiki>{{ISO 639 name|French|fn=iso_639_name_to_code}}</nowiki>}}

==Notes==
The {{tlx|ISO 639 name}} template will trim extraneous [[IETF language tag]]s to just the ISO 639 code. E.g.:
Sanskrit in Latin script, which IETF language tag is <code>sa-Latn</code>, renders as:
* <code><nowiki>{{ISO 639 name|sa-Latn}}</nowiki></code> → {{ISO 639 name|sa-Latn|cat=no}}
The error message can be suppressed with {{para|hide-err|yes}}:
* <code><nowiki>{{ISO 639 name|sa-Latn|hide-err=yes}}</nowiki></code> → {{ISO 639 name|sa-Latn|hide-err=yes}}
The rendered language name can be linked to the appropriate language article with {{para|link|yes}}:
* <code><nowiki>{{ISO 639 name|sa-Latn|hide-err=yes|link=yes}}</nowiki></code> → {{ISO 639 name|sa-Latn|hide-err=yes|link=yes}}
When linking, an alternate link label can be provided with {{para|label|&lt;{{var|label text}}>}}:
* <code><nowiki>{{ISO 639 name|sa-Latn|hide-err=yes|link=yes|label=sa-Latn}}</nowiki></code> → {{ISO 639 name|sa-Latn|hide-err=yes|link=yes|label=sa-Latn}}

The {{tlx|ISO 639 name link}} template is the same as {{tnull|ISO 639 name}} except that it presets {{para|link|yes}}.

Both of these templates {{em|can}} be safely substituted.

==Error messages==
This template produces error messages.  These messages are:
*{{error-small|&lt;{{var|code}}> is an IETF tag}} – [[IETF language tag]]s are not ISO 639 language codes.  When these tags are encountered, the template attempts to render the correct language and also emits this error message
*{{error-small|ISO 639-&lt;{{var|part}}> code is required}} – where &lt;{{var|part}}> is 1, 2, 3, 5; template was called without the required language code
<!-- *{{error-small|&lt;{{var|code}}> is not an ISO 639-&lt;{{var|part}}> code}} – &lt;{{var|code}}> fails simple length validation; 639 part 1, language codes are two characters, for 639 parts 2, 3, and 5, language codes are three characters -->
*{{error-small|&lt;{{var|code}}> not found in ISO 639-&lt;{{var|part}}> list}} – &lt;{{var|code}}> not found after searching ISO 639-&lt;{{var|part}}> data

The module that does the work for this template has other functionality not supported by this template.  See [[Module:ISO 639 name]].  Error messages related to that other functionality are:
*{{error-small|language name required}} – module function <code>iso_639_name_to_code()</code> only – this message emitted when a language name is not provided in the <code><nowiki>{{#invoke:}}</nowiki></code>
*{{error-small|&lt;{{var|part}}> not an ISO 639 part}} – module functions <code>iso_639_name_to_code()</code> and <code>iso_639()</code> only – this message emitted when &lt;{{var|part}}> is not one of 1, 2, 3, or 5
*{{error-small|language code or name required}} – module function <code>iso_639()</code> only – this message emitted when a language name or a language code is not provided in the <code><nowiki>{{#invoke:}}</nowiki></code>

== Tracking categories ==
* {{Category link with count|ISO 639 name template errors}}

== See also ==
* [[:Category:Lang-x templates]]
* [[:Category:Lang-x templates with other than ISO 639]]
* [[:Category:Articles containing non-English-language text]]
* {{tl|lang}}
* {{tl|mw lang}}
* {{tl|language with name}}
* {{tl|ISO 639 name link}}, [[Module:Template wrapper|wraps]] this template with param {{para|link|yes}} preset

<includeonly>{{Sandbox other||
[[Category:ISO 639 templates| ]]
[[Category:Language tag handling templates]]

}}</includeonly>