Serendipity Translator

Download

Spustitelný program - SerendipityTranslator.zip

Zdrojový kód - SerendipityTranslator_source.zip

Instalace

1. Ujistěte se, že máte nainstalovaný Java runtime environment ve verzi 6 nebo vyšší. Pokud nemáte, stáhnete z www.java.com.
2. Stáhnete zip archiv se spustitelnými soubory SerendipityTranslator.zip a rozbalte ho do libovolného adresáře.
3. Poklepáním na soubor SerendipityTranslator.jar program spustíte.

Návod k použití

Nastavení (klávesová zkratka "S")

Po spuštění je třeba program nastavit. Kliknutím na menu "Settings" (nebo klávesová zkratka "s"). Zadejte jazyk, do kterého chcete překládat z předvybraného seznamu. A také jméno překladatele a jeho emailovou adresu. Na tu se nic nebude posílat, jde pouze o řádku, která bude uložena v přeložených souborech, aby případní další překladatelé věděli, kdo před nimi soubor překládal.

do not show plugins without translate file - některé pluginy, zvláště šablony vzhledu, prostě nemají žádné jazykové konstanty, které by se daly přeložit. V seznamu pluginů pak jsou čistě pro informaci. Zaškrtnutím této volby je skryjete, seznam se tak zkrátí a zpřehlední.

Style of line breaks umožňuje vybrat, jaký znak bude použit pro konec řádky.

WWW address with application - Zde můžete zadat vlastní server, ze kterého se budou stahovat aktualizace programu.

Serendipity core, Additional plugins, Additional themes - Zde můžete zadat, pomocí jaké metody (Repository type), z jakého umístění na internetu (URL) se mají aktualizovat jazykové soubory a kam na lokální disk se mají ukládat (Local folder). Výchozí nastavení není třeba měnit, funguje. Pokud se vám zdá stahování pomalé, můžete zkusit toto nastavení změnit. Přečtěte si předtím ale odstavec o přístupových protokolech.

Tlačítko Reset to default settings nastaví výchozí hodnoty pro typ a URL internetového úložiště pro všechny tři součásti Serendipity.

Hlavní okno

Tlačítko "Update plugin list" (klávesová zkratka "U")

Po klinutí se program připojí k webovému úložišti s pluginy (Spartacus), stáhne jejich seznam a z informací o pluginech zjistí, který plugin obsahuje či neobsahuje překlad v nastaveném jazyce. V tomto okamžiku program nezná obsah přeložených souborů, ty je třeba stáhnout kliknutím na následující tlačítko. Program v tuto chvíli pouze ví, že soubor s překladem existuje, ale neví, co obsahuje.

Ve verzi 2.1 byla přidána plná podpora protokolu git. Při jeho použití je třeba aktualizovat celé úložiště před tím, než je možné získat seznam pluginů. To znamená, že pro protokol "git native" dělají tlačítka "Update plugin list" a "Download files" úplně to samé. Postup stahování je zobrazen ve stavovém řádku.

Tlačítko "Download files" (klávesová zkratka "D")

Program stáhne soubory překladů - jednak anglické a pak ve vybraném lokálním jazyku (viz. nastavení) a porovná je z hlediska obsahu. Výsledky porovnání viz. odstvec "Tabulka s pluginy". Stahování může být zdlouhavé, proto o průběhu stahování uživatele informuje ukazatel vývoje stahování ve stavovém řádku.

Od verze 1.6 program stahuje pouze od minula změněné soubory, takže je stahování trochu rychlejsí. Stahování je navíc možno přerušit stisknutím tlačítka "Cancel". Od zmíněné verze jsou stahovány také soubory dokumentace (documentation_xx.html, readme, ChangeLog). O sledování překladů dokumentace více viz sekce Překlad dokumentace.

Tlačítko "Compare files by content" (klávesová zkratka "C")

Pokud z nějakého důvodu nejsou soubory porovnány a tabulka s pluginy ukazuje něco jiného než současný stav (např. po ručním překladu souborů dokumentace), lze program přinutit k opětovnému prohledání jazykových souborů (které jsou uloženy na disku, nic se nestahuje) a jejich porovnání.

