API:Yerelleştirme
Bu sayfa MediaWiki Eylem API'si belgelerinin bir parçasıdır. |
MediaWiki sürümü: | ≥ 1.25 Gerrit change 160798 |
Bu, MediaWiki eylem API'sinin (api.php
) yerelleştirilmesine özgü şeyleri belgeler.
MediaWiki yerelleştirmesi hakkında genel yorumlar için Yerelleştirme sayfasına bakın.
Mesaj dosyaları
MediaWiki çekirdeği için yerelleştirme mesajları includes/api/i18n altında bulunur.
Uzantılar için, yalnızca API belgesi için kullanılan ve çoğu son kullanıcı tarafından görülmeyen mesajlar birden fazla dosya için normal mekanizmalar kullanılarak ayrı bir dosyada olmalıdır. Yeni mesaj eklemeyle ilgili yerelleştirme belgelerine bakın.
Yardım mesajları
Adlandırma
API modülleri için yardım mesajları, action=help “modules” parametresi için kullanılan dize olan "module path" kullanılarak adlandırılır. $wgAPIModules ile eklenen modüller için bu, bu dizide kullanılan anahtarla aynı olurken, $wgAPIPropModules , $wgAPIListModules veya $wgAPIMetaModules ile eklenen modüller için, "query+" önekine sahip anahtar olacaktır.
- Daha önce getDescription() yöntemi tarafından döndürülen açıklama iletisi ikiye bölünmüştür: modülün tek satırlık özetini içeren bir
apihelp-$path-summary
mesajı ve modül düzeyinde ek belgeler içeren birapihelp-$path-extended-description
. Bunlar, karşılık gelen yöntemlerle geçersiz kılınabilir, ancak bunun gerekli olduğu durumlar nadirdir.- 1.30'dan önce bir
apihelp-$path-description
mesajı kullanıldı. Bu, $1 yöntemi uygulanarak geçersiz kılındı, ancak bunun gerekli olduğu durumlar nadirdi. This was be overridden by implementing the getDescriptionMessage() method, but cases where that was needed were rare.
- 1.30'dan önce bir
- Daha önce getParamDescription() yöntemi tarafından döndürülen parametre açıklama iletileri
apihelp-$path-param-$name
(burada$name
, getAllowedParams() öğesinin anahtarıdır). Bu, getAllowedParams() üzerinden döndürülen veri yapısındaApiBase::PARAM_HELP_MSG
için bir değer ayarlanarak geçersiz kılınabilir.- "Daha fazla sonuç olduğunda, devam etmek için bunu kullanın" benzeri bir açıklamaya sahip parametreler, yinelenen bir iletiyi yeniden tanımlamak yerine api-help-param-continue kullanmalıdır.
- "newer" ve "older" (ilgili "start" ve "end" parametreleriyle) değerleri alan parametreleri sıralamak, yinelenen bir iletiyi yeniden tanımlamak yerine api-help-param-direction kullanmalıdır.
needsToken()
uygulayarak CSRF anahtarını kullanan modüllerin token parametresini belgelemeleri gerekmez; bu ApiBase tarafından otomatik olarak yapılır.- Birkaç ek sabit getAllowedParams() olarak kullanılabilir; ayrıntılar için ApiBase bakın.
ApiBase::PARAM_TYPE
dizisi olan parametreler, her değerin ayrı ayrı belgelendiğini belirtmek içinApiBase::PARAM_HELP_MSG_PER_VALUE
kullanabilir. Bu iletiler varsayılan olarakapihelp-$path-paramvalue-$name-$value
şeklindedir. İletiler varsayılana göre adlandırılmışsa, iletileriApiBase::PARAM_HELP_MSG_PER_VALUE
dizisindeki değerlerle eşleştirmeye gerek yoktur (yine de var olması gerekir, ancak boş bırakılabilir). These messages are by defaultapihelp-$path-paramvalue-$name-$value
. If the messages are named according to the default, there is no need to map messages to values in theApiBase::PARAM_HELP_MSG_PER_VALUE
array (it still has to exist but can be left empty).- Tüm örneklerde açıklayıcı bir metin bulunmalıdır. Mesaj adları
apihelp-$path-example-$arbitrarySuffix
satırları boyunca olmalıdır. Message names should be along the lines ofapihelp-$path-example-$arbitrarySuffix
.
Mesaj belgesi
qqq.json içindeki mesajları belgelendirirken aşağıdaki şablonları kullanın:
{{doc-apihelp-summary|modül yolu}}
{{doc-apihelp-description|module path}}
{{doc-apihelp-extended-description|modül yolu}}
{{doc-apihelp-param|modül yolu|parametre adı}}
{{doc-apihelp-paramvalue|modül yolu|parametre adı|parametre değeri}}
{{doc-apihelp-paraminfo|module path|parameter info tag name}}
{{doc-apihelp-example|modül yolu}}
Mesaj biçimlendirme
Tüm mesajlar bir nokta ile bitmeli ve gramer cümleleri olmalıdır. Varsayılan olarak iletilere iletilen parametreler için #Mesaj belgesi'nden bağlanan şablonlara bakın.
İletilerde anlamsal vikimetin işaretlemesi kullanın:
- Parametre anahtarları için
<var>
ve ayrıca $wgMiserMode gibi değişkenlere kaynakçası. - Parametrelerin olası değerleri, değerlere sahip parametrelerden bahsedilmesi (diğer modüllere kaynakça dahil) ve örnek belgelerdeki giriş değerlerinden bahsedilmesi için
<kbd>
. - API çıkışındaki anahtarlardan veya değerlerden bahsetmek için
<samp>
. - Bilgisayar kodu olan herhangi bir şey için
<code>
, ör. "max-age
üstbilgisi" veya "<head>
sayfası". - Anlamsal işaretleme kullanırken ek tırnak işaretlerine ihtiyacınız yoktur.
Diğer API modüllerine kaynağınız gerekiyorsa, bağlantıyı Special:ApiHelp ile bağlayın ve yardım biçimlendiricisi doğru olanı yapacaktır.
Örneğin, belgelerde çeşitli token parametreleri için "[[Special:ApiHelp/query+tokens|action=query&meta=tokens]]
" kullanılır.
Special:ApiHelp bağlantısı, aynı yardım sayfasındaysa, sayfaya bağlı bir bağlantı olarak düzgün bir şekilde görüntülenir (örnek).
Benzer şekilde, $wgMiserMode gibi MediaWiki yapılandırma değişkenlerine yapılan kaynaklar, mediawiki.org'daki belgelere bağlanmalıdır.
Örneklerde atıfta bulunulan sayfalar genellikle bağlantılı olmamalıdır, çünkü bu bağlantıların pek çok vikide bulunması olası değildir.
Hata ve uyarılar
Hatalar $this->dieWithError( $messageObjectOrKey );
çağrılarak ortaya çıkar ve mesaj her zamanki gibi yerelleştirilebilir. Aynı şekilde $warning-snippet ile yapılan uyarılar için.
Likewise for warnings with $this->addWarning( $messageObjectOrKey );
.
Ayrıntılar için API:Errors and warnings sayfasına bakın.
Genellikle API hata mesajlarında apierror-
ile başlayan mesaj anahtarları ve apiwarn-
ile uyarı bulunur.
Mesaj belgelerinde {{doc-apierror}}
kullanabilirsiniz.
API yanıtlarındaki metin
ApiBase ve dolayısıyla tüm API modülleri de bağlam kaynaklarıdır. İletilere genellikle $code kullanılarak erişilmeli ve API modülünün kendisine genellikle bir IContextSource gerektiğinde iletilmelidir.
Messages should generally be accessed using $this->msg()
, and the API module itself should generally be passed when an IContextSource is needed.
Bir istemci yararlı bulabileceğinden, iletiler keyfi olarak çıkışa dahil edilmemelidir.
Translatewiki'deki yerelleştirmeleri geliştirme
translatewiki.net adresindeki API yardım mesajı çevirilerini diğer temel MediaWiki iletilerinde olduğu gibi ekleyebilir ve geliştirebilirsiniz. İlgili mesaj grupları şunları içerir: The relevant message groups include
Ayrıca bakınız
- API/Architecture_work/i18n – Eski API modüllerini mevcut sisteme dönüştürmek için bilgi içeren 2014 tarihli taslak belge.