tracy: improved

Author: dg

tracy/bg/guide.texy

@@ -15,6 +15,7 @@
 
 
 PHP е идеален език за генериране на фини грешки, тъй като предоставя на програмистите голяма гъвкавост. Поради това Tracy\Debugger е по-ценен. Това е най-добрият инструмент сред диагностичните.
+
 Ако срещнете Трейси за първи път, повярвайте ми, животът ви ще се раздели на този преди Трейси и този с нея. Добре дошли в добрата част!
 
 
@@ -41,12 +42,8 @@ use Tracy\Debugger;
 Debugger::enable();
 ```
 
-Първото нещо, което ще забележите на сайта, е лентата Tracy.
-
-(Ако не виждате нищо, това означава, че Tracy работи в производствен режим. От съображения за сигурност Tracy е видима само на localhost.
-Можете да накарате Tracy да работи в режим на разработка, като подадете `Debugger::Development` като първи параметър на метода `enable()` ).
-
-Методът `enable()` предполага промяна на нивото на съобщението за грешка на E_ALL.
+Първото нещо, което ще забележите на страницата, е лентата на Tracy в долния десен ъгъл. Ако не я виждате, това може да означава, че Tracy работи в производствен режим.
+Това е така, защото Tracy е видим само на localhost от съображения за сигурност. За да проверите дали работи, можете временно да го поставите в режим на разработка, като използвате параметъра `Debugger::enable(Debugger::Development)`.
 
 
 Бар Трейси .[#toc-tracy-bar]
@@ -110,23 +107,48 @@ Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // всич
 
 [* tracy-notice.webp .{url:-} *]
 
-За да открием печатните грешки при присвояване на обект, използваме [признака Nette\SmartObject |utils:smartobject].
+Забележка: Когато е активирана функцията Tracy, нивото на отчитане на грешки се променя на E_ALL. Ако искате да промените това, направете го, след като извикате `enable()`.
 
 
-Производствен режим и регистриране на грешки .[#toc-production-mode-and-error-logging]
-======================================================================================
+Разработване срещу производствен режим .[#toc-development-vs-production-mode]
+=============================================================================
 
-Както виждате, Трейси е доста красноречива. Това може да бъде оценено в среда за разработка, но в производствен сървър ще доведе до катастрофа. Там не може да се регистрира информация за отстраняване на грешки. Ето защо Tracy разполага с функция за автоматично откриване на средата и регистриране. Вместо да се покаже, Tracy съхранява информацията в лог файл и показва на посетителя разбираемо за потребителя съобщение за грешка на сървъра:
+Както можете да видите, Трейси е доста разговорлив, което може да се оцени в среда за разработка, докато на производствен сървър това би довело до катастрофа. Това е така, защото там не трябва да се показва информация за отстраняване на грешки. Поради това Tracy има **автоматично откриване на средата** и ако примерът се изпълнява на реален сървър, грешката ще се регистрира, вместо да се показва, а посетителят ще вижда само удобно за потребителя съобщение:
 
 [* tracy-error2.webp .{url:-} *]
 
-Изходът в производствен режим потиска цялата информация за отстраняване на грешки, която се изпраща чрез [dump( |dumper]), и, разбира се, всички съобщения за грешки, генерирани от PHP. По този начин, дори да забравите `dump($obj)` в изходния си код, няма да се налага да се притеснявате за това в производствения си сървър. Нищо няма да се вижда.
+Производственият режим потиска показването на цялата информация за отстраняване на грешки, изпратена с помощта на [dump( |dumper]), и разбира се, на всички съобщения за грешки, генерирани от PHP. Така че, ако сте забравили някои `dump($obj)` в кода, не трябва да се притеснявате, нищо няма да бъде показано на производствения сървър.
+
+Как работи автоматичното откриване на режими? Режимът е за разработка, ако приложението работи на localhost (т.е. IP адрес `127.0.0.1` или `::1`) и няма прокси (т.е. HTTP заглавието му). В противен случай то се изпълнява в производствен режим.
+
+Ако искате да активирате режим на разработка в други случаи, например за разработчици, които осъществяват достъп от определен IP адрес, можете да го зададете като параметър на метода `enable()`:
+
+```php
+Debugger::enable('23.75.345.200'); // можете също така да предоставите масив от IP адреси
+```
+
+Определено препоръчваме да комбинирате IP адреса с бисквитка. Съхранявайте таен токен, например `secret1234`, в бисквитката `tracy-debug` и по този начин активирайте режима за разработка само за разработчици, осъществяващи достъп от определен IP адрес, които имат споменатия токен в бисквитката:
+
+```php
+Debugger::enable('[email protected]');
+```
+
+Можете също така директно да зададете режима на разработка/производство, като използвате константите `Debugger::Development` или `Debugger::Production` като параметър на метода `enable()`.
+
+.[note]
+Ако използвате Nette Framework, погледнете как да [зададете режима за него |application:bootstrap#Development vs Production Mode] и след това той ще се използва и за Tracy.
 
-Режимът на извеждане се определя от първия параметър `Debugger::enable()`. Можете да посочите константа `Debugger::Production`, или `Debugger::Development`. Друга възможност е да зададете режим на разработка да се активира, когато приложението е достъпно от определен IP адрес с определена стойност на "бисквитка" `tracy-debug`. Това се прави с помощта на синтаксиса `cookie-value@ip-address`.
 
-Ако не е зададена, се използва стойността по подразбиране `Debugger::Detect`. В този случай системата идентифицира сървъра чрез IP адрес. Производствен режим се избира, ако достъпът до приложението се осъществява чрез публичен IP адрес. Резултатите от локалния IP адрес са в режим на разработка. В повечето случаи не е необходимо да задавате режима. Режимът се разпознава правилно, когато приложението работи на локалния сървър или в производствен режим.
+Регистриране на грешки .[#toc-error-logging]
+============================================
 
-В производствен режим Tracy автоматично записва всички грешки и изключения в текстов дневник. Освен ако не посочите друго, тя ще се съхранява в log/error.log. Този дневник за грешки е изключително полезен. Представете си, че всички потребители на вашето приложение са всъщност бета Tester. Те вършат безплатно най-съвременната работа по откриване на грешки и би било глупаво да изхвърлите дискретно ценните им доклади в кошчето за боклук.
+В производствен режим Tracy автоматично записва всички грешки и изключения в текстов дневник. За да се извършва записването, трябва да зададете абсолютния път до директорията за запис в променливата `$logDirectory` или да я предадете като втори параметър на метода `enable()`:
+
+```php
+Debugger::$logDirectory = __DIR__ . '/log';
+```
+
+Регистрирането на грешки е изключително полезно. Представете си, че всички потребители на вашето приложение всъщност са бета тестери, които безплатно вършат първокласна работа по откриването на грешки, и би било глупаво да изхвърлите техните ценни доклади незабелязано в кошчето за боклук.
 
 Ако трябва да регистрирате собствени съобщения или прихванати изключения, използвайте метода `log()`:
 
@@ -142,13 +164,7 @@ try {
 }
 ```
 
