Template:Translatable content template/sandbox

{{ {{{page}}}/Content |1={{{key}}} |v1= |v2= |v3= }}

This is the template sandbox page for Template:Translatable content template (diff).

Template documentation

Translatable content template provides a way to design templates and other wikipages that have complex formatting so that the page remains easy to update after the content has been marked for translation through the translate extension.

Usage

TCT allows template designers to completely separate the words within a template from the rest of the markup. All the words in the template are stored in a separate /Content page, and called into the template by a unique key. This makes it easier for the non-linguistic content of a template to be updated like a normal wiki page, without having to mark the template for translation every time it is updated. If you use TCT, the content is still fully translatable, but you can change the layout of the template completely, and even remove/hide individual content units, without going through any of the steps described below.

When to use TCT

Templates with complex formatting: templates (and tables) that have lots of formatting--including standard wikimarkup, table markup, parser functions, and inline HTML and CSS.
Templates that are likely to be updated: templates that will likely be redesigned or tweaked in the future, but need to be available in multiple languages in the meantime.
Portal pages. If portal FOO transcludes multiple templates or sub-pages that are only used within that portal, the content of all of these templates can be placed in a single Foo/Content page. This allows translate admins to mark a single page for translation, saving them time and effort. For an example, see Grants:IdeaLab/Content, which contains the content of all templates transcluded in the Grants:IdeaLab main page.

The problems TCT addresses

Markup complexity

Templates present an especially challenging use case for translation. Templates often contain complex markup (like tables!), inline HTML and CSS, parser functions, magic words, and calls to other templates. This makes templates difficult to read to begin with. When you add <translate> tags and translation unit markers (like ) into the markup of a template, this creates additional noise, which makes it much more difficult to read and understand what the template is doing.

Code re-use

Marking a template for translation also makes it difficult to re-use the template code elsewhere, without manually stripping out all of this extra markup. Let's say you want to re-use code from an existing translated template as a basis for a new template you're designing. If you just paste the code from a translated template to another page, the new template will be marked for translation as soon as you hit 'save' the first time. To avoid this you have to manually strip out all the translate tags and unit markers manually, a time consuming task that is easy to mess up.

Updating the template

The biggest problem is when you want to update the template. Let's say you want to change the background color, or the wording. Due to known issues with the translate extension, if you make these changes on the template page, they won't show up on pages where the template is transcluded. In order to push these updates through transculsion, you have to go through one of the following workflows:

Case #1 (hard): I want to change markup or un-translated content outside of all <translate>tags:

edit the template page
go to any translation unit subpage in the source language (e.g. Translations:Template:Evaluation/Header/1/en)
make a null edit

Case #2 (harder): I want to change markup or translated content that is inside a <translate>tag:

edit the template page
go to the correct translation unit subpage in the source language
make the same change there, too
go to another translation unit subpage in the source language
make a null edit
if it was a significant content change (or a widely used template), alert translators to update the translations in other languages

Case #3 (hardest, requires administrator rights): I want to remove the contents of a translation unit entirely

delete the relevant translation unit subpage in the source language (or ask an admin to do it)
delete the relevant translation unit subpage in all other languages with translations (or ask admin)
go to another translation unit subpage in the source language
make a null edit
remove the relevant <translate> tags and translation unit comment from the template page. This must be done quickly, before FuzzyBot re-creates the translation unit subpage.

Example

This example shows how TCT works on a very simple translated template that you want to transclude on multiple pages. We'll call it Template:IEG_apply_banner.

« New for 2013 »

Apply for an Individual Engagement Grant

Without TCT: a designer has created a template as usual, and a translation admin has manually added the translate tags and translation unit markers into the template. Note that some non-linguistic content ("«") has accidentally been included between the translate tags.

Template page, with words and markup together

<noinclude>
<languages />
</noinclude>
{| style="text-align:center;"
|-
| style="background: #3366BB; font-size: 1.2em; padding: 0 1em 1em 1em; width: 25%; color:#FFFFFF" | <translate>« New for 2013 »</translate> 
[[Grants:IEG|'''<translate>Apply for an Individual Engagement Grant</translate>''']]
|}

With TCT: two pages are created: the template page, and a content page like Template:IEG_apply_banner/Content, which has been prepared for translation. The content page contains parameters for each chunk of text in the template. All the words in the template are transcluded by calling TCT and passing the path to the /Content page as the first parameter, and the key for the appropriate piece of text as the second parameter.

Template page (markup only)

{| style="text-align:center;"
|-
| style="background: #3366BB; font-size: 1.2em; padding: 0 1em 1em 1em; width: 25%; color:#FFFFFF" | « {{TCT|Grants:Start|ieg-new}} » 
[[Grants:IEG|'''{{TCT|Grants:Start|ieg-apply}}''']]
|}

Content page (words)

<noinclude>
<languages />
</noinclude>{{#switch:{{{1}}}
| ieg-new = <translate>
New for 2013</translate>
| ieg-apply = <translate>
Apply for an Individual Engagement Grant</translate>
| #default = {{{1}}}
}}

Advantages of TCT

1. For translate admins. The job of preparing the page for translation is easier because there is less markup noise around the text.

2. For translators. Since the template itself contains all the formatting (including non-linguistic characters), there's less chance that the translate admin will accidentally include non-linguistic characters within the tags. This makes translators' work easier, since they only ever see the words when they edit via the translation interface, never the surrounding markup.

3. For template maintainers.

The maintainer can change the design of the template (the color, or the font size) as easily as they can on any other wiki page, instead of going through the difficult Case #1 workflow above.
If the maintainer wants to remove a piece of text completely (like "New for 2013"), they just remove the call to that text in the template. In Scenario A, they would have to find a wiki administrator to hunt down and delete the translation unit subpage (Case #3 above).

4. For other users. This method also keeps your template free from additional markup, making it more readable and usable. People who want to re-use the template code for other purposes, or crib from the design, can just copy/paste and remove the TCT calls.

Modules

This also could be used in modules that replaces templates.

TemplateData

Translatable content template provides a way to design templates and other wikipages that have complex formatting so that the page remains easy to update after the content has been marked for translation through the translate extension.

Template parameters[Edit template data]
This template prefers inline formatting of parameters.
Parameter		Description	Type	Status
page	`1` `page`	no description	Page name	required
key	`2` `key`	no description	Line	required
uselang	`uselang`	no description	Unknown	optional
v1	`v1`	no description	Unknown	optional
v2	`v2`	no description	Unknown	optional
v3	`v3`	no description	Unknown	optional