MediaWiki

Help:Mensaje del sistema

This page is a translated version of the page Help:System message and the translation is 55% complete.
Languages:
PD Nota: Cuando editas esta página, aceptas liberar tu contribución bajo la licencia CC0. Para más información mira las páginas de ayuda de dominio público. PD
i18n docs
Diagrama etiquetado del formulario Special:Upload, mostrando varios mensajes de sistemas.

Un mensaje del sistema es un fragmento de texto plano (nowiki), wikitexto, CSS o JavaScript que se puede utilizar para personalizar el funcionamiento y la apariencia de MediaWiki según el idioma y la configuración regional. MediaWiki utiliza los mensajes de sistema en toda la interfaz de usuario, lo que permite la internacionalización y regionalización del núcleo y las extensiones. Todos los mensajes que se utilizan en MediaWiki se definen en un archivo de mensajes.

Personalizar mensajes en el wiki

Se pueden cambiar los textos de los mensajes respecto de su valor por defecto editándolos directamente en el wiki. Cada mensaje tiene una página dentro del espacio de nombres MediaWiki, donde el nombre del mensaje se corresponde con el título de la página en ese espacio de nombres. Por ejemplo, el mensaje «aboutsite» se encuentra en la página MediaWiki:aboutsite. De forma predeterminada, la edición de páginas en este espacio de nombres está restringida, permitiendo únicamente la edición a los usuarios con el permiso «editinterface». Puedes encontrar una lista con todos los mensajes en Special:AllMessages. Normalmente editar mensajes es algo sencillo, similar a editar una página, pero está restringido a usuarios con el permiso editinterface permission, que está asignado por defecto únicamente a los administradores (y administradores de la interfaz).

 
Fila de ejemplo en el antiguo Special:AllMessages.

La tabla Special:AllMessages contiene dos columnas: el nombre de interfaz con enlaces y el texto correspondiente. Cuando no existe un mensaje personalizado, se mostrará únicamente el predeterminado. Cuando no existe un mensaje personalizado, solo se mostrará el predeterminado. Para personalizar un mensaje, haz clic en el enlace superior en la columna izquierda (el nombre del mensaje). El enlace es rojo si el texto predeterminado es el que se está usando, porque la página de edición está vacía.

Los enlaces inferiores en las celdas de la columna izquierda llevan a las páginas de discusión de ese mensaje.

Sólo se recomienda redefinir los mensajes en el wiki en los siguientes casos:

  • El mensaje contiene un error grave que debe ser corregido lo antes posible. En este caso, se recomienda cambiar también el error en el código fuente si está en inglés o en la traducción en translatewiki si no. Una vez desplegada la corrección, hay que eliminar la página con la personalización local.
  • Si el wiki local utiliza una terminología diferente. Por ejemplo, muchos mensajes utilizan la palabra «página», pero Wikipedia en español suele usar «artículo» en su lugar.
  • El mensaje local trata de añadir alguna funcionalidad única, por ejemplo, para un accesorio o una plantilla. (En tal caso, todavía se recomienda considerar cambiar el mensaje de origen o encapsular esta funcionalidad en una extensión, para que otros wikis puedan aprovecharla convenientemente sin tener que copiar las personalizaciones a mano.)

Encontrar mensajes y documentación

Cómo se usa cada mensaje en MediaWiki, las variables de que dispone, los parámetros usados, las limitaciones, etc., todo ello está explicado en la documentación completa en el pseudo-idioma qqq, siguiendo las pautas de documentación de mensajes. Pueden existir algunas páginas con explicaciones más largas para algunos mensajes de la interfaz en la antigua Categoría:Mensajes de la interfaz .

En el wiki base de translatewiki.net, qqq es la página que mantiene la documentación del mensaje del usuario (en inglés porque es la misma que se muestra a todos los usuarios).

De la misma manera que /en, /zu, /fr, ..., /qqq es una subpágina del artículo y es directamente visualizable.

Desde este punto de vista, qqq es considerado como un idioma en el parámetro language= de la solicitud.
Versión de MediaWiki:
≥ 1.18

A partir de MediaWiki 1.18, puedes encontrar el nombre del mensaje navegando por el wiki usando el código de pseudo-idioma especial qqx. Para ello, añade ?uselang=qqx a la URL, o &uselang=qqx si la URL ya contiene un carácter ? (ejemplo). Todos los mensajes entonces son reemplazados por sus claves para que puedas identificar qué mensaje es responsable de cada texto. Los mensajes que siempre se muestren en el idioma del contenido nunca aparecerán usando qqx.

Si la página usa pestañas, como por ejemplo en la página especial de «preferencias», tendrás que añadir la pestaña después del parámetro uselang, por ejemplo, Special:Preferences?uselang=qqx#mw-prefsection-rendering.

Versión de MediaWiki:
≥ 1.38
Gerrit change 765385

Antes de MediaWiki 1.38, no se mostraban los mensajes de respaldo, lo que dificultaba la identificación del origen de algunos mensajes, particularmente las pestañas de navegación. A partir de MediaWiki 1.38, se muestran los mensajes de respaldo separados por barras (/).

Versión de MediaWiki:
≥ 1.43
Gerrit change 1025837

Antes de MediaWiki 1.43, tampoco se mostraban las claves de redefinición de mensajes (mediante ganchos o hooks como MessageCacheFetchOverrides ), lo que dificultaba la identificación de la fuente de los mensajes redefinidos por extensiones (como WikimediaMessages ). A partir de MediaWiki 1.43, se muestra la clave de redefinición de mensaje después de un signo igual (=).

