API:Lokalisation

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

Outdated translations are marked like this.

Diese Seite ist Teil der Dokumentation der MediaWiki action API.

MediaWiki Version:

≥ 1.25

Diese Seite dokumentiert Dinge, die bei der Lokalisation der MediaWiki Action API (api.php) spezifiziert werden müssen. Siehe Lokalisation für allgemeine Informationen zur Lokalisation von MediaWiki.

Nachrichtendateien

Lokalisierungsnachrichten für den MediaWiki-Kern befinden sich unter includes/api/i18n.

Für Erweiterungen sollten sich die Nachrichten, die nur von der API-Dokumentation genutzt werden und von den meisten Benutzern nicht gesehen werden, in einer separaten Datei befinden und den normalen Mechanismus für mehrere Dateien nutzen. Siehe die Lokalisierungs-Dokumentation zum Hinzufügen neuer Nachrichten.

Hilfemeldungen

Benennung

Die Hilfenachrichten für API-Module nutzen als Namenspfad den "Modul-Pfad", wobei es sich um die Zeichenkette handelt, die für den Parameter action=help des "Moduls" genutzt wird. Für zu $wgAPIModules hinzugefügte Module ist dies der gleiche Schlüssel, der in dem Array genutzt wird, während für zu $wgAPIPropModules , $wgAPIListModules oder $wgAPIMetaModules hinzugefügte Module der Schlüssel das Präfix "query+" erhält.

Die Beschreibungsnachricht, früher über die Methode getDescription() ausgegeben, wurde auf zwei aufgeteilt: eine Nachricht apihelp-$path-summary mit einer einzeiligen Beschreibung des Moduls und eine apihelp-$path-extended-description, die zusätzliche Modul-Level-Dokumentation enthält. Diese kann über entsprechende Methoden überschrieben werden, was jedoch nur in seltenen Fällen erforderlich ist.
- Vor 1.30 wurde eine Beschreibung apihelp-$path-description genutzt. Dies wurde durch Implementation der Methode $1 überschrieben, wobei dies nur in seltenen Fällen benötigt wurde. This was be overridden by implementing the getDescriptionMessage() method, but cases where that was needed were rare.
Die Parameterbeschreibungsnachrichten, früher über die Methode getParamDescription() ausgegeben, sind apihelp-$path-param-$name (wobei $name der Schlüssel aus getAllowedParams() ist). Dies kann durch Setzen eines Wertes für ApiBase::PARAM_HELP_MSG in der aus getAllowedParams() ausgegebenen Datenstruktur überschrieben werden.
- Parameter mit einer Beschreibung, die "Wenn weitere Ergebnisse verfügbar sind, nutze dies, um fortzufahren" ähnelt, sollten api-help-param-continue nutzen, statt eine doppelte Nachricht neu zu definieren.
- Sortierungparameter, die Werte "neuer" und "älter" übernehmen (mit entsprechenden Parametern "Start" und "Ende"), sollten api-help-param-direction nutzen, statt eine doppelte Nachricht neu zu definieren.
- Module, die CSRF-Token durch Implementation von needsToken() nutzen, müssen den Parameter token nicht dokumentieren; dies erfolgt automatisch über ApiBase.
- Zur Nutzung in getAllowedParams() sind viele zusätzliche Konstanten verfügbar; siehe ApiBase für Details.
Parameter mit einem Array für ApiBase::PARAM_TYPE können ApiBase::PARAM_HELP_MSG_PER_VALUE nutzen, um zu spezifizieren, dass jeder Wert individuell dokumentiert ist. Diese Nachrichten sind standardmäßig apihelp-$path-paramvalue-$name-$value. Wenn die Nachrichten nicht nach dem Standardverfahren benannt sind, ist es nicht nötig, Nachrichten zu Werten im Array ApiBase::PARAM_HELP_MSG_PER_VALUE zu erfassen (es muss weiterhin existieren, kann aber leer bleiben). 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).
Alle Beispiele müssen einen beschreibenden Text haben. Nachrichten sollten sich an den Zeilen von apihelp-$path-example-$arbitrarySuffix befinden. Message names should be along the lines of apihelp-$path-example-$arbitrarySuffix.

