Template:LangSwitch/doc: Difference between revisions

Latest revision as of 16:40, 6 September 2025

Uses Lua:

Module:LangSwitch

This template is used in system messages.

Changes to it can cause immediate changes to the Wikimedia user interface.
To avoid major disruption, any changes should be tested in the template's /sandbox or /testcases subpages, or in your own user subpage. The tested changes can be added to this page in a single edit. Please discuss changes on the talk page before implementing them.

Transclusion count: unknown

This subpage contains documentation, categories, or other content that is not part of the template.
To view the template page itself, see Template:LangSwitch.

العربية ∙ asturianu ∙ Boarisch ∙ беларуская (тарашкевіца) ∙ български ∙ বাংলা ∙ català ∙ čeština ∙ dansk ∙ Deutsch ∙ Zazaki ∙ Ελληνικά ∙ English ∙ Esperanto ∙ español ∙ eesti ∙ euskara ∙ فارسی ∙ suomi ∙ français ∙ galego ∙ עברית ∙ हिन्दी ∙ hrvatski ∙ magyar ∙ Bahasa Indonesia ∙ italiano ∙ 日本語 ∙ ქართული ∙ 한국어 ∙ кыргызча ∙ Lëtzebuergesch ∙ македонски ∙ മലയാളം ∙ ဘာသာမန် ∙ Bahasa Melayu ∙ Mirandés ∙ မြန်မာဘာသာ ∙ norsk bokmål ∙ Plattdüütsch ∙ Nederlands ∙ norsk ∙ polski ∙ português ∙ português do Brasil ∙ русский ∙ sicilianu ∙ Scots ∙ slovenščina ∙ српски / srpski ∙ svenska ∙ ไทย ∙ Türkçe ∙ українська ∙ اردو ∙ oʻzbekcha / ўзбекча ∙ Tiếng Việt ∙ 中文 ∙ 中文（简体） ∙ 中文（繁體） ∙ 中文（臺灣） ∙ +/−

Provides a method to present a string of text selected from an array of many language translations in the language set in the user's preferences or the most appropriate fallback language.

The template automatically sets the following categories: Category:Internationalization templates using LangSwitch

Usage

Warning: This template SHOULD NOT be used out of software interface purpose. For example it SHOULD NOT be used to manage multilingual description of the subject of a media or a category or whatsoever.

Template parameters

Parameter text is empty

TemplateData

TemplateData is a way to store information about template parameters (the description of those and of the whole template) for both humans and machines. It is used by VisualEditor and possibly other tools like Upload Wizard.

Existing template documentation
At Wikimedia Commons, it is recommended to use {{TemplateBox}} with either ‎useTemplateData=1 or ‎useTemplateData=only on the ‎/doc subpage and transcluding it with {{Documentation}} into the template. ‎<nowiki>-tags can be wrapped around the arguments, if required, to avoid templates being expanded.

Newly created template documentation and imports
Another option, especially for imported templates, or for users with JSON experience, is placing raw ‎<templatedata>-tags into the Wikitext of the template, as described in various Wikipediae.

Wikipedia's help about TemplateData • Commons-specific information

Provides a method to present a string of text selected from an array of many language translations in the language set in the user's preferences or the most appropriate fallback language.