Formato de archivo de localización

Todos los mensajes usados en MediaWiki son definidos en un archivo de mensajes.

Hay dos tipos de archivos de mensajes en MediaWiki: JSON and PHP. A fecha de abril de 2014, se han migrado a formato JSON el núcleo de MediaWiki y la mayoría de las extensiones mantenidas. Deberías usar JSON para todo desarrollo nuevo. Para más información sobre la migración a JSON, véase Requests for comment/Localisation format.

JSON

A finales de 2013, se introdujo un nuevo formato de archivo para mensajes: JSON. Este es JSON plano, conocido como formato común y genérico de almacenamiento de datos. Cada clave que contiene es una clave de mensaje, y el valor es el texto del mensaje. Además de ello, se utiliza la clave especial @metadata para almacenar información sobre la traducción, como por ejemplo los autores de la misma.

Usar JSON hace que los archivos de localización sean más seguros, ya que no es ejecutable. También es compatible con jquery.i18n, una biblioteca JavaScript desarrollada como parte de Proyecto Milkshake, que proporciona capacidades de localización similares a las de MediaWiki para el frontend y está siendo utilizada por algunas extensiones que desean reducir su dependencia de MediaWiki, como VisualEditor y UniversalLanguageSelector.

Dado que la suite más amplia de herramientas de internacionalización y localización era conocida como «Project Milkshake», hay gente que denomina a este formato «banana».

Ubicación del archivo

En el núcleo de MediaWiki, los archivos de localización están situados en el directorio languages/i18n. Las extensiones de MediaWiki, por lo general, sitúan los suyos en un subdirectorio i18n/. Si existe un gran número de mensajes dentro de un proyecto, es conveniente separarlos en dos o más subdirectorios temáticos para el mantenimiento. En el contexto de MediaWiki, se utiliza la clave de configuración $wgMessagesDirs para enumerar estos subdirectorios. He aquí un ejemplo de la extensión VisualEditor para MediaWiki: 

{
  "MessagesDirs": {
    "VisualEditor": [
      "lib/ve/modules/ve/i18n",
      "modules/ve-mw/i18n",
      "modules/ve-wmf/i18n",
      "lib/ve/lib/oojs-ui/i18n"
    ]
  }
}

Puedes añadir nuevos mensajes al archivo de mensajes en inglés («en») en.json y documentarlos en el archivo de documentación de mensajes con el código especial pseudolingüístico «qqq» – qqq.json. Véase también: Añadir nuevos mensajes.

Metadatos

En la actualidad, se utilizan los siguientes campos de metadatos en los archivos:

authors
Una lista JSON de los autores de los mensajes. Para el inglés (en) y la documentación de mensajes (qqq), estos se añaden a mano cuando se edita el archivo de mensajes. Para el resto de idiomas, esto se inserta automáticamente al exportar el archivo de mensaje de translatewiki.net. Se puede editar la documentación de los mensajes en translatewiki.net, y se insertan asimismo de forma automática los editores de la documentación en el archivo qqq.json
message-documentation
Este es el código del pseudoidioma utilizado para almacenar la documentación del mensaje. Para MediaWiki, siempre es qqq. (Esto aparece en algunas extensiones, pero en realidad no se procesa de ninguna manera. No es obligatorio.)

Convenciones

Algunos caracteres tales como los saltos de línea se escapan ("\n").

Los caracteres Unicode que representan letras de distintos alfabetos se almacenan como caracteres reales y no como códigos de caracteres, ya que en ocasiones hay personas que leen estos archivos y además esto minimiza el tamaño de los mismos ("誼" en lugar de "\u8ABC"). En cualquier caso, los desarrolladores tienen pocos motivos para editar los mensajes en idiomas distintos del inglés, ya que estos habitualmente se editan mediante translatewiki.net.

El código HTML tampoco se escapa, por lo que "<strong>Warning</strong>" en lugar de "\u003cstrong\u003eWarning\u003c/strong\u003e".

Los archivos JSON se indentan con tabuladores.

PHP

Esta sección trata sobre el uso de archivos MessagesXx.php para localizar mensajes, algo que quedó obsoleto en 2014. Sin embargo, todavía se utilizan los archivos para otras configuraciones específicas de idioma .

El formato anterior de archivo de localización es PHP. Se trata esencialmente de un vector PHP con todos los mensajes. En el núcleo de MediaWiki, cada idioma reside en su propio archivo en el directorio languages/message del código fuente de MediaWiki. En las extensiones, todos los idiomas y la documentación de los mensajes (qqq) se encuentran en el mismo archivo: ExtensionName.i18n.php, generalmente en el directorio principal de la extensión.

Para migrar los mensajes de sistema de PHP a JSON, utiliza el script generateJsonI18n.php . Trasladará los mensajes a archivos JSON y reemplazará el texto del archivo PHP por una capa de compatibilidad que apunta a los archivos JSON. Este código plantilla es necesario para la retrocompatibilidad con MediaWiki 1.19. No se utiliza en extensiones nuevas que no requieren compatibilidad con MediaWiki 1.19.

Utilización de mensajes