Jak byly postupem času přidávány funkce do porovnání souborů pluginů, tak se operace porovnání poněkud natáhla, takže může trvat i docela dlouho. Proto je vývoj porovnávání zobrazen ve stavovém řádku.

Stavový řádek

Průběh všech potenciálně zdlouhavých operací je zobrazován ve stavovém řádku na spodním kraji hlavního okna. Pokud se vám nechce čekat na výsledek operace, můžete ji zastavit stiskem tlačítka Cancel.

Pokud žádná operace neprobíhá, je stavový řádek skrytý.

Tabulka s pluginy

• dvojklik na řádek s pluginem, případně vybrat řádku a "enter" - otevře překládací okno
• Kliknutí pravým tlačítkem zobrazí informace o pluginu a seznam souborů, které se používají k překladu pluginu.
• sloupec "Type":
  1. system - systémový soubor, soubor s hlavními jazykovými zprávami pro serendipity
  2. event - jazykový soubor pro plugin události
  3. sidebar - jazykový soubor pro postranní plugin
  4. template - jazykový soubor pro šablonu vzhledu
• sloupec "Internal" - zaškrtnuté pluginy jsou součástí základního balíčku Serendipity, ostatní jsou dostupné z webu nebo pomocí Spartacuse
• sloupec "en" a sloupec "loc" - počet zpráv (řádků) v anglickém (lokálním, českém) jazykovém souboru. Tady si můžete vybrat, jestli chcete překládat dlouhé nebo krátké soubory (jsou rychle přeložené). Taky lze podle toho posoudit, jak moc, jak dalece jsou přeloženy částečně přeložené soubory, kolik toho v nich zbývá dopřeložit.
• sloupec "Status" a "Translate status":
  1. ok - všechny zprávy (řádky) z anglického souboru jsou přítomny i v lokálním (českém), tedy soubor je úplně přeložen. Neboli číslo v sloupci "en" se shoduje s číslem ve sloupci "loc"
  2. no - jazykový soubor v lokální verzi vůbec neexistuje, je možno ho přeložit
  3. částečně - některé zprávy z anglického souboru jsou přítomny i v lokálním (českém). Neboli číslo v sloupci "en" se neshoduje s číslem ve sloupci "loc". Některé zprávy je třeba dopřeložit.
  4. problem - plugin vůbec nemá anglický soubor s jazykovými konstantami, nic tedy ani nelze překládat.

  Sloupec "Status" porovnává stažený český soubor s anglickým.

  Sloupec "Translate status" porovnává již přeložený soubor s anglickým.

  Může nastat několik situací.
  1. Pokud u toho samého pluginu je "Status" částečný nebo no, ale "translate status" je ok, znamená to, že jsme soubor již přeložili, ale zatím ho pomocí fóra neposkytli komunitě serendipity, tedy není přístupný na webu, je pouze v našem počítači.
  2. "Status" je ok, "Translate status" je no - to znamená, že plugin je úspěšně přeložen, my jsme ho nepřekládali. A ani ho nemusíme překládat.
  3. "Status" je částečně nebo no a "Translate status" je částečně. To znamená, že jsme již soubor částečně přeložili, ale nedokončili. Je tedy třeba dokončit překlad a nahrát ho na forum serendipity.
• Sloupec "Documentation": Zobrazuje jednu z následujících hodnot týkajících se stavu překladu dokumentace:
  1. ok - Český soubor dokumentace existuje (byl stažen ze serveru) a je mladší než anglická dokumentace, tedy je dost dobrý předpoklad, že je překlad kompletní a aktuální.
  2. local - Česká dokumentace neexistuje na serveru, ale mezi přeloženými soubory je a soubor je mladší než anglická dokumentace. Znamená to tedy, že jste dokumentaci už přeložili, jen jste ji ještě nenahráli na server, nezveřejněli světu.
  3. no - Anglická dokumentace existuje, ale česká nikoliv. Je čas přeložit ji:-)
  4. partial, částečně - Česká dokumentace existuje na serveru nebo na lokálním počítači, ale anglická dokumentace je mladší. Znamená to, že anglická dokumentace byla aktualizována, ale tyto změny ještě nejsou promítnuty v české dokumentaci.
  5. problem - Plugin nemá žádnou dokumentaci, není tedy co překládat.

Překládací okno

