Help:Autotranslate
This is about how to set up an automatically translated template using {{Autotranslate}} (see documentation there) and aims to explain the process more clearly and in more detail.
Why localise?
Wikimedia Commons is a multilingual project. Our goal is to provide a localized interface to any user from anywhere in the world.
When to use Autotranslate
If you want to translate a single word or phrase, use MediaWiki-messages or {{LangSwitch}}. If you want something more complex, Autotranslate is the right choice. See Commons:Localization for an overview of internationalisation/localisation.
What does Autotranslate do?
Autotranslate "calls", dependent on the user’s chosen interface language, a subpage of the template specified through the |base= parameter.
This means processing takes place at the server and only the contents of one sub-template are visible to the user.
It detects the user’s chosen language by looking up {{int:lang}}; for you, this evaluates to en, thus, Autotranslate would call the /en subpage for you, if it exists.
Drawbacks
Autotranslate stores different language translations on different template subpages.
This has one significant drawback: the template-subpages must be maintained separately to stay relevant and up-to-date.
Otherwise, users with different languages will see different instructions or different information.
This can lead to problems when users interact with each other.
Therefore, if users alter one version, they must either update all other versions or put a deprecation-note on all other subpage templates.
In practice it often happens that only the /en-subpage (English version) is updated; the coordination of translation updates remains a problem on Commons (this does not just apply to autotranslated templates…).
However, there is a solution now that makes sure that all translations are in sync: The Translate Extension.
Performance
As you can hopefully see in the diagram next to this text, more than 5 templates are involved. Autotranslate itself checks whether a page exists. This is classified as "expensive parser function". Nevertheless, one Autotranslate is better than 10 LangSwitches. When you see a raw {{Autotranslate}}, beware that too many heavy parser functions on one page will stop rendering templates.
Template loop detected!
"Template loop detected:Template:Autotranslate" You may notice this dreaded error message when using autotranslate. The reason is that when one template using autotranslate calls another template using autotranslate, it causes an {{Autotranslate}} loop. Since it uses another base there is no real problem and the error message itself is the only thing that's ruining your day. The solution: use {{#invoke:Autotranslate|autotranslate}} directly.
Required pages
Main template
Also known as the "front template" should look like
{{Autotranslate|base=Example|1={{{1|}}}|2={{{2|}}}}}<noinclude>
{{documentation}}
</noinclude>
- It’s very small
- When creating user talk templates, this is important to allow this template being subst:-ed.
- The
<noinclude>prevents other stuff from being shown when this template is used - The base-parameter is just the template’s name without namespace
- Then, numeric parameters follow (at least 10 are allowed). They will be forwarded to the translation subpages. Only numeric parameters are forwarded. But of course, you can convert a named parameter into a numeric one:
|1={{{namedParameter|}}} {{Documentation}}loads the/doc-subpage of the template and wraps a container around this so the background appears grey and there are some links (edit, view)- The categories are usually transcluded through the documentation. This allows administrators to protect the main template while allowing experienced users still to categorize the template through the
/doc-subpage (where they are added inside a<includeonly>-tag).
Language subpages: /en, /de, /fr, …
They will look like this:
{{Example/layout
|1={{{1|}}}
|2={{{2|}}}
|lang=en
|text1=This is an example text.
|text2=or just a phrase
}}<noinclude>
{{translated tag|insert type here - for types see [[Template:Translated tag]]}}
</noinclude>
- These sub pages are for translation, not for complicated operations
- Complicated transformations on the input parameters should be done in separate templates before the parameters are passed to the language sub page, thus on the main template using preprocessor-templates
- Nurse the translators and they will be thankful
- These templates must be always in sync with each other. Otherwise people using some languages will be misled.
- Always forward all parameters the subpage receives to the layout template
- Also pass the current "language-shortcut" (the subpage name, always hardcoded, don't use
{{SUBPAGENAME}}but you can use{{subst:SUBPAGENAME}}) - Don't add hardcoded links to these language-subpages. If all language subpages should share one link and it is not possible to port this to the /layout-subpage, create a new subpage of the template (e.g. Template:Example/link) and use the link this way:
Example text [[{{Example/link}}|with an example link]] in it because I don't like it foo bar.. If you have to change the link later, you don't have to edit tons of translations. - Don't try to use fallback texts like this:
{{{1|fallback text}}}This won't work because Autotranslate always passes all parameters, even if they are empty. You would have to rewrite the example to{{#if: {{{1|}}}|{{{1}}}|fallback text}}
Layout subpage: /layout
Here you can be creative. But you have to obey some basic rules:
- Use {{LayoutTemplateArgs}} to allow Ajax-in-page-translation of your template when clicking on a language-link. You must closely follow the instructions of {{LayoutTemplateArgs}}. The Ajax-script currently calls the language-subpages directly. This means you must set the parameter names to numbers because the subpage-template only accept numbers or you must ensure all language-subpages accept also named parameters.
- Wrap each image in a {{ImageNoteControl}}:
{{ImageNoteControl|notes=off|img=[[File:Example.jpg|60px]]}}. Otherwise vandals could add inappropriate image notes (and they like doing so). Consider upload-protecting the files that you choose to use. - Tables for layout purposes are deprecated because screen readers have serious difficulties understanding them. But sometimes it’s challenging to replace them.
Here is an example:
<div style="border:2px solid grey; width:99%; padding:5px; min-height:70px" class="layouttemplate">
{{LayoutTemplateArgs|template=Example|args=
{{urlencode: 1={{{1|}}} }}
{{urlencode: 2={{{2|}}} }}
{{urlencode: 3={{{3|}}} }}
}}
{{ImageNoteControl|notes=off|img=[[File:Example.jpg|60px|left]]}} Some text here.
----
{{Example/lang}}
</div>
Lang subpage: /lang
Good news: You don't have to care for this page. After everything else is done, create it with the only content {{subst:lle}}, which will automatically scan for all language subpages and adds links to those that exist.
In case you need customizations, external links e.g. through {{urlencode: … }} should be used for performance reason (in contrast to internal wikilink syntax).[r]
Documentation subpage: /doc
It’s a good idea using a pattern like
{{TemplateBox
|1=
|1d=
|1def=
|1stat=required
|2=
|2d=
|2def=
|2stat=required
|name=Example
|desc=
|namespace=
|usergroup=
|placement=
|usage-notes=
|type=
|example=
|i18n-method=autotranslate
|i18n-desc=
|seealso=
* [[Example]]
|setscats=
|lines=
|shorthand=
|relieson=
}}
<includeonly>
[[Category:Example templates]]
</includeonly>
- For more information, read {{TemplateBox}}
Using Extension:Translate
The Extension:Translate is currently in most cases the recommended system for autotranslation:
- First, make yourself familiar about how to mark a page for translation.
- The "skeleton" is the page which will be marked for translation (i.e. added to the Special:Translate system). It can't be the template page itself, which needs to only contain {{Autotranslate}}. Therefore, put the skeleton in a sub page, preferably /i18n. Translations will then be created (automatically) at /i18n/langcode.
- The skeleton can/should contain all the markup and untranslatable parts as well. The Translate system will automatically copy this wikitext to all subpages, but since the handling is automatic this duplication is not a problem. If you're adapting a template using the earlier autotranslate system, you can call the /layout template from the skeleton, but it’s not recommended.
- There is no need to list the translations manually, so remove any /lang subpage. The <languages/> tag could automatically list the available translations, but it’s not necessary.
- The main template must be adapted and will look like:
{{Autotranslate|base=Example/i18n|1={{{1|}}}|2={{{2|}}}}}<noinclude>
{{documentation}}
</noinclude>
- After you marked the /i18n subpage for translation or asked a translation administrator for help, a bot will automatically update all existing subpages that are translations. The first time a page version is marked for translation, the bot creates the /en subpage which will be used as the main fallback language by autotranslate. Changes at the /i18n subpage won't take effect at the template rendering until after the page is marked for translation.
- Use
ext.translateas the|i18n-method=in the documentation template. Be aware of the|i18n-sub-page=parameter, as if present, it could lead to an uncommon value (default isi18n, except you omit thenameparameter, and should not be changed). - The big advantage is that updating passed parameters to the layout template is now as easy as never before. Additionally, you get an overview over the translation progress and the translators do not have to mess with complicated template constructions. Finally, the main template can be fully protected; the translations are still editable and even the /i18n subpage.
- An example is at Special:PrefixIndex/Template:TemplateBox.