API:Localización

This page is a translated version of the page API:Localisation and the translation is 76% complete.

Outdated translations are marked like this.

Esta página es parte de la documentación de la API de acciones de MediaWiki.

Versión de MediaWiki:

≥ 1.25

Esto documenta aspectos específicos de la localización de la API de acción de MediaWiki (api.php). Véase Localisation para ver comentarios generales acerca de MediaWiki localisation.

Archivos de mensajes

Los mensajes de localización para el núcleo de MediaWiki se encuentran debajo de includes/api/i18n.

Para las extensiones, los mensajes que son solamente usados para la documentación de la API y que la mayoría de los usuarios finales no ven, deben estar en un archivo separado usando los mecanismos normales para tener múltiples archivos. Ver el localización de documentación sobre adición de nuevos mensajes.

Mensajes de ayuda

Denominación

Los mensajes de ayuda para los módulos API tienen un espacio de nombres usando la "ruta del módulo", que es la cadena utilizada para el parámetro "módulos" de action=help. Para los módulos agregados a $wgAPIModules , esta va a ser la misma que la clave utilizada en esa matriz, mientras que para los módulos agregados a $wgAPIPropModules , $wgAPIListModules o $wgAPIMetaModules será esa clave con el prefijo "query +".

El mensaje de descripción, anteriormente devuelto por el método getDescription(), se ha dividido en dos: un mensaje apihelp-$path-summary con resumen de una-línea del módulo y una

apihelp-$path-extended-description que contiene cualquier documentación adicional a nivel-módulo. Estos pueden anularse con los métodos correspondientes, aunque los casos en que es necesario son raros.

- Antes de la 1.30, se usaba un apihelp-$path-description mensaje. Esto se anuló implementando el método $1, pero los casos donde fué necesario fueron raros. This was be overridden by implementing the getDescriptionMessage() method, but cases where that was needed were rare.
Los mensajes de descripción del parámetro, anteriormente devueltos por el método getParamDescription(), es apihelp-$path-param-$name (dónde $nombre es la llave de getAllowedParams()). Esto puede ser borrado configurando un valor ApiBase::PARAM_HELP_MSG en la estructura de datos devuelta desde getAllowedParams()
- Parámetros con una descripción similar a "Cuándo más resultados estén disponibles, uso esto para continuar" tendría que utilizar api-help-param-continue en vez de redefinir un mensaje duplicado.
- Clasificando los parámetros que toman los valores "más nuevos" y "más viejos" (con parámetros relacionados de "inicio" y "fin" ) tendría que utilizar api-help-param-direction en vez de redefinir un mensaje duplicado.
- Los módulos que utilizan CSRF tokens para implementar needsToken() no necesitan parámetro para documentar el token; este es automáticamente manejado por ApiBase.
- Varias constantes adicionales están disponibles para usar en getAllowedParams(); ver ApiBase para más detalles.
Los parámetros con una matriz para ApiBase::PARAM_TYPE pueden usar ApiBase::PARAM_HELP_MSG_PER_VALUE para especificar que cada valor esté individualmente documentado. Estos mensajes son por defecto apihelp-"$path"- paramvalue-"$name"-"$value". Si los mensajes se nombran de acuerdo con el valor por defecto, no es necesario asignar mensajes a valores en la matriz ApiBase:: PARAM_HELP_MSG_PER_VALUE (todavía tiene que existir pero puede dejarse vacío). These messages are by default apihelp-$path-paramvalue-$name-$value. If the messages are named according to the default, there is no need to map messages to values in the ApiBase::PARAM_HELP_MSG_PER_VALUE array (it still has to exist but can be left empty).
Todos los ejemplos tienen que tener un texto descriptivo. Nombres de mensaje tendrían que estar a lo largo de las líneas de apihelp-"$camino"-ejemplo-"$arbitrarySuffix". Message names should be along the lines of apihelp-$path-example-$arbitrarySuffix.

Documentación de los mensajes

Al documentar los mensajes en qqq.json, usa las plantillas siguientes:

{{doc-apihelp-summary|Ruta del módulo}}
{{doc-apihelp-description|module path}}
{{doc-apihelp-extended-description|Ruta del módulo}}
{{doc-apihelp-param|Ruta del módulo|Nombre de parámetro}}
{{doc-apihelp-paramvalue|Ruta del módulo|Nombre de parámetro|Valor de parámetro}}
{{doc-apihelp-paraminfo|module path|parameter info tag name}}
{{doc-apihelp-example|Ruta del módulo}}

Formato de los mensajes

Todos los mensajes terminarían con un periodo, y ser frases gramaticales. Para los parámetros pasados a los mensajes por defecto, ver las plantillas enlazadas desde #documentación de Mensaje.

El uso semántico wikitext markup en mensajes:

‎<var> para mención de claves de parámetro, y también referencias a variables como $wgMiserMode.
‎<kbd> para los valores posibles de parámetros, mención de parámetros con valores (incluyendo referencias a otros módulos), y la mención de los valores de entrada en ejemplo docs.
‎<samp> para mención de claves o valores en la salida de la API.
‎<code> para cualquier otra cosa que sea código de computadora, p. Ej. "el encabezado max-age" o "la página ‎<head>".
No necesitas comillas adicionales cuando usas marcado semántico.

Si necesitas referenciar otros módulos API, canaliza un enlace a Special:ApiHelp y la ayuda del formateador hará lo correcto. Por ejemplo, "[[Special:ApiHelp/query+tokens|action=query&meta=tokens]]" es utilizado en la documentación para varios parámetros token. El enlace Special:ApiHelp se representa correctamente como un enlace anclado en la página si está en la misma página de ayuda (ejemplo). Similarmente, la referencia a las variables de configuración de MediaWiki como $wgMiserMode, enlazarían a la documentación en mediawiki.org.

Las páginas referenciadas en los ejemplos generalmente no deberían estar vinculadas, ya que es improbable que estos enlaces existan en muchos wikis.

Errores y alertas

Los errores se generan llamando a $this->dieWithError( $messageObjectOrKey ); y el mensaje puede ser localizado de la manera habitual. Del mismo modo para advertencias con $warning-snippet. Likewise for warnings with $this->addWarning( $messageObjectOrKey );. Ver API:Errores y advertencias para detalles.

Habitualmente, los mensajes de error de API tienen claves de mensaje que comienzan con apierror- y advertencias con apiwarn-. You can use {{doc-apierror}} in the message documentation.

Texto en respuestas de API

ApiBase y en consecuencia todos los módulos API, también son fuentes de contexto. Por lo general, se debe acceder a los mensajes usando $código, y el módulo API en sí generálmente debería se pasado cuando un IContextSource es necesitado. Messages should generally be accessed using $this->msg(), and the API module itself should generally be passed when an IContextSource is needed.

Los mensajes no tendrían que ser arbitrariamente incluidos en la salida porque un cliente lo podría encontrar útil.

Mejorar las regionalizaciones en Translatewiki

Puedes añadir y mejorar API traducciones del mensaje de ayuda en translatewiki.net, de la misma manera que otro núcleo de mensajes de MediaWiki. Los grupos de mensajes relevantes incluyen The relevant message groups include

Véase también

API/Architecture_work/i18n – Borrador del documento de 2014 con información para convertir los antiguos módulos de la API al sistema actual.