Nachrichtendokumentation

Nutze die folgenden Vorlagen zur Dokumentation der Nachrichten in qqq.json:

{{doc-apihelp-summary|Modulpfad}}
{{doc-apihelp-description|Modulpfad}}
{{doc-apihelp-extended-description|Modulpfad}}
{{doc-apihelp-param|Modulpfad|Parametername}}
{{doc-apihelp-paramvalue|Modulpfad|Parametername|Parameterwert}}
{{doc-apihelp-paraminfo|Modulpfad|Name der Parameterinformation}}
{{doc-apihelp-example|Modulpfad}}

Nachrichtenformatierung

Alle Nachrichten sollten mit einem Punkt enden und vollständige Sätze sein. Für Parameter, die standardmäßig an Nachrichten übergeben werden, siehe die unter #Nachrichtendokumentation verlinkten Vorlagen.

Verwenden Sie semantisches Wikitext-Markup in Nachrichten:

‎<var> für die Erwähnung von Parameterschlüsseln und auch Verweise auf Variablen wie $wgMiserMode.
‎<kbd> für die möglichen Werte von Parametern, Erwähnung von Parametern mit Werten (darunter Verweise auf andere Module) und die Erwähnung von Eingabewerten in der Beispieldokumentation.
‎<samp> für die Erwähnung von Schlüsseln oder Werten in der API-Ausgabe.
‎<code> für jeden anderen Computer-Code, z.B. "der max-age-Header" oder "die Seite ‎<head>".
Du musst keine zusätzlichen Anführungszeichen bei der Nutzung von semantischem Markup verwenden.

Wenn du auf andere API-Module verweisen musst, setze einen Link zu Special:ApiHelp und der Hilfe-Formatierer wird das richtige tun. Zum Beispiel wird "[[Special:ApiHelp/query+tokens|action=query&meta=tokens]]" in der Dokumentation für unterschiedliche token-Parameter genutzt. Der Link Special:ApiHelp wird als interner Anker-Link verwendet, wenn er sich auf der gleichen Seite befindet (Beispiel). Damit vergleichbar sollten Verweise auf die MediaWiki-Konfigurationsvariablen wie $wgMiserMode auf die Dokumentation auf mediawiki.org verlinken.

In Beispielen aufgeführte Verweise sollten generell nicht verlinkt werden, da diese Seiten in vielen Wikis nicht existieren werden.

Fehler und Warnungen

Fehler werden durch Anrufen von $this->dieWithError( $messageObjectOrKey ); angezeigt und die Nachrichten können wie üblich lokalisiert werden. Ähnliches gilt für Warnungen mit $warning-snippet. Likewise for warnings with $this->addWarning( $messageObjectOrKey );. Siehe API:Fehler und Warnungen für Details.

Gewöhnliche API-Fehlernachrichten haben Nachrichtenschlüssel, die mit apierror- beginnen und Warnungen, die mit apiwarn- beginnen. Du kannst in der Nachrichten-Dokumentation {{doc-apierror}} nutzen.

Text in API-Antworten

ApiBase und somit alle API-Module sind auch Verweisquellen. Auf Nachrichten sollte allgemein durch Nutzung von $code zugegriffen werden und das API-Modul selbst sollte allgemein übergeben werden, wenn eine IContextSource benötigt wird. Messages should generally be accessed using $this->msg(), and the API module itself should generally be passed when an IContextSource is needed.

Nachrichten sollten nicht willkürlich in die Ausgabe aufgenommen werden, da ein Client sie nützlich findet.

Verbesserung der Lokalisierung in translatewiki

Du kannst Übersetzungen von API-Hilfenachrichten auf translatewiki.net hinzufügen und verbessern, genau wie andere MediaWiki-Kernnachrichten. Die relevante Nachrichtengruppe enthält The relevant message groups include

Siehe auch

API/Architecture_work/i18n – Entwurf eines Dokuments von 2014 mit Informationen zur Konvertierung alter API-Module in das aktuelle System.