Błędy W Przewodniku

Dopiero zaczynam na poważnie przygodę z frameworkami PHP. Podchodziłem do tego tematu już parę razu ale jakoś brakowało samozaparcia do zmiany przyzwyczajeń. Zainteresowałem się frameworkiem Yii i zgłębianie go zacząłem od strony http://www.yiiframework.com/doc/guide/1.1/pl/index. Niestety im dłużej czytam ten przewodnik tym bardziej załamuje mnie jego poziom. Ilość błędów jest porażająca. Chwilami mam podejrzenia, że pewne fragmenty były tłumaczone jakimś automatem. Błędy są zarówno w kodach jak i treści. Dużo zdań jest bardzo niegramatycznie napisanych i ciężko jest zrozumieć co autor chciał przekazać. W wielu miejscach brakuje literek. Zdarzają się też całe bloki które nie mają sensu. Przed chwilą właśnie trafiłem na taki kwiatek i zdecydowałem się założyć konto na forum.

Strona http://www.yiiframework.com/doc/guide/1.1/pl/database.ar:

To samo na stronie http://www.yiiframework.com/doc/guide/1.1/en/database.ar:

Z polskiej wersji wynika, że autor będzie stosował notację wielbłąda choć później stwierdza, że jednak mądrą decyzją jest stosowanie notacji z małymi literami i podkreśleniami. W kodach kawałek dalej stosuje jednak notację z małymi literami czyli zaprzecza sobie.

Z ostatnich błędów jakie pamiętam to na stronie http://www.yiiframework.com/doc/guide/1.1/pl/database.dao autor myli skrót DSN z DNS. To nie jest błąd w jednym tylko miejscu. Autor konsekwentnie przekręca DSN na DNS. W angielskiej wersji wszystko jest jak trzeba.

Moim celem nie jest psucie reputacji tego projektu. Chciał bym pomóc w doprowadzeniu przewodnika do takiego poziomu, żeby nie trzeba było się za niego wstydzić. Mam dość duże doświadczenie w programowaniu w PHP więc dość łatwo wyłapuję błędy merytoryczne ale wiele osób mogło polec w nauce przez taki przewodnik. Proszę o informację gdzie lub do kogo można przesłać listę błędów w przewodniku tak aby stał się użyteczny dla wszystkich, zwłaszcza początkujących.

Super, że zwróciłeś na to uwagę. Ja sam korzystałem z wersji po angielsku i byłem bardzo pozytywnie zaskoczony jakością. Widocznie autorowi tłumaczenia bardzo się śpieszyło. Wiadomo, ile pracy to wymaga, tym bardziej należy ci się szacunek, że chcesz to poprawić.

Całość jest w repozytorium na Github. Pliki te można edytować tam w locie, tzn bezpośrednio na stronie, i zostanie do tego założony odpowiedni pull request (PR), który na pewno któryś z opiekunów szybko zaakceptuje.

Jednak jeśli chcemy poprawić większą część przewodnika chyba lepiej zrobić to bardziej tradycyjnie, tzn utworzyć forka, zrobić kilka commitów i dopiero założyć PR.

W razie czego mogę pomóc.

Na koniec tylko małe ostrzeżenie. Dobiegają końca pracę nad wersją 2.0 całego frameworka, do którego podręcznik został napisany od zera. Ten też trzeba będzie przetłumaczyć. Może będzie łatwiej po ćwiczeniu na wersji 1.x

Drogi imienniku,

czuję się niejawnie wywołany do odpowiedzi Twoim wpisem, bo tłumaczenie w większości jest mojego autorstwa. Na początek cieszę się, że masz zapał dokumentację poprawić - cieszę się, że w końcu ktoś to zrobi. Sam, pomimo szczerych chęci, od pewnego momentu nie miałem ani motywacji ani przede wszystkim czasu. Cóż, zmian od przeniesienia się Yii na GitHub z Google Code (a to w tym czasie były dodawane ostatnie tłumaczenia), w polskim tłumaczeniu nie było, więc i sam poradnik się trochę zestarzał i rozminął z angielską wersją.

