Help:Extension:Translate/Insertables/cs

<translate> Documentation for <tvar|ext>Rozšíření:Translate</></translate>

<translate> Translators</translate> (<translate> main help page</translate> )

<translate> Translation administrators</translate>

<translate> Sysadmins and developers</translate>

<translate> Translate this template</translate>

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, co nejsou moc běžné, a to pak pochopitelně práci překladatele zpomaluje. A zástupné elementy, to usnadňují, protože se překladateli zobrazují u překládané zprávy jako tlačítka, která do překládané zprávy vloží kód, který pak na stránce nahrazuje kódem, který zastupují. Do překladu je lze buď rovnou napsat, nebo na příslušné místo kde se zrovna nalézá kurzor, vložit kliknutím na zobrazené tlačítko.

Pro každou skupinu zpráv existuje instance třídy InsertablesSuggester. Tato třída obsahuje seznam zástupných elementů (třídy Insertable). A každá třída Insertable má tři části:

To co ze zobrazí uživateli
To co se vloží do překladu na pozici kurzoru nebo co nahradí vybraný obsah.
A to co se vloží do překladu za pozici kurzoru

Rozšíření Translate má integrovanou třídu MediaWikiInsertablesSuggester. Další "našeptávací" třídy (suggesters) můžete najít v phab:diffusion/GTWN/browse/groups git repozitáři translatewiki.net.

Uživatelské rozhraní

File:Translate extension Insertables interface.png

Zástupné elementy jsou zobrazeny na dolním okraji formulářového pole s překladem. Kromě toho, že nabízí možnost rychlého vložení, zároveň upozorňují na to, že jsou v překladu vyznačené kusy kódu, které se budou zobrazovat stejně bez ohledu na zvolený jazyk.

Nastavení

Toto je jednoduchý příklad nastavení našeptávací třídy v YAML syntaxi.

INSERTABLES:
  # třída pro vyhledání výchozích zástupných elementů
  - class: RegexInsertablesSuggester
    params: "/\$[a-zA-Z0-9]+/"
  # třída pro vyhledání uživatelsky definovaných zástupných elementů
  - class: FreeColInsertablesSuggester

AUTOLOAD:
  FreeColInsertablesSuggester: Suggester.php

Přednastavené / Předpřipravené třídy pro zástupné elementy

Toto je přehled tříd pro výběr zástupných elementů, které jsou součástí MediaWiki.

HtmlTagInsertablesSuggester

Tato třída našeptává zástupné elementy místo HTML tagů nalezených v překládaném řetězci.

Například:

U zprávy: This <a href="abc">link</a>link takes you to the home page.
Nápověda zobrazí: <a href="abc"></a>

MediaWikiInsertablesSuggester

Tato třída zas bude zobrazovat zástupné elementy v případě, že pokud ve wikitextu předkládané zprávy najde řetězce s nimiž pracuje MediaWiki. Takže napoví

Parametr $1user, který se používá při volání stránky nápovědy přes API, pokud na něj narazí.
PLURALS, GENDER, GRAMMAR
A rovněž napoví i HTML značky.

NumericalParameterInsertablesSuggester

Tahle třída zajišťuje nápovědu numerických zástupných elementů, jako např. $1, $2, či $33

RegexInsertablesSuggester

Tahle třída generuje zástupné elementy z řetězců co vyhoví nastavenému regulárnímu výrazu.

Například:

  # jednoduchý příklad
  # vyhledá a napoví: $abc
  - class: RegexInsertablesSuggester
    params: "/\$[a-zA-Z0-9]+/"
  # složitější příklad nápovědy, který generuje zástupné elementy z nalezených slov.
  # vybere: [abc](ac) 
  # ale nápověda zobrazí: [](ac)
  - class: RegexInsertablesSuggester
    params:
      regex: /(?<pre>\[)[^]]+(?<post>\]\([^)]+\))/
      display: $pre $post
      pre: $pre
      post: $post

Popis parametrů,

regex - Regulární výraz, který se použije při identifikaci řetězce pro zástupný element. Musí být vždy uveden.
display - To co ze zobrazí uživateli. Pokud parametr není uveden, zobrazí se to, co bylo nalezeno.
pre - Zástupný element vkládající se před vybraný řetězec nebo nahrazuje výběr, pokud post zůstane prázdný. Pokud není uveden, použije se to co bylo nalezeno.
post - Zástupný element vkládající se až za vybraný řetězec. Pokud není uveden, použije se to co bylo nalezeno.

TranslatablePageInsertablesSuggester

Používá se hlavně u překládaných stránek kde má našeptávač zobrazovat proměnné, jako např. $abc.

UrlInsertablesSuggester

Vyhledá URL adresy (které se obvykle nepřekládají) a doporučí je ke vložení.

Vytvoření vlastní třídy pro zástupné elementy

V případě, že žádný ze zástupných elementů které jsou k dispozici nevyhovuje vašim potřebám, si můžete vytvořit třídu, která bude vyhledávat a nabízet vaše vlastní zástupné elementy.

Toto je příklad, jak přidat zástupný element, pro zprávy, které jsou ve skupině: FreeCol. Příslušný soubor v YAML syntaxi vypadá následovně pro zjednodušení je zde uvedena pouze část, která se týká příkladu. Nově přidané řádky jsou zvýrazněny.

FreeCol.yaml:

---
BASIC:
  id: out-freecol
  label: FreeCol
  description: "A strategy game"
  namespace: NS_FREECOL
  class: FileBasedMessageGroup
 
FILES:
  class: JavaFFS
  sourcePattern: %GROUPROOT%/freecol/data/strings/FreeColMessages_%CODE%.properties
  definitionFile: %GROUPROOT%/freecol/data/strings/FreeColMessages.properties
  targetPattern: freecol/data/strings/FreeColMessages_%CODE%.properties

INSERTABLES:
  - class: FreeColInsertablesSuggester

AUTOLOAD:
  FreeColInsertablesSuggester: Suggester.php

Suggester.php:

class FreecolInsertablesSuggester {
	public function getInsertables( $text ) {
		$insertables = array();

		$matches = array();
		// Vyhledej proměnnou ve formátu %name%
		// Jde o stejný regulární výraz, s jakým pracuje Checker.php
		preg_match_all( '/%[a-zA-Z_]+%/', $text, $matches, PREG_SET_ORDER );
		$new = array_map( function( $match ) {
			// $match[0] musí odpovídat uvedenému regulárnímu výrazu a víc nás nezajímá
			// Pokud chceme aby kurzor zůstal až za vloženým kódem, musíme to celé uzavřít do pole "pre".
			return new Insertable( $match[0], $match[0] );
		}, $matches );

		return $insertables;
	}
}

Parametry zástupného elementu jsou pak tyto:

class Insertable {
        /**
         * @param string $display Co se má zobrazit uživateli
         * @param string $pre Co se má vložit před vybraný řetězec nebo nahradit výběr, pokud $post zůstane prázdný
         * @param string $post Co se má vložit za vybraný řetězec
         */
        public function __construct( $display, $pre = '', $post = '' ) {
                $this->display = $display;
                $this->pre = $pre;
                $this->post = $post;
        }
[...]
}