V horní části překládacího okna jsou tři pole - název editované zprávy, její znění v angličtině a třetí je znění v češtině.

Zprávy jde editovat jak v tabulce, tak ve velkém poli s českým zněním zprávy.

Ve status řádku se zobrazuje "original" x "modified" podle toho, zda-li bylo v překladu něco změněno nebo ne. Pokud je status "modified", je možné soubor uložit. Takto uložený soubor se nachází v adresáři "plugins_translated".

Řádky tabulky mohou mít celkem 4 barvy:

• červená - zpráva není přeložená do lokálního jazyka (češtiny)
• zelená - zpráva existuje v lokálním jazyce, ale je totožná s anglickou. Je tedy velmi pravděpodobné, že překladatel před námi pouze zkopíroval anglické zprávy do českého souboru a zapomněl je přeložit.
• žlutá - zpráva existuje v loklním jazyce, ale není v angličtině. Nejspíš byla v nové verzi odstraněna z anglického souboru. Pokud ji chceme odstranit i z českého, smažeme její znění. Prázdné zprávy se při ukládání nezapisují do souboru.
• bílá - zpráva existuje jak v anlgickém, tak v českém souboru, jsou různé, tedy úspěšně přeložené. Úplně přeložené soubory by měly obsahovat většinu bílých a případně zelené řádky (pokud se překlad zprávy shoduje s anglickým zněním).

Překládání dokumentace

Soubory s anglickou dokumentací jsou rozmístěny v různě nazvaných souborech. Anglická dokumentace by sice měla být v souboru "documentation_en.html", ale u spousty pluginů existuje pouze readme (navíc různě pojmenované jako "readme, readme.txt, pluginReadme.txt, credits.txt" nebo ChangeLog). Všechny tyto soubory jsou stahovány ze serveru a je s nimi zacházeno jako s dokumentací.

Protože se formát souborů s dokumentací navzájem liší, není v programu žádný nástroj na její překlad. Ten musíte zvládnout sami pomocí vnějšího textového editoru.

Pokud chcete využívat výhod sledování stavu překladu dokumentace a jejího automatického zabalování do zip archivu, měli byste uložit přeložené soubory do podadresáře pluginu v adresáři "plugins_translated" a ukládat ji striktně pod jménem souboru "documentation_xx.html", kde "xx" nahraďte zkratkou jazyka.

Od verze programu 1.9 už jsou automaticky vytvářeny soubory dokumentace v kódování utf-8 ze souborů s národním kódováním, pokud soubor utf-8 ještě neexistuje. Nicméně tato funkce má jistá omezení. Soubory v kódování utf-8 mohou být mírně odlišné od souborů v národním kódování. V souborech html je jiná hlavička meta, která obsahuje informaci o kódování použitém v dokumentu. Také odkazy na lokální soubory musí obsahovat navíc předponu "../", aby ukazovaly na správné soubory, nejčastěji obrázky, a aby se tyto nemusely kopírovat do nového adresáře v podadresáři UTF-8. Všechny vyjmenované změny program umí automaticky. Co se týče odkazů, tak ty, které začínají "http://" nebo "mailto:" zůstávají netknuty. Všechny další odlišnosti utf-8 souborů ale musí zajistit překladatel ručně.

Soubory jsou do kódování utf-8 převedeny po kliknutí na export, tj. "export translated files to zip file" v menu "translations".

Protokoly - přístup k internetovým úložištím

POZOR! URL adresa internetového úložiště je logicky pevně svázána s typem úložiště - např. github.com poskytuje html rozhraní pro git, sourceforge.net html rozhraní pro cvs. Serendipity Translator tuto závislost nijak nehlídá, takže pokud to nastavíte špatně (například zadáte adresu github.com a k tomu vyberete cvs úložiště), tak vám to nebude fungovat.

Typy protokolů:

• HTML protokoly - svn, cvs - U těch je to jednoduché - ty se připojí k zadané www adrese, prohlédnou si její obsah, jako to můžete udělat sami v internetovém prohlížeči, vyzobají z něj informace o pluginech a souborech a stáhnou ze serverů na lokální disk soubory změněné od posledního stahování. S lokálními soubory pak dále pracují při překladech.
• git html (nedoporučeno) - Standardní html protokol, který se připojí k webovému rozhraní gitHubu a snaží se přečíst jeho html stránku. Bohužel html rozhraní githubu je postavené poněkud nešťastně. Je totiž prošpikované javascriptem, který je pro SerendipityTranslator neprůchodný. Takže například datum poslední změny lze získat jen ve speciálních případěch. V důsledku toho se z githubu vždy stahují všechny soubory (větší provoz po síti a déle to trvá) a u dokumentace nefunguje indikace stavu, tj. jestli je nebo není přeložená, protože k tomu je potřeba znát datum poslední změny souboru. Doporučuji použít výchozí "git native" protokol. Viz níže.
• folder - Ignoruje nastavení URL adresy pro vzdálený počítač. Prostě jen čte soubory ze zadaného adresáře na lokálním disku. Nic nestahuje, soubory je třeba aktualizovat mimo SerendipityTranslator. Informace o poslední změně souboru se bere z jeho data. Tedy nefunguje příliš dobře varianta, že sami založíte cvs nebo git adresář a ukážete na něj v Serendipity Tranlsatoru pomocí protokolu "folder", protože soubory aktualizované pomocí cvs nebo gitu nemají datum poslední změny shodné s datem posledního commitu, kdy byl soubor měněn.
• git native - využívá vymoženosti verzovacího protokolu git. Od verze 2.1 umí založit lokální git úložiště a napojit ho na vzdálené úložiště např. na githubu, zadané v nastavení "remote URL". Nastavení URL je použito pouze při prvotním propojení lokálního úložiště se vzdáleným, pak je ignorováno. Pokud chcete aktualizovat lokální úložiště z jiného vzdáleného, musíte smazat celý adresář s lokálním úložištěm a vytvořit ho znovu za použití jiné URL adresy. Datum poslední změny se nebere z data souboru, ale z data posledního commitu, kdy byl soubor změněn.

Jak program vnitřně funguje

Doplňování jinde již přeložených zpráv

• V některých pluginech (většinou v šablonách vzhledu) se často opakují některé zprávy. Je to hlavně případ šablon vzhledu, které jejich autoři často vytvářejí kopírováním z jiné šablony, a ponechávají jim přitom původní jazykový soubor nebo ho jen minimálně mění. SerendipityTranslator si při každém porovnání souborů uloží do interní databáze seznam překládaných zpráv, a pokud někdy v budoucnu najde zprávu, která není přeložená, ale jejíž klíč již existuje v databázi, doplní přeloženou zprávu z databáze. Tato funkce podporuje koherenci překladu. Je méně pravděpodobné, že v různých pluginech přeložíte různě zprávu, která by měla být logicky stejná.

Adresáře, které program vytváří

• plugins - adresář se staženými soubory. Tyto soubory se mění pouze po klinutí na tlačítko "Download files", nikdy jindy. Obsahují stejné jazykové soubory, které jsou k dispozici v internetovém skladišti.
• plugins_translated - Tady je výsledek Vašich překladů. Zde uložené soubory je nutné k jejich uveřejnění nahrát na diskuzní fórum serenedipity (board.s9y.org). Přeložené pluginy jsou tříděny do podadresářů podle různých skupin, které jsou správci serendipity různě spravovány.

Formát ukládaných souborů

• hlavička - je standardně generována, obsahuje informace o verzi překladu, jméno překladatele (nastaví se v dialogu nastavení) a datum překladu
• Soubor, který se tvoří z čisté vody načisto, má jazykové konstanty řazené stejně jako anglická předloha
• Soubor, který již má předchůdce, tedy pokud upravujeme existující překlad, má stejné řazení a formátování jako již existující soubor. Části, které se nemění, jsou v obou souborech totožné. Nově přeložené zprávy jsou přidány na konec souboru. Snaha je o zachování stejného formátu (zvláště zarovnání, znaky mezi definicí klíče a textem ve funkci @define).

Kontrola syntaxe

Pokud máte nainstalované php (tedy pokud ho lze spustit přes příkazovou řádku např. příkazem "php -l jmenosouboru.php"), pak je mu předán každý ukládaný soubor ke kontrole syntaxe. Jste tak varováni vždy, když vytvoříte nevalidní php kód, který by mohl případně shodit celý blog.

Export do zip archivu

