Jump to content

Help:Mensaje del sistema

From mediawiki.org
This page is a translated version of the page Help:System message and the translation is 100% complete.
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.

La documentación en los archivos qqq sólo se debería editar al añadir mensajes nuevos o al cambiar un mensaje existente en inglés de una manera que requiera un cambio en la documentación, por ejemplo, al añadir o eliminar parámetros. En los demás casos, generalmente se debería editar la documentación en translatewiki. Cada una de las cadenas de documentación es accesible en https://translatewiki.net/wiki/MediaWiki:clave-de-mensaje/qqq, como si fuera una traducción. Estas ediciones se exportan a los repositorios de origen junto con las traducciones.

Se debería incluir en la documentación información útil como la siguiente:

  1. Manejo de mensajes (análisis sintáctico, escapado, texto plano).
  2. Tipos de parámetros con valores de ejemplo.
  3. Dónde se utiliza el mensaje (páginas, localizaciones en la interfaz de usuario).
  4. Qué uso tiene el mensaje (título de página, texto de un botón, etc.).
  5. Qué otros mensajes se utilizan junto con este, o a qué otros mensajes se refiere este.
  6. Cualquier otra cosa que pueda entenderse cuando el mensaje se ve en su contexto, pero no cuando el mensaje se muestra solo (lo cual es el caso cuando se está traduciendo).
  7. En su caso, notas sobre gramática. Por ejemplo, «open» en inglés puede ser tanto un verbo como un adjetivo. En muchos otros idiomas, las palabras son diferentes y es imposible determinar cómo traducirlas sin documentación.
  8. Los adjetivos que describen cosas, como «disabled», «open» o «blocked», siempre deben indicar qué cosa describen. En muchos idiomas, como el español, los adjetivos deben concordar en género con el sustantivo que describen. También puede ocurrir que distintos tipos de cosas necesiten distintos adjetivos.
  9. Si el mensaje tiene propiedades especiales, por ejemplo, si es el título de una página; o si no debe ser una traducción directa, sino adaptada a la cultura o al proyecto.
  10. Si el mensaje aparece junto a otro mensaje, por ejemplo, en una lista o en un menú. La redacción o las características gramaticales de las palabras probablemente deban ser similares a aquellas de otros mensajes cercanos. Además, los elementos de una lista probablemente deban estar relacionados con el título de la lista.
  11. Partes del mensaje que no deben traducirse, como nombres genéricos de espacios de nombres, direcciones URL o etiquetas.
  12. Explicaciones de palabras potencialmente confusas, por ejemplo, abreviaturas (como «CTA») o jerga específica (como «template», «suppress» o «stub»). (¡Ten en cuenta que es mejor evitar palabras así en primer lugar!)
  13. Las capturas de pantalla son muy útiles. No recortes: una imagen de la pantalla completa en la que aparece el mensaje proporciona un contexto completo y se puede reutilizar en varios mensajes.

Algunas pautas adicionales:

  • Recuerda que muy, muy a menudo, los traductores traducen los mensajes sin utilizar el software.
  • Por lo general, los traductores no tienen ninguna información contextual ni de tu módulo ni de otros mensajes del mismo.
  • Un mensaje reformulado por sí solo es inútil en la mayoría de las circunstancias.
  • No utilices jerga de diseñadores como «hamburger», «nav» o «comps».
  • Considera escribir un glosario de los términos técnicos utilizados en tu módulo. Si lo haces, enlázalo desde la documentación de los mensajes.

Puedes enlazar a otros mensajes mediante {{msg-mw|message key}}. Procura hacerlo si hay partes del mensaje que provienen de otros (en caso de que esto no se pueda evitar) o si algunos mensajes se muestran juntos o en el mismo contexto.

translatewiki.net proporciona algunas plantillas predeterminadas para la documentación:

  • {{doc-action|[...]}} - para mensajes action-
  • {{doc-right|[...]}} - para mensajes right-
  • {{doc-group|[...]|[...]}} - para mensajes relacionados con grupos de usuarios (group, member, page, js y css)
  • {{doc-accesskey|[...]}} - para mensajes accesskey-

Echa un vistazo a las páginas de las plantillas para más información.

Pautas de internacionalización

