Newsletters/Translation

Translate this page

Newsletters are a way for Wikimedians to stay informed about specific topics they're interested in. Providing newsletters in languages other than just English widens your potential audience, as many Wikimedians don't understand English. Others can read English but still prefer to read news in their native language.

As of 2014, there are tools available that make preparing and delivering a multilingual newsletter relatively easy:

The Translate extension for structured translation of your newsletter's content;
The Assemble multilingual message Lua module to assemble all translations of a page into a text to be sent across wikis;
The MassMessage tool for easy global delivery of a message to a selection of pages (or subscribers) across Wikimedia wikis.

Most of the processes, tools and tips described on this page have been built and collected by the Tech News team. You can read their blog post for more details about how the technical newsletter is prepared, translated and delivered in multiple languages each week.

If you encounter difficulties setting up your multilingual newsletter, you can ask Guillaume for assistance.

Preparing and delivering multilingual newsletter: How it works

In short, this is how the process goes:

When your content is stable, tag it and mark it for translation, and reach out to Wikimedia translators to ask for their help.
When your translations are ready, use the Lua script to combine all your translations into a composite text.
Use the MassMessage tool to send that composite text to your subscribers. If a translation is available for a wiki's content language, the text will be posted in that language. Otherwise, it will be posted in the default language (English).

This page focuses on assembling and delivering the newsletter and its translations. For more information about page translation and the Translate extension, see:

Initial setup

There are a few things you need to do the first time you want to send a multilingual newsletter. You'll only have to do this once.

Import the Lua script on your source wiki

Many newsletters are prepared on Meta and can use Module:Assemble multilingual message directly.

If your newsletter and its translations are living on another wiki, you need to import Module:Assemble multilingual message into that wiki. It's best to use transwiki import from Meta to preserve attribution and the history.

Create a sandbox page

The sandbox page is where you'll use the Lua script to automatically assemble the translations. For example, Tech/News/Sandbox is where the multilingual version of Tech News is assembled. For the moment, simply create a page for your newsletter with boilerplate text (please avoid main namespace).

Regular process

The process that follows is the one you'll go through every time you send an issue of your newsletter. The process is very detailed to make it easier to get started; once you've done it a couple of times, you probably won't need it any more.

Mark the content of your newsletter

You probably have content on your page that you don't want to include in the newsletter you send. This typically includes headers, navigation templates and categories.

The Lua script uses Labeled section transclusion to identify the actual content you want to send. Choose a marker like my-nifty-newsletter and tag your content outside of the <translate></translate> tags like so:

<section begin="my-nifty-newsletter"/><translate>The content of your newsletter starts here.
...
The content of your newsletter continues here.
...
The content of your newsletter ends here.</translate><section end="my-nifty-newsletter"/>

This is something you need to add to each issue of your newsletter, but once you've added it once it's a simple matter of copy-paste to add it to the next one.

Generate the multilingual message

The Lua script pulls all translations together to assemble the multilingual newsletter, ready for delivery.

At this point, you should have:

the Lua script
the sandbox page
the translatable newsletter you want to distribute; in the example below, we'll call it "My nifty newsletter/2014/August"

The process goes like this:

Go to your sandbox page, and open the edit window.
Add the following code:
{{#invoke:Assemble multilingual message|assembleMessage|marker=|page=|}}.
- marker= is where you add the marker you used above to tag your content;
- page= is where you add the translatable page you want to send;
After the page, add the list of language codes of the languages in which your page has been translated. For instance, add |es|fr|uk if your page has been translated to Spanish, French and Ukrainian. Do not add "en" for the English version: as the default language, it is automatically included.
Your code should now be something like:
{{#invoke:Assemble multilingual message|assembleMessage|marker=my-nifty-newsletter|page=My nifty newsletter/2014/August|es|fr|uk}}.
Save your edit.

Voilà! This one line of code should now have generated a whole bunch of wikitext, that consists of a giant #switch parser function containing all the translations.

Send the multilingual message with MassMessage

The multilingual newsletter is delivered to subscribers across wikis by MassMessage; if a translation is available for the wiki's language, that translation is posted.

The Lua script does all the hard work: it goes through all the translations you give it, and assembles them together to generate a ready-to-send message:

On the sandbox page, copy the whole content generated by the script;
Open Special:MassMessage and paste the copied content into the field labeled "Body of the message"
Scroll to the bottom, and add links to your userpage/usertalkpage before the timestamp (~~~~~). (A 3-tilde or 4-tilde signature would just be signed by "MediaWiki message delivery".)
Fill out the other fields as you would do for a monolingual newsletter (see help about mass messages)

Known limitations

Lua script

You can't use tables for your newsletter's layout. Tables mess up the {{#switch used to select the appropriate language when the newsletter is posted. As a general rule, you should avoid tables and other complex formatting for newsletters, as they're easier to get wrong (see the general tips for newsletter authors).

Errors in one translation will break the assembled message when sent

If one of the translations has a markup error, such as an un-closed [[wikilink, it will break the assembled newsletter by showing all languages at once when you send it (to your test distribution list). To find the broken translation, add each language one at the time in the Assemble module.