{"id":15021517,"url":"https://github.com/php/doc-pl","last_synced_at":"2025-09-06T08:48:21.616Z","repository":{"id":141191602,"uuid":"324774943","full_name":"php/doc-pl","owner":"php","description":"Polish translation of the PHP documentation","archived":false,"fork":false,"pushed_at":"2025-05-16T06:32:26.000Z","size":5409,"stargazers_count":6,"open_issues_count":3,"forks_count":9,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-09-03T00:40:21.632Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/php.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security/apache.xml","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-12-27T14:06:44.000Z","updated_at":"2025-05-16T06:32:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"e1e7d8fa-59a2-46da-b818-f5aba1c8ad5b","html_url":"https://github.com/php/doc-pl","commit_stats":{"total_commits":2003,"total_committers":38,"mean_commits":52.71052631578947,"dds":0.6285571642536196,"last_synced_commit":"3fdeee947143865df184fdc1ac51fb6f6a5e5099"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/php/doc-pl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php%2Fdoc-pl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php%2Fdoc-pl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php%2Fdoc-pl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php%2Fdoc-pl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/php","download_url":"https://codeload.github.com/php/doc-pl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php%2Fdoc-pl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273879928,"owners_count":25184428,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T19:56:40.368Z","updated_at":"2025-09-06T08:48:21.603Z","avatar_url":"https://github.com/php.png","language":"HTML","readme":"# Polskie tłumaczenie dokumentacji PHP\n\nTo repozytorium zawiera pliki polskiego tłumaczenia dokumentacji na [php.net](https://php.net),\na ten dokument opisuje, w jaki sposób można uczestniczyć w procesie tłumaczenia.\n\n## Spis treści\n\n1. [Instalacja](#instalacja)\n2. [Zbuduj dokumentację](#zbuduj-dokumentację)\n3. [Śledzenie wersji](#śledzenie-wersji)\n4. [Tłumaczenie](#tłumaczenie)\n 1. [Słowniczek](#słowniczek)\n 2. [Inne porady dot. tłumaczenia](#inne-porady-dot-tłumaczenia)\n5. [Praca z git](#praca-z-git)\n6. [Obecny stan polskiego tłumaczenia](#obecny-stan-polskiego-tłumaczenia)\n\n## Instalacja\n\nAby wziąć udział w tworzeniu tłumaczenia dokumentacji PHP na język polski, musisz zacząć od zrobienia\n[forka][gh-forking] tego repozytorium, tj. `doc-pl`.\n\n\u003e **Uwaga:** Jeśli posiadasz konto na php.net (przydzielane ręcznie za długotrwały wkład) i uprawnienia\n\u003e do tego repozytorium, to możesz pracować bez użycia forka, ale jest to rzadka sytuacja, więc\n\u003e skupmy się na tym, co dotyczy większości ludzi.\n\nPoza `doc-pl` potrzebujesz jeszcze dwóch dodatkowych repozytoriów. W zdecydowanej większości sytuacji\nnie ma potrzeby dokonywać w nich żadnych zmian, aby pracować nad polską dokumentacją, tak więc nie ma\npotrzeby ich forkować. Możesz sklonować je prosto z oryginalnych repozytoriów organizacji PHP na GitHubie.\n\nNajlepiej jest stworzyć jeden katalog, do którego zostaną sklonowane wszystkie trzy repozytoria, na przykład\n`phpdoc`.\n\n- `php/doc-base`: to repozytorium zawiera narzędzia do tworzenia dokumentacji. Repozytorium znajduje się\n pod adresem https://github.com/php/doc-base\n- `php/doc-en`: angielska wersja dokumentacji, która jest używana m.in. wtedy, gdy dana podstrona nie\n została przetłumaczona na j. polski. Repozytorium znajduje się pod adresem https://github.com/php/doc-en\n- `php/doc-pl`: polskie tłumaczenie dokumentacji PHP. Jak wspomniane wyżej, prawdopodobnie musisz stworzyć\n fork tego repozytorium i sklonować repozytorium znajdujące się na Twoim własnym koncie GitHub\n\n\u003e **Uwaga:** upewnij się (przy klonowaniu lub zmieniając nazwę bezpośrednio po nim), że folder z angielską\n\u003e dokumentacją nazywa się `en`, a polską `pl`. Innymi słowy, upewnij się, że w sklonowanych repozytoriach\n\u003e katalogi z wersjami językowymi (poza `doc-base`) **nie** zaczynają się od `doc-`!\n\n## Zbuduj dokumentację\n\nPo dokonaniu jakichkolwiek zmian w tłumaczeniu powinieneś skorzystać ze skryptu, który buduje dokumentację,\naby upewnić się, że kod XML nie zawiera żadnych błędów. W tym momencie powinieneś mieć następującą strukturę\nkatalogów:\n\n```\n|- phpdoc\n |- doc-base\n |- en\n |- pl\n |- ...\n```\n\nJeśli znajdujesz się w katalogu `pl`, to musisz uruchomić po prostu następujące polecenie:\n\n```bash\nphp ../doc-base/configure.php --with-lang=pl\n```\n\nJeżeli wszystko poszło okej, to zobaczysz komunikat podobny do tego:\n\n```\nAll good. Saving .manual.xml... done.\nAll you have to do now is run 'phd -d /home/user/Dev/phpdoc/doc-base/.manual.xml'\nIf the script hangs here, you can abort with ^C.\n _ _..._ __\n \\)` (` /\n / `\\\n | d b |\n =\\ Y =/--..-=\"````\"-.\n '.=__.-' `\\\n o/ /\\ \\\n | | \\ \\ / )\n \\ .--\"\"`\\ \u003c \\ '-' /\n // | || \\ '---'\n jgs ((,,_/ ((,,___/\n\n (Run `nice php configure.php` next time!)\n```\n\nW przeciwnym razie zobaczysz informację o błędach, które wystąpiły w plikach XML.\n\n\u003e **Uwaga:** mimo iż proces nazywa się \"budowanie\", to ten krok nie tworzy jeszcze plików dokumentacji,\n\u003e które można wygodnie czytać (np. plików HTML). Komenda powyżej tworzy jedynie jeden gigantyczny plik\n\u003e XML i sprawdza jego poprawność, a _renderowaniem_ dokumentacji do czytelnej formy zajmuje się [phd][phd]\n\n## Śledzenie wersji\n\nKluczową sprawą przy tłumaczeniu dokumentacji jest jej zgodność z angielskim pierwowzorem. W tym celu\npowstał system `revcheck`, który jest dostępny m.in. na [doc.php.net], który śledzi\nzmiany, jakie wystąpiły w angielskiej wersji manuala, a więc to, co musimy zmienić w polskim tłumaczeniu,\naby było ono aktualne.\n\nCały system opiera się o hashe commitów gita i komentarze zawarte na górze każdego przetłumaczonego pliku\nXML:\n\n```xml\n\u003c!-- EN-Revision: git-hash Maintainer: XXXX Status: ready --\u003e\n```\n\nKiedy tłumaczymy jakiś plik, to `git-hash` w komentarzu powyżej musi być zamieniony na hash _angielskiej_\nwersji pliku, na którym opieraliśmy tłumaczenie. Pomaga w tym wspomniana witryna [doc.php.net]. Na przykład\nzakładka \"[Outdated files](http://doc.php.net/revcheck.php?p=files\u0026lang=pl)\" pokazuje, które z plików\nprzetłumaczonych już na język polski, wymagają aktualizacji. Podaje ona wtedy, o jaki hash jest oparte\nobecne tłumaczenie, hash najnowszej angielskiej wersji, a także diff (wykaz zmian) między nimi. Hash\nnajnowszej angielskiej wersji musimy umieścić w polu `EN-Revision` wyżej wspomnianego komentarza.\n\nPodobnie ma się sprawa przy tłumaczeniu nowych stron, przechodzimy do sekcji \"Untranslated files\"\nhttp://doc.php.net/revcheck.php?p=missfiles\u0026lang=pl, wybieramy katalog na górze, po czym widzimy,\njakie pliki nie zostały przetłumaczone i jaki jest ich obecny hash commita w angielskiej wersji\nmanuala. Wtedy do naszego nowego tłumaczenia dodajemy komentarz jak powyżej, a podany na stronie\nhash umieszczamy jako wartość `EN-Revision`.\n\n\u003e **Uwaga:** informacje na stronie [doc.php.net] są aktualizowane co cztery godziny. Czasy ostatniej\n\u003e aktualizacji, podane tam w stopce, są w UTC.\n\nJeżeli chodzi o pole `Maintainer` to przy aktualizacji tłumaczeń zasadniczo nie zmieniamy go. W wypadku\nnowych tłumaczeń możemy tam podać którąś z istniejących już wartości lub, jeśli bierzemy już częstszy udział\nw tłumaczeniu na j. polski, pokusić się o \"stworzenie\" własnego nicku. Nie wymaga to żadnej rejestracji,\na jedynie dodania wpisu do pliku `translation.xml`, znajdującego się w głównym katalogu tego repozytorium.\n\n## Tłumaczenie\n\nPliki XML powinny używać wcięć o szerokości jednej spacji. W tym repozytorium dołączono plik `.editorconfig`,\nwięc jeśli używasz edytora, który wspiera ten standard (bezpośrednio lub przez wtyczki), to powinno to zostać\nwykryte automatycznie.\n\nTłumacząc pliki, warto zadbać o to, aby tekst był podzielony na nowe linie w tych samych miejscach, co angielski\npierwowzór. Bardzo ułatwia to późniejszą analizę diffów na [doc.php.net], a więc i aktualizację tłumaczeń. Wiadomo,\nże nie zawsze jest to możliwe, bo często szyk zdania w języku polskim jest zupełnie inny niż w angielskim, ale warto\ndbać o to tam, gdzie to możliwe.\n\n### Słowniczek\n\nPoniżej zamieszczono listę kilku z częściej występujących i mniej oczywistych tłumaczeń, na które łatwo się natknąć\nw dokumentacji PHP.\n\n\u003e **Uwaga:** żadna z osób biorących udział w pracach nad polską wersją podręcznika PHP nie jest zawodowym tłumaczem.\n\u003e Pewne frazy można zapewne przetłumaczyć lepiej, więc sugestie są mile widziane. Dobrze byłoby jednak zadbać o spójność,\n\u003e więc do momentu osiągnięcia ewentualnego konsensusu w sprawie nowego tłumaczenia, stosujmy się do tych, które już są\n\u003e używane w polskiej wersji i zostały wymienione poniżej.\n\n| Angielski wyraz lub wyrażenie | Polskie tłumaczenie | Komentarz |\n|----------------------------------------------|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| coercive typing | luźne typowanie | Odnosi się do trybu, w którym działa system typów PHP (strict types vs. coercive typing); prawdopodobnie jest to dalekie od poprawnego tłumaczenia | \n| constructor property promotion | automatyczne tworzenie właściwości | Pomimo wielu poszukiwań nie znalazłem żadnego tłumaczenia w polskim internecie. To tylko moja radosna twórczość, jestem otwarty na lepsze propozycje | \n| first class callable syntax | Obsługa callable przy użyciu dedykowanej składni (first-class) | Podałem najbardziej rozbudowane tłumaczenie, używane np. jako pełen nagłówek opisujący tę funkcjonalność. Oczywiście w wielu kontekstach wystarczy krótsza forma, np. \"dedykowana składnia\" |\n| handler | funkcja obsługi | |\n| intersection types | typy przecinające się? | Bardzo możliwe, że lepiej po prostu tego nie tłumaczyć. Na razie dorzucam zawsze oryginalny termin w nawiasie |\n| Locale settings | Ustawienia regionalne (locale) | Jako iż nie ma powszechnie używanego tłumaczenia na j. polski to zawieramy też oryginalne słówko, aby ułatwić np. Googlowanie |\n| locale-dependent / locale-specific | z uwzględnieniem ustawień regionalnych (locale) | |\n| locale-independent | bez uwzględnienia ustawień regionalnych (locale) | |\n| null-coalescing operator | - | Nie jest mi znane żadne tłumaczenie, tym bardziej żadne powszechnie zrozumiałe |\n| property | właściwość | W kontekście właściwości klas |\n| scope | zasięg | W kontekście zmiennych |\n| string | ciąg znaków | Ewentualnie _łańcuch znaków_, jeśli gdzieś chcemy uniknąć powtórzeń |\n| trait, traits | trait, traity | Brak tłumaczenia, jedynie polska odmiana |\n| type juggling | dopasowywanie typów | Dosłowne tłumaczenie \"żonglowanie typami\" nie istnieje nigdzie w wynikach Google, więc \"dopasowywanie typów\" przynajmniej daje okazję zrozumieć o czym mowa |\n| variable variables | zmienne zmiennych | |\n| will generate deprecation notice | wygeneruje komunikat `\u003cconstant\u003eE_DEPRECATED\u003c/constant\u003e` | |\n| `\u003cconstant\u003eE_WARNING\u003c/constant\u003e` is raised | generowane jest ostrzeżenie (`\u003cconstant\u003eE_WARNING\u003c/constant\u003e`) | |\n| `\u003cparameter\u003efoo\u003c/parameter\u003e` | Parametr `\u003cparameter\u003efoo\u003c/parameter\u003e` | Poprzedzić słowem \"parametr\" przynajmniej przy pierwszym opisywaniu danego parametru na danej stronie. W przeciwnym razie dostajemy mieszkankę polskiego i angielskiego, która nie zawsze jest zrozumiała |\n| `\u003cparameter\u003efoo\u003c/parameter\u003e` is nullable now | Parametr `\u003cparameter\u003efoo\u003c/parameter\u003e dopuszcza teraz \u0026null; | |\n| `\u003cfunction\u003ebar\u003c/function\u003e` example | Przykład użycia `\u003cfunction\u003ebar\u003c/function\u003e` | W tytułach większości przykładów |\n| `\u0026array;` | `\u003clink linkend=\"language.types.array\"\u003eTablica\u003c/link\u003e` | Nie zawsze warto tłumaczyć, patrz pkt. 4 poniżej |\n| `\u0026bool;` | `\u003clink linkend=\"language.types.bool\"\u003eWartość logiczna\u003c/link\u003e` | Nie zawsze warto tłumaczyć, patrz pkt. 4 poniżej |\n| `\u0026float;` | `\u003clink linkend=\"language.types.float\"\u003eLiczba zmiennoprzecinkowa\u003c/link\u003e` | Nie zawsze warto tłumaczyć, patrz pkt. 4 poniżej |\n| `\u0026integer;` | `\u003clink linkend=\"language.types.integer\"\u003eLiczba\u003c/link\u003e` | Czasami też \"liczba całkowita\". Nie zawsze warto tłumaczyć, patrz pkt. 4 poniżej |\n| `\u0026object;` | `\u003clink linkend=\"language.types.object\"\u003eObiekt\u003c/link\u003e` | Nie zawsze warto tłumaczyć, patrz pkt. 4 poniżej |\n| `\u0026resource;` | `\u003clink linkend=\"language.types.resource\"\u003eZasób\u003c/link\u003e` | Nie zawsze warto tłumaczyć, patrz pkt. 4 poniżej |\n| `\u0026string;` | `\u003clink linkend=\"language.types.string\"\u003eCiąg znaków\u003c/link\u003e` | Nie zawsze warto tłumaczyć, patrz pkt. 4 poniżej |\n\n\n### Inne porady dot. tłumaczenia\n\n1. Nie należy się bać zmian szyku zdania. Zbyt dosłowne przekładanie szyku zdania z angielskiego jest chyba najczęstszym\n powodem, dla którego polska treść, mimo iż zrozumiała, jest mocno nienaturalna w odbiorze.\n2. `\u003crefpurpose\u003e` czyli jednozdaniowy opis na górze strony funkcji tłumaczymy w trybie oznajmującym, czyli np. _\"Pobiera obecną\n datę_\", a nie _\"Pobierz obecną datę\"_\n3. Odpowiedniki wielu angielskich wyrażeń, np. `As of PHP X`, `Prior to PHP X`, czy `however`, _nie_ mają po sobie obowiązkowego\n przecinka w języku polskim\n4. Jeśli chodzi o encje reprezentujące link do opisu typu danych (np. `\u0026array;` czy `\u0026string;`) to nie zawsze jest konieczność\n linkowania ich do konkretnej strony. Ze względu na brak konieczności tłumaczenia i odmiany tych wyrazów w j. angielskim, te\n encje są używane znacznie częściej niż jest to niezbędne\n 1. Ponadto ciężko tutaj o regułę, ale nie widzę konieczności każdorazowego tłumaczenia np. \"string\" na \"ciąg znaków\". W tych\n czasach nazwy typów są raczej zrozumiałe nawet dla ludzi nieposługujących się j. angielskim. Osobiście staram się przetłumaczyć\n nazwę typu przynajmniej raz na stronie, a potem nie mam problemu z pozostawieniem angielskiej wersji\n\n## Praca z git\n\nPrzygotuj jakąś ilość zmian. Możesz zająć się jednym lub kilkunastoma plikami, ale zalecane jest, aby na początek brać\nmniejsze ilości plików. W ten sposób będzie mniej do ewentualnej poprawki po procesie code review. Później można stopniowo\nzwiększać ilość zmian, wraz z nabieraniem doświadczenia ...choć też bez przesady ze zmianami w jednym pull requeście, żeby\nprzeglądanie zmian nie trwało wieków, bo to może być demotywujące :)\n\nOpisy commitów tworzymy w języku angielskim, choćby ze względu na to, że pewne zmiany struktury są wykonywane przez ludzi z różnych\nkrajów dla wszystkich tłumaczeń jednocześnie, tak więc w ten prosty sposób znacząco ułatwiamy pracę komukolwiek spoza Polski.\n\nPo przygotowaniu zmian w forku należy [otworzyć pull request][gh-prs] do repozytorium `php/doc-pl`, a następnie poczekać\nna przejrzenie i zatwierdzenie zmian. Najlepiej zapoznać się z całą sekcją \"Propose changes\" w spisie treści wyświetlanym\npo lewej stronie, po otwarciu powyższego linku. Można też oczywiście poszukać materiałów w języku polskim na ten temat.\n\n## Obecny stan polskiego tłumaczenia\n\nMówiąc w wielkim skrócie: gorsza wiadomość jest taka, że polskie tłumaczenie nie jest obecnie widoczne na [php.net](https://php.net).\nZnacznie lepsza wiadomość to taka, że polskie tłumaczenie jest jednocześnie w najlepszym stanie od przynajmniej ośmiu lat\ni że w perspektywie około miesiąca (tj. okolice czerwca, _ewentualnie_ lipca 2024) powinno się to zmienić.\n\nPolskie tłumaczenie nie ma może największej ilości przetłumaczonej treści (na maj 2024 jest to około 5% całości), ale też\nsam manual PHP jest _gigantyczny_. Większość zawartości manuala PHP to opisy rozszerzeń, w tym takich rzadko używanych lub niemal\nmartwych rozszerzeń PECL, z których nikt nie korzysta i niemal nikt nie czyta ich dokumentacji. Polskie tłumaczenie skupia\nsię w większości na najczęściej wykorzystywanych funkcjach i rozdziałach podręcznika.\n\nW połączeniu z faktem, że polska wersja ma małą ilość zdeaktualizowanych tłumaczeń, stawia nas to w naprawdę dobrej\npozycji wyjściowej w porównaniu do większości innych języków. Nie widać tego obecnie na [doc.php.net],\nale faktycznych tłumaczeń dokumentacji PHP jest około 30. Większość z nich po prostu jest w stanie tak złym, że zrezygnowano\nz cyklicznego analizowania ich statusu w tym narzędziu do momentu, gdy ktoś zabrałby się za ich wskrzeszenie i zapewnił\naktualne tłumaczenie przynajmniej dla kilku setek plików. Jest to coś, czego polska wersja robić nie musi :)\n\n\n[doc.php.net]: http://doc.php.net/revcheck.php?p=filesummary\u0026lang=pl\n[gh-forking]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo\n[gh-prs]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork\n[phd]: https://github.com/php/phd\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphp%2Fdoc-pl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphp%2Fdoc-pl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphp%2Fdoc-pl/lists"}