-Директорията за регистриране на грешки може да бъде зададена като втори параметър на метода enable():
-
-```php
-Debugger::enable(Debugger::Detect, __DIR__ . '/mylog');
-```
-
-Ако искате Tracy да регистрира PHP грешки като `E_NOTICE` или `E_WARNING` с подробна информация (HTML отчет), задайте `Debugger::$logSeverity`:
+If you want Tracy to log PHP errors like `E_NOTICE` or `E_WARNING` with detailed information (HTML report), set `Debugger::$logSeverity`:
 
 ```php
 Debugger::$logSeverity = E_NOTICE | E_WARNING;

tracy/cs/guide.texy

@@ -42,12 +42,8 @@ use Tracy\Debugger;
 Debugger::enable();
 ```
 
-První, čeho si můžete na stránce všimnout, Tracy Bar.
-
-(Pokud nic nevidíte, znamená to, že Tracy běží v produkčním režimu. Tracy je z bezpečnostních důvodů viditelná pouze na localhost.
-Můžete vynutit, aby Tracy běžela ve vývojovém režimu předáním `Debugger::Development` jako prvního parametru metody `enable()`.)
-
-`enable()` změní úroveň hlášených chyb na E_ALL.
+První, čeho si na stránce všimnete, je Tracy Bar v pravém dolním rohu. Pokud jej nevidíte, může to znamenat, že Tracy běží v produkčním režimu.
+Tracy je totiž z bezpečnostních důvodů viditelná pouze na localhost. Pro otestování, zda funguje, ji můžete dočasně přepnout do vývojovém režimu pomocí parametru `Debugger::enable(Debugger::Development)`.
 
 
 Tracy Bar
@@ -111,23 +107,48 @@ Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // všechny
 
 [* tracy-notice.webp .{url:-} *]
 
-Abychom odhalili i překlepy při přiřazení do proměnné objektu, použijeme [traitu Nette\SmartObject |utils:smartobject].
+Poznámka: Tracy po aktivaci změní úroveň hlášení chyb na E_ALL. Pokud chcete tuto hodnotu změnit, učiňte tak po volání `enable()`.
 
 
-Produkční režim a logování chyb
-===============================
+Vývojářský vs produkční režim
+=============================
 
