Nápověda:Rozšíření:Translate/Validátory

This page is a translated version of the page Help:Extension:Translate/Validators and the translation is 100% complete.

Překládané řetězce často obsahují značky, které chceme u překladu zachovat tak, jak jsou. Zápis takových značek do překladu může být pro překladatele problematický, obzvláště, pokud se při něm pracuje se speciálními znaky, které nejsou moc běžné. Proto se při značkování používají zástupné elementy, které pak v překladatelském rozhraní nabízí tlačítka, po jejichž stisknutí se na aktuální pozici kurzoru vloží do překládané zprávy zástupný prvek. Pokud se takový zástupný element do překladu nevloží, může na to rozšíření překladatele upozornit, nebo dokonce může jeho překlad odmítnout, je-li kód zástupného elementu nezbytný pro to, aby se překlad zobrazoval správně.

Kupříkladu následující řetězec

Adapted by %{name} from a work by %{original}

bude vyžadovat hned dva zástupné elementy. Pro řetězce %{name} a %{original}.

Pokud by je překladatel do překladu nevložil, tak by se přeložená zpráva nezobrazovala správně.

Proto existuje komponenta MessageValidator která pomáhá překladatelům tím, že ověřuje překlady. Pracuje při tom s tzv. validátory, které se aplikují na překlad ještě před uložením. Pokud nevyhoví jejich nastavení, překladatele upozorní nebo rovnou oznámí chybu. Je-li oznámeno pouze varování, překlad se uloží, ale při ohlášené chybě ne. Jedině uživatel, který má právo translate-manage může uložit i překlad ve kterém je chyba.

Konfigurační soubor validátoru identifikuje řetězce na základě regulárního výrazu. Proto nesmí chybět. Validátor z něj může vygenerovat zástupný element, který se pak zobrazí jako tlačítko v překladatelském rozhraní, přes které se dá do překladu vložit.

Můžete si vytvořit i vlastní validátory, pokud potřebujete mít více specializované ověřování.

Konfigurace

Takto vypadá kompletní konfigurace validátoru:

VALIDATORS:
    # Příklad 1
    - id: InsertableRegex
      enforce: true
      insertable: true
      params: /\$[a-z0-9]+/
      keymatch:
        - 'untranslated' # Nepřekládá se nic, takže se dá řetězec rovnou použít
        - 
          type: 'wildcard'
          pattern: '*translated*' # Vyhovující řetězce se mohou překládat
    # Příklad 2
    - id: InsertableRegex
      insertable: true
      params:
          regex: /(?<pre>\[)[^]]+(?<post>\]\([^)]+\))/
          display: $pre $post
          pre: $pre
          post: $post
    # Příklad 3
    - class: MathJaxMessageValidator
      enforce: true
    # Příklad 4
    - id: BraceBalance

K výše uvedenému příkladu:

  1. InsertableRegex je validátor dodávaný v rámci instalace, jehož regulární výraz si můžete upravit, tak aby vyhovoval vašim požadavkům na ověřování.
  2. MathJaxMessageValidator je třída, která ověřuje řetězec podle vlastních pravidel.
  3. BraceBalance je další validátor, který je součástí instalace.

VALIDATORS je pole. Parametry, které se v rámci tohoto pole použijí, jsou klíče zastupující jednotlivé položky.

Parametry