• Do zip archivu jsou exportovány pouze nové úplně přeložené překlady. To znamená, že "Translated status" musí být "ok" (zelená fajfka) a zároveň "Status" nesmí být "ok" a když je, tak obsah jednotlivých zpráv nesmí být u původního i nově přeloženého souboru totožný.
• Exportovány jsou pouze soubory aktuálního jazyku.
• Soubory dokumentace jsou exportovány pouze pro aktuální jazyk a pokud mají status "local".
• Jsou exportovány jak soubory v místním kódování, tak v UTF-8.
• Export probíhá do jediného zip archivu, ve kterém jsou překlady členěny podle kategorií - internal x external, plugins x templates.

Řešení problémů

• Program vytváří soubor "error.log" s chybovými hláškami.
• V případě, že aplikace nefunguje tak, jak je očekáváno, odešlete prosím soubor "error.log" autorovi.

Licence

Tento program poskytuji světu pod BSD licencí, jejíž text následuje:

---

Copyright © 2012, Vladimír Ajgl. Všechna práva vyhrazena.

Redistribuce a použití zdrojových i binárních forem díla, v původním i upravovaném tvaru, jsou povoleny za následujících podmínek:

• Šířený zdrojový kód musí obsahovat výše uvedenou informaci o copyrightu, tento seznam podmínek a níže uvedené zřeknutí se odpovědnosti.
• Šířený binární tvar musí nést výše uvedenou informaci o copyrightu, tento seznam podmínek a níže uvedené zřeknutí se odpovědnosti ve své dokumentaci a/nebo dalších poskytovaných materiálech.
• Ani jméno vlastníka práv, ani jména přispěvatelů nemohou být použita při podpoře nebo právních aktech souvisejících s produkty odvozenými z tohoto software bez výslovného písemného povolení.

TENTO SOFTWARE JE POSKYTOVÁN DRŽITELEM LICENCE A JEHO PŘISPĚVATELI „JAK STOJÍ A LEŽÍ“ A JAKÉKOLIV VÝSLOVNÉ NEBO PŘEDPOKLÁDANÉ ZÁRUKY VČETNĚ, ALE NEJEN, PŘEDPOKLÁDANÝCH OBCHODNÍCH ZÁRUK A ZÁRUKY VHODNOSTI PRO JAKÝKOLIV ÚČEL JSOU POPŘENY. DRŽITEL, ANI PŘISPĚVATELÉ NEBUDOU V ŽÁDNÉM PŘÍPADĚ ODPOVĚDNI ZA JAKÉKOLIV PŘÍMÉ, NEPŘÍMÉ, NÁHODNÉ, ZVLÁŠTNÍ, PŘÍKLADNÉ NEBO VYPLÝVAJÍCÍ ŠKODY (VČETNĚ, ALE NEJEN, ŠKOD VZNIKLÝCH NARUŠENÍM DODÁVEK ZBOŽÍ NEBO SLUŽEB; ZTRÁTOU POUŽITELNOSTI, DAT NEBO ZISKŮ; NEBO PŘERUŠENÍM OBCHODNÍ ČINNOSTI) JAKKOLIV ZPŮSOBENÉ NA ZÁKLADĚ JAKÉKOLIV TEORIE O ZODPOVĚDNOSTI, AŤ UŽ PLYNOUCÍ Z JINÉHO SMLUVNÍHO VZTAHU, URČITÉ ZODPOVĚDNOSTI NEBO PŘEČINU (VČETNĚ NEDBALOSTI) NA JAKÉMKOLIV ZPŮSOBU POUŽITÍ TOHOTO SOFTWARE, I V PŘÍPADĚ, ŽE DRŽITEL PRÁV BYL UPOZORNĚN NA MOŽNOST TAKOVÝCH ŠKOD.

Historie verzí

• 1.0
  Prerelease verze - otestování základní funkčnosti (stahování seznmu pluginů, editace překladů)
• 1.1
  Přidané údajů o překladech (počet zpráv v překládaném souboru), grafické vylepšení (odlišení překládaných zpráv - podle toho, jestli jsou/nejsou přeložená, zpráva v angličtině je totožná s přeloženou zprávou atp.)
• 1.2
  Úprava uživatelského rozhraní (lišta s menu, nastavení programu ve vlastním dialogu, dialog "o programu", dialog s nápovědou), úprava formátování přeloženého souboru (např. zjišťování formátu již uložených řádků)