Trudno nie zgodzić się z twierdzeniem, że dokumentacja nie jest tłumaczona na bardzo wysokim poziomie, aczkolwiek powstawała w momencie dla frameworka najbardziej dynamicznym, czyli na samym jego początku istnienia. Wtedy też zarówno zmian we frameworku jak i w poradniku było bardzo wiele i nie zawsze dawało się "nadążyć" za autorami Yii. Jak wiele się zmieniało można zauważyć porównując dokumentację z wersji 1.0 do 1.1. Nie wiem czy kiedyś tłumaczyłeś poradniki, ale faktem jest że tłumaczenie tekstów technicznych na język polski jest bardzo trudne, ze względu na częsty brak polskich, jednoznacznych, odpowiedników. Świetnym przykładem są terminy typu named scopes, behavior, fixtures, i tak dalej. Dodatkowo używanie zaimków "te", "tego", "ich" w zdaniach, które są wielokrotnie złożone (a te w dokumentacji królują), wprowadza sporo zamieszania - stąd częste powtórzenia (patrz zacytowany przez Ciebie teksty).

Co do DNS to zwyczajnie niefortunna literówka (przestawienie liter), zwłaszcza, że na innej stronie http://www.yiiframew…-startowy-testu mamy już prawidłowy skrót dla źródła danych DSN.

Wracając zaś do notacji wielbłąda (camelCase notation) to zważ, że tekst ten mówi, że w tym poradniku stosowana konwencja będzie camelCase ale nie zawsze ona się sprawdza, czego dobrym przykładem jest postgre. Jeżeli zajrzysz do wcześniejszej wersji 1.0 dokumentacji w języku angielskim (http://www.yiiframew…fining-ar-class), to zauważysz, ze oryginalny tekst brzmi następująco, co już tak bardzo od tłumaczenia nie odbiega.

[/size]

[size="2"]Co więcej, jeżeli spojrzysz na kod w wersji 1.0 to z pewnością zauważysz, że pola table nazywane są tam np. CreateTime, gdy tymczasem w wersji 1.1. już create_time.[/size]

Mam nadzieję, że moim wpisem chociaż trochę wyjaśniłem dlaczego tłumaczenie jest takie a nie inne.

Tymczasem trzymam kciuki za poprawienie dokumentacji i mam nadzieję, że na słomianym zapale się nie skończy,

pozdrawiam,

Tomek

@nineinchnick: widzę, że dosyć mocno udzielasz się na GitHubie dla Yii2. Może ze względu na to, że jesteś dosyć mocno zapoznany z dwójką to Ty powinieneś rozpocząć tłumaczenie dokumentacji na język polski?

Jak przyjdzie odpowiedni moment to czemu nie, z radością machnąłem tłumaczenie podstawowych etykiet kiedy wszyscy zaczęli wysyłać swoje. BTW ktoś mógłby na to zerknąć, póki jesteśmy jeszcze przed betą.

Porównywałem jedynie aktualną polską wersją z aktualną angielską wersją i stąd wyciągałem wnioski. Jeśli jednak ta dokumentacja przechodziła dużo zmian wynikających zarówno z poprawek jak i zmian wersji Yii to już rozumiem skąd te problemy. Już zgłosiłem dwie poprawki przez edycję bezpośrednio na stronie Github które zostały zaakceptowane. Na razie nie widać ich na stronie dokumentacji ale to pewnie kwestia czasu. Teraz już zainstalowałem Githuba pod Windowsa na własnym komputerze i jak radził nineinchnick zrobię wiele zmian za jednym razem. Poprawię to co potrafię czyli literówki, łamanie linii, uszkodzone bloki kodu (np. http://www.yiiframework.com/doc/guide/1.1/pl/database.arr pod koniec strony), nazwy w kodach i odmiany. Interpunkcji i szyku w zdaniach nie tykam się bo wydaje mi się, że w paru miejscach coś nie gra ale niestety polonistą nie jestem i nie mam pewności jak powinno być poprawnie.

Co do wersji 2.0, to z tego co pobieżnie przeczytałem, będzie się wyraźnie różnić od 1.1. Osobom które będą zmuszone do rozpoczęcia pracy z 1.1 będzie potrzebna obecna wersja dokumentacji więc warto ją dopracować. Mam tylko nadzieję, że wystarczy mi zapału do przejrzenia jeszcze raz tego co czytałem wcześniej. To co teraz czytam poprawiam już na bieżąco.

Witam,

Czy jest jakiś przybliżony termin wydania stabilnej wersji Yii2?