Template parameters
This template prefers block formatting of parameters.
Parameter		Description	Type	Status
Default fallback	`default`	Default text to return in case none of the languages specified with the “xx=text” options match the language selected by the “lang=” option (or the language selected in user's preferences, if that option is not specified); by default, the English version (if provided in the “en=text” parameter) will be shown, otherwise a error message will be returned. Default {{{en\|}}} (English version)	String	suggested
English	`en`	Text in the English language. Unless the “default=” option is used, this text will also be returned by default if none of the languages provided match the language selected in the optional “lang=” option (or the language selected in the user's preferences, if that last option is not specified). If you do not want to show any text when the user's language is English, then use “en=~”.	String	required
Language code	`lang`	Language code (only needs to be provided if the language displayed is to be fixed and independent of the user’s preferences). Note that specifying “{{#if: {{{lang\|}}} \| {{{lang\|}}} \| {{Int:Lang}} }}” in this value is usually not necessary, unless one wants to override the default target language. Default Value of “{{Int:Lang}}” (the preferred language of the visitor viewing the page).	String	optional
No category?	`nocat`	“nocat=1” will overwrite the default behavior which tracks (in the “LangSwitch template without default version” category page) the incorrect uses of this template, where none of the two options “en=text in English” or “default=text by default” is specified with a non-empty value.	String	optional
Translation	`xx`	Text translated in language with code “xx” (the parameter name “xx” can be any supported language code, conforming to the BCP 47 or ISO 639-1 standards). Use “xx=~” if you do not want any text (not even the default text) in this specific language. You may also map multiple languages to the same text by using “{{LangSwitch \|xx/yy/zz=text }}”, which is equivalent to “{{LangSwitch \|xx=text \|yy=text \|zz=text }}”. You can specify as many such parameters as needed for each translated language.	String	optional

Additional information

The template is intended to be used in the following namespaces: no namespace specified

The template is intended to be used by the following user groups: all users

Relies on:
Module:LangSwitch

Localization

This template is not intended to be localized.

Help for choosing the right template for your use case:
I18n templates:	{{Multilingual description\|lang= \|de,en,default=Deutsch/English \|fr=français \|... }}	{{de\|Deutsch}} {{en\|English}} {{fr\|français}} ...	{{LangSwitch\|lang= \|de,en,default=Deutsch/English \|fr=français \|... }}	{{Autotranslate}}	{{tnt}}	Language-aware transclusion
Recommended use at	Categories, galleries	File description pages (deprecated, can be safely replaced by {{Multilingual description}})	Small templates, whenever the previous options are not suitable (removes the visual indication of the language before each translated text)	Data tables with translated cells or larger templates, when used on pages that do not have language subpages (e.g. not having `Main page/en`, `Main page/de`) and where the language displayed will be automatically determined by the language set in user preferences	Data tables with translated cells or larger templates, when used on pages that do have language subpages; most of the time these will be pages prepared with the Translate Extension	Data tables with translated cells or larger templates, when used on pages that do have language subpages; the transcluded page needs to be prepared with the Translate Extension, the transcluding page needs to be either prepared with the Translate Extension, or have the page language set by a translation administrator
Requires JavaScript enabled for folding	Yes		No
Folding can be disabled by user	Yes		No
Folding is done server-side	No		Yes
Folding when at least n languages are provided	1 (all translations are shown without folding if the preferred language selected by the user has no matching translation)	4	1
Detection of duplicate, incorrect, or unsupported language codes	Yes	No	Yes	Duplicate language codes are impossible by design. Incorrect or unsupported codes are never displayed, but not reported. The Translate extension's interface (if it's used on the translation subpages) doesn't let the user create translations with invalid codes, but other methods (e.g. entering the translation's URL directly) allow it without any warning.
Allows the same translation to be used for several languages	Yes	No	Yes
Supports language fallbacks	No		Yes		No
Collation order of languages (when not folded)	Consistent order by native language name, languages grouped by script: LTR scripts: Latin, Latin or Cyrillic, Cyrillic, Greek, other simple LTR alphabets (Armenian, Georgian, etc.), abugidas (North Indian, South Indian, other South-East Asian, etc.), syllabaries (European, American, African, Asian), Korean alphabets (basic Jamos, Hangul including some sinograms), Japanese syllabaries (including some sinograms), sinograms (including some syllabaries) RTL scripts: Hebrew, Arabic, other RTL abjads (Divehi, etc.), RTL syllabaries (N'ko)	As provided by the user in the wikitext (any inconsistent order may be difficult to lookup visually)	N/A
Search indexing issues	No (all translations are included on the same page, however search results may be less relevant with many languages mixed)		Yes (may not index all languages depending on search engines, unless there's a list of links for visiting other languages)	Partially (where used; language subpages of templates are indexed)	No (translated pages should include a `<languages/>` navigation bar for visiting other languages)
Page size issues	Yes (may exhaust size or time limits in the wiki parser if many languages are included; larger pages to download for all visitors; slower navigation for visitors with slow Internet access; may be costly for visitors with limited data plans)		No (only the content for the selected language or a suitable fallback language is present in the generated page)
Contains expensive parser functions	No			Yes, checks for several translations along the fallback chain until finds a suitable	Yes, 2–4 checks per call	No

Examples

Without a default option

Here are a few examples showing template behavior for three languages: English, Italian and Corsican (which defaults to Italian if Corsican text is not available):

Test	Code	lang=en	lang=it	lang=co
No en; default	{{LangSwitch\|it=Italian\|default=default}}	default	Italian	Italian
No en; no default	{{LangSwitch\|it=Italian\|co=Corsu}}	LangSwitch Error: no default^[1]	LangSwitch Error: no default^[1]	LangSwitch Error: no default^[1]
en; default	{{LangSwitch\|en=English\|co=Corsu\|default=default}}	English	default	Corsu
en; no default	{{LangSwitch\|en=English\|co=Corsu}}	English	English	Corsu
en; skip default	{{LangSwitch\|en=English\|co=Corsu\|default=~}}	English		Corsu
en; empty default	{{LangSwitch\|en=English\|co=Corsu\|default=}}	English	English	Corsu
Skip en; default	{{LangSwitch\|en=~\|it=Italian\|default=default}}		Italian	Italian
Skip en; no default	{{LangSwitch\|en=~\|it=Italian}}		Italian	Italian
Empty en; no default	{{LangSwitch\|en=\|it=Italian}}	LangSwitch Error: no default^[1]	Italian	LangSwitch Error: no default^[1]
en; default; skip it	{{LangSwitch\|en=English\|it=~\|co=Corsu\|default=default}}	English		Corsu
en; default; empty it	{{LangSwitch\|en=English\|it=\|co=Corsu\|default=default}}	English	default	Corsu
en; no default; skip it	{{LangSwitch\|en=English\|it=~\|co=Corsu}}	English		Corsu
Forced "lang=co"	{{LangSwitch\|en=English\|co=Corsu\|default=default\|lang=co}}	Corsu	Corsu	Corsu

Default option

The default option is intended for providing more language independent option. For example:

{{LangSwitch{{{sandbox|}}}
|de={{Wd|Warschau}}
|en={{W|Warsaw}}
|fr={{Wf|Varsovie}}
|ja={{W日|ワルシャワ}}
|pl={{WP|Warszawa}}
|ru={{Wr|Варшава}}
|default=[[d:Q270]]
}}

provides a link to Wikipedia articles in case one of the languages provided matches user's language but will link to Commons gallery page (Warsaw) if any other language is used.

The expression {{W|Q270||d}} is equivalent to the shorter [[d:Q270]] (it just does not show the “d:”).

Combination of multiple languages in the same option

“{{LangSwitch |de=Grün |es/it/pt=Verde |fr=Vert |en=Green |lang={{{lang|{{int:lang}}}}} }}” gives “Green” for the language with code en.

Note that several language codes (separated by /) are combined in the same parameter name, when these languages are mapped to the same output text (this helps simplifying usages).

However this combination still does not work correctly for the language code en if there’s no parameter default= or en= specified separately (when this occurs, this template still returns a usage error message^[1]).

Returning empty texts

“red{{LangSwitch |en=~ |default= ({{I18n/red}}) }}”,
“bleu{{LangSwitch |fr=~ |default= ({{I18n/blue}}) }}”, and
“orange{{LangSwitch |en/fr=~ |default= ({{I18n/orange}}) }}”

are respectively and conditionally appending parenthesized translations of

the standard English term “red” in (when the current user language is not standard English, or simple English, or any language where standard English is a predefined fallback),
the standard French term “bleu” (when the current user language is not standard French, or Cajun French, or any language where standard French is a predefined fallback), and
the standard English or French term “orange” (when the current user language is not standard French or English, or any language where standard French or English is a predefined fallback):

red	bleu (blue)	orange (blue)

Notes

↑ ^1.0 ^1.1 ^1.2 ^1.3 ^1.4 ^1.5 would add Category:LangSwitch template without default version

[c-1] 1.0 ^1.1 ^1.2 ^1.3 ^1.4 ^1.5 would add Category:LangSwitch template without default version

[1]

@@ Line 4: / Line 4: @@
 |name=LangSwitch{{{sandbox|}}}
+|desc-de=Bietet eine Methode zur Anzeige einer Textzeichenfolge, die aus einer Auswahl von Übersetzungen in verschiedenen Sprachen ausgewählt wurde, in der Sprache, die in den Benutzereinstellungen des Benutzers/in festgelegt ist, oder in der am besten geeigneten Ausweichsprache.
 |desc-en=Provides a method to present a string of text selected from an array of many language translations in the language set in the user's preferences or the most appropriate fallback language.
 |desc-fr=Permet de présenter un texte dans la langue de l’utilisateur, en sélectionnant depuis un ensemble de versions en différentes langues. La langue choisie est soit celle définie dans les préférences de l’utilisateur, soit la plus appropriée (déterminée par GetFallback).
@@ Line 12: / Line 13: @@
 |1=en
 |1label=English
+|1label-de=Englisch
+|1d-de=Text in englischer Sprache. Sofern nicht die Option „default=” verwendet wird, wird dieser Text standardmäßig auch dann zurückgegeben, wenn keine der angegebenen Sprachen mit der in der optionalen Option „lang=” Auswahl übereinstimmt (oder mit der in den Benutzereinstellungen ausgewählten Sprache, wenn diese Option nicht angegeben ist). Wenn Sie keinen Text anzeigen möchten, wenn die Sprache des Benutzers Englisch ist, verwenden Sie „en=~”.
 |1d-en=Text in the English language. Unless the “default=” option is used, this text will also be returned by default if none of the languages provided match the language selected in the optional “lang=” option (or the language selected in the user's preferences, if that last option is not specified). If you do not want to show any text when the user's language is English, then use “en=~”.
 |1d-fr=Le texte en anglais. À moins que l’option « default= » soit utilisée, ce texte sera également retournée si aucune des langues fournies ne correspond à la langue sélectionnée dans l’option facultative « lang= » (ou à la langue sélectionnée dans les préférences de l’utilisateur, si cette dernière option n’est pas indiquée). Si vous ne souhaitez retourner aucun texte lorsque la langue sélectionnée est l’anglais, utilisez « en=~ ».
@@ Line 21: / Line 24: @@
 |2=xx
 |2label=Translation
+|2label-de=Übersetzung
+|2d-de=Text übersetzt in die Sprache mit dem Code „xx“ (der Parametername „xx“ kann jeder unterstützter Sprachcode sein, der den Standards BCP 47 oder ISO 639-1 entspricht). Verwende „xx=~“, wenn du keinen Text (auch nicht den Standardtext) in dieser bestimmten Sprache haben möchtest. Du kannst auch mehrere Sprachen demselben Text zuordnen, indem du „<nowiki>{{LangSwitch |xx/yy/zz=text }}</nowiki>“ verwendest, was „<nowiki>{{LangSwitch |xx=text |yy=text |zz=text }}</nowiki>“ entspricht. Du kannst für jede übersetzte Sprache so viele Parameter wie nötig angeben.
 |2d-en=Text translated in language with code “xx” (the parameter name “xx” can be any supported language code, conforming to the BCP 47 or ISO 639-1 standards). Use “xx=~” if you do not want any text (not even the default text) in this specific language. You may also map multiple languages to the same text by using “<nowiki>{{LangSwitch |xx/yy/zz=text }}</nowiki>”, which is equivalent to “<nowiki>{{LangSwitch |xx=text |yy=text |zz=text }}</nowiki>”. You can specify as many such parameters as needed for each translated language.
 |2d-fr=Le texte traduit dans la langue de code « xx » (le nom du paramètre « xx » peut être n’importe quel code langue pris en charge, conforme au standard BCP 47 ou à la norme ISO 639-1). Utilisez « xx=~ » si vous ne voulez aucun texte (ni même le texte par défaut) dans cette langue spécifique. Vous pouvez également faire correspondre plusieurs langues au même texte en utilisant « <nowiki>{{LangSwitch |xx/yy/zz=texte }}</nowiki> », ce qui est équivalent à « <nowiki>{{LangSwitch |xx=texte |yy=texte |zz=texte }}</nowiki> » . Vous pouvez indiquer autant de paramètres similaires que nécessaire pour chaque langue de traduction.
@@ Line 31: / Line 36: @@
 |3=default
 |3label=Default fallback
+|3label-de=Standard-Fallback
+|3d-de=Standardtext, der angezeigt wird, wenn keine der mit den Optionen „xx=text“ angegebenen Sprachen mit der über die Option „lang=” ausgewählten Sprache übereinstimmt (oder mit der in den Präferenzen des Benutzers/in ausgewählten Sprache, wenn diese Option nicht angegeben ist); standardmäßig wird die englische Version (sofern im Parameter „en=text“ angegeben) angezeigt, andernfalls wird eine Fehlermeldung ausgegeben.
 |3d-en=Default text to return in case none of the languages specified with the “xx=text” options match the language selected by the “lang=” option (or the language selected in user's preferences, if that option is not specified); by default, the English version (if provided in the “en=text” parameter) will be shown, otherwise a error message will be returned.
 |3d-fr=Le texte par défaut à retourner au cas où aucune des langues indiquées par les options « xx=texte » ne correspond à la langue sélectionnée par l’option « lang= » (ou la langue sélectionnée dans les préférences de l’utilisateur, si cette option n’est pas indiquée) ; par défaut, la version anglaise (si elle est fournie dans le paramètre « en=texte ») sera affichée, sinon un message d’erreur sera retourné.
@@ Line 40: / Line 47: @@
 |4=lang
 |4label=Language code
+|4label-de=Sprachcode
 |4d={{Language-code-documentation}} Note that specifying “<nowiki>{{#if: {{{lang|}}} | {{{lang|}}} | {{Int:Lang}} }}</nowiki>” in this value is usually not necessary, unless one wants to override the default target language.
+|4d-de={{Language-code-documentation}} Beachte, dass die Angabe von „<nowiki>{{#if: {{{lang|}}} | {{{lang|}}} | {{Int:Lang}} }}</nowiki>” in diesem Wert normalerweise nicht nötig ist, es sei denn, man will die Standardzielsprache überschreiben.
+|4def-de=Wert von „<nowiki>{{Int:Lang}}</nowiki>“ (die bevorzugte Sprache von dir, der die Seite anschaut).
 |4def-en=Value of “<nowiki>{{Int:Lang}}</nowiki>” (the preferred language of the visitor viewing the page).
 |4def-fr=La valeur de « <nowiki>{{Int:Lang}}</nowiki> » (la langue préférée du visiteur visualisant la page).
@@ Line 49: / Line 59: @@
 |5=nocat
 |5label=No category?
+|5label-de=Keine Kategorie?
+|5d-de=“nocat=1” überschreibt das Standardverhalten, das (auf der Kategorie-Seite „LangSwitch-Vorlage ohne Standardversion“) die falschen Verwendungen dieser Vorlage verfolgt, wenn keine der beiden Optionen „en=Text auf Englisch“ oder „default=Text standardmäßig“ mit einem nicht leeren Wert angegeben ist.
 |5d-en=“nocat=1” will overwrite the default behavior which tracks (in the “LangSwitch template without default version” category page) the incorrect uses of this template, where none of the two options “en=text in English” or “default=text by default” is specified with a non-empty value.
 |5d-fr=« nocat=1 » permet d’empêcher le comportement par défaut qui trace (dans la page de catégorie « LangSwitch template without default version ») les usages incorrects de modèle, où aucune des deux options « en=texte en anglais » ou « default=texte par défaut » n’est spécifiée avec une valeur non vide.
@@ Line 57: / Line 69: @@
 |example=
 |usage-notes={{LangSwitch
+ |de='''Warning:''' Diese Vorlage '''SOLLTE NICHT''' außerhalb von Software-Interface verwendet werden. Sie '''SOLLTE'' zum Beispiel '''NICHT''' dazu benutzt werden, mehrsprachige Beschreibungen von Medien, Kategorien oder so weiter zu verwalten.
   |en='''Warning:''' This template '''SHOULD NOT''' be used out of software interface purpose. For example it '''SHOULD NOT''' be used to manage multilingual description of the subject of a media or a category or whatsoever.
   |fr='''Attention:''' Ce modèle '''NE DEVRAIT PAS''' être utilisé en dehors de la traduction de l'interface logicielle. Par exemple il ne '''DEVRAIT PAS''' être utilisé pour gérer les descriptions multilingues du sujet d'un média ou d'une catégorie.
@@ Line 172: / Line 185: @@
 |}
+{{LangSwitch
+|en=<nowiki />
 === Default option ===
 The default option is intended for providing more language independent option. For example:
+|de=<nowiki />
+=== Standardoption ===
+Die Standardoption ist dafür gedacht, mehr sprachunabhängige Optionen zu bieten. Zum Beispiel:}}
+<syntaxhighlight lang="wikitext" copy>
+{{LangSwitch{{{sandbox|}}}
+|de={{Wd|Warschau}}
+|en={{W|Warsaw}}
+|fr={{Wf|Varsovie}}
+|ja={{W日|ワルシャワ}}
+|pl={{WP|Warszawa}}
+|ru={{Wr|Варшава}}
+|default=[[d:Q270]]
+}}
+</syntaxhighlight>
+{{LangSwitch
+|en=provides a link to Wikipedia articles in case one of the languages provided matches user's language but will link to Commons gallery page ([[Warsaw]]) if any other language is used.
-<blockquote style="border:1px solid #AAA;background:#FFF;color:#222;padding:2px .3em">
+The expression <code><nowiki>{{W|Q270||d}}</nowiki></code> is equivalent to the shorter <code><nowiki>[[d:Q270]]</nowiki></code> (it just does not show the “d:”).
-<nowiki>{{LangSwitch</nowiki>{{{sandbox|}}}<br />
+|de=bietet einen Link zu Wikipedia-Artikeln, falls eine der angebotenen Sprachen mit der Sprache des Benutzers übereinstimmt, verlinkt aber auf die Commons-Galerie-Seite ([[Warsaw]]), wenn eine andere Sprache verwendet wird.
-<nowiki>|de={{Wd|Warschau}}</nowiki><br />
-<nowiki>|en={{W|Warsaw}}</nowiki><br />
-<nowiki>|fr={{Wf|Varsovie}}</nowiki><br />
-<nowiki>|ja={{W日|ワルシャワ}}</nowiki><br />
-<nowiki>|pl={{WP|Warszawa}}</nowiki><br />
-<nowiki>|ru={{Wr|Варшава}}</nowiki><br />
-<nowiki>|default=[[d:Q270]]</nowiki><br />
-<nowiki>}}</nowiki>
-</blockquote>
-provides a link to Wikipedia articles in case one of the languages provided matches user's language but will link to Commons gallery page ([[Warsaw]]) if any other language is used.
+Der Ausdruck <code><nowiki>{{W|Q270||d}}</nowiki></code> ist gleichbedeutend mit dem kürzeren <code><nowiki>[[d:Q270]]</nowiki></code> (nur das „d:” wird nicht angezeigt).
-The expression <code><nowiki>{{W|Q270||d}}</nowiki></code> is equivalent to the shorter <code><nowiki>[[d:Q270]]</nowiki></code> (it just does not show the “d:”).
+}}
 === Combination of multiple languages in the same option ===