• 1.3
  Zjišťování seznamu pluginů z webového rozhraní svn/cvs skladiště pluginů a šablon vzhledů. Export přeložených pluginů do zip archivu. Statistiky.
• 1.4
  Porovnání již stažených souborů při aktualizaci seznamu pluginů. Výpis chybových hlášek do souboru.
• 1.5
  Odstranění problému s (ne)stahováním souborů v některých případech. Přidání automatického doplňování překladu opakujících se zpráv.
• 1.6
  Přidáno sledování stavu dokumentace.
  Přidána funkce automatického zjišťování nových verzí programu a automatické aktualizace.
  Nově stahovány pouze měněné soubory -> rychlejší stahování.
  Přidána možnost přerušení stahování pluginů.
• 1.7
  Opravena chyba v (ne)stahování souborů s dokumentací.
  Dialog postupu stahování - ukládání jeho pozice a rozměrů + další vylepšení vzhledu.
• 1.8
  Přidána kontrola dostupnosti cvs/svn serverů. Při jejich nedostupnosti se zobrazí chybová hláška.
• 1.9 - 10.7.2011
  Oprava - nyní se stahují i soubory, které jsou staré pouze několik sekund.
  Oprava exportu souborů, které mají stejný obsah, ale liší se ve znacích ukončení řádků (\n - unixový styl nebo \r\n - styl windows). Nyní jsou považovány za identické.
  Ukládání stažených souborů s origiálním časovým razítkem. To eliminuje falešné označování dokumentace jako nepřeložené.
  Přidána automatická konverze souborů dokumentace do kódování utf-8.
• 2.0 - 10.12.2011
  Přidáno stahování souborů "todo", "copy*", "author(s)" jako dokumentace.
  Rozšířen dialog "nastavení". Nyní je možné nastavit, ze kterého internetového úložiště se mají stahovat zdrojové soubory.
  Přidána podpora Gitu.
  Přepracována funkce na aktualizaci softwaru - pro git se používá knihovna, takže se program rozrostl na více souborů, které je třeba stahovat v zip souboru a následně rozbalit.
• 2.1 - 7.1.2012
  Přidáno - nové tlačítko, možnost vrátit nastavení na výchozí hodnoty
  Změněno - výchozí hodnoty vzdálených úložišť, vše přesměrováno na github přes protokol git
  Vylepšeno - stahování pomocí git protokolu. Nyní je plně použitelné - umí si založit nové lokální úložiště, aktualizovat ho ze vzdáleného, umí i dávat průběžné výsledky o stahování.
  Změněno - dialog s průběhem stahování byl zrušeno, pruh s průběhem byl integrován do hlavního okna a nyní zobrazuje i průběh dalších operací jako je získávání seznamu pluginů nebo porovnávání souborů v pluginech.
  Vylepšeno - git html protokol. Nyní jsou už stahovány soubory z posledního commitu. Nicméně je doporučeno používat výchozí nastavení a přistupovat ke githubu přes nativní git protokol.
  Změněno - použitá knihovna jgit byla aktualizována na nejnovější verzi.
• 2.2 - 18.2.2012
  Opraveno - špatné zařazování pluginů do kategorií (jádro/externí; plugin/šablona)
  Opraveno - špatné zařazování do adresářů při exportu do ZIP souboru
  Přidáno - splash screen při startu aplikace
  Přidáno - kontrola syntaxe pomocí externího php parseru
  Přidáno - zobrazení informací o pluginu a seznamu souborů pluginu po kliknutí pravým tlačítkem na řádku s pluginem v tabulce pluginů
  Přidáno - možnost vybrat styl znaků konce řádky (windows x linux)
• 2.3 - 31.12.2013
  Přidáno - ikona
  Opraveno - neošetřená výjimka při parsování čísla verze a subverze jazykového souboru
  Opraveno - git pull selhal při přístupu na git server pomocí ssh s klíčem chráněným heslem - aplikace se nyní zeptá na toto heslo
  Změněno - struktura jazykového souboru již dále neobsahuje CVS tagy (protože se už delší dobu používá git jako úložiště)

Autor

Vladimír Ajgl, 2009-2012 (c)