Manual:API de mensajes

Los mensajes de MediaWiki se pueden utilizar en el código mediante la clase Message y sus métodos asociados.

Parámetros de los mensajes

Algunos mensajes toman parámetros. Estos se representan como $1, $2, $3, … en los textos (estáticos) del mensaje y se reemplazan por su valor en tiempo de ejecución. Los valores típicos para los parámetros son números (el «3» en «¿Deseas eliminar 3 versiones?»), nombres de usuario (el «Fulano» en «Página editada por última vez por Fulano»), nombres de páginas, enlaces, etc., o en ocasiones otros mensajes. Pueden presentar una complejidad arbitraria.

La lista de parámetros definidos para cada mensaje concreto se guarda en el archivo especial «qqq.json» ubicado en la carpeta «languages/» de MediaWiki - consulta la Documentación de mensajes para más información.

Es preferible utilizar palabras completas con las palabras mágicas PLURAL, GENDER (género) y GRAMMAR (gramática). Por ejemplo, es mejor {{PLURAL:$1|subpágina|subpáginas}} que sub{{PLURAL:$1|página|páginas}}. Facilita las búsquedas.

Hacer referencia a otros mensajes

A veces es conveniente hacer referencia a submensajes dentro de un mensaje, por ejemplo, en frases como «Usa el botón X» o «Visita la página Y», para asegurar que las traducciones sean consistentes. Para ello, puedes utilizar la siguiente sintaxis:

• {{int:X}} - para usar el submensaje en el idioma de la interfaz. Esto se usa habitualmente para hacer referencia a los botones de los formularios o a la navegación del sitio, por ejemplo, showpreview.
• {{MediaWiki:Y}} - para usar el submensaje en el idioma del contenido. Esto se usa habitualmente cuando el submensaje define un nombre traducible de página local, por ejemplo, mainpage, grouppage-sysop o policy-url.
• {{#Special:Z}} - para usar el nombre de una página especial en el idioma del contenido.

Si necesitas algo más complejo (por ejemplo, si el submensaje utilizado depende de la configuración), analízalo en tu código y pasa el submensaje entero como un parámetro.

Ejemplo:

Before saving, use the {{int:foo-test}} button to test the changes. Visit [[{{MediaWiki:foo-help}}|the help page]] to learn more.Customize this feature at [[{{#Special:Preferences}}]].

Selectores en los mensajes…

En ocasiones, los valores de los parámetros influyen en la expresión exacta o en las variaciones gramaticales en los mensajes. No recurrimos a constructos feos como «$1 (sub)page(s) of his/her userpage» porque resultan mediocres para los usuarios y podemos hacer las cosas mejor. En lugar de ello, creamos selectores que se ejecutarán en función de los valores que se conocerán en tiempo de ejecución. Entonces, el texto estático del mensaje suministra cada una de las opciones posibles en una lista, precedida por el nombre del selector y una referencia al valor que distingue los casos. Esto se asemeja a la forma en que se llama a las $2 en MediaWiki. Se dispone de varios tipos de selectores. Sin embargo, sólo funcionan si haces un análisis sintáctico completo, o transformación de los {{, de los mensajes.

…en números mediante PLURAL

MediaWiki tiene en cuenta los plurales, lo que proporciona un mayor atractivo al producto. Por ejemplo:

'undelete_short' => 'Undelete {{PLURAL:$1|one edit|$1 edits}}',

Si existe una forma plural para un número específico, se puede utilizar la siguiente sintaxis:

'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.'

Atención con el uso de PLURAL en todos los números

Véase también: translatewiki:Plural

A la hora de introducir un número en el texto de un mensaje, ten en cuenta que algunos idiomas tendrán que usar PLURAL aunque ese número siempre vaya a ser mayor que 1. El motivo es que en distintos idiomas pueden crearse distinciones muy diversas y complejas, como ocurre en español con 1.^er, 1.ª, 1.^os, 1.^as, 2.º, 2.ª, …, 3.^er, 3.ª, …, etc.

No trates de proporcionar tres mensajes distintos para casos como «ningún elemento», «un elemento» y «varios elementos». En lugar de eso, utiliza un solo mensaje para cubrir todos los casos y deja a los traductores y a PLURAL la tarea de tratar adecuadamente cualquier diferencia de presentación en los distintos idiomas.

Si es posible, incluye siempre el número como parámetro. Añade siempre la sintaxis {{PLURAL:}} a los mensajes de origen siempre que sea posible, incluso aunque no tenga sentido en inglés (o en el idioma de origen, en general). La sintaxis guía a los traductores.

Se admiten números fraccionarios, aunque puede que las reglas para formar los plurales no estén completas.

Pasar el número de elementos de una lista como parámetro para mensajes que hacen referencia a la lista

No asumas que sólo existe el singular y el plural. Muchos idiomas cuentan con más de dos formas que pueden depender del propio número utilizar, y tienen que utilizar formas gramaticales que dependen del número de elementos de una lista para expresar qué contiene en una lista visible para los lectores. Por tanto, cuando tu código compute una lista, incluye count( $list ) como parámetro en cabeceras, entradas, pies de página y otros mensajes que hagan referencia a la lista, incluso aunque no se use el recuento en inglés. Existe una forma neutral de hablar sobre listas invisibles, de forma que puedes incluir enlaces a listas en páginas adicionales sin tener que contar los elementos de antemano.

…en nombres de usuario mediante GENDER

'foobar-edit-review' => 'Please review {{GENDER:$1|his|her|their}} edits.'

Si vas a referirte a un usuario en un mensaje, pasa al mensaje el nombre de usuario como parámetro y menciona en la documentación del mensaje que este tiene en cuenta el género. Si es probable que se vaya a usar GENDER en traducciones a idiomas con flexiones de género, añádelo de forma explícita a los mensajes de origen en inglés.

Si te diriges directamente al usuario actualmente conectado, deja vacío el parámetro del nombre de usuario:

'foobar-logged-in-user' => 'You said {{GENDER:|you were male|you were female|nothing about your gender}}.'

Versión de MediaWiki:

≥ 1.31 Gerrit change 398772

En caso de incluir el nombre del usuario en el mensaje (por ejemplo, «$1 te lo agradeció.»), considera pasarlo primero a través de wfEscapeWikitext() para asegurar que no se interpreten caracteres tales como * o ;.

Los usuarios tienen género gramatical

Véase también: translatewiki:Gender

Cuando un mensaje habla, se refiere o se dirige a un usuario, se debe pasar al mensaje el nombre de usuario como parámetro. Así, los idiomas que deban o quieran utilizar construcciones gramaticales que dependan del género podrán hacerlo. Esto debe hacerse aun cuando el nombre de usuario no vaya a aparecer en el mensaje, por ejemplo, «informar al usuario/a en su página de discusión», que se puede reformular mejor como «informar al usuario en su página de discusión».

Esto no significa que debas «sexualizar» el lenguaje de los mensajes: es preferible utilizar fórmulas neutras siempre que se pueda preservar así la claridad y la precisión.

…según el contexto de las frases mediante GRAMMAR

También se pueden utilizar transformaciones gramaticales para lenguas aglutinantes (Q171263). Por ejemplo, en finés, donde es absolutamente necesario para que los archivos de idioma sean independientes del sitio, es decir, para poder retirar las referencias a Wikipedia. En finés, «about Wikipedia» se traduce como «Tietoja Wikipediasta» y «you can upload it to Wikipedia» se traduce como «Voit tallentaa tiedoston Wikipediaan». Dependiendo de la función gramatical de la palabra, se le añaden sufijos, además de hacerse modificaciones menores en la raíz. Hay una larga lista de excepciones, pero como sólo hace falta traducir unas pocas palabras, como por ejemplo el nombre del sitio, no es necesario incluirla.

MediaWiki cuenta con funciones de transformación gramatical para más de 20 idiomas. Algunas de ellas no son más que diccionarios de nombres de sitios de Wikimedia, pero otros tienen algoritmos simples que fallarán en todos los casos excepto en los más comunes.

Incluso antes de que MediaWiki aceptara transformaciones gramaticales arbitrarias, contaba con distinciones entre nominativo y genitivo para los nombres de los meses. Esta distinción es necesaria en algunos idiomas si deseas sustituir nombres de meses en las frases.

Filtrar caracteres especiales en parámetros y mensajes

El otro problema (mucho más simple) de la sustitución de parámetros es el escapado HTML. A pesar de ser mucho más simple, MediaWiki lo hace de forma bastante deficiente.

Utilizar mensajes en PHP

Advertencia:

Asegúrate de utilizar siempre uno de los modos de salida mencionados a continuación

He aquí un ejemplo sencillo:

$out = Xml::submitButton( wfMessage( 'submit' )->text() );

wfMessage() es una función global que actúa como un envoltorio para la clase Message y que permite crear un objeto Message. Este ejemplo entonces inoca el método text() de Message que recoge el texto del mensaje 'submit' en el idioma actual, realiza ciertas transformaciones idiomáticas (como el género y el plural) y devuelve el texto del mensaje sin escapar.

He aquí un ejemplo más complejo donde el mensaje hace un recuento y asume el manejo del plural lingüístico.

$out = Xml::label( wfMessage( 'numberofpages' )->numParams( $count )->text() );

Las siguientes secciones explican el código.

Parámetros

Dado un mensaje como el siguiente:

{
    "msg": "Values are $1, $2"
}

Puedes pasar parámetros a los mensajes que los necesitan de varias maneras:

wfMessage( 'msg', 'param1', 'param2' )->plain();
wfMessage( 'msg' )->params( 'param1', 'param2' )->plain();
wfMessage( 'msg', [ 'param1', 'param2' ] )->plain();

La primera opción es la más habitual; utiliza la segunda cuando vayas a mezclar distintos tipos de parámetros y la tercera para construir objetos Message de forma dinámica a partir de otros datos. Existen distintos tipos de parámetros:

wfMessage( 'msg' )->params( $username )->plain();
wfMessage( 'msg' )->rawParams( $link )->plain();
wfMessage( 'msg' )->plaintextParams( $userInput )->plain();

wfMessage( 'msg' )->numParams( $count )->plain();
wfMessage( 'msg' )->durationParams( $duration )->plain(); // MediaWiki 1.22+
wfMessage( 'msg' )->expiryParams( $expiry )->plain(); // MediaWiki 1.22+
wfMessage( 'msg' )->timeperiodParams( $period )->plain(); // MediaWiki 1.22+
wfMessage( 'msg' )->sizeParams( $size )->plain(); // MediaWiki 1.22+
wfMessage( 'msg' )->bitrateParams( $bitrate )->plain(); // MediaWiki 1.22+

params()

Sustitución normal de los parámetros de un mensaje.

rawParams()

Sustituye el parámetro después de que se haya procesado el mensaje por otra vía; esto significa que estos parámetros no están disponibles para las funciones del analizador, y que tampoco se pueden escapar si se usa el modo de salida escapado (véase a continuación). Asegúrate de escaparlos adecuadamente por tu cuenta.

plaintextParams()

Como rawParams(), pero realiza el escape. Es útil para pasar la entrada del usuario que puede contener wikitexto que no se desea analizar.

Cada una de las funciones del segundo grupo formatea el valor de una manera particular antes de la sustitución. Se debe utilizar numParams() si el mensaje utiliza {{PLURAL:}}. En algunos casos, puede que no desees utilizarlo incluso aunque tengas un número, por ejemplo, un identificador de revisión. Las demás funciones corresponden a funciones del lenguaje formatDuration, formatExpiry, formatTimePeriod, formatSize y formatBitrate, y no son más que formas abreviadas para llamarlas directamente.

Idioma

Para redefinir el idioma en el que deseas el mensaje, existe un método y un atajo para el caso somún de utilizar el idioma del contenido del wiki. En el último caso, puedes utilizar un código de idioma o un objeto de idioma. Se aplican las cadenas habituales de idiomas de respaldo, por lo que el mensaje que recibas podrá estar en un idioma distinto del solicitado en caso de que no exista la traducción a este.

wfMessage( 'message-key' )->inContentLanguage();
wfMessage( 'message-key' )->inLanguage( $lang );

Modos de salida y escapado

La clase Message, y por tanto el objeto devuelto por wfMessage(), tiene cinco modos de salida:

• plain() - devuelve el mensaje tal como está; sólo se sustituyen los parámetros
• text() - transforma el texto del mensaje (véase MessageCache::transform()) cambiando todos los {{}} incluyendo las plantillas y las funciones del analizador sintáctico como PLURAL y GENDER, pero ni escapa ni limpia (sanitiza)
• escaped() - igual que 'text', pero también lo escapa para su uso en HTML
• parse() - analiza el wikicódigo del texto del mensaje para devolver HTML y lo limpia (MessageCache::parse(), que llama al analizador)
• parseAsBlock() - la salida queda envuelta en un elemento HTML a nivel de bloque si no lo estaba ya, de forma similar a OutputPage::addWikiMsg

Recuerda que las funciones Html:: escapan todo lo que se les introduzca, y por tanto utiliza el formato text() para evitar escapar dos veces. Por lo tanto, el formato de salida más común es text(). Además, asegúrate de usar parse() o parseAsBlock() si el mensaje contiene wikitexto, de otra manera, se escapará el wikitexto y se devolverá en forma de texto plano.

Al usar wfMessage() o $this->msg(), debes especificar siempre un tipo de salida. text() es adecuado cuando lo estás haciendo salir a través de addWikiText().

Qué modo de salida usar

En general, los modos que utilizarás en la mayoría de los casos son ->parse() y ->text(). Utiliza ->parse() en la mayoría de los casos donde haya soporte para el marcado HTML, y ->text() si no hay tal soporte o si el contenido se va a escapar a HTML.

Algunos casos comunes:

• Si pasas el mensaje en la parte de texto (tercer argumento) de Html::element, usa ->text(). Alternativamente, también puedes usar Html::rawElement() con el modo ->parse().
• Si pasas el texto (tercer argumento) de Html::rawElement(), deberías usar generalmente ->parse().
• Si pasas los atributos (segundo argumento) de Html::rawElement() o Html::element(), usa ->parse().
• Si estás construyendo a mano los atributos HTML, deberías usar ->escaped(). Sin embargo, nunca deberías construir atributos HTML a mano.
• Para $out->addWikiText() donde $out es un objeto OutputPage, usa ->text() o ->plain(). Sin embargo, considera usar en su lugar $out->addWikiMsg.
• Para $out->addHTML(), usa ->parse().

Encadenamiento de métodos

La mayoría de los métodos de Message devuelven el objeto actual, de modo que puedes llamar fácilmente a uno tras otro para operar sobre un objeto antes de devolver su texto al final. Esto se denomina encadenamiento de métodos. He aquí un ejemplo:

wfMessage( 'key' )
	->params( 'apple' )
	->numParams( $numOfApples )
	->setContext( $context )
	->inContentLanguage()
	->parse()

Métodos adicionales para imprimir mensajes

La función general para mensajes de MediaWiki es wfMessage. Sin embargo, dado que en un mensaje el valor de las palabras mágicas puede depender del contexto, existir diversos envoltorios para esta función que establecen automáticamente el contexto correcto.

OutputPage cuenta con algunos métodos que permiten concatenar directamente a la salida generada. Los métodos útiles son:

$out->addWikiMsg( 'pageheader' );
$out->wrapWikiMsg( '<div class="error">\n$1\n</div>', [ 'someerrormessage', $user->getName() ] );

Los dos anteriores analizan el wikitexto en el contexto de la página actual antes de concatenarla al búfer de salida.

Las clases que extienden ContextSource tienen un método msg que establece automáticamente el contexto actual (idioma, página actual, etc.). Se recomienda por tanto usar $this->msg() para estas clases, como con las páginas especiales. He aquí una lista no exhaustiva de estas clases:

• CategoryViewer
• HTMLForm
• LogEventsList
• DifferenceEngine
• OutputPage
• IndexPager
• ImageHistoryList
• ApiBase
• ChangesList
• Skin

Advertencia:

La clase QuickTemplate y sus subclases (BaseTemplate) tienen un método msg diferente del de ContextSource. En estas clases, $this->msg() producirá el texto escapado del mensaje sin más.

Ejemplos de uso correcto:

wfMessage( 'key' )->numParams( 567 )->text();
$this->msg( 'key' )->numParams( 567 )->parse();

Ejemplos de uso incorrecto:

wfMessage( 'key', 345 )->parseInline(); # El número no está formateado correctamente
$this->msg( 'key', 345 )->numParams( 234 )->plain() # La sintaxis del plural no se convierte en formato plano

Utilizar mensajes en JavaScript

Véase también: ResourceLoader/Core modules#mediaWiki.message

Esta página sólo tiene en cuenta el núcleo de MediaWiki. Para el módulo jquery.i18n, véase la documentación específica.

Obtener los mensajes para el cliente

Para usar los mensajes, debemos asegurarnos primero de que están disponibles en el lado del cliente. Esto se puede hacer ya sea mediante un módulo ResourceLoader (caso más habitual) o una consuta a la API desde JavaScript (más raro).

Utilizar un módulo ResourceLoader

Véase también: Manual:$wgResourceModules

Este es el método más común para transmitir mensajes. Es recomendable utilizar este método a menos que tengas una buena razón para no hacerlo.

Vamos a utilizar ResourceLoader para verificar que los mensajes están disponibles en el lado del cliente. Para ello, en tus módulos ResourceLoader, define los mensajes para exportar al lado del cliente.

Si pretendes utilizar mw.message(…).parse() para generar el HTML a partir del wikitexto en mensajes de la interfaz, es importante cargar el módulo mediawiki.jqueryMsg.

Ejemplo (extension.json):

{
	"ResourceModules": {
		"ext.abuseFilter.edit": {
			"scripts": "ext.abuseFilter.edit.js",
			"messages": [
				"abusefilter-edit-syntaxok",
				"abusefilter-edit-syntaxerr",
				"abusefilter-http-error",
				"abusefilter-edit-throttle-placeholder",
				"abusefilter-edit-tag-placeholder",
				"abusefilter-edit-warn-leave",
				"unknown-error",
				"jan",
				"feb",
				"mar"
			],
			"dependencies": [
				"mediawiki.util",
				"mediawiki.api",
				"mediawiki.confirmCloseWindow",
				"jquery.textSelection",
				"jquery.spinner",
				"oojs-ui-core",
				"oojs-ui-widgets"
			]
		}
	}
}

Utilizar una consulta a la API desde JavaScript

Esta no es una forma muy común de cargar mensajes. Sólo deberías hacer esto si hay una buena razón para no usar el módulo ResourceLoader mencionado anteriormente.

Puedes utilizar el siguiente código:

Versión de MediaWiki:

≥ 1.27

// Cuando: El módulo 'mediawiki.api' esté cargado y la página esté lista
$.when( mw.loader.using( [ 'mediawiki.api', 'mediawiki.jqueryMsg' ] ), $.ready )
    // Entonces: Carga los mensajes que necesites (si aún no están cargados)
    .then( function() {
        return new mw.Api().loadMessagesIfMissing( [ 'january', 'february', 'march' ] );
    } )
    // Entonces: Haz lo que tengas que hacer
    .then( doStuff );

Para obtener los mensajes en un idioma distinto de UserLanguage, utiliza getMessages en lugar de loadMessagesIfMissing e indica el idioma deseado en el campo «amlang» del segundo parámetro opcional, así:

// Cuando: El módulo 'mediawiki.api' esté cargado. No es necesario esperar a que la página esté lista.
$.when( mw.loader.using( [ 'mediawiki.api' ] ) )
    // Entonces: Obtén algunos mensajes en French (código de idioma 'fr')
    .then( function() {
        return new mw.Api().getMessages( [ 'january', 'february', 'march' ], { amlang: 'fr' }  );
    } )
    // Entonces: Haz lo que tengas que hacer
    .then( doStuff );
// doStuff es una función que recibirá como primer parámetro un objeto similar a:
// { february: "février", january: "janvier", march: "mars" }

Utilización de los mensajes

Los mensajes definidos en los ejemplos anteriores estarán disponibles en el lado del cliente y serán accesibles para mw.message( 'message-key-name' ).

Por ejemplo:

$( '<div>' ).text( mw.message( 'translate-msggroupselector-projects' ).text() );

Observa cómo se ha utilizado el método text de jQuery para escapar la salida adecuadamente al utilizar el formato text de mw.message.

Si tu mensaje contiene wikitexto formateado, puedes utilizar lo siguiente:

$( '<div>' ).append( mw.message( 'translate-msggroupselector-projects' ).parseDom() );

Aquí se ha utilizado el método append de jQuery para insertar en el DOM los nodos devueltos por el formato parseDom de mw.message.

En un código más antiguo, también puedes encontrar lo siguiente (parseDom no estaba disponible antes de MediaWiki 1.27)

$( '<div>' ).html( mw.message( 'translate-msggroupselector-projects' ).escaped() );
$( '<div>' ).html( mw.message( 'translate-msggroupselector-projects' ).parse() );

Existen otras combinaciones correctas, pero, siempre que sea posible, ajústate a los patrones anteriores para evitar vulnerabilidades XSS y haz que tu código sea fácil de entender para los demás.

También se pueden pasar los parámetros dinámicos al mensaje (es decir, los valores de $1, $2, etc.) como se muestra a continuación.

$( '<div>' ).text( mw.message( 'hello-user', username ).text() );

En los ejemplos anteriores, observa que el mensaje debería estar definido en un archivo de i18n (internacionalización). Si la clave del mensaje no se encuentra en ningún archivo de i18n, el resultado será la clave del mensaje entre corchetes angulares curvos U+29FC/U+29FD (parte de los símbolos matemáticos), como '⧼message-key-foo⧽'. En versiones anteriores de MediaWiki, la clave del mensaje se devolvía entre corchetes angulares, como '<message-key-foo>', lo que podía generar elementos HTML falsos o inválidos. En caso en que la clave del mensaje no exista, el método .exists() del objeto de mensaje devuelto también devolverá false en lugar de true.

Para utilizar un mensaje que no deba pasar por el analizador (por ejemplo, al pasar datos JSON como mensajes, o cuando el mensaje se vaya a utilizar como texto precargado de una página), utiliza:

mw.message( 'foobar' ).plain()

Opciones de formato

Si no especificas el formato de la salida, mw.message sólo devolverá un objeto Message. Para devolver el propio mensaje, deberías especificar un formato de salida. Los formatos son generalmente los mismos que en el lado PHP:

• mw.message( 'foobar' ).plain() Devuelve el texto del mensaje tal como está; sólo se sustituyen los parámetros.
• mw.message( 'foobar' ).text() Transforma el texto del mensaje (todos los bloques {{}} compatibles se reemplazan por resultados transformados). Consulta #Soporte de funcionalidades en JavaScript para más información al respecto. Por ejemplo, ciertas palabras clave ({{int:}} (pero sólo sin parámetros), {{GENDER}}, {{SITENAME}}, etc.) funcionan, pero la transclusión (por ejemplo, {{MediaWiki:}}) y las palabras mágicas del lado del servidor tales como {{NUMBEROFEDITS}} o {{ns:Project}} no funcionan,
• mw.message( 'foobar' ).escaped() Versión HTML-escapada de text.
• mw.message( 'foobar' ).parse() Analiza el texto del mensaje de wikitexto a HTML. Esto admite todo desde el modo text, así como la mayoría de los enlaces y las listas HTML.
• mw.message( 'foobar' ).parseDom() Como parse(), pero devuelve una colección jQuery en lugar de una cadena HTML.

Advertencia:

Si el módulo mediawiki.jqueryMsg no está cargado, todos los métodos anteriores se comportan esencialmente como plain() con un posible escapado.

No hay equivalente de parseAsBlock. Donde sea necesario, envuelve por tu cuenta la salida en un elemento de bloque.

Parámetros

Se pueden especificar los parámetros como argumentos adicionales de mw.message(). Se pueden pasar como cadenas o como nodos del DOM o colecciones jQuery.

Al contrario que en PHP, no se analiza el wikitexto contenido en los parámetros. En efecto, todos los parámetros de tipo cadena se comportan como plaintextParams().

Se pueden utilizar parámetros DOM/jQuery para conseguir un efecto equivalente a rawParams().

No hay soporte para otros formatos de parámetros. En lugar de numParams(), tienes que formatear los números mediante mw.language.convertNumber() antes de pasarlos como parámetros.

$( '<div>' ).text( mw.message( 'translate-msggroupselector-view-subprojects', mw.language.convertNumber( count ) ).text() );

Soporte de funcionalidades en JavaScript

Advertencia:

El soporte de wikitexto en los mensajes JS requiere que se haya cargado el módulo mediawiki.jqueryMsg; de otro modo, estas funcionalidades se ignorarán sin avisar.

Los mensajes JavaScript sólo soportan un pequeño subconjunto de la sintaxis de wikicódigo. Las funcionalidades compatibles comprenden:

• Los enlaces internos (excepto los que usen el truco de tubería)
• Los enlaces externos explícitos (no autonumerados ni enlaces libres)
• Las palabras mágicas SITENAME, PAGENAME, PAGENAMEE; SERVERNAME (desde MW 1.38); CONTENTLANGUAGE (desde MW 1.43)
• Las funciones de analizador PLURAL, GENDER, GRAMMAR, int, ns, formatnum, lc, uc, lcfirst, ucfirst; fullurl (desde MW 1.44)
• Las etiquetas HTML admitidas en el wikitexto (el HTML debe estar bien formado)
• Las entidades HTML ', ", <, > y &
• La etiqueta ‎<nowiki>

Sintaxis de wikitexto notable que no tiene soporte:

• Las plantillas
• Los enlaces interwiki no locales
• Todas las demás funciones del analizador y palabras mágicas
• Los módulos (por ejemplo, Módulo:String)
• Todas las demás etiquetas de tipo XML (etiquetas de extensiones)
• Las marcas de negrita y cursiva ''' y '' (utiliza en su lugar ‎<b> y ‎<i>)
• Las listas que utilizan * y # (utiliza en su lugar ‎<ul> o ‎<ol>, junto con ‎<li>)
• Las listas de definiciones e indentaciones que utilizan ; y : (utiliza en su lugar ‎<dl>, ‎<dt> y ‎<dd>)
• Los párrafos múltiples (usa en su lugar ‎<p>)
• Las etiquetas HTML autocerradas
• Los comentarios <!-- -->
• Algunos tipos de anidación (por ejemplo, {{PLURAL:$1|<strong>$1</strong>}})

Se puede utilizar la plantilla doc-jqueryMsg para documentar estos mensajes y así permitir a los traductores saber qué restricciones se aplican al wikicódigo.

mw.msg

La función mw.msg() se utiliza habitualmente como atajo para mw.message().text().

Exportar mensajes mediante retrollamadas (callbacks) de ResourceLoader

Si necesitas procesar un mensaje en el servidor y enviar el resultado al cliente (por ejemplo, porque necesitas analizar el mensaje utilizando funcionalidades sin soporte en JS), puedes hacerlo mediante una retrollamada de archivos del paquete en tu módulo ResourceLoader. Cuando hagas esto, asegúrate de utilizar $context->msg(), ya que wfMessage() provocará errores.

Utilizar mensajes en Lua

Los módulos escritos en Lua y que utilizan Scribunto se ejecutan de forma similar a las plantillas y tienen acceso a los mensajes de MediaWiki. La biblioteca Lua de MediaWiki incluye la clase mw.message para procesar mensajes. Consulta la documentación completa de la biblioteca de mensajes Lua para la API completa. He aquí un ejemplo sencillo:

local p = {}

function p.nmembers( frame )
	local nmembersMsg = mw.message.new( 'nmembers' )
	nmembersMsg:numParams( 3 ) -- Esto asegura la localización de los números
	-- Mostrar el mensaje en el idioma del wiki. frame:preprocess expande la cláusula {{plural}}.
	return frame:preprocess( nmembersMsg:plain() )
end

return p

Notas sobre GENDER, GRAMMAR y PLURAL

Véase también #Selectores en los mensajes…; la propia sintaxis está documentada en Ayuda:Palabras mágicas#Localización y relacionadas.

En general, las palabras mágicas GENDER, GRAMMAR y PLURAL funcionan de forma idéntica en el lado PHP y en el lado JavaScript.

1. Tienes que utilizar un formato de salida entre text, escaped, parse y parseAsBlock para que funcionen.
   • En PHP, puedes utilizar wfMessage o $this->msg.
   • En JavaScript, asegúrate de que tu módulo de carga de recursos dependa de jqueryMsg (véase #Utilizar mensajes en JavaScript).
2. Tienes que pasar al mensaje el parámetro relevante como un parámetro normal.
   • El parámetro es el número para PLURAL; el nombre de usuario en texto plano o escapado a wikitexto para GENDER en PHP; o el género obtenido de las preferencias o un objeto de usuario para GENDER en JavaScript (véase más adelante).
   • Para habilitar el plural y la localización correcta de números en PHP, tienes que utilizar numParams para el número, véase también #Encadenamiento de métodos.
   • Para habilitar el plural y la localización correcta de números en JavaScript, tienes que utilizar mw.language.convertNumber para el número.

Ejemplo de sintaxis de PLURAL

# Plural simple
'key' => '$1 crying {{PLURAL:$1|baby|babies}}'

GENDER en JavaScript

Esto necesita un jqueryMsg explícito, véase #Utilizar mensajes en JavaScript.

Si tienes un mensaje, digamos, "message-key-gender-foo": "{{GENDER:$1|he|she|they}} created an article", en JavaScript, puedes utilizarlo como sigue:

mw.message( 'message-key-gender-foo', 'male' ).text(); // devuelve 'he created an article'
mw.message( 'message-key-gender-foo', 'female' ).text(); // devuelve 'she created an article'
mw.message( 'message-key-gender-foo', 'unknown' ).text(); // devuelve 'they created an article'

En lugar de pasar directamente el género, se puede pasar cualquier objeto asimilable a un usuario con una opción de género. Por ejemplo, el objeto de usuario actual mw.user.

var user = mw.user; // usuario actual
mw.message( 'message-key-gender-foo', user ).text(); // El mensaje devuelto se basará en el género del usuario actual.

Si el género que se pasa no es válido o es desconocido, se utilizará la forma de género neutro tal como se define para cada idioma. Pasa 'unknown' si deseas explícitamente la forma neutra.

Por último, si deseas utilizar el género del usuario actual, puedes pasar una cadena vacía:

// la siguiente línea ilustra el contenido del mensaje, puedes ejecutar este código en la consola de desarrollador.
mw.messages.set( 'message-key-gender-foo', '{{GENDER:$1|male|female|unknown}}' );
mw.user.options.values.gender = 'female'; // manipula temporalmente tu preferencia de género
mw.message( 'message-key-gender-foo', '' ).text(); // el valor devuelto depende de tu preferencia de género

PLURAL en JavaScript

Esto necesita un jqueryMsg explícito, véase #Utilizar mensajes en JavaScript.

Si tienes un mensaje, digamos, 'message-key-plural-foo' => 'There {{PLURAL:$1|is $1 item|are $1 items}}' , en JavaScript, puedes utilizarlo como sigue:

mw.message( 'message-key-plural-foo', count ).text();
// devuelve 'There is 1 item' si count = 1
// devuelve 'There are 6 items' si count = 6

Ayuda para reemplazar funciones obsoletas de wfMsg*

Estas funciones fueron retiradas a partir de MediaWiki 1.27 LTS.

El código que utiliza estas funciones a menudo presenta un escapado incorrecto y otros problemas de calidad de código, por lo que se recomienda:

• reemplazar todas las funciones Xml:: por sus equivalentes Html::, lo que facilita hacer las cosas bien;
• donde sea posible, evita utilizar variables globales y utiliza msg() (véase más arriba);
• reemplaza htmlspecialchars() por ->escaped() donde sea apropiado.

Cambio en el código	Descripción
En lugar de: wfMsg( 'key' ); escribe: wfMessage( 'key' )->text();
En lugar de: wfMsgExt( 'key', SOME_FORMAT, 'apple' ); escribe: wfMessage( 'key', 'apple' )->SOME_FORMAT_FUNCTION();	El segundo parámetro especifica el modo de salida; generalmente expresado en forma de vector como array( 'escape' ), pero a veces simplemente como 'escape': debe reemplazarse de acuerdo con los #Modos de salida y escapado, como ->escaped().
En lugar de: wfMsgExt( 'key', array( 'parse' ), 'apple' ); escribe: wfMessage( 'key', 'apple' )->parseAsBlock();	Utiliza el análisis completo y envuelve la salida entre etiquetas HTML de nivel de bloque.
En lugar de: wfMsgExt( 'key', array( 'parseinline' ), 'apple' ); escribe: wfMessage( 'key', 'apple' )->parse();	Utiliza el análisis completo. Se utiliza parseinline porque es más útil a la hora de preconstruir código HTML. En el caso habitual, es mejor utilizar OutputPage::(add|wrap)WikiMsg.
En lugar de: wfMsgExt( 'key', array( 'parsemag' ), 'apple', 'pear' ); escribe: wfMessage( 'key', 'apple', 'pear' )->text();	Casos en los que no se pueda utilizar HTML. Se realiza la transformación de '{{'.
En lugar de: wfMsgHtml( 'key', 'apple' ); escribe: wfMessage( 'key' )->rawParams( 'apple' )->escaped();	wfMsgHtml no escapa parámetros: para obtener el mismo resultado, tienes que utilizar rawParams; comprueba que el parámetro es seguro para la salida HTML. Si se hace salir el mensaje como HTML, tienes que utilizar escaped() por seguridad: escapará asimismo los parámetros, lo que no se desea en todos los casos, aunque no importe, por ejemplo, si el parámetro es un número.
En lugar de: wfMsgForContent( 'key' ); escribe: wfMessage( 'key' )->inContentLanguage()->text();	Obtiene un mensaje en el idioma de contenido del wiki ($wgLanguageCode ).
En lugar de: wfMsgForContentNoTrans( 'key' ); escribe: wfMessage( 'key' )->inContentLanguage()->plain();	Obtiene un mensaje en el idioma de contenido del wiki ($wgLanguageCode ), pero no transforma el mensaje.
En lugar de: wfEmptyMsg( 'key', $message = wfMsgForContent( 'key' ) ); escribe: wfMessage( 'key' )->inContentLanguage()->isBlank();	Comprueba si el mensaje 'key' (clave) en el idioma de contenido del wiki está vacío. A menudo, isDisabled() es una comprobación más apropiada y se debería utilizar en su lugar.
En lugar de: wfMsgReal( $error['message'], $error['params'] ); escribe: ?	No hay una alternativa sencilla, depende de los parámetros. Nunca debió haberse utilizado en primer lugar.
En lugar de: wfMsgGetKey escribe: ?	No hay una alternativa sencilla, depende de los parámetros. Nunca debió haberse utilizado en primer lugar.

Véase también

• API:Allmessages
• Help:HTML_in_wikitext
• Documentación de la clase Message