MediaWiki utiliza un repositorio central de mensajes que están referenciados por claves en el código. Esto se diferencia, por ejemplo, del sistema gettext, que extrae las cadenas traducibles de los archivos fuente. El sistema basado en claves facilita algunas cosas, como refinar los textos originales y rastrear los cambios en los mensajes. La contrapartida es que se pueden desincronizar la lista de mensajes utilizados y la lista de textos fuente para esas claves. En la práctica, no es un problema grave, y el único inconveniente significativo es que a veces se mantienen para la traducción mensajes extra que ya no se utilizan.

Para facilitar el mantenimiento y la búsqueda de claves de mensajes, asegúrate de escribirlas por completo y no confíes demasiado en crearlas dinámicamente. Puedes concatenar partes de claves de mensajes si crees que mejora la estructura de tu código, pero hazlo sólo si hay definitivamente varias posibilidades,[1] y asegúrate de añadir un comentario al lado con una lista de las posibles claves resultantes. Por ejemplo: 

// Mensajes que pueden utilizarse aquí:
// * myextension-connection-success
// * myextension-connection-warning
// * myextension-connection-error
$text = wfMessage( 'myextension-connection-' . $status )->parse();

Véanse también las convenciones de código para identificadores dinámicos.

Para utilizar un mensaje en JavaScript, tienes que listarlo en la definición de tu módulo ResourceLoader, en la propiedad "messages".

En Manual:API de mensajes se explica detalladamente el uso de funciones de mensajes en PHP y JavaScript. Ésta es una página importante de documentación, y deberías leerla antes de escribir código que utilice mensajes.

Fuentes de mensajes

El código busca mensajes de sistema de las siguientes fuentes:

  • El espacio de nombres MediaWiki. Esto permite a los wikis adoptar o redefinir todos sus mensajes cuando los mensajes estándar no se ajustan o no son deseados.
    • MediaWiki:Clave-de-mensaje es el mensaje por defecto,
    • MediaWiki:Clave-de-mensaje/código-de-idioma es el mensaje utilizado cuando un usuario ha seleccionado un idioma distinto del predeterminado del wiki.
  • Archivos de mensajes:
    • El propio núcleo de MediaWiki y la mayoría de extensiones mantenidas en la actualidad utilizan un archivo por idioma, zyx.json, donde zyx es el código del idioma.
    • Algunas extensiones anteriores utilizan un archivo de mensajes combinado que contiene todos los mensajes en todos los idiomas, que generalmente tiene el nombre NombreDeExtensión.i18n.php.
    • Muchos wikis de la Fundación Wikimedia acceden a algunos mensajes de la extensión WikimediaMessages , lo que les permite estandarizar mensajes entre los wikis de la Fundación sin por ello imponérselos a cualquier instalación de MediaWiki.
    • Algunas extensiones utilizan otras técnicas.

Almacenamiento en caché

Los mensajes de sistema son uno de los componentes más importantes de MediaWiki, principalmente porque se utilizan en cualquier petición web. Los archivos de mensajes PHP son grandes, ya que almacenan miles de claves y valores de mensajes. Cargar este archivo (o posiblemente varios archivos, si el idioma del usuario es distinto del idioma del contenido) tiene un alto coste de memoria y de rendimiento. Se utiliza un sistema agresivo de almacenamiento en caché por capas para reducir este impacto en el rendimiento.

MediaWiki tiene incorporados muchos mecanismos de almacenamiento en caché, lo que hace que el código sea algo más difícil de entender. Desde 1.16 hay un nuevo sistema que almacena los mensajes en caché ya sea en archivos cdb o en la base de datos. Los mensajes personalizados se almacenan en caché en el sistema de archivos y en memcached (o equivalente), dependiendo de la configuración.

La siguiente tabla ofrece una sinopsis de las configuraciones implicadas:

Ubicación del almacenamiento en caché $wgLocalisationCacheConf
'store' => 'db'
 		 'store' => 'detect'
(por defecto)		 'store' => 'files'
 		 'store' => 'array'
(experimental desde MW ≥ 1.26)
$wgCacheDirectory = false
(por defecto) 		l10n cache table l10n cache table error (ruta no definida) error (ruta no definida)
= path l10n cache table sistema de archivos local (CDB) sistema de archivos local (CDB) sistema de archivos local (vector PHP)
Versiones de MediaWiki:
1.27.0 – 1.27.2
Gerrit #Id3e2d2

En MediaWiki 1.27.0 y 1.27.1, se cambió la autodetección para favorecer el backend de archivos. En el caso 'store' => 'detect' (el predeterminado), se utiliza el backend de archivos con la ruta de $wgCacheDirectory . Si no se ha establecido este valor (que es el predeterminado), se utilizará un directorio temporal determinado por el sistema operativo. Si no se puede detectar un directorio temporal, se utilizará el backend de la base de datos como respaldo. Esto se revirtió desde 1.27.2 y 1.28.0 debido a un conflicto de archivos en hosts compartidos y a problemas de seguridad (véase T127127 y T161453).

Traza de funciones

Para representar mejor de forma visual las capas de almacenamiento en caché, he aquí una traza de funciones que indican a qué métodos se llama al recuperar un mensaje. Véanse las siguientes secciones para una explicación de cada capa.

  • Message::fetchMessage()
  • MessageCache::get()
  • Language::getMessage()
  • LocalisationCache::getSubitem()
  • LCStore::get()

MessageCache

La clase MessageCache es el nivel superior del almacenamiento en caché de los mensajes. Recibe una llamada de la clase Message y devuelve el contenido final en bruto de un mensaje. Esta capa maneja la siguiente lógica:

El último punto es importante. Los respaldos de idiomas permiten a MediaWiki utilizar un idioma alternativo si el original no dispone de un mensaje que se está solicitando. Como se menciona en la siguiente sección, la mayor parte de la resolución de respaldo de idiomas se produce a un nivel inferior. Sin embargo, sólo la capa MessageCache comprueba la base de datos en busca de mensajes redefinidos. Por lo tanto, la integración de mensajes redefinidos en la cadena de respaldo se produce aquí. Si no utilizas la base de datos, puedes deshabilitar por completo esta capa.

LocalisationCache

Véase LocalisationCache.php

LCStore

La clase LCStore es una mera implementación backend utilizada por la clase LocalisationCache para almacenar en caché y recuperar los mensajes. Al igual que la clase BagOStuff, que se utiliza para el almacenamiento general en caché en MediaWiki, hay varios tipos de caché diferentes (configurados mediante $wgLocalisationCacheConf ):

  • «db» (por defecto) - Almacena los mensajes en la base de datos
  • «file» (por defecto si se ha establecido $wgCacheDirectory) - Utiliza CDB para almacenar los mensajes en un archivo local
  • «accel» - Utiliza APC u otra caché de código de operación para almacenar los datos

La Fundación Wikipedia utiliza la opción «file», y es la opción recomendada porque es más rápida que acceder a la base de datos y más fiable que la caché APC, especialmente dado que APC es incompatible con las versiones de PHP 5.5 o posteriores.

Añadir nuevos mensajes

Elegir la clave de mensaje

Véase también: Manual:Convenciones de código

La clave de mensaje debe ser única a nivel global. Esto incluye el núcleo de MediaWiki y todas las extensiones y apariencias.

Cíñete a letras minúsculas, números y guiones para nombres de mensajes; la mayoría de los demás caracteres son entre menos prácticos y completamente inutilizables. Según la convención de MediaWiki, todos los caracteres son sensibles a mayúsculas con la excepción del primero.

Procura seguir las convenciones globales o locales para nombrar los mensajes. Para las extensiones, utiliza un prefijo estándar, preferentemente el nombre de la extensión en minúsculas seguido de un guion (-). Las excepciones son:

Mensajes utilizadas por la API
Estos deben empezar por apihelp-, apiwarn- o apierror-. Pon el prefijo de extensión después de este prefijo. (Ten en cuenta que estos mensajes deberían estar en un archivo separado, generalmente bajo includes/i18/api.)
Mensajes relacionados con registros
Estos deben empezar por logentry-, log-name- o log-description.
Derechos de usuario
La clave del nombre del derecho tal como se muestra en Special:ListGroupRights debe empezar por right-. El nombre de la acción que completa la frase «No tienes permiso para $2, por los siguientes motivos:» debe empezar por action-.
Etiquetas de revisión
Las etiquetas de revisión deben empezar por tag-.
Títulos de páginas especiales
Los títulos de páginas especiales deben empezar por special-.
Descripciones de extensiones
Las descripciones de extensiones deben empezar por el nombre de las extensión y deben terminar por -desc.

They appear in the table on Special:Version, and their content must briefly explain what the extension does.

Género

Los mensajes en inglés casi nunca necesitan tener palabras que cambien en función del género del usuario. El inglés sólo necesita utilizar esto en los pronombres de tercera persona «he» y «she», pero son sorprendentemente raros en los mensajes. Cuando sea necesario, utiliza he o they.

Sin embargo, muchos idiomas distintos del inglés necesitan palabras diferentes en función del género del usuario, no sólo para los pronombres de tercera persona, sino también para otros pronombres, así como verbos en distintos tiempos (por ejemplo, «creado/a», «eliminado/a»), sustantivos (por ejemplo, «mentor(a)», «administrador(a)»), adjetivos (por ejemplo, «nuevo/a»), etc. Por tanto, en general conviene utilizar GENDER en mensajes en inglés, incluso en casos en que en inglés no haya palabras que cambien. Esto da a los traductores una pista de que se puede utilizar GENDER en un mensaje. También evita que aparezcan advertencias en translatewiki sobre parámetros faltantes cuando falte un parámetro opcional de nombre de usuario (algo que ocurre especialmente a menudo en mensajes de entrada de registro).