Además de la documentación, los traductores piden a los desarrolladores que tengan en consideración unas pautas para facilitar su trabajo, ser más eficientes y permitir una localización real y de calidad para todos los idiomas. Incluso aunque sólo se vayan a añadir o editar mensajes en inglés, se deben tener en cuenta las necesidades de todos los idiomas. Cada mensaje se traduce a más de 300 idiomas y esto debería hacerse de la mejor manera posible. La correcta implementación de estas pautas muy a menudo te ayudará a escribir mejor los mensajes incluso en inglés.

Localización#Ayuda e información de contacto enumera los sitios principales donde puedes conseguir la asistencia de personas experimentadas en lo que respecta a la internacionalización.

Utiliza adecuadamente los parámetros y selectores de los mensajes

Es un prerrequisito para la correcta redacción de tus mensajes.

Evita la reutilización de mensajes

Los traductores recomiendan evitar la reutilización de mensajes. Esto puede parecer antiintuitivo, ya que copiar y duplicar código suele ser una mala práctica, pero en los mensajes de sistema a menudo es necesario. Aunque dos conceptos se puedan expresar con la misma palabra en inglés, no es necesariamente el caso en todos los idiomas. «OK» es un buen ejemplo: en inglés se utiliza para una etiqueta de botón genérica, pero en algunos idiomas se prefiere utilizar una etiqueta de botón relacionada con la operación que se va a realizar al pulsar el botón. Otro ejemplo es prácticamente cualquier adjetivo: una palabra como «several» cambia en función del género en muchos idiomas (por ejemplo, en español, «varios» o «varias»), por lo que no debes reutilizarla para describir cosas distintas y en su lugar debes crear varios mensajes separados.

Si vas a añadir varios mensajes idénticos, procura añadir documentación para describir las diferencias en sus contextos. No te preocupes por el trabajo extra de los traductores. La memoria de traducción ayuda mucho en casos así a la vez que se preserva la flexibilidad de disponer de traducciones diferentes si es necesario.

Evita los mensajes fragmentados o en forma de «patchwork»

Los distintos idiomas varían en el orden de las palabras y tienen complejas reglas gramaticales y sintácticas. Los mensajes formados por varias piezas de texto, posiblemente con alguna indirección, también denominados «concatenación de cadenas», en en código que los traductores no pueden controlar directamente, se conocen en la jerga de los desarrolladores como «lego» o «patchwork». Es prácticamente imposible traducir correctamente este tipo de mensajes.

Haz que cada mensaje sea una frase completa. Normalmente se pueden combinar varias frases con mucha mayor facilidad en un único bloque de texto, si es necesario. Cuando desees combinar varias cadenas en un mensaje, pásalas en forma de parámetros, ya que los traductores podrán ordenarlas correctamente para su idioma.

Mensajes que citan otros mensajes

Una excepción a la regla son mensajes que se refieren a otros mensajes: «Introduce el nombre del autor original en el campo '{{int:name}}' y haz clic en '{{int:proceed}}' cuando acabes». Esto hace que el mensaje sea consistente si en el futuro un desarrollador de software o un operador del wiki altera los mensajes name («nombre») y proceed («proceder»). Sin el truco del int, cada vez que los desarrolladores y operadores alteraran un mensaje, tendrían que tener en cuenta todos los mensajes relacionados que necesitaran los ajustes correspondientes.

Escribe los mensajes en un lenguaje natural

En la medida de lo posible, escribe mensajes en un lenguaje natural, humano. Prueba a leer el mensaje en voz alta y piensa: ¿suena a un inglés correcto, gramatical, a un inglés que habla la gente? Si es complejo, difícil de pronunciar o por el motivo que sea no resulta natural en inglés, será aún más difícil para los traductores y para los usuarios en otros idiomas.

Evita el uso de signos de puntuación que resulten demasiado técnicos o burocráticos o que no puedan leerse en voz alta. La barra (/) normalmente debería ser reemplazada por or. And/or debería ser reemplazado por and o or. Las frases donde se utiliza la coma para unir proposiciones independientes (comma splice) deberían dividirse en frases más cortas.

No utilices términos y plantillas que sean específicos de un proyecto en particular