Vlastnost Typ Popis
id řetězec ID validátoru, v případě, že se používá přibalený případně předem poskytnutý validátor. Povinné, pokud není specifikováno class.
class řetězec Pokud se používá vlastní validátor, použijte tuto možnost místo id. Určuje název třídy validátoru. Viz příklad #3 ve výše uvedené konfiguraci. K načtení třídy lze použít volbu AUTOLOAD. Povinné, pokud není specifikováno id.
enforce boolean Zda má být validátor vynucován. Pokud je nastaveno na hodnotu true a překlad se nezdaří, zobrazí se chyba, kterou je nutné opravit, aby se překlad uložil.
insertable boolean Zda má být validátor také vložitelný.
keymatch pole Touto volbou je možné omezit určitá ověření na určité zprávy. Keymatch je pole, kde každá možnost je buď řetězec nebo prototyp. Pokud se jedná o řetězec, je provedeno přímé porovnání s klíčem zprávy. Viz příklad #1 ve výše uvedené konfiguraci.
keymatch[i].type řetězec Typ je buď regex nebo wildcard. Toto je přístup, který bude použit ke kontrole, zda klíč zprávy odpovídá danému vzoru.
keymatch[i].pattern řetězec Vzor je řetězec, který bude použit pro párování.
params řetězec či asociativní pole Pokud je parametr zadán jako řetězec, použije se jako regulární výraz. Viz příklad #1

V tomto případě, pokud je vložitelný text true,

  1. display je první hodnota ze shody regulárního výrazu.
  2. pre je také první hodnota ze shody regulárního výrazu.
  3. post zůstává prázdný.

Pokud jsou parametry specifikovány jako asociativní pole (viz příklad č. 2), další podrobnosti naleznete níže.

params.regex řetězec Regulární výraz, který se má použít pro validátor. Je nutné použít pojmenované zachycení. Při zadávání pojmenovaných zachycení nepoužívejte v názvu symbol $.

V příkladu #2 jsou použity dvě pojmenovaná zachycení - pre a post.

params.display řetězec Povinná hodnota. Zobrazená hodnota pro vložení. Zde se používají pojmenovaná zachycení s předponou $. Viz příklad #2.
params.pre řetězec Předběžná hodnota pro vložitelný prvek. Hodnota vložená před pozici kurzoru. Zde se používají pojmenovaná zachycení s předponou $. Pokud není specifikováno, je nastaveno na zobrazovanou hodnotu. Viz příklad #2.
params.post řetězec Hodnota příspěvku pro vložitelný prvek. Hodnota vložená za pozici kurzoru. Zde se používají pojmenovaná zachycení s předponou $. Viz příklad #2. Není-li zadáno, výchozí hodnota je prázdný řetězec.

Předpřipravené / Dodávané validátory

Toto je přehled validátorů, které jsou již předpřipravené

BraceBalance

ID: BraceBalance

Zajišťuje, že počet otevřených závorek / závorek odpovídá počtu uzavřených závorek / závorek v překladu.

Prošly by například následující překlady:

  • {{ }}
  • [ ]

