API:Localisation/es

Versión de MediaWiki:

≥ 1.25 Gerrit change 160798

Esto documenta cosas específicas para 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.

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.

• • Prior to 1.30, a apihelp-$path-description message was used. This was be overridden by implementing the getDescriptionMessage() method, but cases where that was needed were rare.
• The parameter description messages, formerly returned by the getParamDescription() method, are apihelp-$path-param-$name (where $name is the key from getAllowedParams()). This may be overridden by setting a value for ApiBase::PARAM_HELP_MSG in the data structure returned from getAllowedParams().
  • Parameters with a description similar to "When more results are available, use this to continue" should use api-help-param-continue instead of redefining a duplicate message.
  • Sorting parameters taking values "newer" and "older" (with related "start" and "end" parameters) should use api-help-param-direction instead of redefining a duplicate message.
  • Modules using CSRF tokens by implementing needsToken() do not need to document the token parameter; this is automatically handled by ApiBase.
  • Several additional constants are available for use in getAllowedParams(); see ApiBase for details.
• Parameters with an array for ApiBase::PARAM_TYPE may use ApiBase::PARAM_HELP_MSG_PER_VALUE to specify that each value is individually documented. 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).
• All examples must have a descriptive text. Message names should be along the lines of apihelp-$path-example-$arbitrarySuffix.

Documentación de los mensajes

When documenting the messages in qqq.json, use the following templates:

• {{doc-apihelp-summary|module path}}
• {{doc-apihelp-extended-description|module path}}
• {{doc-apihelp-param|module path|parameter name}}
• {{doc-apihelp-paramvalue|module path|parameter name|parameter value}}
• {{doc-apihelp-example|module path}}

Formato de los mensajes

All messages should end with a period, and be grammatical sentences. For parameters passed to the messages by default, see the templates linked from #Message documentation.

Use semantic wikitext markup in messages:

• ‎<var> for mention of parameter keys, and also references to variables like $wgMiserMode.
• ‎<kbd> for the possible values of parameters, mention of parameters with values (including references to other modules), and the mention of the input values in example docs.
• ‎<samp> for mention of keys or values in the API output.
• ‎<code> for anything else that's computer code, e.g. "the max-age header" or "the page ‎<head>".
• You don't need additional quotation marks when using semantic markup.

If you need to reference other API modules, pipe a link to Special:ApiHelp and the help formatter will do the right thing. For example, "[[Special:ApiHelp/query+tokens|action=query&meta=tokens]]" is used in the documentation for various token parameters. The Special:ApiHelp link properly renders as an in-page anchored link if it's on the same help page (example). Similarly, reference to MediaWiki configuration variables such as $wgMiserMode should link to the documentation on mediawiki.org.

Pages referenced in examples should generally not be linked, as these links are unlikely to exist on many wikis.

Errores y alertas

Errors are raised by calling $this->dieWithError( $messageObjectOrKey ); and the message can be localized in the usual way. Likewise for warnings with $this->addWarning( $messageObjectOrKey );. See API:Errores y advertencias for details.

Customarily API error messages have message keys starting with apierror- and warnings with apiwarn-.

Texto en respuestas de API

ApiBase, and thus all API modules, are also context sources. Messages should generally be accessed using $this->msg(), and the API module itself should generally be passed when an IContextSource is needed.

Messages should not be arbitrarily included in the output because a client might find it useful.

Mejorar las regionalizaciones en Translatewiki

You can add and improve API help message translations on translatewiki.net, in the same manner as other core MediaWiki messages. The relevant message groups include

• MediaWiki action API
• API feature usage

Véase también

• API/Architecture_work/i18n – Draft document with information for converting old API modules to the new system.