Hay una gran diversidad de personas que utilizan MediaWiki, ya sea dentro del movimiento Wikimedia como fuera de él. Aunque se construyó en primer lugar para una enciclopedia, en la actualidad se utiliza para diversos tipos de contenido. Por lo tanto, utiliza términos generales. Por ejemplo, evita utilizar términos como article («artículo») y utiliza en su lugar page («página») a menos que tengas la completa seguridad de que la funcionalidad que estás desarrollando sólo se va a utilizar en un sitio cuyas páginas se denominen «artículos». No utilices village pump, que es el nombre de la página de la comunidad de Wikipedia en inglés. En su lugar, utiliza un término genérico, como community discussion page («página de discusión de la comunidad»).

No des por sentado que una determinada plantilla existe en todos los wikis. Las plantillas son locales en cada wiki. Esto se aplica tanto a los mensajes de origen como a sus traducciones. Si los mensajes utilizan plantillas, sólo funcionarán si se crean las plantillas correspondientes en cada wiki donde se vaya a desplegar la funcionalidad. Es mejor evitar por completo el uso de plantillas en los mensajes. Si de verdad necesitas utilizarlas, debes documentarlo claramente en la documentación del mensaje y en las instrucciones de instalación de la extensión.

Separa las fechas y horas en las frases

En algunos idiomas hay que insertar algo entre la fecha y la hora que depende gramaticalmente de otras palabras en la frase. Por lo tanto, no se podrá utilizar una combinación fecha/hora. En otros idiomas, esta combinación puede ser conveniente; por lo tanto, la mejor opción es proporcionar en estos casos tres parámetros (fecha/hora, fecha y hora) y que en la traducción se deje vacío ya sea el primero o los dos últimos según sea necesario.

Evita utilizar {{SITENAME}} en los mensajes

{{SITENAME}} tiene varias desventajas. Puede ser cualquier cosa (acrónimo, palabra, frase corta, etc.) y, en función del idioma, puede requerir el uso de {{GRAMMAR}} en cada ocurrencia. Independientemente de ello, cada mensaje que contenga {{SITENAME}} necesitará ser revisado en la mayoría de idiomas en cada uno de los wikis en los que se instale tu código. En la mayoría de casos, cuando no hay una configuración general de GRAMMAR para un idioma, los operadores del wiki tendrán que añadir o enmendar el código PHP para que {{GRAMMAR}} funcione correctamente en {{SITENAME}}. Esto requiere de más habilidades y de un mejor entendimiento que la alternativa. Es más conveniente recurrir a referencias genéricas como «este wiki». Esto no impide que en las instalaciones se alteren localmente estos mensajes para utilizar {{SITENAME}}, pero al menos no será necesario hacerlo, y se podrá posponer la adaptación de los mensajes hasta que el wiki esté activo y en uso.

Evita referirte a la presentación visual y a las posiciones

Lo que ves y la posición en la que lo ves depende de la apariencia utilizada. La mayoría de las veces, la presentación de elementos en pantalla está reflejada en los idiomas que se escriben de izquierda a derecha respecto de los idiomas que se escriben de derecha a izquierda, pero no siempre, y para algunos idiomas y wikis, no por completo. Los dispositivos portátiles, las ventanas estrechas, etc. pueden mostrar bloques uno debajo del otro, cuando en pantallas más grandes se mostrarían uno al lado del otro. Dado que los scripts de JavaScript y los accesorios a nivel de sitio, así como los escritos por los usuarios, pueden exhibir comportamientos (y lo hacen) como esconder o mover partes de forma impredecible, no hay una forma fiable de determinar la presentación real.

Es incorrecto vincular la información de presentación al idioma del contenido, ya que el idioma de la interfaz de usuario puede no coincidir con el idioma del contenido de la página, y la presentación puede ser una mezcla de características de los dos dependiendo de las circunstancias. Los agentes de usuario no visuales tales como los lectores de pantalla acústicos y otros dispositivos auxiliares ni siquiera tienen un concepto de presentación visual. Por lo tanto, no deberías hacer referencia a la posición de los elementos en su presentación en pantalla, aunque siguen siendo aceptables términos semánticos de presentación («pasos anteriores del formulario», etc.).

