Nápověda:Rozšíření:Translate/Developer guide

Dokumentace pro Rozšíření:Translate

Pro překladatele (hlavní stránka nápovědy )

• Jak se překládá
• Osvědčené postupy
• Statistika a hlášení
• Záruka kvality
• Přehled o stavu překladu zpráv
• Offline překlad
• Slovníček

Pro správce překladů

• Jak připravit stránku k překladu
• Správa překladu stránky
• Překlad nestrukturovaných prvků
• Správa skupin
• Přesun překládané stránky
• Import překladů přes CSV
• Working with message bundles

Pro systémové administrátory a vývojáře

• Instalace
• Konfigurace
• Než začnete s vývojem
• Průvodce pro vývojáře
• Rozšíření Překladače
• Validátory (ověřovače)
• Zástupné prvky
• Konfigurace skupiny
• Příklad konfigurace skupiny
• Překladové paměti
• Nápověda překladatele
• Enabling message bundles
• Háčky PHP

Přeložte tuto šablonu

Rozšíření Translate je velké rozšíření se stovkami tříd. Tato stránka poskytuje pokyny pro vývojáře, kteří chtějí pracovat na kódu. Po přečtení této stránky a propojených dokumentů lépe pochopíte, jak je kód v Translate organizován a jaké speciální konvence se používají. Obecné zásady vývoje MediaWiki, konvence kódování a používání nástrojů jako Gerrit a Phabricator jsou mimo rozsah této statě. Předpokládá se, že tato témata znáte, a pokud se týkají Translate, nebudou se zde opakovat.

Rozšíření Translate prochází mnoha velkými migracemi současně. Zde uvádíme hlavní migrace, které právě probíhají, a podrobně popisujeme, který styl je preferován pro nový kód. Obecně platí, že při úpravách stávajícího kódu je lepší držet se aktuálního stylu a migrace provádět samostatně. Při osahávání kódu je v pořádku provést některá drobná čištění.

Migrace jmenného prostoru

Právě probíhá migrace veškerého kódu Translate pod jmenným prostorem \MediaWiki\Extension\Translate. Veškerý jmenný kód je umístěn v adresáři src/. Všechny nové soubory PHP by měly být umístěny do vhodného jmenného prostoru. Informace o tom, které jmenné prostory budou k dispozici, najdete v Extension:Translate/Namespaces . Jmenné prostory jsou organizovány podle domény, nikoli podle funkce. Ve jmenných prostorech a názvech tříd je potřebné se vyhnout zkratkám. Starší kód je v kořenovém adresáři úložiště a různých podadresářích.

V Gerritu SonarQube počítá pokrytí kontroly kódu pouze pro kód v adresáři src/.

Rozdělení testů na integrační a unit

Dříve se nerozlišovalo mezi integračními a unit testy. U nového kódu by hlavním typem testů měly být unit testy. Testy unit jsou umístěny v adresáři tests/phpunit/unit, který odpovídá rozložení jmenného prostoru. V tomto adresáři je Makefile pro snadné spuštění všech nebo částí testů unit během vývoje.

Typ prohlášení a komentáře

Každý nový kód by měl deklarovat parametry i návratové typy. Kromě toho by měly být povoleny přísné typy pomocí declare( strict_types = 1 );.

Díky deklaracím typů je nyní většina komentářů funkcí a metod nadbytečná, protože by pouze opakovaly názvy a typy parametrů. Z tohoto důvodu jsou linter (programátorský nástroj pro statickou analýzu kódu) kontroly na chybějící parametry nebo deklarace typu návratu zakázány pro kód pod src/ a tests/, které zhruba korelují s místy pomocí deklarací typu. U tohoto kódu nepřidávejte nadbytečnou dokumentaci, pokud neposkytuje další hodnotu. Jedním takovým příkladem je poskytnutí přesnějších tipů pro typy polí, například:

class UserManager {
  /** @return User[] */
  public function getAllUsers(): array { ... }
}

Jak je znázorněno výše, pro komentáře, které mají pouze jednu značku nebo popis jednoho řádku, použijte také syntaxi komentáře s jedním řádkem.

Neexistuje žádný linter o mezerách kolem : v deklaracích návratových typů. Dokud tato norma nepřijde, používejte prosím ilustrovaný styl: Bez mezery před, jedna mezera za.

Vkládání závislosti na konstruktoru

Nový kód by měl mít všechny své závislosti vložené pomocí konstruktoru. V některých případech to zatím není možné, protože některé služby jsou dostupné pouze v nejnovější verzi MediaWiki a také chybí podpora ObjectFactory pro některé typy tříd, jako jsou úlohy a skripty údržby. Pro takový nový kód umístěte všechny závislosti do konstruktoru třídy (nebo hlavní vstupní bod do třídy), abyste je v budoucnu snadno migrovali při vkládání závislostí konstruktoru.

Skripty údržby nemohou používat žádný kód, který vyžaduje autoloader PHP, a proto lze všechny závislosti deklarovat pouze v metodě execute, nikoli v konstruktoru.

Záhlaví souboru

Pro nový kód jsme zvolili následující minimalistickou hlavičku:

<?php
declare( strict_types = 1 );

namespace Example;

use OtherStuff;

/**
 * Class description.
 * @author Your name
 * @license GPL-2.0-or-later
 * @since 2020.06
 */
class ExampleClass {
  /** @return User[] */
  public function getAllUsers(): array { ... }
}

Pokud chcete svá autorská práva uplatnit explicitněji, můžete volitelně přidat také tag @copyright.

Změny a čísla verzí

Pokud Translate mění kód zpětně nekompatibilními způsoby, zkontrolujte https://codesearch.wmcloud.org/search/ pro všechny uživatele kódu. Známí uživatelé jsou TwnMainPage, TranslateSVG, CentralNotice, MassMessage a spousta věcí v úložišti translatewiki.

Můžete použít prostředky pro ukončení podpory poskytované jádrem MediaWiki, včetně značky @deprecated a tvrdého ukončení podpory wfDeprecated(). Pokud nejsou známí uživatelé kódu, je v pořádku jej změnit zpětně nekompatibilním způsobem bez ukončení podpory, pokud není výslovně označen jako stabilní (viz Zásady stabilního rozhraní). Kód označený jako stabilní by měl být tvrdě zastaralý alespoň pro jedno vydání Balíček jazykových rozšíření MediaWiki (MLEB).

Čísla základních verzí MediaWiki nemají v kontextu Translate žádný význam, protože Translate vždy podporuje více vydání MediaWiki. Samotný Translate používá verzování ve stylu YYYY.MM (jako součást MLEB). Nové třídy a metody by měly být označeny značkami @since YYYY.MM.