Más cosas que tener en cuenta a la hora de crear mensajes

  1. Asegúrate de manejar adecuadamente el mensaje (análisis sintáctico, reemplazo de {{, escapado de HTML, etc.).
  2. Si tu mensaje forma parte del núcleo, por lo general debería añadirse a languages/i18n/en.json, aunque algunos componentes tales como Installer, etiquetas EXIF y ApiHelp tienen sus propios archivos de mensajes.
  3. Si tu mensaje está en una extensión, añádelo al archivo i18n/en.json o al archivo en.json en el subdirectorio correspondiente. En particular, los mensajes de la API que sólo ven los desarrolladores y no la mayoría de usuarios finales se encuentran en un archivo separado tal como i18n/api/en.json. Si una extensión tiene muchos mensajes, puedes crear subdirectorios bajo i18n. Todos los directorios de mensajes, incluido el directorio por defecto i18n/, deben estar enumerados en la sección MessagesDirs de extension.json o en la variable $wgMessagesDirs .
  4. Tómate un respiro y reflexiona sobre la redacción del mensaje. ¿Es suficientemente clara? ¿Se puede malinterpretar? Si puedes, pide más opiniones a otros desarrolladores o localizadores. Sigue las pautas de internacionalización.
  5. Incluye la documentación en qqq.json en el mismo directorio.
  6. La secuencia de mensajes en el archivo debería ajustarse aproximadamente a las funcionalidades de tu proyecto. Pon juntos los mensajes sobre la misma funcionalidad. Esto ayuda a los traductores a mantener el foco y a ser eficientes y consistentes.
  7. Pon los mensajes que se espera sean los más básicos y habituales al principio y los más raros y más avanzados desde el punto de vista técnico hacia el final.

Mensajes que no deben traducirse

  1. Los mensajes ignorados son aquellos que sólo deberían existir en el archivo de mensajes en inglés. Son mensajes que no deberían necesitar traducción, ya que únicamente referencian otros mensajes o características independientes del idioma, por ejemplo, un mensaje de «{{SITENAME}}».
  2. Los mensajes opcionales pueden traducirse sólo si cambian en el idioma de destino.

Para marcar tales mensajes:

Eliminar mensajes existentes

Elimínalo de en.json y qqq.json. No preocupes por los demás idiomas. Las actualizaciones de translatewiki.net se encargarán de ello automáticamente.

Además de ello, comprueba si el mensaje aparece en cualquier lugar en la configuración de translatewiki, por ejemplo, en la lista de mensajes opcionales o en la de mensajes más utilizados (un simple «git grep» debería bastar). Elimínalo de estas listas si es necesario.

Cambiar mensajes existentes

  1. Considera actualizar la documentación de mensajes.
  2. Cambia la clave del mensaje si las traducciones antiguas ya no son apropiadas para el nuevo mensaje. Esto también incluye cambios en el manejo de mensajes (análisis sintáctico, escapado, parámetros, etc.). Las mejoras en la redacción de un mensaje sin que haya cambios técnicos no suele ser motivo para cambiar una clave. En translatewiki.net, las traducciones se marcarán como desactualizadas para que los traductores puedan abordarlas. Cambiar una clave de mensaje no requiere hablar con el equipo de internacionalización ni presentar una solicitud de soporte. Sin embargo, si tienes alguna duda o circunstancia especial, pregunta en #translatewiki connect o en la página de asistencia de translatewiki.net .
  3. Si la extensión está soportada por translatewiki.net , cambia únicamente el mensaje de origen en inglés y/o la clave, así como la entrada correspondiente en qqq.json. En caso necesario, el equipo de translatewiki.net se encargará de actualizar las traducciones marcándolas como desactualizadas, limpiando el archivo o renombrando las claves donde sea posible. Esto también concierne los casos en que te limitas a cambiar cosas como las etiquetas HTML que podrías cambiar en otros idiomas sin necesidad de hablarlos. La mayoría de estas acciones se llevarán a cabo en translatewiki.net y llegarán a Git en el plazo aproximado de un día.

Documentación de mensajes

La documentación de mensajes utiliza el código de pseudoidioma qqq. Se trata de uno de los códigos ISO 639 reservados para uso privado. En él no guardamos traducciones de cada mensaje, sino que recopilamos frases en inglés acerca de cada mensaje que informan de dónde se utiliza el mensaje, dan pautas de traducción, enumeran y describen sus parámetros, enlazan a mensajes relacionados, etc. En translatewiki.net, se muestran estas pautas a los traductores cuando editan los mensajes.

Los programadores deben documentar todos y cada uno de los mensajes. La documentación de mensajes es un recurso esencial – no sólo para los traductores, sino para todas las personas que mantienen el módulo. Cada vez que se añade un mensaje al software, se debe añadir también una entrada correspondiente qqq; las revisiones que no lo hacen así se marcan como «V-1» hasta que se añada la documentación.

Documentation in qqq files should be edited directly only when adding new messages or when changing an existing English message in a way that requires a documentation change, for example adding or removing parameters. In other cases, documentation should usually be edited in translatewiki. Each documentation string is accessible at https://translatewiki.net/wiki/MediaWiki:message-key/qqq, as if it were a translation. These edits will be exported to the source repositories along with the translations.

Useful information that should be in the documentation includes:

  1. Message handling (parsing, escaping, plain text).
  2. Type of parameters with example values.
  3. Where the message is used (pages, locations in the user interface).
  4. How the message is used where it is used (a page title, button text, etc.).
  5. What other messages are used together with this message, or which other messages this message refers to.
  6. Anything else that could be understood when the message is seen on the context, but not when the message is displayed alone (which is the case when it is being translated).
  7. If applicable, notes about grammar. For example, "open" in English can be both a verb and an adjective. In many other languages the words are different and it's impossible to guess how to translate them without documentation.
  8. Adjectives that describe things, such as "disabled", "open" or "blocked", must always say what are they describing. In many languages adjectives must have the gender of the noun that they describe. It may also happen that different kinds of things need different adjectives.
  9. If the message has special properties, for example, if it is a page name, or if it should not be a direct translation, but adapted to the culture or the project.
  10. Whether the message appears near other message, for example in a list or a menu. The wording or the grammatical features of the words should probably be similar to the messages nearby. Also, items in a list may have to be properly related to the heading of the list.
  11. Parts of the message that must not be translated, such as generic namespace names, URLs or tags.
  12. Explanations of potentially unclear words, for example abbreviations, like "CTA", or specific jargon, like "template", "suppress" or "stub". (Note that it's best to avoid such words in the first place!)
  13. Screenshots are very helpful. Don't crop – an image of the full screen in which the message appears gives complete context and can be reused in several messages.

A few other hints:

  • Remember that very, very often translators translate the messages without actually using the software.
  • Most usually, translators do not have any context information, neither of your module, nor of other messages in it.
  • A rephrased message alone is useless in most circumstances.
  • Don't use designers' jargon like "hamburger", "nav", or "comps".
  • Consider writing a glossary of the technical terms that are used in your module. If you do it, link to it from the messages' documentation.

You can link to other messages by using {{msg-mw|message key}}. Please do this if parts of the messages come from other messages (if this cannot be avoided), or if some messages are shown together or in same context.

translatewiki.net provides some default templates for documentation:

  • {{doc-action|[...]}} - for action- messages
  • {{doc-right|[...]}} - for right- messages
  • {{doc-group|[...]|[...]}} - for messages around user groups (group, member, page, js and css)
  • {{doc-accesskey|[...]}} - for accesskey- messages

Have a look at the template pages for more information.

Pautas de internacionalización

Besides documentation, translators ask developers to consider some hints so as to make their work easier and more efficient and to allow an actual and good localisation for all languages. Even if only adding or editing messages in English, one should be aware of the needs of all languages. Each message is translated into more than 300 languages and this should be done in the best possible way. Correct implementation of these hints will very often help you write better messages in English, too.

Localisation#Help and contact info lists the main places where you can find the assistance of experienced and knowledgeable people regarding i18n.

Use message parameters and switches properly

That's a prerequisite of a correct wording for your messages.

Avoid message re-use

The translators discourage message re-use. This may seem counter-intuitive, because copying and duplicating code is usually a bad practice, but in system messages it is often needed. Although two concepts can be expressed with the same word in English, this doesn't necessarily mean they can be expressed with the same word in every language. "OK" is a good example: in English this is used for a generic button label, but in some languages they prefer to use a button label related to the operation which will be performed by the button. Another example is practically any adjective: a word like "multiple" changes according to gender in many languages, so you cannot reuse it to describe several different things, and you must create several separate messages.

If you are adding multiple identical messages, please add message documentation to describe the differences in their contexts. Don't worry about the extra work for translators. Translation memory helps a lot in these while keeping the flexibility to have different translations if needed.

Avoid fragmented or "patchwork" messages

Languages have varying word orders, and complex grammatical and syntactic rules. Messages formed by multiple pieces of text, possibly with some indirection, also called "string concatenation", in code that cannot be directly controlled by translators, are called "lego" or "patchwork" messages in developers' jargon. It's practically impossible to translate "lego" messages correctly.

Make every message a complete phrase. Several sentences can usually be combined much more easily into a text block, if needed. When you want to combine several strings in one message, pass them in as parameters, as translators can order them correctly for their language when translating.

Messages quoting each other

Página principal: Manual:Messages API#Referring to other messages

An exception from the rule may be messages referring to one another: 'Enter the original author's name in the field labelled "{{int:name}}" and click "{{int:proceed}}" when done'. This makes the message consistent when a software developer or wiki operator alters the messages "name" or "proceed" later. Without the int-trick, developers and operators would have to be aware of all related messages needing adjustment, when they alter one.

Write messages in natural language

As much as possible, write messages in natural, human language. Try reading the message aloud and think: is this something that sounds like correct, grammatical English that humans speak? If it's complex, hard to pronounce, or in any way unnatural in English, it will be even harder for translators and for users in other languages.

Avoid punctuation that is too technical or bureaucratic or that can't be read aloud. Slash (/) should usually be replaced with or. And/or should be replaced with and or or. Sentences with comma splice should be split into shorter sentences.

Don't use terms and templates that are specific to particular projects

MediaWiki is used by very diverse people, within the Wikimedia movement and outside of it. Even though it was originally built for an encyclopedia, it is now used for various kinds of content. Therefore, use general terms. For example, avoid terms like "article", and use "page" instead, unless you are absolutely sure that the feature you are developing will only be used on a site where pages are called "articles". Don't use "village pump", which is the name of an English Wikipedia community page, and use a generic term, such as "community discussion page", instead.

Don't assume that a certain template exists on all wikis. Templates are local to wikis. This applies to both the source messages and to their translations. If messages use templates, they will only work if a template is created on each wiki where the feature is deployed. It's best to avoid using templates in messages completely. If you really have to use them, you must document this clearly in the message documentation and in the extension installation instructions.

Separate times from dates in sentences

Some languages have to insert something between a date and a time which grammatically depends on other words in a sentence. Thus, they will not be able to use date/time combined. Others may find the combination convenient, thus it is usually the best choice to supply three parameter values (date/time, date, time) in such cases, and in each translation leave either the first one or last two unused as needed.

Avoid {{SITENAME}} in messages

{{SITENAME}} has several disadvantages. It can be anything (acronym, word, short phrase, etc.) and, depending on language, may need the use of {{GRAMMAR}} on each occurrence. No matter what, each message having {{SITENAME}} will need review in most wiki languages for each new wiki on which your code is installed. In the majority of cases, when there is not a general GRAMMAR configuration for a language, wiki operators will have to add or amend PHP code so as to get {{GRAMMAR}} for {{SITENAME}} working. This requires both more skills, and more understanding, than otherwise. It is more convenient to have generic references like "this wiki". This does not keep installations from locally altering these messages to use {{SITENAME}}, but at least they don't have to, and they can postpone message adaption until the wiki is already running and used.

Avoid references to visual layout and positions

What is rendered where depends on skins. Most often screen layouts of languages written from left-to-right are mirrored compared to those used for languages written from right-to-left, but not always, and for some languages and wikis, not entirely. Handheld devices, narrow windows, and so on may show blocks underneath each other, that would appear side-by-side on larger displays. Since site- and user-written JavaScript scripts and gadgets can, and do, hide parts, or move things around in unpredictable ways, there is no reliable way of knowing the actual layout.

It is wrong to tie layout information to content languages, since the user interface language may not be the page's content language, and layout may be a mixture of the two depending on circumstances. Non-visual user agents like acoustic screen readers and other auxiliary devices do not even have a concept of visual layout. Thus, you should not refer to visual layout positions in the majority of cases, though semantic layout terms may still be used ("previous steps in the form", etc.).

MediaWiki does not support showing different messages or message fragments based on the current directionality of the interface (see T30997).

The upcoming browser and MediaWiki support for East and North Asian top-down writing[2] will make screen layouts even more unpredictable, with at least eight possible layouts (left/right starting position, top/bottom starting position, and which happens first).

Avoid references to screen colours

The colour in which something is rendered depends on many factors, including skins, site- and user-written JavaScript scripts and gadgets, and local user agent over-rides for reasons of accessibility or technological limitations. Non-visual user agents like acoustic screen readers and other auxiliary devices do not even have a concept of colour. Thus, you should not refer to screen colours. (You should also not rely on colour alone as a mechanism for informing the user of state, for the same reason.)

Avoid markup that doesn't need to be translated

HTML markup not requiring translation, such as enclosing ‎<div> tags, rulers above or below, and similar, should usually not be part of messages. It's an unnecessary burden on translators, and is often accidentally altered or skipped in the translation process. The translation interface has no syntax highlighting or validation, and mistakes are common.

Avoid complex wikitext markup as well. Wikitext is sometimes terser than writing the same thing in PHP, and it's tempting to write something like:

MediaWiki:Revreview-basic/en
This is the [[{{MediaWiki:Validationpage}}|stable version]], [{{fullurl:{{#Special:Log}}|type=review&page={{FULLPAGENAMEE}}}} checked] on <i>$2</i>.
[{{fullurl:{{FULLPAGENAMEE}}|oldid=$1&diff=cur}} $3 pending {{PLURAL:$3|change|changes}}] {{PLURAL:$3|awaits|await}} review.

However, this is difficult for translators, especially when translating to right-to-left languages, because parts of the message must remain in English, resulting in text direction changing many times in one line:

MediaWiki:Revreview-basic/ar
هذه هي [[{{MediaWiki:Validationpage}}|النسخة المستقرة]]، [{{fullurl:{{#Special:Log}}|type=review&page={{FULLPAGENAMEE}}}} المفحوصة] في <i>$2</i>.
[{{fullurl:{{FULLPAGENAMEE}}|oldid=$1&diff=cur}} {{PLURAL:$3||تغيير واحد معلق|تغييران معلقان|$3 تغييرات معلقة|$3 تغييرا معلقا|$3 تغيير معلق}}] {{PLURAL:$3||ينتظر|ينتظران|تنتظر|ينتظر}} المراجعة.

It's best to pass any link targets as message parameters, and use only simple markup like [$1 Label] and [[$1|Label]].

Translated messages are often longer than you think!

Skimming foreign language message files, you almost never find translated messages shorter than Chinese ones and rarely shorter than English ones. However, you will often find translations that are much longer than English ones.

Especially in forms, in front of input fields, English messages tend to be terse, and short. That is often not kept in translations. Languages may lack the technical vocabulary present in English, and may require multiple words or even complete sentences to explain some concepts. For example, the brief English message "TSV file:" may have to be translated in a language as literally:

Please type a name here which denotes a collection of computer data that is comprised of a sequentially organised series of typewritten lines which themselves are organised as a series of informational fields each, where said fields of information are fenced, and the fences between them are single signs of the kind that slips a typewriter carriage forward to the next predefined position each. Here we go: _____ (thank you)

This is, admittedly, an extreme example, but you get the trait. Imagine this sentence in a column in a form where each word occupies a line of its own, and the input field is vertically centered in the next column. :-(

Avoid using very close, similar, or identical words to denote different things, or concepts

For example, pages may have older revisions (of a specific date, time, and edit), comprising past versions of said page. The words revision, and version can be used interchangeably. A problem arises, when versioned pages are revised, and the revision, i.e. the process of revising them, is being mentioned, too. This may not pose a serious problem when the two synonyms of "revision" have different translations. Do not rely on that, however. It is better to avoid the use of "revision" aka "version" altogether, then, so as to avoid it being misinterpreted.

Basic words may have unforeseen connotations, or not exist at all

There are some words that are hard to translate because of their very specific use in MediaWiki. Some may not be translated at all. For example, there is no word "user" relating to "someone who uses something" in several languages. Similarly, in Kölsch the English words "namespace" and "apartment" translate the same word. Also, in Kölsch, they say "corroborator and participant" in one word since any reference to "use" would too strongly imply "abuse". The term "wiki farm" is translated as "stable full of wikis", since a single-crop farm would be a contradiction in terms in the language, and not understood, etc..

Use ‎<code>, ‎<var>, and ‎<kbd> tags where needed

When talking about technical parameters, values, or keyboard inputs, mark them appropriately as such using the HTML tags ‎<code>, ‎<var>, or ‎<kbd>. Thus they are typographically set off form the normal text. That clarifies their sense to readers, avoiding confusion, errors and mis-representations. Ensure that your message handler allows such markup.

Symbols, colons, brackets, etc. are parts of messages

Many symbols are localisable, too. Some scripts have other kinds of brackets than the Latin script has. A colon may not be appropriate after a label or input prompt in some languages. Having those symbols included in messages helps to make better and less Anglo-centric translations, and also reduces code clutter.

For example, there are different quotation mark conventions used in «Norwegian», ”Swedish”, »Danish«, „German”, and 「Japanese」.[3]

If you need to wrap some text in localized parentheses, brackets, or quotation marks, you can use the parentheses ($1) or brackets [$1] or quotation-marks "$1" messages like so: 

wfMessage( 'parentheses' )->rawParams( /* text to go inside parentheses */ )->escaped()
wfMessage( 'brackets' )->rawParams( /* text to go inside brackets */ )->escaped()
wfMessage( 'quotation-marks' )->rawParams( /* text to go inside quotation marks */ )->escaped()

Do not expect symbols and punctuation to survive translation

Languages written from right to left (as opposed to English) usually swap arrow symbols being presented with "next" and "previous" links, and their placement relative to a message text may, or may not, be inverted as well. Ellipsis may be translated to "etc.", or to words. Question marks, exclamation marks, colons will be placed other than at the end of a sentence, not at all, or twice. As a consequence, always include all of those in the text of your messages, and never try to insert them programmatically.

Use full stops

Do terminate normal sentences with full stops. This is often the only indicator for a translator to know that they are not headlines or list items, which may need to be translated differently.

Make sure that the anchor describes the target page well. Always avoid commonplace and generic words. For example, "Click here" is an absolute no-go,[4] since target pages are almost never about "click here". Instead, Use precise action words telling what a user will get to when following the link, such as "You can upload a file if you wish."

See also Help users predict where they are going, and mystery meat navigation, and The main reasons why we shouldn't use click here as link text.

Avoid jargon and slang

Avoid developer and power user jargon in messages. Try to use a simple language whenever possible. Avoid saying "success", "successfully", "fail", "error occurred while", etc., when you want to notify the user that something happened or didn't happen. This comes from developers' perspective of seeing everything as true or false, but users usually just want to know what actually happened or didn't, and what they should do about it (if at all). So:

  • "The file was successfully renamed" -> "The file was renamed"
  • "File renaming failed" -> "There is a file with this name already. Please choose a different name."

Be aware of whitespace and line breaks

MediaWiki's localised messages usually get edited within the wiki, either by wiki operations on live wikis, or by the translators on translatewiki.net. You should be aware of how whitespace, especially at the beginning or end of your message, will affect editors:

  • Spaces and line breaks (newlines) at the end of the message are always automatically removed by the wikitext editor. Your message must not end with a space or line break, as it will be lost when it's edited on the wiki.
  • Spaces and line breaks at the beginning are not automatically removed, but they are likely to be removed by accident during editing, and should be avoided.

Start and end your message with active text; if you need a newline or paragraph break around it, your surrounding code should deal with adding it to the returned text.

There are some messages which require a space at the end, such as 'word-separator' (which consists of just a space character in most languages). To support such use cases, the following HTML entities are allowed in messages and transformed to the actual characters, even if the message otherwise doesn't allow wikitext or HTML formatting:[5]

On a related note, any other syntax elements affected by pre-save transforms also must not be used in messages, as they will be transformed when the message is edited on the wiki.

Use standard capitalisation

Capitalisation gives hints to translators as to what they are translating, such as single words, list or menu items, phrases, or full sentences. Correct (standard) capitalisation may also play a role in search engines' assessment of your pages. MediaWiki uses sentence case (The quick brown fox jumps over the lazy dog) in interface messages.

Always remember that many writing systems don't have capital letters at all, and some of those that do have them, use them differently from English. Therefore, don't use ALL-CAPS for emphasis. Use CSS, or HTML ‎<em> or ‎<strong> per below:

Emphasis

In normal text, emphasis like boldface or italics and similar should be part of message texts. Local conventions on emphasis often vary, especially some Asian scripts have their own. Translators must be able to adjust emphasis to their target languages and areas. Try to use "‎<em>" and "‎<strong>" in your user interface to allow mark-up on a per language or per script basis.

In modern screen layouts of English and European styles, emphasis becomes less used. Do convey it in your #Message documentation still, as it may give valuable hints as to how to translate. Emphasis can and should be used in other cultural contexts as appropriate, provided that translators know about it.


Véase también

Notes

  1. ↑ Algunos linters rechazarán listas de mensajes con un único elemento, por ejemplo, mediawiki/msg-doc no acepta documentos válidos con 1 entrada.
  2. ↑ http://dev.w3.org/csswg/css3-writing-modes/
  3. ↑ w:Quotation_mark#Summary_table
  4. ↑ http://www.w3.org/QA/Tips/noClickHere
  5. ↑ https://github.com/wikimedia/mediawiki/blob/REL1_34/includes/cache/MessageCache.php#L887
Retrieved from "https://www.mediawiki.org/w/index.php?title=Help:System_message/es&oldid=6885707"