MediaWiki no soporta la visualización de mensajes o fragmentos de mensajes diferentes en función de la direccionalidad actual de la interfaz (véase T30997).

El soporte venidero por parte de los navegadores y de MediaWiki de sistemas de escritura de arriba abajo de Asia Oriental y del Norte[2] hará que las presentaciones en pantalla sean aún más impredecibles, al haber al menos ocho posibilidades (posición inicial en la dimensión horizontal, a la izquierda o a la derecha; en la dimensión vertical, arriba o abajo; y cuál de las dos dimensiones tiene prioridad en el flujo del texto).

Evita referirte a colores en pantalla

El color en el que se muestra algo depende de muchos factores, incluyendo apariencias, scripts de JavaScript y accesorios a nivel de sitio o escritos por los usuarios, así como la configuración del agente de usuario local por motivos de accesibilidad o por limitaciones tecnológicas. Los agentes de usuario no visuales como los lectores de pantalla acústicos y otros dispositivos auxiliares ni siquiera disponen de un concepto de color. Por lo tanto, no deberías hacer referencia a colores en pantalla. (Tampoco deberías depender del color por sí solo como mecanismo para informar al usuario del estado por la misma razón.)

Evita utilizar marcado que no se tenga que traducir

El marcado HTML que no requiera traducción, por ejemplo, etiquetas ‎<div> que encierran elementos, reglas en la parte superior o inferior, etc. normalmente no deberían ser parte de los mensajes. Es una carga innecesaria para los traductores, quienes a menudo la alteran o la pasan por alto en el proceso de traducción. La interfaz de traducción no dispone de resaltado ni de validación de sintaxis, y los errores son habituales.

Evita asimismo utilizar un marcado complejo de wikitexto. El wikitexto a veces resulta más sucinto que escribir lo mismo en PHP, y es tentador escribir algo como:

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.

Sin embargo, esto es difícil para los traductores, especialmente a la hora de traducir a idiomas que se escriben de derecha a izquierda, ya que algunas partes del mensaje deben permanecer en inglés, lo que resulta en que la dirección del texto cambia muchas veces en una sola línea:

هذه هي [[{{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||ينتظر|ينتظران|تنتظر|ينتظر}} المراجعة.

Es mejor pasar los destinos de los enlaces como parámetros de los mensajes y ceñirte a un marcado simple como [$1 Etiqueta] y [[$1|Label]].

¡Los mensajes traducidos suelen ser más largos de lo que crees!

Al recorrer archivos de mensajes en otros idiomas, casi nunca vas a encontrar mensajes traducidos más cortos que los mensajes en chino y rara vez los vas a encontrar más cortos que en inglés. Sin embargo, a menudo encontrarás traducciones mucho más largas que los textos en inglés.

Sobre todo en los formularios, delante de los campos de entrada, los mensajes en inglés tienden a ser cortos y sucintos. Esto a menudo no se mantiene en las traducciones. Otros idiomas pueden carecer del vocabulario técnico presente en inglés y deben recurrir a explicar algunos conceptos con varias palabras o incluso frases enteras. Por ejemplo, el breve mensaje en inglés TSV file: («Archivo de valores separados por tabuladores:») podría tener que traducirse en otro idioma literalmente como:

Por favor, escribe aquí un nombre que denota una colección de datos informáticos que se compone de una serie de líneas de texto mecanografiado organizadas secuencialmente, cada una de las cuales a su vez se compone de una serie de campos de información, donde dichos campos de información están separados entre sí y las separaciones entre ellos son signos individuales del tipo que hace que el carro de una máquina de escribir se desplace hasta la siguiente posición predefinida. Vamos allá: _____ (gracias)

De acuerdo, este es un ejemplo extremo, pero te puede dar una idea. Imagina esta frase en una columna en un formulario donde cada palabra ocupa una línea propia y el campo de entrada de texto está centrada verticalmente en la siguiente columna. :-(

Evita utilizar palabras muy próximas, similares o idénticas para denotar conceptos diferentes

Por ejemplo, las páginas pueden tener revisiones anteriores (de una fecha, hora y edición específicas) que comprende versiones anteriores de dicha página. Las palabras revisión y versión se pueden utilizar indistintamente. Pero surge un problema cuando las versiones de las páginas son revisadas y se menciona asimismo la revisión, es decir, el proceso de revisarlas. Esto puede que no suponga un problema grave cuando los dos sinónimos de «revisión» tienen distintas traducciones. Pero no confíes en ello. Es mejor evitar por completo el uso de «revisión» en el sentido de «versión» para evitar que se interprete de forma errónea.

Las palabras básicas pueden tener connotaciones imprevistas o no existir en absoluto

Algunas palabras son difíciles de traducir debido a su uso muy específico en MediaWiki. Algunas no deben traducirse en absoluto. Por ejemplo, en algunos idiomas no existe una palabra similar a «usuario» que designe a «alguien que usa algo». De manera similar, en el dialecto colonés (kölsch), los términos ingleses namespace («espacio de nombres») y apartment («apartamento») se traducen por una misma palabra. Además, en colonés, dicen «corroborador y participante» en una palabra ya que cualquier referencia a «usar» implicaría sistemáticamente «abusar». El término wiki farm («granja de wikis») se traduciría como «establo lleno de wikis», ya que en ese idioma la palabra «granja» implica que da varios tipos de productos, por lo que no se entendería una granja de una sola cosa, etc..

Utiliza las etiquetas ‎<code>, ‎<var> y ‎<kbd> donde haga falta

Cuando hables sobre parámetros técnicos, valores o entradas de teclado, márcalos apropiadamente mediante las etiquetas HTML ‎<code>, ‎<var> y ‎<kbd>. Así, se distinguirán tipográficamente del texto normal. Esto clarifica su significado a los lectores, evitando confusiones, errores y malas interpretaciones. Asegúrate de que tu manejador de mensajes permite este marcado.

Los símbolos, dos puntos, corchetes, etc. son partes de mensajes

Muchos símbolos también se pueden localizar. Algunos sistemas de escritura tienen otros tipos de corchetes diferentes de los que se utilizan en la escritura latina. En algunos idiomas, puede que no sea adecuado añadir un carácter de dos puntos después de una etiqueta o un mensaje de entrada de texto. Incluir estos símbolos en los mensajes ayuda a mejorar las traducciones y hacerlas menos anglocéntricas, y además reduce el desorden en el código.

Por ejemplo, hay distintas convenciones para el uso de las comillas en «noruego», ”sueco”, »danés«, „alemán” y 「japonés」.[3]

Si necesitas encerrar algún texto entre paréntesis, corchetes o comillas localizadas, puedes utilizar los mensajes parentheses ($1), brackets [$1] o quotation-marks "$1", así:

wfMessage( 'parentheses' )->rawParams( /* texto entre paréntesis */ )->escaped()
wfMessage( 'brackets' )->rawParams( /* texto entre corchetes */ )->escaped()
wfMessage( 'quotation-marks' )->rawParams( /* texto entre comillas */ )->escaped()

No asumas que los símbolos y la puntuación sobrevivan a la traducción

Los idiomas que se escriben de derecha a izquierda (al contrario que el inglés o el español) suelen intercambiar los símbolos de flechas que se presentan en enlaces «siguiente» y «anterior», y pueden (o no) intercambiar también su ubicación respecto del texto del mensaje. Las elipsis pueden traducirse como «etc.» o en forma de palabras. Puede que los signos de interrogación y de exclamación y los dos puntos se pongan en un lugar diferente del final de la frase, que no se pongan o que se pongan dos veces. Debido a ello, procura incluirlos siempre en el texto de sus mensajes y nunca trates de insertarlos programáticamente.

Escribe el punto final

Asegúrate de terminar las frases normales con un punto. A menudo, es el único indicador que tiene el traductor para saber que no se trata de titulares ni de elementos de una lista, que pueden tener que traducirse de forma diferente.

Utiliza textos significativos en los enlaces

Asegúrate de que el texto del enlace describe adecuadamente la página de destino. Evita siempre utilizar palabras comunes y genéricas. Por ejemplo, «Pincha aquí» nunca es aceptable,[4] ya que las páginas de destino casi nunca tratan sobre «pinchar aquí». En lugar de ello, utiliza palabras de acción precisas que indiquen lo que va a obtener el usuario cuando siga el enlace, como «Puedes subir un archivo si lo deseas».

Véanse también Ayudar a los usuarios a predecir adónde van, Navegación a ciegas y Las principales razones para no utilizar pincha aquí como texto de enlace.

Evita la jerga y el argot

Evita utilizar en los mensajes la jerga de los desarrolladores o de los usuarios más experimentados. Procura utilizar un lenguaje más simple donde sea posible. Evita expresiones como success («éxito»), fail («fracaso»), error occurred while («se produjo un error mientras»), etc., cuando desees notificar al usuario de que algo sucedió o no sucedió. Esto proviene de la perspectiva de los desarrolladores de verlo todo en términos de verdadero o falso, pero a menudo los usuarios sólo quieren saber qué ocurrió o no, y qué tienen que hacer al respecto (si es que tienen que hacer algo). Por lo tanto:

  • «El archivo fue renombrado con éxito» → «El archivo fue renombrado»
  • «El cambio de nombre del archivo falló» → «Ya existe un archivo con este nombre. Elige un nombre diferente.»

Ten cuidado con los espacios en blanco y los saltos de línea

Los mensajes localizados de MediaWiki se suelen editar dentro del wiki, ya sea mediante operaciones wiki en wikis activos o mediante los traductores en translatewiki.net. Debes tener en cuenta cómo el espacio en blanco, especialmente al principio y al final de tu mensaje, afectará a los editores.

  • El editor de wikitexto siempre eliminará automáticamente los espacios y los saltos de línea (nuevas líneas) al final de los mensajes. Tus mensajes no deben terminar con un espacio o un salto de línea, ya que se perderá cuando se edite en el wiki.
  • Los espacios y saltos de línea iniciales no se eliminan automáticamente, pero es probable que se eliminen por accidente durante la edición, por lo que también deben evitarse.

Procura que tus mensajes empiecen y terminen con texto real; si necesitas añadir una línea nueva o un salto de línea al principio o al final, el código circundante debería encargarse de añadírselo al texto devuelto.

Algunos mensajes requieren un espacio al final, como 'word-separator' (que consiste en un solo carácter de espacio en la mayoría de los idiomas). Para dar soporte a estos casos de uso, las siguientes entidades HTML están permitidas en los mensajes y son convertidas a los caracteres finales incluso aunque el mensaje por otra parte no permitiera el uso de wikitexto o el formato HTML:[5]

En relación con esto, cualquier otro elemento sintáctico afectado por transformaciones antes del guardado tampoco debe utilizarse en los mensajes, ya que será convertido cuando se edite el mensaje en el wiki.

Utiliza las convenciones estándar de mayúsculas

El uso de mayúsculas y minúsculas da indicaciones a los traductores sobre la naturaleza de lo que están traduciendo: palabras sueltas, elementos de lista o de menú o frases completas. La capitalización correcta (estándar) también puede tener un rol en la evaluación de tus páginas por parte de los motores de búsqueda. MediaWiki utiliza la capitalización de oración (Jovencillo emponzoñado de whisky: ¡qué figurota exhibe!) en los mensajes de interfaz.

Recuerda también que muchos sistemas de escritura carecen por completo de distinción entre mayúsculas y minúsculas y que algunos de los que la tienen la emplean de forma diferente al inglés. Por tanto, no escribas TODO EN MAYÚSCULAS para dar énfasis. Utiliza CSS o las etiquetas HTML ‎<em> o ‎<strong> como se indica a continuación:

Énfasis

En el texto normal, el énfasis en forma de negritas, cursiva o similar debería formar parte de los mensajes. Las convenciones locales sobre el énfasis suelen variar, en particular, algunas escrituras asiáticas tienen las suyas propias. Los traductores deben poder ajustar el énfasis a sus idiomas y áreas de destino. Trata de utilizar «‎<em>» y «‎<strong>» en tu interfaz de usuario para permitir el marcado en función del idioma o del sistema de escritura.

En las presentaciones en pantalla actuales de estilos anglófonos y europeos, el énfasis se utiliza menos. Indícalo igualmente en la #Documentación de los mensajes, ya que puede dar indicaciones valiosas sobre cómo traducir. En énfasis puede y debe utilizarse en otros contextos culturales según proceda, siempre que los traductores lo conozcan.


Véase también

Notas