-Jak vidíte, Laděnka je poměrně výřečná, což lze ocenit ve vývojovém prostředí, zatímco na produkčním serveru by to způsobilo hotové neštěstí. Tam se totiž žádné ladící informace vypsat nesmí. Laděnka proto disponuje autodetekcí prostředí a pokud příklad spustíme na ostrém serveru, chyba se místo zobrazení zaloguje a návštěvník uvidí jen uživatelsky srozumitelnou hlášku:
+Jak vidíte, Laděnka je poměrně výřečná, což lze ocenit ve vývojovém prostředí, zatímco na produkčním serveru by to způsobilo hotové neštěstí. Tam se totiž žádné ladící informace vypsat nesmí. Laděnka proto disponuje **autodetekcí prostředí** a pokud příklad spustíme na ostrém serveru, chyba se místo zobrazení zaloguje a návštěvník uvidí jen uživatelsky srozumitelnou hlášku:
 
 [* tracy-error2.webp .{url:-} *]
 
 Produkční režim potlačí zobrazování všech ladících informacích, které posíláme ven pomocí [dump() |dumper], a samozřejmě také všech chybových zpráv, které generuje PHP. Pokud jste tedy v kódu zapomněli nějaké `dump($obj)`, nemusíte se obávat, na produkčním serveru se nic nevypíše.
 
-K nastavování režimu se používá první parametr metody `Debugger::enable()`. Režim lze napevno nastavit konstantou `Debugger::Production` nebo `Debugger::Development`. Další možnost je, že bude vývojový režim zapnutý při přístupu z dané IP adresy s danou hodnotou `tracy-debug` cookie. Používá se syntaxe `hodnota-cookie@ip-adresa`.
+Jak funguje autodetekce režimu? Režim je vývojářský tehdy, pokud je aplikace spuštěna na localhostu (tj. IP adresa `127.0.0.1` nebo `::1`) a není přitomna proxy (tj. její HTTP hlavička). Jinak běží v produkčním režimu.
+
+Pokud chceme vývojářský režim povolit i v dalších případech, například programátorům přistupujícím z konkrétní IP adresy, uvedeme ji jako parametr metody `enable()`:
+
+```php
+Debugger::enable('23.75.345.200'); // lze uvést i pole IP adres
+```
+
+Rozhodně doporučujeme kombinovat IP adresu s cookie. Do cookie `tracy-debug` uložíme tajný token, např. `secret1234`, a tímto způsobem aktivujeme vývojářský režim jen pro programátory přistupující z konkrétní IP adresy, kteří mají v cookie zmíněný token:
+
+```php
+Debugger::enable('[email protected]');
+```
+
+Vývojářský/produkční režim můžeme také přímo nastavit použitím konstanty `Debugger::Development` nebo `Debugger::Production` jako parametru metody `enable()`.
 
-Pokud jej neuvedeme, má výchozí hodnotu `Debugger::Detect` a v takovém případě se detekuje režim podle IP adresy serveru - je-li dostupný přes veřejnou IP adresu, běží v produkčním režimu, je-li na lokální, tak ve vývojářském. V drtivé většině případů tak není potřeba režim nastavovat a správně se rozezná podle toho, jestli aplikaci spouštíme na svém lokálním serveru nebo v ostrém provozu.
+.[note]
+Pokud používát Nette Framework, podívejte se, jak [nastavit režim pro něj |application:bootstrap#Vývojářský vs produkční režim] a ten se následně použije i pro Tracy.
 
-V produkčním režimu Laděnka automaticky všechny chyby a zachycené výjimky zaznamenává do textového logu. Pokud neurčíme jinak, půjde o soubor `log/error.log`. Logování chyb je přitom nesmírně užitečné. Představte si, že všichni uživatelé vaší aplikace jsou vlastně betatesteři, kteří zdarma odvádějí špičkovou práci v hledání chyb a vy byste udělali hloupost, kdybyste jejich cenné reporty zahodili bez povšimnutí do odpadkového koše.
+
+Logování chyb
+=============
+
+V produkčním režimu Laděnka automaticky všechny chyby a zachycené výjimky zaznamenává do textového logu. Aby logování mohlo probíhat, musíme nastavit absolutní cestu k logovacímu adresáři do proměnné `$logDirectory` nebo předat jako druhý parametr metody `enable()`:
+
+```php
+Debugger::$logDirectory = __DIR__ . '/log';
+```
+
+Logování chyb je přitom nesmírně užitečné. Představte si, že všichni uživatelé vaší aplikace jsou vlastně betatesteři, kteří zdarma odvádějí špičkovou práci v hledání chyb a vy byste udělali hloupost, kdybyste jejich cenné reporty zahodili bez povšimnutí do odpadkového koše.
 
 Pokud potřebujeme zalogovat vlastní zprávu nebo vámi zachycenou výjimku, použijeme k tomu metodu `log()`:
 
@@ -143,12 +164,6 @@ try {
 }
 ```
 
-Jiný adresář pro logování chyb lze nastavit druhým parametrem metody enable():
-
-```php
-Debugger::enable(Debugger::Detect, __DIR__ . '/mylog');
-```
-
 Pokud chcete, aby Tracy logovala PHP chyby jako `E_NOTICE` nebo `E_WARNING` s podrobnými informacemi (HTML report), nastavte `Debugger::$logSeverity`:
 
 ```php