přičemž následující by se nezdařilo:

  • [ ]]
  • {{ }

Tento validátor nelze označit jako vložitelný.

EscapeCharacter

ID: EscapeCharacter

Validátor zajišťuje, že v překladu je přítomen pouze zadaný znak escape.

Povolené znaky escape lze zadat při přidávání validátoru a mohou obsahovat pouze:

  • \t
  • \n
  • \'
  • \"
  • \f
  • \r
  • \a
  • \b
  • \\

Tento validátor nelze vložit.

GettextNewline

ID: GettextNewline

Funguje speciálně pro skupiny zpráv založených na GetText.

Zajišťuje, že překlad má na začátku a na konci řetězce stejný počet nových řádků jako zdrojová zpráva.

GettextPlural

ID: GettextPlural

Funguje konkrétně na skupinách zpráv založených na GetText.

Zajišťuje, že pokud zdroj / definice obsahuje množné číslo ve formátu - foo {{PLURAL:GETTEXT|one|many}} bar, překlad jej musí obsahovat také. Na základě jazyka se také kontroluje, zda má překlad správný počet tvarů množného čísla. Například angličtina má dva, ale hebrejština čtyři.

InsertableRegex

ID: InsertableRegex

Obecný opakovaně použitelný validátor, který lze použít ke specifikaci vlastních validací a vložitelných položek.

Vezměte například následující konfiguraci, kde je validátor označen jako vložitelný a vynucený:

- id: InsertableRegex
  enforce: true
  insertable: true
  params: "/\$[a-zA-Z0-9]+/"

Vzhledem k následující zdrojové zprávě – Hello $name. My name is $myName., která se překládá, musí mít překlad parametry – $name a $myName. Budou také zobrazeny jako vložené položky, aby je překladatelé mohli snáze použít v překladu. Absence těchto parametrů způsobí, že se v překladači zobrazí chyba.

InsertableRubyVariable

ID: InsertableRubyVariable

Toto je validátor, který odpovídá rubínovým proměnným v překladech. Interně rozšiřuje InsertableRegexValidator a používá následující regulární výraz - %{[a-zA-Z_]+}. Tento validátor je vložitelný.

Příklad: %{abc}

IosVariable

ID: IosVariable

Vložitelný validátor proměnných pro IOS. Regex se používá odtud. Tento validátor je vložitelný.

Příklad: %@

MatchSet

ID: MatchSet

Zajistí, že překlad je přítomen v seznamu hodnot. Také přebírá parametr – caseSensitive, který může být buď true (výchozí) nebo false.

Například v následující konfiguraci validátor ověří zprávu pomocí klíče - html.dir a zajistí, že hodnoty pro ni mohou být buď ltr nebo rtl. Všimněte si, že LTR nebo RTL nebudou platné hodnoty, protože caseSensitive je ve výchozím nastavení true.

  - id: MatchSet
    enforce: true
    keymatch:
      - html.dir
    params:
      values:
        - ltr
        - rtl

ID: MediaWikiLink

Zkontroluje, zda překlad používá odkazy, které jsou odrazovány. Platné odkazy jsou ty, které odkazují na Speciální: stránky, {{ns:special}}: nebo projektové stránky prostřednictvím zpráv MediaWiki jako je {{MediaWiki:helppage-url}}:. Takže odkazy v definici jsou povoleny.

MediaWikiPageName

ID: MediaWikiPageName

Zajišťuje, že pokud zdroj / definice obsahuje jmenný prostor, jako je {{ns:project}}:hello, provedené překlady se nepokusí přeložit samotné jmenné prostory.

MediaWikiParameter

ID: MediaWikiParameter

Toto je validátor, který odpovídá parametrům wiki v překladech. Interně rozšiřuje InsertableRegexValidator a používá následující regulární výraz - /\$[1-9]/. Tento validátor je vložitelný.

Příklad: $1, $2.

MediaWikiPlural

ID: MediaWikiPlural

Zajišťuje, že pokud zdroj / definice obsahuje {{PLURAL:$1|message|messages}}, měl by ji obsahovat i překlad. Lze jej použít i jako vložku. Na základě jazyka se také kontroluje, zda má překlad správný počet tvarů množného čísla. Například angličtina má dva, ale hebrejština tři.

MediaWikiTimeList

ID: MediaWikiTimeList

Poskytuje ověření možností vypršení platnosti a možností blokování IP specifikovaných v jádře MediaWiki. Ty jsou obvykle ve formátu,

indefinite:indefinite,3 hours:3 hours,12 hours:12 hours,24 hours:24 hours,31 hours:31 hours,36 hours:36 hours,48 hours:48 hours,60 hours:60 hours,72 hours:72 hours,1 week:1 week,2 weeks:2 weeks,1 month:1 month,3 months:3 months,6 months:6 months,1 year:1 year,2 years:2 years,3 years:3 years,infinite:indefinite

Validace zajišťují, že překlady mají přesně stejný počet párů klíč–hodnota. Tato ověření se spouštějí pouze u zpráv s klíči:

  1. protect-expiry-options
  2. ipboptions

Newline

ID: Newline

Zajišťuje, že překlad má stejný počet nových řádků jako zdrojová / definiční zpráva na začátku řetězce. Tento validátor nelze vložit.

NotEmpty

ID: NotEmpty

Zajišťuje, že překlad má nějaký obsah a že obsahem nejsou jen mezery. Tento validátor nelze vložit.

NumericalParameter

ID: NumericalParameter

Tento validátor odpovídá číselným parametrům pomocí následujícího regulárního výrazu: /\$\d+/. Tento validátor je vložitelný.

Příklad: $33, $1 etc.

Printf

ID: Printf

Tento validátor kontroluje chybějící a neznámé znaky formátování printf v překladech. Tento validátor je vložitelný.

Příklad: %2$f, %d etc.

PythonInterpolation

ID: PythonInterpolation

Tento validátor porovnává proměnné interpolace řetězců pythonu pomocí následujícího regulárního výrazu: /\%(?:\([a-zA-Z0-9]*?\))?[diouxXeEfFgGcrs]/U. Tento validátor je vložitelný.

Příklad: %s, %(name)s

Replacement

ID: Replacement

Zkontroluje, zda překlad používá řetězec search, a místo toho navrhne překladateli, aby použil řetězec uvedený pod replacement. Tento validátor nelze vložit.

  - id: Replacement
    enforce: true
    params:
      search: '{{PLURAL:'
      replace: '{PLURAL:'

SmartFormatPlural

ID: SmartFormatPlural

Funguje konkrétně na skupinách zpráv založených na SmartFormat.

Zajišťuje, že pokud zdroj / definice obsahuje množné číslo ve formátu - {1:test|tests}{0:message|messages}, překlad jej musí obsahovat také. Na základě jazyka se také kontroluje, zda má překlad správný počet tvarů množného čísla. Například angličtina má dva, ale hebrejština čtyři.

UnicodePlural

ID: UnicodePlural

Zajišťuje, že pokud zdroj / definice obsahuje množné číslo ve formátu - foo {{PLURAL|one=one|many}} bar, překlad jej musí obsahovat také. Na základě jazyka se také kontroluje, zda má překlad správný počet tvarů množného čísla. Například angličtina má dva, ale hebrejština tři.

Uživatelské rozhraní

Uživatelské rozhraní bylo aktualizováno, aby rozlišovalo mezi chybami a varováními.

 
Varování a chyba zobrazené nad překladem

Pokud během překladu dojde k chybě při překladu, tlačítko Uložit překlad je deaktivováno, pokud uživatel, který překládá, nemá oprávnění translate-manage.

Další ověření se také provádí na serveru, když uživatel ukládá překlad. To stále umožňuje uživatelům, kteří mají oprávnění translate-manage, uložit překlad, i když obsahuje chyby.

Vlastní validátory

Některé komplikované validace mohou i nadále vyžadovat napsání vlastního validátoru. Vlastní validátory musí implementovat rozhraní MediaWiki\Extensions\Translate\Validation\MessageValidator [1].

Níže je uveden příklad vlastního validátoru:

<?php
// Filename: Validator.php
use MediaWiki\Extensions\Translate\Validation\MessageValidator;
use MediaWiki\Extensions\Translate\Validation\ValidationIssue;
use MediaWiki\Extensions\Translate\Validation\ValidationIssues;

/**
 * Můj vlastní validátor
 */
class MyCustomValidator implements MessageValidator {
	
	public function getIssues( TMessage $message, string $targetLanguage ): ValidationIssues {
		$issues = new ValidationIssues();
	    
	    // Zde je ověřovací kód. Vložte ValidationIssue do ValidationIssues. Například:
	    $issue = new ValidationIssue(
			'value-not-present',                                // typ
		    'invalid',                                          // podtyp
			'translate-checks-value-not-present',               // klíč zprávy
			[                                                   // parametry zprávy
				[ 'PLAIN-PARAMS', $this->possibleValues ],
				[ 'COUNT', count( $this->possibleValues ) ]
			]
		);

		$issues->add( $issue );
	    
	    return $issues;
	}
}

Podívejte se také na následující třídy:

  1. ValidationIssues - https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/extensions/Translate/+/master/src/Validation/ValidationIssues.php
  2. ValidationIssue - https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/extensions/Translate/+/master/src/Validation/ValidationIssue.php

Přidejte vlastní validátor do konfiguračního souboru:

VALIDATORS:
  - class: MyCustomValidator
    enforce: true

AUTOLOAD:
  MyCustomValidator: Validator.php