Skip to content

🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev

docs: Add Russian docs for the website

Karim shoair50c99b9b3fc3
diff --git a/docs/README_RU.md b/docs/README_RU.md
index 9a1e9ce..5192822 100644
--- a/docs/README_RU.md
+++ b/docs/README_RU.md
@@ -1,66 +1,66 @@
<!-- mcp-name: io.github.D4Vinci/Scrapling -->
<h1 align="center">
- <a href="https://scrapling.readthedocs.io">
+ <a href="https://scrapling.readthedocs.io/en/latest/ru/">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/docs/assets/cover_dark.svg?sanitize=true">
- <img alt="Scrapling Poster" src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/docs/assets/cover_light.svg?sanitize=true">
+ <img alt="Обложка Scrapling" src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/docs/assets/cover_light.svg?sanitize=true">
</picture>
</a>
<br>
- <small>Effortless Web Scraping for the Modern Web</small>
+ <small>Простой веб-скрапинг для современного интернета</small>
</h1>
<p align="center">
- <a href="https://github.com/D4Vinci/Scrapling/actions/workflows/tests.yml" alt="Tests">
- <img alt="Tests" src="https://github.com/D4Vinci/Scrapling/actions/workflows/tests.yml/badge.svg"></a>
- <a href="https://badge.fury.io/py/Scrapling" alt="PyPI version">
- <img alt="PyPI version" src="https://badge.fury.io/py/Scrapling.svg"></a>
+ <a href="https://github.com/D4Vinci/Scrapling/actions/workflows/tests.yml" alt="Тесты">
+ <img alt="Тесты" src="https://github.com/D4Vinci/Scrapling/actions/workflows/tests.yml/badge.svg"></a>
+ <a href="https://badge.fury.io/py/Scrapling" alt="Версия PyPI">
+ <img alt="Версия PyPI" src="https://badge.fury.io/py/Scrapling.svg"></a>
<a href="https://hub.docker.com/r/pyd4vinci/scrapling" target="_blank">
- <img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/pyd4vinci/scrapling?labelColor=%20%23FDB062&logo=Docker&labelColor=%20%23528bff"></a>
- <a href="https://clickpy.clickhouse.com/dashboard/scrapling" rel="nofollow"><img src="https://img.shields.io/pypi/dm/scrapling" alt="PyPI package downloads"></a>
- <a href="https://scrapling.readthedocs.io/en/latest/ai/agent-skill.html" alt="AI Agent Skill">
- <img alt="Static Badge" src="https://img.shields.io/badge/Skill-black?style=flat&label=Agent&link=https%3A%2F%2Fscrapling.readthedocs.io%2Fen%2Flatest%2Fai%2Fagent-skill.html"></a>
- <a href="https://clawhub.ai/D4Vinci/scrapling-official" alt="OpenClaw Skill">
- <img alt="OpenClaw Skill" src="https://img.shields.io/badge/Clawhub-darkred?style=flat&label=OpenClaw&link=https%3A%2F%2Fclawhub.ai%2FD4Vinci%2Fscrapling-official"></a>
+ <img alt="Загрузки Docker" src="https://img.shields.io/docker/pulls/pyd4vinci/scrapling?labelColor=%20%23FDB062&logo=Docker&labelColor=%20%23528bff"></a>
+ <a href="https://clickpy.clickhouse.com/dashboard/scrapling" rel="nofollow"><img src="https://img.shields.io/pypi/dm/scrapling" alt="Загрузки пакета PyPI"></a>
+ <a href="https://scrapling.readthedocs.io/en/latest/ru/ai/agent-skill.html" alt="Skill для AI-агентов">
+ <img alt="Значок Agent Skill" src="https://img.shields.io/badge/Skill-black?style=flat&label=Agent&link=https%3A%2F%2Fscrapling.readthedocs.io%2Fen%2Flatest%2Fru%2Fai%2Fagent-skill.html"></a>
+ <a href="https://clawhub.ai/D4Vinci/scrapling-official" alt="Skill для OpenClaw">
+ <img alt="Skill для OpenClaw" src="https://img.shields.io/badge/Clawhub-darkred?style=flat&label=OpenClaw&link=https%3A%2F%2Fclawhub.ai%2FD4Vinci%2Fscrapling-official"></a>
<br/>
<a href="https://discord.gg/EMgGbDceNQ" alt="Discord" target="_blank">
<img alt="Discord" src="https://img.shields.io/discord/1360786381042880532?style=social&logo=discord&link=https%3A%2F%2Fdiscord.gg%2FEMgGbDceNQ">
</a>
- <a href="https://x.com/Scrapling_dev" alt="X (formerly Twitter)">
- <img alt="X (formerly Twitter) Follow" src="https://img.shields.io/twitter/follow/Scrapling_dev?style=social&logo=x&link=https%3A%2F%2Fx.com%2FScrapling_dev">
+ <a href="https://x.com/Scrapling_dev" alt="X (бывший Twitter)">
+ <img alt="Подписаться в X (бывший Twitter)" src="https://img.shields.io/twitter/follow/Scrapling_dev?style=social&logo=x&link=https%3A%2F%2Fx.com%2FScrapling_dev">
</a>
<br/>
- <a href="https://pypi.org/project/scrapling/" alt="Supported Python versions">
- <img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/scrapling.svg"></a>
+ <a href="https://pypi.org/project/scrapling/" alt="Поддерживаемые версии Python">
+ <img alt="Поддерживаемые версии Python" src="https://img.shields.io/pypi/pyversions/scrapling.svg"></a>
</p>
<p align="center">
- <a href="https://scrapling.readthedocs.io/en/latest/parsing/selection.html"><strong>Методы выбора</strong></a>
+ <a href="https://scrapling.readthedocs.io/en/latest/ru/parsing/selection.html"><strong>Поиск элементов</strong></a>
&middot;
- <a href="https://scrapling.readthedocs.io/en/latest/fetching/choosing.html"><strong>Выбор Fetcher</strong></a>
+ <a href="https://scrapling.readthedocs.io/en/latest/ru/fetching/choosing.html"><strong>Выбор Fetcher</strong></a>
&middot;
- <a href="https://scrapling.readthedocs.io/en/latest/spiders/architecture.html"><strong>Пауки</strong></a>
+ <a href="https://scrapling.readthedocs.io/en/latest/ru/spiders/architecture.html"><strong>Пауки</strong></a>
&middot;
- <a href="https://scrapling.readthedocs.io/en/latest/spiders/proxy-blocking.html"><strong>Ротация прокси</strong></a>
+ <a href="https://scrapling.readthedocs.io/en/latest/ru/spiders/proxy-blocking.html"><strong>Смена прокси</strong></a>
&middot;
- <a href="https://scrapling.readthedocs.io/en/latest/cli/overview.html"><strong>CLI</strong></a>
+ <a href="https://scrapling.readthedocs.io/en/latest/ru/cli/overview.html"><strong>CLI</strong></a>
&middot;
- <a href="https://scrapling.readthedocs.io/en/latest/ai/mcp-server.html"><strong>Режим MCP</strong></a>
+ <a href="https://scrapling.readthedocs.io/en/latest/ru/ai/mcp-server.html"><strong>MCP-сервер</strong></a>
</p>
-Scrapling - это фреймворк для Web Scraping на Python, который объединяет быстрые HTTP-запросы, скрытные браузеры, мощный парсинг и параллельный обход сайтов в одной библиотеке.
+Scrapling объединяет быстрые HTTP-запросы, скрытные браузеры, мощный разбор страниц и параллельный обход сайтов в одной библиотеке Python.
-Собирайте данные со статических страниц, выполняйте JavaScript, взаимодействуйте с сайтами и извлекайте данные из их API-запросов. Создавайте краулеры с повторно используемыми сессиями, ротацией прокси, автоматическими повторными попытками, паузой и возобновлением работы и встроенным экспортом данных.
+Загружайте статические страницы, выполняйте JavaScript, работайте с сайтами и извлекайте данные из API этих сайтов. Создавайте краулеры с повторным использованием сессий, сменой прокси, автоматическими повторами, паузой и продолжением работы, а также готовым экспортом данных.
-Используйте Scrapling из Python, терминала или через своего ИИ-агента с помощью MCP-сервера и Agent Skill. Scrapling охватывает весь процесс сбора данных из интернета: от извлечения нескольких полей до сбора целого сайта в чистом Markdown.
+Используйте Scrapling из Python, терминала или AI-агента через MCP-сервер и Agent Skill. Библиотека помогает на всех этапах: от извлечения нескольких полей до сохранения целого сайта в виде чистых Markdown-файлов.
-## Что можно делать с Scrapling
+## Что можно сделать со Scrapling
-- **[Загружать и взаимодействовать](https://scrapling.readthedocs.io/en/latest/fetching/choosing.html)**: Быстрые HTTP-запросы, скрытные браузеры, рендеринг JavaScript, работа с Cloudflare Turnstile/Interstitial, постоянные сессии и запись фоновых API-запросов.
-- **[Разбирать и извлекать](https://scrapling.readthedocs.io/en/latest/parsing/selection.html)**: CSS, XPath, поиск по тексту и регулярным выражениям, адаптивное отслеживание элементов, поиск похожих элементов и вывод в чистом Markdown.
-- **[Обходить сайты и экспортировать данные](https://scrapling.readthedocs.io/en/latest/spiders/getting-started.html)**: Параллельные пауки, ротация прокси, повторные попытки, AutoThrottle, пауза и возобновление работы, Streaming, готовые шаблоны и экспорт в JSON/JSONL/CSV/XML.
-- **[Собирать данные с ИИ или из терминала](https://scrapling.readthedocs.io/en/latest/ai/mcp-server.html)**: MCP-сервер для ИИ-агентов с возможностью просматривать сайты и извлекать данные, Agent Skill, команды CLI и интерактивная Shell.
+- **[Загрузка и работа с сайтами](https://scrapling.readthedocs.io/en/latest/ru/fetching/choosing.html)**: быстрые HTTP-запросы, скрытные браузеры, выполнение JavaScript, прохождение Cloudflare Turnstile и Interstitial, постоянные сессии и запись фоновых API-ответов.
+- **[Разбор и извлечение данных](https://scrapling.readthedocs.io/en/latest/ru/parsing/selection.html)**: CSS, XPath, поиск по тексту и регулярным выражениям, поиск элементов после изменений страницы, поиск похожих элементов и чистый Markdown.
+- **[Обход и экспорт](https://scrapling.readthedocs.io/en/latest/ru/spiders/getting-started.html)**: параллельные Spider, смена прокси, повторы, AutoThrottle, пауза и продолжение, потоковая выдача, готовые шаблоны и экспорт в JSON, JSONL, CSV и XML.
+- **[Сбор данных с AI или из терминала](https://scrapling.readthedocs.io/en/latest/ru/ai/mcp-server.html)**: MCP-сервер для работы AI-агентов с сайтами и данными, Agent Skill, команды CLI и интерактивная оболочка.
Начните с одной страницы:
@@ -72,7 +72,7 @@ quotes = page.css('.quote .text::text').getall()
print(quotes)
```
-Или масштабируйте сбор данных с помощью Spider:
+Или используйте Spider для обхода многих страниц:
```python
from scrapling.spiders import Spider, Response
@@ -93,7 +93,7 @@ print(len(result.items))
result.items.to_json("quotes.json")
```
-Код выводит `10` и сохраняет цитаты и авторов в `quotes.json`.
+Код выведет `10` и сохранит цитаты с авторами в `quotes.json`.
<p align="center">
<a href="https://dataimpulse.com/?utm_source=scrapling&utm_medium=banner&utm_campaign=scrapling" target="_blank" style="display:flex; justify-content:center; padding:4px 0;">
@@ -110,7 +110,7 @@ result.items.to_json("quotes.json")
</a>
</td>
<td>
- <a href="https://go.nodemaven.com/scraplingseptember" target="_blank">NodeMaven</a> - самый эффективный провайдер прокси для веб-скрапинга и автоматизации с самым высоким качеством IP на рынке. Используйте код SCRAPLING35 для получения скидки 35%.
+ <a href="https://go.nodemaven.com/scraplingseptember" target="_blank">NodeMaven</a> - самый эффективный провайдер прокси для веб-скрапинга и автоматизации с IP-адресами самого высокого качества на рынке. Используйте код SCRAPLING35 для получения скидки 35%.
</td>
</tr>
<tr>
@@ -119,10 +119,10 @@ result.items.to_json("quotes.json")
<img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/HyperSolutions.png">
</a>
</td>
- <td> Scrapling справляется с Cloudflare Turnstile. Для защиты корпоративного уровня
+ <td> Scrapling справляется с Cloudflare Turnstile. Для обхода защиты корпоративного уровня
<a href="https://hypersolutions.co?utm_source=github&utm_medium=readme&utm_campaign=scrapling">
<b>Hyper Solutions</b>
- </a> предоставляет API-эндпоинты, генерирующие валидные antibot-токены для <b>Akamai</b>, <b>DataDome</b>, <b>Kasada</b> и <b>Incapsula</b> . Простые API-вызовы, без автоматизации браузера.
+ </a> предоставляет API для получения действительных antibot-токенов для <b>Akamai</b>, <b>DataDome</b>, <b>Kasada</b> и <b>Incapsula</b>. Достаточно простых вызовов API. Автоматизация браузера не нужна.
</td>
</tr>
<tr>
@@ -134,7 +134,7 @@ result.items.to_json("quotes.json")
<td>
<a href="https://evomi.com?utm_source=github&utm_medium=banner&utm_campaign=d4vinci-scrapling">
<b>Evomi</b>
- </a>: резидентные прокси от $0.49/ГБ. Браузер для скрапинга с полностью подменённым Chromium, резидентными IP, автоматическим решением CAPTCHA и обходом анти-бот систем. </br>
+ </a>: резидентные прокси от $0,49/ГБ. Браузер для скрапинга на основе Chromium с полной подменой отпечатка браузера, резидентными IP, автоматическим решением CAPTCHA и обходом защиты от ботов. </br>
<b>Scraper API для получения результатов без лишних сложностей. Доступны интеграции с MCP и N8N.</b>
</td>
</tr>
@@ -145,7 +145,7 @@ result.items.to_json("quotes.json")
</a>
</td>
<td>
- <a href="https://tikhub.io/?utm_source=github.com/D4Vinci/Scrapling&utm_medium=marketing_social&utm_campaign=retargeting&utm_content=carousel_ad" target="_blank">TikHub.io</a> предоставляет более 900 стабильных API на 16+ платформах, включая TikTok, X, YouTube и Instagram, с более чем 40 млн наборов данных. <br /> Также предлагает <a href="https://ai.tikhub.io/?ref=KarimShoair" target="_blank">AI-модели со скидкой</a> - Claude, GPT, GEMINI и другие со скидкой до 71%.
+ <a href="https://tikhub.io/?utm_source=github.com/D4Vinci/Scrapling&utm_medium=marketing_social&utm_campaign=retargeting&utm_content=carousel_ad" target="_blank">TikHub.io</a> предоставляет более 900 стабильных API на 16+ платформах, включая TikTok, X, YouTube и Instagram, с доступом к более чем 40 млн наборов данных. <br /> Также предлагает <a href="https://ai.tikhub.io/?ref=KarimShoair" target="_blank">AI-модели со скидкой</a> - Claude, GPT, GEMINI и другие со скидкой до 71%.
</td>
</tr>
<tr>
@@ -155,7 +155,7 @@ result.items.to_json("quotes.json")
</a>
</td>
<td>
- Прочитайте полный обзор <a href="https://substack.thewebscraping.club/p/scrapling-hands-on-guide?utm_source=github&utm_medium=repo&utm_campaign=scrapling" target="_blank">Scrapling на The Web Scraping Club</a> (ноябрь 2025) - рассылка №1, посвящённая веб-скрейпингу.
+ Прочитайте полный обзор <a href="https://substack.thewebscraping.club/p/scrapling-hands-on-guide?utm_source=github&utm_medium=repo&utm_campaign=scrapling" target="_blank">Scrapling на The Web Scraping Club</a> (ноябрь 2025), опубликованный в рассылке №1 по веб-скрапингу.
</td>
</tr>
<tr>
@@ -175,7 +175,7 @@ result.items.to_json("quotes.json")
</a>
</td>
<td>
- <a href="https://byteful.com/?utm_source=github&utm_medium=github-sponsor&utm_campaign=scrapling_github_sponsor" target="_blank">Byteful</a> предоставляет резидентные, мобильные, ISP- и дата-центровые прокси из этичных источников, а также инструменты для веб-скрейпинга и автоматизации с ИИ. Используйте код SCRAPLING10 для получения скидки 10% на резидентные прокси.
+ <a href="https://byteful.com/?utm_source=github&utm_medium=github-sponsor&utm_campaign=scrapling_github_sponsor" target="_blank">Byteful</a> предоставляет резидентные, мобильные, ISP- и дата-центровые прокси из этичных источников, а также инструменты для веб-скрапинга и автоматизации с AI. Используйте код SCRAPLING10 для получения скидки 10% на резидентные прокси.
</td>
</tr>
<tr>
@@ -185,7 +185,7 @@ result.items.to_json("quotes.json")
</a>
</td>
<td>
- <a href="https://proxylane.dev/?utm_source=scrapling&utm_medium=partnership&utm_campaign=scrapling_platinum_202609&utm_content=github_readme" target="_blank">ProxyLane</a>: Сократите число блокировок и CAPTCHA на 90%. 28 млн премиальных резидентных IP-адресов для интенсивного веб-скрейпинга. 195 стран. Таргетинг по городу/ISP/почтовому индексу. Сессии с постоянным IP или ротацией. Трафик без срока действия от $2/GB. Код <strong>SCRAPEANDTAKE</strong>: <em>скидка 25%</em>.
+ <a href="https://proxylane.dev/?utm_source=scrapling&utm_medium=partnership&utm_campaign=scrapling_platinum_202609&utm_content=github_readme" target="_blank">ProxyLane</a>: Сократите число блокировок и CAPTCHA на 90%. 28 млн премиальных резидентных IP-адресов для интенсивного веб-скрапинга. 195 стран. Выбор города, ISP и почтового индекса. Сессии с постоянным IP или сменой IP. Трафик без срока действия от $2/ГБ. Код <strong>SCRAPEANDTAKE</strong>: <em>скидка 25%</em>.
</td>
</tr>
<tr>
@@ -195,7 +195,7 @@ result.items.to_json("quotes.json")
</a>
</td>
<td>
- <a href="https://www.lundproxy.com?utm_source=github&utm_medium=sponsorship&utm_campaign=scrapling&utm_content=text" target="_blank">LundProxy</a>: Хватит платить за каждый GB. Безлимитный резидентный трафик, более 100 млн IP-адресов, более 190 стран. Оплата по пропускной способности. Запросите бесплатный пробный доступ к резидентным прокси на скорости 50 Mbps.
+ <a href="https://www.lundproxy.com?utm_source=github&utm_medium=sponsorship&utm_campaign=scrapling&utm_content=text" target="_blank">LundProxy</a>: Хватит платить за каждый ГБ. Безлимитный резидентный трафик, более 100 млн IP-адресов, более 190 стран. Оплата по пропускной способности. Запросите бесплатный пробный доступ к резидентным прокси на скорости 50 Мбит/с.
</td>
</tr>
<tr>
@@ -205,12 +205,12 @@ result.items.to_json("quotes.json")
</a>
</td>
<td>
- $1/GB в <a href="https://dataimpulse.com/?utm_source=website&utm_medium=github_readme&utm_campaign=scrapling_platinum" target="_blank">DataImpulse</a>. Прокси из этичных источников, без посредников. Более 90 млн IP-адресов, более 195 стран. Резидентные, дата-центровые и мобильные. Оплата по мере использования = без подписки. Трафик без срока действия.
+ $1/ГБ в <a href="https://dataimpulse.com/?utm_source=website&utm_medium=github_readme&utm_campaign=scrapling_platinum" target="_blank">DataImpulse</a>. Прокси из этичных источников, без посредников. Более 90 млн IP-адресов, более 195 стран. Резидентные, дата-центровые и мобильные. Оплата по мере использования, без подписки. Трафик без срока действия.
</td>
</tr>
</table>
-<i><sub>Хотите показать здесь свою рекламу? Нажмите [здесь](https://github.com/sponsors/D4Vinci/sponsorships?tier_id=586646)</sub></i>
+<i><sub>Хотите разместить здесь свою рекламу? Нажмите [здесь](https://github.com/sponsors/D4Vinci/sponsorships?tier_id=586646)</sub></i>
# Спонсоры
<!-- sponsors -->
@@ -228,71 +228,77 @@ result.items.to_json("quotes.json")
<!-- /sponsors -->
-<i><sub>Хотите показать здесь свою рекламу? Нажмите [здесь](https://github.com/sponsors/D4Vinci) и выберите подходящий вам уровень!</sub></i>
+<i><sub>Хотите разместить здесь свою рекламу? Нажмите [здесь](https://github.com/sponsors/D4Vinci) и выберите подходящий план!</sub></i>
---
-## Ключевые особенности
-
-### Spider'ы - полноценный фреймворк для обхода сайтов
-- 🕷️ **Scrapy-подобный Spider API**: Определяйте Spider'ов с `start_urls`, async `parse` callback'ами и объектами `Request`/`Response`.
-- ⚡ **Параллельный обход**: Настраиваемые лимиты параллелизма, ограничение скорости по домену и задержки загрузки.
-- 🔄 **Поддержка нескольких сессий**: Единый интерфейс для HTTP-запросов и скрытных headless-браузеров в одном Spider - маршрутизируйте запросы к разным сессиям по ID.
-- 💾 **Пауза и возобновление**: Сохраняйте ожидающие запросы и посещённые URL с `crawldir`. Остановите процесс через Ctrl+C и запустите с тем же каталогом.
-- 📡 **Режим Streaming**: Стримьте извлечённые элементы по мере их поступления через `async for item in spider.stream()` со статистикой в реальном времени - идеально для UI, конвейеров и длительных обходов.
-- 🛡️ **Обнаружение заблокированных запросов**: Автоматическое обнаружение и повторная отправка заблокированных запросов с настраиваемой логикой.
-- 🚦 **AutoThrottle**: Больше не нужно угадывать задержки. Spider сам подбирает задержку для каждого домена по скорости ответа сайта, удваивает её (или ждёт столько, сколько просит `Retry-After`), когда сайт начинает блокировать или ограничивать вас, и снова ускоряется, когда это прекращается.
-- 🤖 **Соответствие robots.txt**: Опциональный флаг `robots_txt_obey`, который учитывает директивы `Disallow`, `Crawl-delay` и `Request-rate` с кэшированием по доменам.
-- 🧪 **Режим разработки**: Кэшируйте ответы на диск при первом запуске и воспроизводите их при последующих запусках - итерируйте над логикой `parse()`, не отправляя повторные запросы к целевым серверам.
-- 🧩 **Готовые шаблоны Spider**: Обойдитесь без шаблонного кода - `CrawlSpider` для перехода по ссылкам на основе правил, `SitemapSpider` для обхода на основе sitemap/robots.txt, `XMLFeedSpider`/`CSVFeedSpider` для перебора XML/RSS- и CSV-фидов и `ShopifySpider` для сбора товаров из общедоступных магазинов Shopify, по одной записи на вариант.
-- 🔗 **Извлечение ссылок**: Отдельный примитив `LinkExtractor` с шаблонами allow/deny, фильтрами доменов, ограничением области через CSS/XPath, фильтрацией расширений и канонизацией - используйте его внутри шаблонов или сам по себе.
-- 📦 **Встроенный экспорт**: Экспортируйте результаты через хуки и собственный конвейер или встроенные экспортеры JSON/JSONL/CSV/XML с `result.items.to_json()`, `to_jsonl()`, `to_csv()` и `to_xml()`.
-
-### Продвинутая загрузка сайтов с поддержкой Session
-- **HTTP-запросы**: Быстрые и скрытные HTTP-запросы с классом `Fetcher`. Может имитировать TLS fingerprint браузера, заголовки и использовать HTTP/3.
-- **Динамическая загрузка**: Загрузка динамических сайтов с полной автоматизацией браузера через класс `StealthyFetcher`, поддерживающий Chromium от Playwright и Google Chrome.
-- **Обход антибот-защиты**: Продвинутые возможности скрытности с `StealthyFetcher` и подменой отпечатков. Легко обходит любые типы Turnstile/Interstitial от Cloudflare с помощью автоматизации.
-- **Управление сессиями**: Поддержка постоянных сессий с классами `FetcherSession` и `StealthySession` для управления cookie и состоянием между запросами.
-- **Ротация Proxy**: Встроенный `ProxyRotator` с циклической или пользовательскими стратегиями для всех типов сессий, а также переопределение Proxy для каждого запроса.
-- **Блокировка доменов и рекламы**: Блокируйте запросы к определённым доменам (и их поддоменам) или включите встроенную блокировку рекламы (~3 500 известных рекламных/трекерных доменов) в браузерных Fetcher'ах.
-- **Защита от утечки DNS**: Опциональная поддержка DNS-over-HTTPS для маршрутизации DNS-запросов через Cloudflare DoH, предотвращая утечку DNS при использовании прокси.
-- **Удалённые браузеры**: Вместо запуска браузера локально подключайтесь по CDP через `cdp_url` к уже запущенному браузеру - на той же машине, на другом хосте или у провайдера управляемых браузеров. С помощью `executable_path` можно также направить любой браузерный Fetcher на вашу собственную сборку Chromium.
-- **Перехват фоновых API-запросов**: Включите `record_requests=True` в сессии браузера и ищите сохранённые ответы с помощью `session.network.search(limit=None)`. Читайте данные API и ошибки HTTP после загрузки разных страниц без повторной отправки запросов. История ограничена по размеру и сохраняет текстовые тела ответов.
-- **Поддержка async**: Полная async-поддержка во всех Fetcher'ах и выделенных async-классах сессий.
-
-### Парсинг и извлечение данных
-- 🔄 **Умное отслеживание элементов**: Перемещайте элементы после изменений сайта с помощью интеллектуальных алгоритмов подобия.
-- 🎯 **Умный гибкий выбор**: CSS-селекторы, XPath-селекторы, поиск на основе фильтров, текстовый поиск, поиск по регулярным выражениям и многое другое.
-- 🔍 **Поиск похожих элементов**: Автоматически находите элементы, похожие на найденные.
-
-### Возможности для ИИ
-- 🤖 **MCP-сервер**: Позвольте ИИ-чатботам и агентам (Claude/Cursor/и др.) скрапить через Scrapling с помощью HTTP-запросов, действий в браузере, скриншотов, сохранённых входов и фоновых ответов API. Наш скрытный браузер и нужные инструменты позволяют подходящим ИИ-моделям обходить любую CAPTCHA, с которой они столкнутся во время работы (не говоря уже о нашем решателе Cloudflare). Использует множество методов, чтобы сократить объём данных для модели, блокировать рекламу и защитить её от Prompt-Injection. Доступны удалённые браузеры через CDP и HTTP-транспорт с настройками аутентификации. ([Демонстрация](https://www.youtube.com/watch?v=qyFk3ZNwOxE))
-- 🧠 **Agent Skill**: Готовый к установке [Agent Skill](https://scrapling.readthedocs.io/en/latest/ai/agent-skill.html), который обучает кодовых агентов всей библиотеке, чтобы код, который они пишут с Scrapling, соответствовал актуальному API, а не догадкам.
-- 📚 **Markdown для RAG**: Превратите любую страницу в чистый, очищенный и готовый для LLM Markdown одной строкой (`page.markdown()`) или обойдите весь сайт, собрав корпус Markdown с помощью шаблона `ContentSpider`, и всё это без участия LLM в процессе. ([документация](https://scrapling.readthedocs.io/en/latest/ai/building-rag-systems.html))
-
-### Высокопроизводительная и проверенная в боях архитектура
-- 🚀 **Молниеносная скорость**: Оптимизированная производительность, превосходящая большинство Python-библиотек для скрапинга.
-- 🔋 **Эффективное использование памяти**: Оптимизированные структуры данных и ленивая загрузка для минимального потребления памяти.
-- ⚡ **Быстрая сериализация JSON**: В 10 раз быстрее стандартной библиотеки.
-- 🏗️ **Проверено в боях**: Scrapling имеет не только 92% покрытия тестами и полное покрытие type hints, но и ежедневно использовался сотнями веб-скраперов в течение последнего года.
-
-### Удобный для разработчиков/веб-скраперов опыт
-- 🎯 **Интерактивная Web Scraping Shell**: Опциональная встроенная IPython-оболочка с интеграцией Scrapling, ярлыками и новыми инструментами для ускорения разработки скриптов Web Scraping, такими как преобразование curl-запросов в запросы Scrapling и просмотр результатов запросов в браузере.
-- 🚀 **Используйте прямо из терминала**: При желании вы можете использовать Scrapling для скрапинга URL без написания ни одной строки кода!
-- 🛠️ **Богатый API навигации**: Расширенный обход DOM с методами навигации по родителям, братьям и детям.
-- 🧬 **Улучшенная обработка текста**: Встроенные регулярные выражения, методы очистки и оптимизированные операции со строками.
-- 📝 **Автоматическая генерация селекторов**: Генерация надёжных CSS/XPath-селекторов для любого элемента.
-- 🔌 **Знакомый API**: Похож на Scrapy/BeautifulSoup с теми же псевдоэлементами, используемыми в Scrapy/Parsel.
-- 🤝 **Прямая интеграция со Scrapy**: Уже используете Scrapy? Оберните любой callback декоратором `scrapling_response`, чтобы разбирать уже получаемые ответы парсером Scrapling - без переписывания проекта.
-- 📘 **Полное покрытие типами**: Полные type hints для отличной поддержки IDE и автодополнения кода. Вся кодовая база автоматически проверяется **PyRight** и **MyPy** при каждом изменении.
-- 🔋 **Готовый Docker-образ**: С каждым релизом автоматически создаётся и публикуется Docker-образ, содержащий все браузеры.
+## Основные возможности
+
+### Spider: всё для обхода сайтов
+
+- 🕷️ **API Spider в стиле Scrapy**: задайте `start_urls`, асинхронные обработчики `parse` и объекты `Request`/`Response`.
+- ⚡ **Параллельный обход**: настройте число одновременных запросов, ограничения для каждого домена и задержки между загрузками.
+- 🔄 **Несколько сессий**: используйте HTTP-запросы и скрытные браузеры без окна в одном Spider. Выбирайте сессию для запроса по её ID.
+- 💾 **Пауза и продолжение**: сохраняйте ожидающие запросы и посещённые URL с помощью `crawldir`. Нажмите Ctrl+C для корректной остановки, затем запустите Spider с той же папкой.
+- 📡 **Потоковая выдача**: получайте данные сразу после извлечения через `async for item in spider.stream()` и следите за статистикой в реальном времени. Удобно для интерфейсов, обработки данных и долгих обходов.
+- 🛡️ **Обнаружение блокировок**: заблокированные запросы автоматически обнаруживаются и повторяются. Логику можно настроить.
+- 🚦 **AutoThrottle**: больше не нужно угадывать задержки. Spider сам меняет задержку для каждого домена по скорости ответа сайта. При блокировках или ограничении частоты запросов он удваивает её либо ждёт время из `Retry-After`, а затем снова ускоряется.
+- 🤖 **Соблюдение robots.txt**: включите `robots_txt_obey`, чтобы учитывать `Disallow`, `Crawl-delay` и `Request-rate`. Правила кешируются для каждого домена.
+- 🧪 **Режим разработки**: сохраните ответы на диск при первом запуске и используйте их снова. Меняйте логику `parse()` без повторных обращений к серверам.
+- 🧩 **Готовые шаблоны Spider**: `CrawlSpider` обходит ссылки по правилам, `SitemapSpider` использует sitemap и robots.txt, `XMLFeedSpider`/`CSVFeedSpider` читают ленты XML/RSS и CSV, а `ShopifySpider` собирает товары из открытых магазинов Shopify, по одной записи на вариант.
+- 🔗 **Извлечение ссылок**: `LinkExtractor` поддерживает разрешающие и запрещающие шаблоны, фильтры доменов и расширений, выбор области через CSS/XPath и приведение URL к единому виду. Используйте его в шаблонах или отдельно.
+- 📦 **Готовый экспорт**: сохраняйте результаты через хуки и собственную обработку либо в JSON, JSONL, CSV и XML через `result.items.to_json()`, `to_jsonl()`, `to_csv()` и `to_xml()`.
+
+### Загрузка сайтов с поддержкой сессий
+
+- **HTTP-запросы**: `Fetcher` отправляет быстрые и скрытные запросы. Он умеет имитировать TLS-отпечаток и заголовки браузера, а также использовать HTTP/3.
+- **Динамические страницы**: `StealthyFetcher` загружает сайты с полной автоматизацией браузера. Поддерживаются Chromium из Playwright и Google Chrome.
+- **Обход защиты от ботов**: `StealthyFetcher` скрывает признаки автоматизации и подменяет отпечаток браузера. Он автоматически проходит все виды проверок Cloudflare Turnstile и Interstitial.
+- **Управление сессиями**: `FetcherSession` и `StealthySession` сохраняют cookie и состояние между запросами.
+- **Смена прокси**: `ProxyRotator` перебирает прокси по кругу или по вашим правилам во всех типах сессий. Для отдельного запроса можно указать другой прокси.
+- **Блокировка доменов и рекламы**: блокируйте запросы к выбранным доменам и их поддоменам. В браузерных Fetcher можно включить блокировку рекламы, которая охватывает около 3 500 рекламных и отслеживающих доменов.
+- **Защита от утечек DNS**: включите DNS-over-HTTPS, чтобы отправлять DNS-запросы через DoH от Cloudflare и не допускать утечек DNS при работе с прокси.
+- **Удалённые браузеры**: подключайтесь к уже запущенному браузеру через CDP с помощью `cdp_url`. Браузер может работать на том же компьютере, другом сервере или у провайдера браузерных услуг. Параметр `executable_path` позволяет указать собственную сборку Chromium для любого браузерного Fetcher.
+- **Запись фоновых API-ответов**: включите `record_requests=True` в браузерной сессии, затем ищите сохранённые ответы через `session.network.search(limit=None)`. Читайте API-данные и HTTP-ошибки от разных загрузок страниц без повторной отправки запросов. История имеет ограниченный размер и сохраняет текстовые тела ответов.
+- **Асинхронная работа**: все Fetcher поддерживают асинхронные вызовы. Есть и отдельные классы асинхронных сессий.
+
+### Разбор и извлечение данных
+
+- 🔄 **Поиск элементов после изменений**: алгоритмы сходства находят элементы снова, даже если сайт изменился.
+- 🎯 **Гибкий поиск**: используйте CSS, XPath, фильтры, текст, регулярные выражения и другие способы.
+- 🔍 **Похожие элементы**: автоматически находите элементы, похожие на уже найденные.
+
+### Возможности для AI
+
+- 🤖 **MCP-сервер**: AI-боты и агенты, такие как Claude и Cursor, могут собирать данные через Scrapling. Им доступны HTTP-запросы, действия в браузере, снимки экрана, сохранённый вход и фоновые API-ответы. Скрытный браузер и нужные инструменты позволяют подходящим AI-моделям проходить любые CAPTCHA во время работы, а проверки Cloudflare обрабатываются встроенным решением. Сервер уменьшает объём данных для модели, блокирует рекламу и защищает от Prompt Injection. Есть подключение к удалённым браузерам по CDP и HTTP-транспорт с настройками аутентификации. ([Демонстрация](https://www.youtube.com/watch?v=qyFk3ZNwOxE))
+- 🧠 **Agent Skill**: готовый к установке [Agent Skill](https://scrapling.readthedocs.io/en/latest/ru/ai/agent-skill.html) знакомит агента со всей библиотекой. Он помогает писать код под текущий API без догадок.
+- 📚 **Markdown для RAG**: одна строка (`page.markdown()`) превращает страницу в чистый и безопасный Markdown для LLM. Шаблон `ContentSpider` сохраняет целый сайт в набор Markdown-файлов. Для самого сбора и преобразования LLM не нужна. ([Документация](https://scrapling.readthedocs.io/en/latest/ru/ai/building-rag-systems.html))
+
+### Высокая скорость, проверенная на практике
+
+- 🚀 **Быстрая работа**: оптимизации позволяют опережать большинство библиотек Python для скрапинга.
+- 🔋 **Мало памяти**: оптимизированные структуры данных и загрузка только по мере необходимости.
+- ⚡ **Быстрое преобразование в JSON**: в 10 раз быстрее стандартной библиотеки.
+- 🏗️ **Проверено на практике**: 92% покрытия тестами и аннотации типов для всего кода. За последний год сотни специалистов ежедневно использовали Scrapling для сбора данных.
+
+### Удобные инструменты для разработчиков
+
+- 🎯 **Интерактивная оболочка**: дополнительная оболочка IPython со Scrapling, сокращёнными командами и инструментами для быстрой разработки. Преобразуйте curl-запросы в запросы Scrapling и просматривайте результаты в браузере.
+- 🚀 **Работа из терминала**: собирайте данные по URL, не написав ни строки кода!
+- 🛠️ **Навигация по DOM**: переходите к родителям, соседним и дочерним элементам.
+- 🧬 **Обработка текста**: регулярные выражения, очистка текста и быстрые операции со строками.
+- 📝 **Создание селекторов**: получайте надёжные CSS- и XPath-селекторы для любого элемента.
+- 🔌 **Знакомый API**: подход похож на Scrapy и BeautifulSoup, с теми же псевдоэлементами, что и в Scrapy/Parsel.
+- 🤝 **Интеграция со Scrapy**: добавьте декоратор `scrapling_response` к обработчику, чтобы разбирать уже загруженные ответы парсером Scrapling. Переписывать проект не нужно.
+- 📘 **Полные аннотации типов**: удобная работа в редакторе и автодополнение. При каждом изменении весь код автоматически проверяется **PyRight** и **MyPy**.
+- 🔋 **Готовый образ Docker**: с каждым выпуском автоматически собирается и публикуется образ со всеми браузерами.
## Начало работы
-Давайте кратко покажем, на что способен Scrapling, без глубокого погружения.
+Вот несколько примеров того, что умеет Scrapling.
### Базовое использование
-HTTP-запросы с поддержкой Session
+HTTP-запросы с сессиями
```python
from scrapling.fetchers import Fetcher, FetcherSession
@@ -329,8 +335,8 @@ page = StealthyFetcher.fetch('https://quotes.toscrape.com/')
data = page.css('.quote .text::text').getall()
```
-### Spider'ы
-Создавайте полноценные обходчики с параллельными запросами, несколькими типами сессий и Pause & Resume:
+### Пауки
+Создавайте краулеры с параллельными запросами, разными сессиями, паузой и продолжением работы:
```python
from scrapling.spiders import Spider, Response
@@ -375,13 +381,13 @@ class MultiSessionSpider(Spider):
else:
yield Request(link, sid="fast", callback=self.parse) # явный callback
```
-Приостанавливайте и возобновляйте длительные обходы с помощью Checkpoint'ов, запуская Spider следующим образом:
+Сохраняйте прогресс, чтобы приостанавливать и продолжать долгий обход. Запустите Spider так:
```python
QuotesSpider(crawldir="./crawl_data").start()
```
Если задан `crawldir`, нажмите Ctrl+C, чтобы сохранить ожидающие запросы и уже посещённые URL. Для продолжения запустите Spider с тем же `crawldir`. Сохраняйте извлечённые данные отдельно.
-Или совсем не пишите логику обхода: используйте готовые шаблоны, например, чтобы собрать весь каталог магазина Shopify:
+Можно взять готовый шаблон. Например, для сбора всего каталога магазина Shopify:
```python
from scrapling.spiders import ShopifySpider
@@ -390,9 +396,9 @@ class MyStore(ShopifySpider):
result = MyStore().start() # Все товары магазина, по одной записи на вариант
```
-Шаблон читает товары из публичных API коллекций, по одной записи на вариант.
+Шаблон получает товары через открытые API коллекций и выдаёт одну запись на каждый вариант товара.
-### Продвинутый парсинг и навигация
+### Расширенный разбор и навигация
```python
from scrapling.fetchers import Fetcher
@@ -422,7 +428,7 @@ parent_container = first_quote.parent
similar_elements = first_quote.find_similar()
below_elements = first_quote.below_elements
```
-Вы можете использовать парсер напрямую, если не хотите загружать сайты, как показано ниже:
+Можно использовать парсер напрямую, без загрузки сайта:
```python
from scrapling.parser import Selector
@@ -430,7 +436,7 @@ page = Selector("<html>...</html>")
```
И он работает точно так же!
-### Примеры async Session
+### Асинхронные сессии
```python
import asyncio
from scrapling.fetchers import FetcherSession, AsyncStealthySession
@@ -449,13 +455,13 @@ async def main():
asyncio.run(main())
```
-## CLI и интерактивная Shell
+## CLI и интерактивная оболочка
-Scrapling включает мощный интерфейс командной строки:
+Scrapling можно использовать из командной строки:
[![asciicast](https://asciinema.org/a/736339.svg)](https://asciinema.org/a/736339)
-Запустить интерактивную Web Scraping Shell
+Запустите интерактивную оболочку для сбора данных:
```bash
pip install "scrapling[shell]"
scrapling shell
@@ -469,52 +475,52 @@ scrapling extract fetch 'https://nopecha.com/demo/cloudflare' captchas.html --cs
```
> [!NOTE]
-> Есть множество дополнительных возможностей, но мы хотим сохранить эту страницу краткой, включая MCP-сервер и интерактивную Web Scraping Shell. Ознакомьтесь с полной документацией [здесь](https://scrapling.readthedocs.io/en/latest/)
+> О других возможностях, включая MCP-сервер и интерактивную оболочку, читайте в [документации](https://scrapling.readthedocs.io/en/latest/ru/).
## Тесты производительности
-Scrapling не только мощный - он ещё и невероятно быстрый. Следующие тесты производительности сравнивают парсер Scrapling с последними версиями других популярных библиотек.
+Scrapling не только мощный, но и очень быстрый. Следующие тесты производительности сравнивают парсер Scrapling с последними версиями других популярных библиотек.
-### Тест скорости извлечения текста (5000 вложенных элементов)
+### Скорость извлечения текста: 5 000 вложенных элементов
-| # | Библиотека | Время (мс) | vs Scrapling |
+| # | Библиотека | Время (мс) | По сравнению со Scrapling |
|---|:-----------------:|:----------:|:------------:|
-| 1 | Scrapling | 1.99 | 1.0x |
-| 2 | Parsel/Scrapy | 2.06 | 1.035 |
-| 3 | Raw Lxml | 2.56 | 1.286 |
-| 4 | PyQuery | 23.98 | ~12x |
-| 5 | Selectolax | 197.02 | ~99x |
-| 6 | MechanicalSoup | 1545.15 | ~776.5x |
-| 7 | BS4 with Lxml | 1562.1 | ~785.0x |
-| 8 | BS4 with html5lib | 3412.73 | ~1714.9x |
+| 1 | Scrapling | 1,99 | 1,0x |
+| 2 | Parsel/Scrapy | 2,06 | 1,035 |
+| 3 | Чистый Lxml | 2,56 | 1,286 |
+| 4 | PyQuery | 23,98 | ~12x |
+| 5 | Selectolax | 197,02 | ~99x |
+| 6 | MechanicalSoup | 1545,15 | ~776,5x |
+| 7 | BS4 + Lxml | 1562,1 | ~785,0x |
+| 8 | BS4 + html5lib | 3412,73 | ~1714,9x |
-### Производительность подобия элементов и текстового поиска
+### Поиск похожих элементов и текста
-Возможности адаптивного поиска элементов Scrapling значительно превосходят альтернативы:
+Адаптивный поиск элементов в Scrapling значительно опережает другие решения:
-| Библиотека | Время (мс) | vs Scrapling |
+| Библиотека | Время (мс) | По сравнению со Scrapling |
|-------------|:----------:|:------------:|
-| Scrapling | 2.3 | 1.0x |
-| AutoScraper | 12.58 | 5.47x |
+| Scrapling | 2,3 | 1,0x |
+| AutoScraper | 12,58 | 5,47x |
-> Все тесты производительности представляют собой средние значения более 100 запусков. См. [benchmarks.py](https://github.com/D4Vinci/Scrapling/blob/main/benchmarks.py) для методологии.
+> Результаты усреднены по более чем 100 запускам. Методика приведена в [benchmarks.py](https://github.com/D4Vinci/Scrapling/blob/main/benchmarks.py).
## Установка
-Scrapling требует Python 3.10 или выше:
+Для Scrapling нужен Python 3.10 или новее:
```bash
pip install scrapling
```
> [!IMPORTANT]
-> Эта установка включает только движок парсера и его зависимости, без каких-либо Fetcher'ов или зависимостей командной строки. Поэтому импорт чего-либо из `scrapling.fetchers` или `scrapling.spiders`, как в примерах выше, вызовет `ModuleNotFoundError` при такой установке. Если вы собираетесь использовать какие-либо Fetcher'ы или Spider'ы, сначала установите зависимости Fetcher'ов, как показано ниже.
+> Эта команда устанавливает только парсер и его зависимости. Fetcher и инструменты командной строки в неё не входят. Поэтому импорт из `scrapling.fetchers` или `scrapling.spiders`, как в примерах выше, вызовет `ModuleNotFoundError`. Чтобы использовать Fetcher или Spider, сначала установите зависимости для загрузки страниц, как показано ниже.
-### Опциональные зависимости
+### Дополнительные зависимости
-1. Если вы собираетесь использовать какие-либо из дополнительных возможностей ниже, Fetcher'ы или их классы, вам необходимо установить зависимости Fetcher'ов и браузеров следующим образом:
+1. Для Fetcher, их классов и дополнительных функций ниже установите зависимости для загрузки страниц и браузеров:
```bash
pip install "scrapling[fetchers]"
@@ -522,9 +528,9 @@ pip install scrapling
scrapling install --force # force reinstall
```
- Это загрузит все браузеры вместе с их системными зависимостями и зависимостями для манипуляции fingerprint'ами.
+ Команда загрузит все браузеры, нужные системные пакеты и средства изменения отпечатков браузера.
- Или вы можете установить их из кода вместо выполнения команды:
+ Вместо команды можно запустить установку из кода:
```python
from scrapling.cli import install
@@ -533,46 +539,46 @@ pip install scrapling
```
2. Дополнительные возможности:
- - Установить функцию MCP-сервера:
+ - MCP-сервер:
```bash
pip install "scrapling[ai]"
```
- - Установить зависимости для ([создания RAG-систем](https://scrapling.readthedocs.io/en/latest/ai/building-rag-systems.html)):
+ - Зависимости для [создания RAG-систем](https://scrapling.readthedocs.io/en/latest/ru/ai/building-rag-systems.html):
```bash
pip install "scrapling[rag]"
```
- - Установить функции Shell (Web Scraping Shell и команда `extract`):
+ - Интерактивная оболочка и команда `extract`:
```bash
pip install "scrapling[shell]"
```
- - Установить всё:
+ - Все возможности:
```bash
pip install "scrapling[all]"
```
- Выполните `scrapling install`, если нужны браузерные fetchers. Для HTTP-запросов устанавливать браузер не нужно.
+ Выполните `scrapling install`, если нужны браузерные Fetcher. Для HTTP-запросов устанавливать браузер не нужно.
### Docker
-Вы также можете установить Docker-образ со всеми дополнениями и браузерами с помощью следующей команды из DockerHub:
+Образ Docker со всеми дополнениями и браузерами можно скачать из DockerHub:
```bash
docker pull pyd4vinci/scrapling
```
-Или скачайте его из реестра GitHub:
+Или из реестра GitHub:
```bash
docker pull ghcr.io/d4vinci/scrapling:latest
```
-Этот образ автоматически создаётся и публикуется с помощью GitHub Actions и основной ветки репозитория.
+Образ автоматически собирается и публикуется через GitHub Actions из основной ветки репозитория.
## Участие в разработке
-Мы приветствуем участие! Пожалуйста, прочитайте наши [руководства по участию в разработке](https://github.com/D4Vinci/Scrapling/blob/main/CONTRIBUTING.md) перед началом работы.
+Присоединяйтесь к разработке! Перед началом прочитайте [руководство для участников](https://github.com/D4Vinci/Scrapling/blob/main/CONTRIBUTING.md).
## Отказ от ответственности
> [!CAUTION]
-> Эта библиотека предоставляется только в образовательных и исследовательских целях. Используя эту библиотеку, вы соглашаетесь соблюдать местные и международные законы о скрапинге данных и конфиденциальности. Авторы и участники не несут ответственности за любое неправомерное использование этого программного обеспечения. Всегда уважайте условия обслуживания веб-сайтов и файлы robots.txt.
+> Библиотека предназначена только для обучения и исследований. Используя её, вы соглашаетесь соблюдать местные и международные законы о сборе данных и конфиденциальности. Авторы и участники не отвечают за неправомерное использование программы. Соблюдайте условия сайтов и правила robots.txt.
## 🎓 Цитирование
-Если вы использовали нашу библиотеку в исследовательских целях, пожалуйста, цитируйте нас со следующей ссылкой:
+Если вы использовали библиотеку в исследовании, укажите её так:
```text
@misc{scrapling,
author = {Karim Shoair},
@@ -585,12 +591,12 @@ docker pull ghcr.io/d4vinci/scrapling:latest
## Лицензия
-Эта работа лицензирована по лицензии BSD-3-Clause.
+Проект распространяется по лицензии BSD-3-Clause.
## Благодарности
-Этот проект включает код, адаптированный из:
+В проекте есть код на основе следующих проектов:
- Parsel (лицензия BSD) - Используется для подмодуля [translator](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/translator.py)
---
-<div align="center"><small>Разработано и создано с ❤️ Карим Шоаир.</small></div><br>
+<div align="center"><small>Разработал и создал с ❤️ Карим Шоаир.</small></div><br>
diff --git a/docs/locales/ru/ai/agent-skill.md b/docs/locales/ru/ai/agent-skill.md
new file mode 100644
index 0000000..f267c36
--- /dev/null
+++ b/docs/locales/ru/ai/agent-skill.md
@@ -0,0 +1,42 @@
+---
+title: "Scrapling Agent Skill: установка и использование"
+description: "Установите навык Scrapling для агента, который пишет код. Дайте ему актуальные примеры API и справочные материалы по загрузке, парсингу и обходу сайтов."
+---
+
+# Scrapling Agent Skill {#scrapling-agent-skill}
+
+[MCP-сервер](mcp-server.md) даёт ИИ-чатботам инструменты для сбора данных с сайтов. **Scrapling Agent Skill** знакомит агентов, которые пишут код, с самой библиотекой. Так они используют текущий API Scrapling, а не угадывают его по устаревшим обучающим данным.
+
+Навык соответствует спецификации [AgentSkills](https://agentskills.io/specification), поэтому его могут читать [Claude Code](https://claude.com/product/claude-code), [OpenClaw](https://github.com/openclaw/openclaw) и другие инструменты с ИИ-агентами. Он содержит руководства по загрузке страниц, парсингу, обходу сайтов, MCP и RAG в виде справочных Markdown-файлов, которые агент загружает по мере необходимости. Есть и готовые к запуску примеры. Это позволяет отвечать на большинство вопросов о Scrapling и писать правильный код для сбора данных, не выходя из редактора.
+
+Навык находится в каталоге [agent-skill](https://github.com/D4Vinci/Scrapling/tree/main/agent-skill) репозитория под именем `scrapling-official`. Его версия всегда соответствует версии библиотеки.
+
+## Установка {#installation}
+
+### Skills.sh {#skillssh}
+
+Установите навык из репозитория с помощью CLI [skills.sh](https://skills.sh):
+```bash
+npx skills add D4Vinci/Scrapling --skill scrapling-official
+```
+CLI найдёт установленных агентов и добавит им навык.
+
+### Clawhub {#clawhub}
+
+Если вы используете OpenClaw, навык можно установить через [Clawhub](https://docs.openclaw.ai/tools/clawhub):
+```bash
+clawhub install scrapling-official
+```
+Или со [страницы в Clawhub](https://clawhub.ai/D4Vinci/scrapling-official).
+
+### Скачивание вручную {#manual-download}
+
+Скачайте ZIP-файл навыка [прямо из репозитория](https://github.com/D4Vinci/Scrapling/raw/refs/heads/main/agent-skill/Scrapling-Skill.zip) и распакуйте его в каталог навыков вашего агента. Для Claude Code это `~/.claude/skills/`.
+
+## Что входит в навык {#whats-inside}
+
+- **`SKILL.md`**: файл, который агент читает первым. В нём описаны настройка, выбор Fetcher и правила безопасности. Например, для защиты от внедрения инструкций в промпт агент должен всегда передавать `--ai-targeted` командам CLI.
+- **`references/`**: копии страниц документации в Markdown: парсинг, загрузка страниц, Spider, MCP-сервер и интеграции. Они загружаются по мере необходимости и до этого не занимают контекст агента.
+- **`examples/`**: готовые к запуску скрипты, из которых агент может брать код.
+
+Мы проверили навык в OpenClaw и Claude Code. Если возникнут проблемы, создайте [Issue](https://github.com/D4Vinci/Scrapling/issues/new/choose) или напишите на нашем [Discord-сервере](https://discord.gg/EMgGbDceNQ).
diff --git a/docs/locales/ru/ai/building-rag-systems.md b/docs/locales/ru/ai/building-rag-systems.md
new file mode 100644
index 0000000..4e72a10
--- /dev/null
+++ b/docs/locales/ru/ai/building-rag-systems.md
@@ -0,0 +1,109 @@
+---
+title: "Сбор страниц в Markdown для RAG с помощью Scrapling"
+description: "Преобразуйте ответы страниц в Markdown или соберите сайт с помощью ContentSpider. Подготовьте набор документов для разбиения на части и индексации в RAG-системе."
+---
+
+# Создание RAG-систем со Scrapling {#building-rag-systems-with-scrapling}
+
+Качество RAG зависит от текста, который вы передаёте системе. Исходный HTML тратит токены на разметку, навигацию, скрипты и код отслеживания. Он также может содержать скрытые инструкции, которые попадут прямо в LLM. Scrapling превращает страницы и целые сайты в очищенный Markdown без участия LLM. Поэтому загрузка данных проходит быстро и не требует оплаты LLM за каждую страницу.
+
+## Установка {#installation}
+
+```bash
+pip install "scrapling[rag]"
+
+scrapling install
+```
+
+Дополнительная группа зависимостей `rag` устанавливает Fetcher с поддержкой преобразования в Markdown. Она также входит в `ai`, `shell` и `all`. Команда `scrapling install` скачивает зависимости браузера, которые нужны только для Fetcher, работающих через браузер.
+
+## Одна страница в Markdown {#one-page-to-markdown}
+
+У каждого [Response](../fetching/choosing.md#response-object) есть метод `markdown()`:
+
+```python
+from scrapling.fetchers import Fetcher
+
+markdown = Fetcher.get("https://example.com").markdown(main_content_only=True)
+```
+
+Он работает со всеми Fetcher, поэтому для страниц за Cloudflare тоже достаточно одной строки:
+
+```python
+from scrapling.fetchers import StealthyFetcher
+
+markdown = StealthyFetcher.fetch("https://protected.example.com", solve_cloudflare=True).markdown(main_content_only=True)
+```
+
+Вывод настраивается двумя аргументами:
+
+- `main_content_only`: преобразовать только содержимое тега `<body>`.
+- `css_selector`: преобразовать только элементы, соответствующие CSS-селектору. Все совпадения объединяются. Так можно извлечь именно ту часть, которая нужна системе, и сэкономить токены:
+
+```python
+markdown = Fetcher.get("https://example.com/docs/page").markdown(css_selector="article")
+```
+
+Независимо от аргументов перед преобразованием всегда удаляются скрипты, стили и скрытое содержимое. [MCP-сервер](mcp-server.md) использует ту же очистку для защиты ИИ-агентов от внедрения инструкций в промпт. Она удаляет элементы, скрытые встроенными стилями, элементы с `aria-hidden="true"`, скрытые слоты, теги `<template>`, HTML-комментарии и символы нулевой ширины. MCP-сервер выполняет эту очистку при `main_content_only=True`.
+
+## Весь сайт в набор документов Markdown {#a-whole-website-to-a-markdown-corpus}
+
+Шаблон `ContentSpider` обходит сайт и преобразует каждую страницу. Он использует [фреймворк Spider](../spiders/architecture.md), поэтому доступны параллельная обработка, AutoThrottle, соблюдение robots.txt, пауза и возобновление:
+
+```python
+from scrapling.spiders import ContentSpider
+
+class DocsSpider(ContentSpider):
+ name = "docs"
+ start_urls = ["https://example.com/docs/"]
+ allowed_domains = {"example.com"}
+ output_dir = "docs_markdown"
+ max_pages = 200
+
+result = DocsSpider().start()
+result.items.to_jsonl("docs.jsonl")
+```
+
+Каждая собранная страница становится записью с ключами `url`, `title` и `markdown`. Если задан `output_dir`, страница также записывается в Markdown-файл с именем на основе её URL. В результате приведённый выше запуск создаёт папку с файлами `.md` и файл `docs.jsonl`, готовый для загрузки в систему.
+
+Шаблону нужен `allowed_domains`, чтобы обход не выходил за пределы целевого сайта. Доступны следующие параметры:
+
+- `css_selector` / `main_content_only`: передаются в `markdown()` для каждой страницы. `main_content_only` включён по умолчанию.
+- `output_dir`: если задан, каждая страница записывается в отдельный Markdown-файл.
+- `max_pages`: максимальное число преобразованных страниц. Запросы, уже попавшие в очередь к моменту достижения лимита, могут быть выполнены, но их страницы не преобразуются. `0` по умолчанию отключает лимит.
+
+По умолчанию обход следует по всем ссылкам на страницы внутри `allowed_domains`. Шаблон основан на [CrawlSpider](../spiders/generic-templates.md#crawlspider), поэтому можно переопределить `rules()` и использовать свой [LinkExtractor](../spiders/generic-templates.md#linkextractor-reference). `allow` ограничивает обход нужными шаблонами URL, а `deny` исключает ненужные: страницы входа, списки тегов, версии для печати и другие:
+
+```python
+from scrapling.spiders import CrawlRule, LinkExtractor, ContentSpider
+
+class DocsSpider(ContentSpider):
+ name = "docs"
+ start_urls = ["https://example.com/"]
+ allowed_domains = {"example.com"}
+
+ def rules(self):
+ return [CrawlRule(LinkExtractor(allow=r"/docs/", deny=[r"/docs/changelog/", r"\?print="]))]
+```
+
+`deny` имеет приоритет над `allow`. Как и в любом **CrawlSpider**, правило может содержать `priority` или хук `process_request`.
+
+## Передача данных в векторное хранилище {#feeding-a-vector-store}
+
+Вывод JSONL можно передать в любую систему создания эмбеддингов. Минимальный пример:
+
+```python
+import json
+
+with open("docs.jsonl", encoding="utf-8") as f:
+ for line in f:
+ page = json.loads(line)
+ for chunk in split_into_chunks(page["markdown"]):
+ vector_store.add(text=chunk, metadata={"url": page["url"], "title": page["title"]})
+```
+
+Используйте `css_selector` в Spider, чтобы убрать повторяющиеся служебные блоки до разбиения текста на части, а не очищать их на следующих этапах. Чем меньше лишнего содержимого в эмбеддингах, тем лучше поиск.
+
+## Работа в диалоге {#interactive-alternatives}
+
+Если вы хотите собирать данные в диалоге, а не строить цепочку обработки, [MCP-сервер](mcp-server.md) предоставляет ИИ-чатботу те же инструменты извлечения Markdown. А [Agent Skill](agent-skill.md) учит агентов самостоятельно писать такой код.
diff --git a/docs/locales/ru/ai/mcp-server.md b/docs/locales/ru/ai/mcp-server.md
new file mode 100644
index 0000000..62b9ef1
--- /dev/null
+++ b/docs/locales/ru/ai/mcp-server.md
@@ -0,0 +1,499 @@
+---
+title: "MCP-сервер Scrapling: настройка и сбор данных"
+description: "Подключите ИИ-клиент к Scrapling для сбора данных через HTTP и браузер. Используйте сессии, сохранённый вход, действия, точечное извлечение и историю API."
+---
+
+# MCP-сервер Scrapling {#scrapling-mcp-server-guide}
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/qyFk3ZNwOxE?si=3FHzgcYCb66iJ6e3" title="Видеоплеер YouTube" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+**MCP-сервер Scrapling** добавляет возможности сбора данных Scrapling в ваш любимый ИИ-чатбот или ИИ-агент. Через интерфейс Claude или любого другого клиента с поддержкой MCP можно в диалоге загружать сайты, извлекать данные и обходить защиту от ботов.
+
+## Возможности {#features}
+
+MCP-сервер Scrapling предоставляет 16 инструментов для сбора данных и работы с браузером. Одноразовые инструменты загружают один URL и закрывают свой браузер или клиент. Инструменты сессий сохраняют Cookie и настройки между вызовами, чтобы ИИ мог продолжить действия в той же вкладке и изучить сетевую историю.
+
+### Одноразовые инструменты {#one-shot-tools}
+
+#### 🚀 Обычный сбор данных через HTTP {#basic-http-scraping}
+- **`make_request`**: быстрые HTTP-запросы разными методами (GET, POST, PUT, DELETE), имитация отпечатка браузера, генерация настоящих заголовков браузера, соответствующих версии TLS, поддержка HTTP/3 и другие возможности.
+
+#### 🔒 Сбор данных через скрытный браузер {#stealth-browser-scraping}
+- **`browser_fetch_once`**: выполняет JavaScript и собирает данные с динамических страниц через браузер с функциями скрытности. Поддерживает подмену отпечатка, обход Cloudflare Turnstile/Interstitial и настройку браузера и запроса.
+
+### Инструменты сессий {#session-tools}
+
+#### 🔌 Управление сессиями {#session-management}
+- **`browser_open`**: создаёт постоянную сессию скрытного браузера для нескольких вызовов `browser_fetch`. Это позволяет не запускать новый браузер каждый раз. Сессия хранит настройки уровня браузера и возвращает только `session_id` и `session_type`. Действующие `settings` можно посмотреть через `list_sessions`. Для CDP-сессий они пусты.
+- **`open_request_session`**: создаёт постоянную HTTP-сессию без браузера для `session_make_request`. Между запросами сохраняются Cookie, соединения и отпечаток браузера (`impersonate`). Возвращает только `session_id` и `session_type`; тип равен `static`. Действующие `settings` доступны через `list_sessions`.
+- **`close_session`**: закрывает постоянную сессию браузера или HTTP и освобождает её ресурсы.
+- **`list_sessions`**: показывает все активные сессии, их сведения и `settings`.
+
+#### Состояние браузера {#browser-state}
+
+- **`browser_save_state`**: сохраняет Cookie, local storage и IndexedDB в JSON-файл, совместимый с Playwright. Это позволяет восстановить вход после завершения сессии браузера. Существующий файл перезаписывается.
+- **`browser_load_state`**: загружает сохранённый файл в открытую сессию браузера, в том числе до первой загрузки страницы. Текущее сохранённое состояние заменяется, но открытые вкладки не закрываются и не переходят на другие страницы. Чтобы использовать восстановленный вход, загрузите или обновите страницу.
+
+Файлы состояния находятся на машине, где работает MCP-сервер. Они не содержат `sessionStorage`, открытые вкладки или настройки браузера.
+
+#### 🎯 Загрузка через сессию {#fetching-through-a-session}
+- **`browser_fetch`**: выполняет JavaScript и загружает один URL через открытую сессию скрытного браузера. Поддерживает подмену отпечатка и обход Cloudflare Turnstile/Interstitial. Также может создать структурированный снимок страницы со ссылками на элементы, их координатами и размерами. Это помогает ИИ находить элементы управления и планировать действия мышью.
+- **`session_make_request`**: выполняет быстрые HTTP-запросы разными методами (GET, POST, PUT, DELETE), с имитацией отпечатка браузера, соответствующими заголовками и поддержкой HTTP/3. Повторно использует Cookie, соединения и отпечаток через сессию, открытую с помощью `open_request_session`.
+
+#### 📸 Скриншоты {#screenshots}
+
+- **`browser_screenshot`**: снимает текущую страницу или выбранный элемент в PNG или JPEG без перезагрузки. Можно проверить заполненные поля, открытые меню, графики или карточки результатов. Снимок отдельного элемента уменьшает объём лишнего содержимого. Поддерживает видимую область, полную страницу и один элемент, а также настройку качества JPEG. Скриншот возвращается как настоящий блок изображения, который модель видит напрямую.
+
+#### Содержимое текущей страницы {#current-page-content}
+
+- **`browser_extract`**: читает текущую страницу или один элемент как снимок для ИИ, HTML, Markdown или текст без перезагрузки. Позволяет извлечь результаты после заполнения формы или загрузки новых данных. Снимки содержат роли, имена, ссылки, координаты и размеры элементов для последующих действий. Поиск по регулярному выражению возвращает совпавшие строки снимка с соседним контекстом и родительскими узлами.
+
+#### Действия в браузере {#browser-actions}
+
+- **`browser_actions`**: объединяет в одном вызове действия мышью, заполнение полей, сочетания клавиш, ответы на диалоговые окна и ожидания. Можно принять или отклонить уведомление и подтверждение, а также ввести текст в диалог запроса. Например, заполнить строку поиска, отправить запрос, дождаться результатов и открыть один из них. ИИ может объединять известные шаги, а снимки получать отдельно, когда нужно проверить изменение страницы.
+
+ Показывайте меню и подсказки наведением, нажимайте кнопки и ссылки, перемещайтесь на вложенную панель и прокручивайте её по вертикали или горизонтали. Для перемещения и клика можно указать селектор, ссылку из снимка или координаты. При выборе элемента инструмент сам дождётся его и прокрутит в видимую область. Поддерживаются перемещение по координатам в несколько шагов, клики левой, правой и средней кнопкой, а также двойной клик.
+
+ Выбирайте поля в любой части страницы с помощью селекторов или ссылок из снимка. Можно вводить текст, устанавливать и снимать флажки, выбирать радиокнопки и один или несколько вариантов в обычных выпадающих списках по видимой подписи. Текст можно заменить, очистить или дописать в позиции курсора. Сочетания клавиш позволяют выделять и удалять текст, менять фокус, отправлять формы и закрывать меню. Медленный режим вводит по одному символу и добавляет случайные паузы между символами и всеми действиями.
+
+ Перед следующим действием можно дождаться появления результатов, исчезновения индикатора загрузки или события загрузки страницы. Также поддерживаются пауза заданной длины и ожидание завершения сетевой активности.
+
+#### JavaScript {#javascript}
+
+- **`browser_evaluate`**: выполняет JavaScript на текущей странице для собственного извлечения данных, вычислений и задач, зависящих от страницы. ИИ может собрать данные из нескольких элементов, прочитать состояние приложения или изменить содержимое страницы. Поддерживает асинхронные скрипты и возвращает результат в JSON.
+
+#### Сетевая история {#network-history}
+
+- **`browser_network_requests`**: ищет завершённые запросы между вкладками, загрузками страниц и действиями браузера. Можно найти API, из которого страница получает данные, проверить HTTP-ошибки и сохранённые перенаправления. Статические ресурсы по умолчанию скрыты, чтобы уменьшить результат. Сведения о запросах возвращаются в JSON, а длинную историю можно читать постранично.
+- **`browser_network_request`**: показывает сводку одного записанного запроса, заголовки, отправленные данные или текстовое тело ответа в виде структурированного JSON. Выбранная часть возвращается полностью, без загрузки страницы или повторной отправки запроса. Сохранённые ответы доступны после перехода на другие страницы. Размер истории ограничен; для нетекстовых, слишком больших или недоступных тел ответа указывается причина. Прочитайте нужные сведения до закрытия MCP-сессии.
+
+Тела ответов читаются и сохраняются только для поддерживаемых текстовых значений `Content-Type`, например HTML, JSON, XML или JavaScript. Для двоичных, неизвестных или неуказанных типов сохраняются метаданные запроса и заголовки, но тело не читается и не записывается. Браузер продолжает загружать ресурсы как обычно.
+
+Сохраняются только завершённые запросы, в том числе ответы HTTP 4xx и 5xx. Неудачные и незавершённые запросы не включаются. Запись появляется после завершения сохранения; чтение истории и закрытие сессии этого не ждут. Запись, ещё не завершённая при переходе или закрытии, может быть пропущена. Сохранённые байты поступают из браузера и могут отличаться от байтов сервера. Если текст является корректным UTF-8, он декодируется так же, как в Playwright. В остальных случаях используется заявленная кодировка.
+
+### Shadow DOM {#shadow-dom}
+
+Чтобы включить содержимое открытого Shadow DOM, задайте `pierce_shadow=true` в `browser_fetch_once` или в каждом вызове `browser_fetch`. По умолчанию используется `false`. Примеры селекторов и ограничения описаны в разделе [Shadow DOM](../fetching/stealthy.md#shadow-dom).
+
+### Основные возможности {#key-capabilities}
+- **Извлечение содержимого**: преобразование страниц и элементов в Markdown, HTML или очищенный текст.
+- **Поддержка CSS-селекторов**: точный выбор элементов движком Scrapling до передачи содержимого ИИ.
+- **Обход защиты от ботов**: работа с Cloudflare Turnstile, Interstitial и другими видами защиты.
+- **Поддержка прокси**: анонимность и выбор региона подключения.
+- **Имитация браузера**: TLS-отпечаток, настоящие заголовки соответствующей версии браузера и другие признаки.
+- **Сохранение сессий**: повторное использование браузера для нескольких запросов повышает скорость.
+- **Блокировка рекламы**: все браузерные инструменты автоматически блокируют запросы примерно к 3 500 известным рекламным и отслеживающим доменам, экономя токены и ускоряя загрузку.
+- **Защита от внедрения инструкций в промпт**: автоматическое удаление скрытого содержимого, пригодного для таких атак: элементов со встроенными скрывающими стилями, aria-hidden, скрытых слотов, символов нулевой ширины, HTML-комментариев и тегов template.
+
+#### Почему стоит выбрать MCP-сервер Scrapling вместо других инструментов {#but-why-use-scrapling-mcp-server-instead-of-other-available-tools}
+
+Помимо функций скрытности и обхода Cloudflare Turnstile/Interstitial, сервер Scrapling позволяет выбрать конкретные элементы для передачи ИИ. Это единственный сервер с такой возможностью, которая заметно экономит время и токены.
+
+Другие серверы сначала извлекают всё содержимое, затем передают его ИИ для поиска нужных полей. Из-за лишнего содержимого ИИ расходует больше токенов, чем нужно. Scrapling позволяет заранее сузить содержимое CSS-селектором, поэтому весь процесс становится быстрее и эффективнее.
+
+Если вы не умеете писать CSS-селекторы, не беспокойтесь. Попросите ИИ в промпте подобрать селекторы для нужных полей. Он будет пробовать разные варианты, пока не найдёт подходящий. Ниже мы покажем примеры.
+
+
+## Установка {#installation}
+
+Установите Scrapling с поддержкой MCP и убедитесь, что зависимости браузера тоже установлены.
+
+```bash
+# Install Scrapling with MCP server dependencies
+pip install "scrapling[ai]"
+
+# Install browser dependencies
+scrapling install
+```
+
+Или используйте Docker-образ прямо из Docker Registry:
+```bash
+docker pull pyd4vinci/scrapling
+```
+Его также можно скачать из реестра GitHub:
+```bash
+docker pull ghcr.io/d4vinci/scrapling:latest
+```
+
+## Настройка MCP-сервера {#setting-up-the-mcp-server}
+
+Здесь мы покажем, как добавить MCP-сервер Scrapling в [Claude Desktop](https://claude.ai/download) и [Claude Code](https://www.anthropic.com/claude-code). Тот же принцип подходит для других чатботов с поддержкой MCP.
+
+!!! note "Примечание"
+ Команда `scrapling-mcp` ниже появилась в v0.4.13 как сокращение для `scrapling mcp`. Она упрощает добавление Scrapling в реестры и клиенты MCP, которые ожидают одну команду. В более старой версии используйте команду `scrapling` с первым аргументом `mcp`.
+
+### Claude Desktop {#claude-desktop}
+
+1. Откройте Claude Desktop.
+2. Нажмите меню (☰) в левом верхнем углу, затем выберите Settings → Developer → Edit Config.
+3. Добавьте конфигурацию MCP-сервера Scrapling:
+```json
+"ScraplingServer": {
+ "command": "scrapling-mcp"
+}
+```
+Если это первый добавляемый MCP-сервер, замените содержимое файла следующим:
+```json
+{
+ "mcpServers": {
+ "ScraplingServer": {
+ "command": "scrapling-mcp"
+ }
+ }
+}
+```
+Согласно [официальной статье](https://modelcontextprotocol.io/quickstart/user), это действие открывает существующий файл настроек или создаёт новый. Файл находится здесь:
+
+1. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+2. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Чтобы команда работала надёжно, используйте полный путь к исполняемому файлу `scrapling-mcp`:
+
+1. **macOS**: `which scrapling-mcp`
+2. **Windows**: `where scrapling-mcp`
+
+На моём Mac команда вернула `/Users/<MyUsername>/.venv/bin/scrapling-mcp`, поэтому итоговая конфигурация получилась такой:
+```json
+{
+ "mcpServers": {
+ "ScraplingServer": {
+ "command": "/Users/<MyUsername>/.venv/bin/scrapling-mcp"
+ }
+ }
+}
+```
+#### Docker {#docker}
+Для Docker-образа конфигурация будет примерно следующей:
+```json
+{
+ "mcpServers": {
+ "ScraplingServer": {
+ "command": "docker",
+ "args": [
+ "run", "-i", "--rm", "pyd4vinci/scrapling", "mcp"
+ ]
+ }
+ }
+}
+```
+
+Тот же подход работает в [Cursor](https://cursor.com/docs/context/mcp), [WindSurf](https://windsurf.com/university/tutorials/configuring-first-mcp-server) и других клиентах.
+
+### Claude Code {#claude-code}
+В [Claude Code](https://www.anthropic.com/claude-code) всё проще:
+
+```bash
+claude mcp add ScraplingServer "/Users/<MyUsername>/.venv/bin/scrapling-mcp"
+```
+Путь к исполняемому файлу Scrapling можно узнать так:
+
+1. **macOS**: `which scrapling-mcp`
+2. **Windows**: `where scrapling-mcp`
+
+Подробности есть в статье Anthropic о [добавлении MCP-серверов в Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp#option-1%3A-add-a-local-stdio-server).
+
+
+После добавления сервера полностью закройте выбранное приложение и запустите его снова. В Claude Desktop справа внизу поля ввода должен появиться значок MCP-сервера (🔧), либо `ScraplingServer` появится в меню `Search and tools` в поле чата.
+
+### Свой исполняемый файл браузера {#custom-browser-executable}
+
+Инструменты `browser_fetch_once` и `browser_open` могут использовать другой Chromium-совместимый исполняемый файл вместо встроенного Chromium. Это полезно для собственных сборок или облегчённых браузерных движков.
+
+Чтобы задать его для всего MCP-сервера, передайте путь при запуске:
+
+```bash
+scrapling-mcp --executable-path "/path/to/chromium"
+```
+
+В настройках Claude Desktop добавьте параметр в аргументы сервера:
+
+```json
+{
+ "mcpServers": {
+ "ScraplingServer": {
+ "command": "/Users/<MyUsername>/.venv/bin/scrapling-mcp",
+ "args": [
+ "--executable-path",
+ "/path/to/chromium"
+ ]
+ }
+ }
+}
+```
+
+Также можно задать переменную окружения `SCRAPLING_EXECUTABLE_PATH` перед запуском. При этом ИИ всё ещё может выбрать другой исполняемый файл для одного вызова `browser_fetch_once` или при открытии сессии через `browser_open`.
+
+### Подключение к удалённому браузеру {#connecting-to-remote-browsers}
+
+`browser_open` не обязательно запускает браузер локально. Передайте CDP URL, чтобы подключиться к уже работающему браузеру через [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). Он может находиться на той же машине, другом сервере или в управляемом браузерном сервисе:
+```
+Open a stealthy browser session on wss://cdp.provider.example/session/abc123, then use it to scrape the product details from https://shop.example.com. Close the session when you're done.
+```
+Полученный `session_id` используется как обычно с `browser_fetch`, `browser_extract`, `browser_actions`, `browser_evaluate`, `browser_screenshot`, `browser_network_requests`, `browser_network_request`, `browser_save_state` и `browser_load_state`.
+
+URL может быть WebSocket-адресом (`ws://`/`wss://`) от браузерного сервиса или HTTP-адресом браузера, который вы запустили сами с открытым портом удалённой отладки:
+```commandline
+chrome --remote-debugging-port=9222
+```
+К нему можно подключиться через `cdp_url="http://localhost:9222"`. Если браузер работает на другой машине, используйте её адрес.
+
+!!! note "Примечания"
+
+ * Браузер уже запущен, поэтому CDP-сессии игнорируют параметры, нужные только при запуске: `headless`, `real_chrome` и `executable_path`, включая описанное выше значение по умолчанию для всего сервера.<br/>
+ * Остальные параметры работают: `locale`, `useragent`, `proxy`, `cookies`, `timezone_id` и другие. Каждая сессия создаёт свой браузерный контекст в удалённом браузере.
+
+### Streamable HTTP {#streamable-http}
+Начиная с версии 0.3.6, MCP-сервер может использовать транспорт Streamable HTTP вместо обычного stdio.
+
+Для stdio используется такая команда:
+```bash
+scrapling-mcp
+```
+Чтобы включить Streamable HTTP, замените её следующей:
+```bash
+scrapling-mcp --http
+```
+По умолчанию сервер слушает адрес 127.0.0.1 и порт 8000. Оба значения можно изменить:
+```bash
+scrapling-mcp --http --host '0.0.0.0' --port 8000
+```
+По умолчанию принимаются только подключения с той же машины. Чтобы открыть доступ по сети, передайте `--host '0.0.0.0'`. Это отдельная настройка, не связанная с выбором аутентификации ниже.
+
+Если Streamable HTTP работает в Docker, нужно самостоятельно привязать сервер к 0.0.0.0 и задать токен. Иначе опубликованный порт не сможет подключиться к серверу: адрес 127.0.0.1 контейнера доступен только внутри него.
+```bash
+docker run -p 8000:8000 -e SCRAPLING_MCP_AUTH_TOKEN="<your-token>" pyd4vinci/scrapling mcp --http --host '0.0.0.0'
+```
+
+### Аутентификация {#authentication}
+
+К stdio может обратиться только программа, которая его запустила. Но при переходе на Streamable HTTP любой, у кого есть доступ к порту, может вызывать все инструменты, в том числе загружать любой URL с машины сервера. Поэтому Streamable HTTP требует аутентификации. С одним `--http` сервер не запустится и попросит токен:
+```bash
+scrapling-mcp --http --auth-token "$(openssl rand -hex 32)"
+```
+Клиенты должны отправлять этот токен в заголовке `Authorization`. Запрос без него отклоняется с кодом `401`:
+```json
+{
+ "mcpServers": {
+ "ScraplingServer": {
+ "url": "https://your-server.example.com/mcp",
+ "headers": {
+ "Authorization": "Bearer <your-token>"
+ }
+ }
+ }
+}
+```
+Токен, переданный в командной строке, остаётся в истории оболочки и списке процессов. Лучше использовать переменную окружения `SCRAPLING_MCP_AUTH_TOKEN`:
+```bash
+export SCRAPLING_MCP_AUTH_TOKEN="<your-token>"
+scrapling-mcp --http
+```
+Если сервер без аутентификации действительно нужен, например для локальной проверки на стандартном адресе 127.0.0.1, явно укажите `--no-auth`:
+```bash
+scrapling-mcp --http --no-auth
+```
+Сочетание `--no-auth` и `--host '0.0.0.0'` открывает все инструменты любому, кто может подключиться к порту. Не используйте его за пределами доверенной сети.
+
+Если сервер слушает публичный адрес, также задайте разрешённые имена хостов. Это включает защиту от DNS rebinding: атаки, при которой открытый в браузере сайт пытается обратиться к вашему серверу. Параметр можно повторять:
+```bash
+scrapling-mcp --http --allowed-host 'your-server.example.com:8000'
+```
+
+!!! note "Примечания"
+
+ * Аутентификация применяется только к Streamable HTTP. В stdio она игнорируется, о чём сервер пишет предупреждение в журнал.<br/>
+ * Обычный HTTP передаёт токен открытым текстом. Перед публикацией в интернете разместите сервер за обратным прокси, который обрабатывает TLS.<br/>
+ * Это один общий ключ, а не отдельные учётные данные для каждого клиента. Все клиенты используют одинаковый токен, а для его замены нужно перезапустить сервер.<br/>
+ * При запуске с `--http --no-auth` сервер всё равно записывает предупреждение об отсутствии аутентификации.<br/>
+ * Если передать и `--auth-token`, и `--no-auth`, токен сохранится. Сервер не отключит аутентификацию незаметно.
+
+## Примеры {#examples}
+
+Покажем несколько промптов, которые мы использовали при тестировании MCP-сервера. Возможно, вы придумаете более интересные и точные варианты :)
+
+Начнём с простых промптов и постепенно перейдём к сложным. В примерах используется Claude Desktop, но тот же принцип работает и в других клиентах.
+
+1. **Обычный сбор данных со страницы**
+
+ Извлеките основное содержимое страницы в Markdown:
+
+ ```
+ Scrape the main content from https://example.com and convert it to markdown format.
+ ```
+
+ Claude может использовать `make_request`, чтобы получить страницу и вернуть чистый, удобный для чтения текст. HTTP-запросы по умолчанию выполняются с максимум тремя попытками и задержкой в одну секунду между ними. Если странице нужен JavaScript или она блокирует HTTP-запросы, ИИ может выбрать `browser_fetch_once`. Оба инструмента закрывают свои ресурсы после вызова.
+
+ Более точный вариант того же промпта:
+ ```
+ Use regular requests to scrape the main content from https://example.com and convert it to markdown format.
+ ```
+ Он сразу указывает Claude, какой инструмент использовать. Без этого Claude иногда начинает с обычных запросов, а иногда без явной причины выбирает браузер. Обычно лучше задавать инструмент явно: это экономит время и деньги и делает результаты стабильнее.
+
+2. **Извлечение конкретных данных**
+
+ Извлеките нужные элементы с помощью CSS-селекторов:
+
+ ```
+ Get all product titles from https://shop.example.com using the CSS selector '.product-title'. If the request fails, retry up to 5 times every 10 seconds.
+ ```
+
+ Сервер вернёт только элементы, совпавшие с селектором, в виде структурированного списка. Здесь задано до 5 попыток на случай проблем с соединением, но для большинства задач достаточно значения по умолчанию.
+
+3. **Сбор данных интернет-магазина**
+
+ Ещё один, чуть более сложный промпт:
+ ```
+ Open a stealthy browser session and visit these e-commerce URLs one at a time:
+ - https://shop1.com/product-a
+ - https://shop2.com/product-b
+ - https://shop3.com/product-c
+
+ Get the product names, prices, and descriptions from each page. Close the session when done.
+ ```
+
+ Claude может повторно использовать одну сессию браузера, последовательно вызвать `browser_fetch` для каждого URL и затем проанализировать извлечённые данные.
+
+4. **Более сложный процесс**
+
+ Допустим, нужно получить все игры в жанре экшен с первой страницы магазина PlayStation прямо сейчас. Для этого можно использовать такой промпт:
+ ```
+ Extract the URLs of all games on this page, then visit each game in order and return a list of all action games: https://store.playstation.com/en-us/pages/browse
+ ```
+ Если данные доступны через обычные запросы, попросите ИИ повторно использовать HTTP-сессию, чтобы не запускать браузер:
+ ```
+ Open an HTTP session, extract the URLs of all games on this page, then fetch each game in order and return a list of all action games. Close the session when done: https://store.playstation.com/en-us/pages/browse
+ ```
+ Если вы умеете писать CSS-селекторы, можно сузить содержимое до того, как его прочитает ИИ:
+ ```
+ Use an HTTP session to extract the URLs of all games on the page below, then fetch each game in order and return a list of all action games.
+ The selector for games in the first page is `[href*="/concept/"]` and the selector for the genre in each game page is `[data-qa="gameInfo#releaseInformation#genre-value"]`.
+ Close the session when done.
+
+ URL: https://store.playstation.com/en-us/pages/browse
+ ```
+
+5. **Получение данных с сайта под защитой Cloudflare**
+
+ Если вы предполагаете, что сайт использует Cloudflare, сообщите об этом Claude сразу, не заставляя его выяснять это самостоятельно.
+ ```
+ What's the price of this product? Be cautious, as it utilizes Cloudflare's Turnstile protection. Make the browser visible while you work.
+
+ https://ao.com/product/oo101uk-ninja-woodfire-outdoor-pizza-oven-brown-99357-685.aspx
+ ```
+
+6. **Длинный процесс**
+
+ Например, можно использовать такой промпт:
+ ```
+ Extract all product URLs for the following category, then return the prices and details for the first 3 products.
+
+ https://www.arnotts.ie/furniture/bedroom/bed-frames/
+ ```
+ Но лучше написать так:
+ ```
+ Go to the following category URL and extract all product URLs using the CSS selector "a". Then, reuse the session to fetch the first 3 product pages in order and extract each product’s price and details. Close the session when done.
+
+ Keep the output in markdown format to reduce irrelevant content.
+
+ Category URL:
+ https://www.arnotts.ie/furniture/bedroom/bed-frames/
+ ```
+
+7. **Постоянные сессии**
+
+ При сборе нескольких страниц одного сайта используйте постоянную сессию браузера, чтобы не тратить ресурсы на новый запуск для каждого запроса:
+ ```
+ Open a stealthy browser session, then use it to scrape the main details from the first 5 product pages on https://shop.example.com. Close the session when you're done.
+ ```
+ Claude создаст сессию через `browser_open`, вызовет `browser_fetch` для каждой страницы товара в этой сессии, а в конце вызовет `close_session`. Это заметно быстрее, чем запускать браузер для каждой страницы.
+
+ !!! danger "Опасно"
+
+ Всегда закрывайте постоянную сессию после работы, иначе она останется открытой!
+
+
+8. **Постоянная сессия в длинном процессе**
+
+ Ещё один длинный тест, над которым Claude придётся подумать:
+
+ ```
+ Use Scrapling MCP to do the following in this order:
+
+ 1. Open a stealthy browser session with headless mode off.
+ 2. Go to this page and collect the number of stars: https://github.com/D4Vinci/Scrapling
+ 3. From the README, get the URL that shows the number of downloads and go to it.
+ 4. Get the number of downloads and the top 3 countries from the graph.
+ 5. Prepare a report with the results.
+ 6. Close the browser.
+ ```
+
+Это лишь примеры. Дальше всё зависит от ваших идей.
+
+## Рекомендации {#best-practices}
+
+Несколько технических советов.
+
+### 1. Выбирайте подходящий инструмент {#1-choose-the-right-tool}
+- **`make_request`**: быстрый HTTP-запрос к одной странице или API.
+- **`browser_fetch_once`**: одна динамическая страница с JavaScript или защищённый сайт, в том числе с Cloudflare.
+- **Инструменты сессий**: связанные запросы, действия браузера, скриншоты и сетевая история.
+
+### 2. Повышайте скорость {#2-optimize-performance}
+- Повторно используйте сессию и загружайте URL по порядку.
+- Отключайте ненужные ресурсы.
+- Задавайте подходящие тайм-ауты.
+- Используйте CSS-селекторы для точечного извлечения.
+
+### 3. Учитывайте динамическое содержимое {#3-handle-dynamic-content}
+- Для SPA используйте `network_idle`.
+- Задавайте `wait_selector` для нужных элементов.
+- Увеличивайте тайм-аут для медленных сайтов.
+
+### 4. Следите за качеством данных {#4-data-quality}
+- Используйте `main_content_only=true`, чтобы выбрать и очистить основное содержимое страницы.
+- Выбирайте подходящий для задачи `extraction_type`.
+
+### 5. Защищайтесь от внедрения инструкций в промпт {#5-prompt-injection-protection}
+При включённом `main_content_only`, как по умолчанию, MCP-сервер автоматически очищает полученное содержимое. Он удаляет скрытые данные, с помощью которых вредоносные сайты могут передавать инструкции в контекст ИИ:
+
+- **Встроенные скрывающие стили**: `display:none`, `visibility:hidden`, а также нулевые непрозрачность, размер шрифта, высота, ширина, максимальная высота и максимальная ширина.
+- **Элементы, скрытые от средств доступности**: `aria-hidden="true"`.
+- **Теги template и скрытые слоты**: элементы `<template>` и `<slot hidden>`.
+- **HTML-комментарии**: `<!-- ... -->`.
+- **Символы нулевой ширины**: невидимые символы Unicode, например пробел нулевой ширины.
+
+Защита автоматически работает при извлечении HTML, Markdown и текста. Для максимальной защиты оставьте стандартное значение `main_content_only=true`.
+
+### 6. Управляйте сессиями {#6-manage-sessions}
+- Для разовой загрузки используйте `make_request` или `browser_fetch_once`. Они закрывают свои ресурсы и не оставляют сессию для следующих вызовов.
+- Для нескольких страниц создайте постоянную сессию браузера через `browser_open`, затем вызывайте `browser_fetch` для каждой страницы в этой сессии.
+- Для нескольких обычных HTTP-запросов используйте `open_request_session` и вызывайте `session_make_request` для каждого запроса. Без браузера между вызовами сохраняются Cookie, соединения и отпечаток браузера (`impersonate`).
+- Сессия хранит настройки, заданные при открытии: headless, locale, cookies, переключатели скрытности и другие для браузера; `impersonate` и `proxy` для HTTP-сессий. Параметры отдельных запросов, такие как timeout, wait_selector, network_idle и solve_cloudflare, передаются в `browser_fetch`/`session_make_request` при каждом вызове. Их значения по умолчанию указаны в схемах инструментов.
+- `browser_fetch` может решать проверки Cloudflare в открытой сессии скрытного браузера.
+- Всегда закрывайте сессии через `close_session` после работы, чтобы освободить ресурсы.
+- Через `list_sessions` можно проверить активные сессии и `settings`, с которыми они созданы. Эти сведения возвращаются ИИ-агенту; для CDP-сессий настройки пусты.
+- Передайте свой `session_id` инструментам открытия сессии, чтобы использовать понятные имена вроде `"search"` или `"checkout"` вместо случайного шестнадцатеричного значения. Если ID уже занят, инструмент выдаст ошибку, поэтому конфликт можно обнаружить сразу.
+
+### 7. Делайте скриншоты {#7-capturing-screenshots}
+
+- `browser_screenshot` снимает страницу, уже открытую через `browser_fetch` в сессии скрытного браузера. Он не перезагружает страницу, поэтому ИИ может проверить заполненные поля, открытые меню и другие результаты действий.
+- Изображение возвращается настоящим блоком `ImageContent`, поэтому модель видит страницу напрямую.
+- Можно снять видимую область или всю страницу, включая содержимое ниже текущего экрана.
+- Снимайте отдельное поле, график, карточку или результат, чтобы убрать лишнее окружение. При съёмке элемента инструмент может прокрутить его в видимую область.
+- Выбирайте PNG для изображения без потерь или JPEG с настраиваемым качеством, чтобы уменьшить объём данных.
+- Перед скриншотом ИИ может использовать `browser_actions`, чтобы дождаться содержимого или закончить действия.
+
+## Правовые и этические вопросы {#legal-and-ethical-considerations}
+
+⚠️ **Важные правила:**
+
+- **Проверяйте robots.txt**: откройте `https://website.com/robots.txt`, чтобы узнать правила сбора данных.
+- **Соблюдайте ограничения частоты**: не перегружайте сервер запросами.
+- **Условия использования**: прочитайте правила сайта и следуйте им.
+- **Авторское право**: уважайте права на интеллектуальную собственность.
+- **Конфиденциальность**: учитывайте законы о защите персональных данных.
+- **Коммерческое использование**: убедитесь, что у вас есть нужное разрешение для деловых целей.
+
+---
+
+*Создано с ❤️ командой Scrapling. Удачного сбора данных!*
diff --git a/docs/locales/ru/api-reference/custom-types.md b/docs/locales/ru/api-reference/custom-types.md
new file mode 100644
index 0000000..96815c5
--- /dev/null
+++ b/docs/locales/ru/api-reference/custom-types.md
@@ -0,0 +1,26 @@
+---
+title: "Справочник API TextHandler и AttributesHandler"
+description: "Типы Scrapling для текста, списков текста и атрибутов: регулярные выражения, JSON и поиск значений."
+---
+
+# Пользовательские типы {#custom-types-api-reference}
+
+Здесь описаны аргументы, атрибуты и методы всех пользовательских типов Scrapling.
+
+Их можно импортировать напрямую:
+
+```python
+from scrapling.core.custom_types import TextHandler, TextHandlers, AttributesHandler
+```
+
+## ::: scrapling.core.custom_types.TextHandler
+ handler: python
+ :docstring:
+
+## ::: scrapling.core.custom_types.TextHandlers
+ handler: python
+ :docstring:
+
+## ::: scrapling.core.custom_types.AttributesHandler
+ handler: python
+ :docstring:
diff --git a/docs/locales/ru/api-reference/fetchers.md b/docs/locales/ru/api-reference/fetchers.md
new file mode 100644
index 0000000..174c7f4
--- /dev/null
+++ b/docs/locales/ru/api-reference/fetchers.md
@@ -0,0 +1,48 @@
+---
+title: "Справочник API HTTP- и браузерных Fetcher"
+description: "API Fetcher, AsyncFetcher, StealthyFetcher и сессий: параметры запросов, настройки браузера и типы ответов."
+---
+
+# Классы Fetcher {#fetchers-classes}
+
+Здесь описаны аргументы, атрибуты и методы всех классов Fetcher.
+
+Их можно импортировать напрямую:
+
+```python
+from scrapling.fetchers import (
+ Fetcher, AsyncFetcher, StealthyFetcher,
+ FetcherSession, AsyncStealthySession, StealthySession
+)
+```
+
+## ::: scrapling.fetchers.Fetcher
+ handler: python
+ :docstring:
+
+## ::: scrapling.fetchers.AsyncFetcher
+ handler: python
+ :docstring:
+
+## ::: scrapling.fetchers.StealthyFetcher
+ handler: python
+ :docstring:
+
+
+## Классы сессий {#session-classes}
+
+### HTTP-сессии {#http-sessions}
+
+## ::: scrapling.fetchers.FetcherSession
+ handler: python
+ :docstring:
+
+### Скрытные сессии {#stealth-sessions}
+
+## ::: scrapling.fetchers.StealthySession
+ handler: python
+ :docstring:
+
+## ::: scrapling.fetchers.AsyncStealthySession
+ handler: python
+ :docstring:
diff --git a/docs/locales/ru/api-reference/mcp-server.md b/docs/locales/ru/api-reference/mcp-server.md
new file mode 100644
index 0000000..c8b987a
--- /dev/null
+++ b/docs/locales/ru/api-reference/mcp-server.md
@@ -0,0 +1,96 @@
+---
+title: "Справочник API MCP-сервера Scrapling"
+description: "Инструменты MCP, модели запросов и ответов и операции с сессиями для сбора данных через HTTP и браузер."
+---
+
+# Справочник API MCP-сервера {#mcp-server-api-reference}
+
+**MCP-сервер Scrapling** предоставляет шестнадцать инструментов для сбора данных и работы с браузером через Model Context Protocol (MCP). Он подключает Scrapling к AI-ботам и агентам, чтобы можно было собирать данные через диалог и обходить защиту от ботов.
+
+Запустите MCP-сервер командой:
+
+```bash
+scrapling mcp
+```
+
+Или импортируйте класс сервера напрямую:
+
+```python
+from scrapling.core.ai import ScraplingMCPServer
+
+server = ScraplingMCPServer()
+server.serve(http=False, host="127.0.0.1", port=8000)
+```
+
+Чтобы использовать собственный браузер на основе Chromium, передайте путь в `executable_path`:
+
+```python
+server = ScraplingMCPServer(executable_path="/path/to/chromium")
+```
+
+## Модель ответа {#response-model}
+
+Инструменты загрузки страниц и HTTP-запросов возвращают по одному ответу на вызов в формате ниже. Управление сессиями использует отдельные модели, описанные дальше. `browser_screenshot` возвращает изображение страницы или элемента и текущий URL как блоки изображения и текста. `browser_extract` и `browser_actions` возвращают обычный текст. Оба сетевых инструмента возвращают структурированный JSON в моделях ниже. `browser_evaluate` возвращает результат в виде JSON в текстовом блоке.
+
+## ::: scrapling.core.ai.server.ResponseModel
+ handler: python
+ :docstring:
+
+## Модели сетевых запросов {#network-request-models}
+
+`browser_network_requests` возвращает `NetworkRequestsModel` с полями `requests`, `next_cursor`, `has_more` и `dropped_count`. Каждый `NetworkRequestInfo` содержит `id`, `url`, `method`, `resource_type` и `status`. Для продолжения передайте `next_cursor` в `after_id`. Поле `has_more` показывает, есть ли ещё подходящие записи в текущей истории.
+
+`browser_network_request` возвращает `NetworkRequestModel` с полями `request_id`, `part`, `data` и `note`. Сводка и заголовки представлены объектами. Полный сохранённый текст тела возвращается строкой, даже если это JSON. Поле `note` объясняет, почему тела нет или заголовки неполные.
+
+## ::: scrapling.core.ai._network_formatting.NetworkRequestInfo
+ handler: python
+ :docstring:
+
+## ::: scrapling.core.ai.server.NetworkRequestsModel
+ handler: python
+ :docstring:
+
+## ::: scrapling.core.ai._network_formatting.NetworkRequestModel
+ handler: python
+ :docstring:
+
+## Модели сессий {#session-models}
+
+Классы моделей для управления сессиями:
+
+## ::: scrapling.core.ai.server.SessionInfo
+ handler: python
+ :docstring:
+
+## ::: scrapling.core.ai.server.SessionCreatedModel
+ handler: python
+ :docstring:
+
+## ::: scrapling.core.ai.server.SessionClosedModel
+ handler: python
+ :docstring:
+
+## Класс MCP-сервера {#mcp-server-class}
+
+Основной класс MCP-сервера предоставляет следующие инструменты:
+
+- **`make_request`**: получает один URL по HTTP с имитацией браузера и автоматически закрывает клиент. Поддерживает GET, POST, PUT и DELETE.
+- **`browser_fetch_once`**: получает один URL через скрытный браузер, выполняет JavaScript, проходит проверки Cloudflare и закрывает браузер. Если нужны дальнейшие действия или история запросов, используйте постоянную сессию.
+
+- **`browser_extract`**: читает текущую страницу или элемент в виде снимка структуры для AI, HTML, Markdown или текста без перезагрузки. Результаты работы с формами и страницей сохраняются. Снимок содержит роли, имена, ссылки на элементы, их положение и размеры. Поиск по регулярному выражению возвращает совпавшие строки, соседний контекст и родительские узлы.
+- **`browser_actions`**: выполняет движения мыши, наведение, клики, прокрутку, заполнение полей, сочетания клавиш, ответы на диалоги и ожидание за один вызов. Принимайте или закрывайте уведомления и подтверждения, вводите текст в диалогах. Можно заполнить поиск, отправить его, дождаться результатов и открыть один из них без отдельного вызова на каждый шаг.
+
+ Для движения и клика укажите селектор, ссылку из снимка или координаты. Инструмент дождётся элемента и прокрутит его в видимую область. Есть пошаговое движение, левая, правая и средняя кнопки, двойной клик и прокрутка вложенных областей.
+
+ Находите поля через селекторы или ссылки из снимка. Вводите текст, ставьте и снимайте флажки, выбирайте радиокнопки и один или несколько пунктов обычного выпадающего списка по подписи. Заменяйте и очищайте текст или добавляйте его в позиции курсора. Сочетания клавиш действуют на элемент в фокусе. Медленный режим добавляет случайные паузы между символами и действиями.
+
+ Ждите, пока содержимое или индикатор загрузки достигнет нужного состояния, используя селектор или ссылку из снимка. Можно также дождаться события загрузки, прекращения сетевой активности или задать паузу.
+
+- **`browser_evaluate`**: выполняет JavaScript на текущей странице для извлечения данных, вычислений, чтения состояния приложения или изменения содержимого. Поддерживает асинхронные скрипты и возвращает результат в JSON.
+- **`browser_network_requests`**: ищет завершённые запросы из разных вкладок, переходов и действий. Находит API-вызовы, HTTP-ошибки и сохранённые перенаправления. Статические ресурсы по умолчанию скрыты, чтобы сократить результат. Незавершённые запросы и запросы со сбоем не включаются. Возвращает структурированные данные с разбивкой на страницы.
+- **`browser_network_request`**: читает сводку, заголовки, отправленные данные или текст тела сохранённого ответа в виде структурированного JSON, не повторяя запрос. Выбранная часть возвращается целиком, включая сохранённый текст. Ответы остаются доступны после переходов по страницам, в том числе ответы HTTP 4xx и 5xx. Запись появляется после завершения сохранения. Чтение истории и закрытие сессии не ждут его окончания, поэтому незавершённая запись может потеряться при переходе или закрытии. Байты получены от Playwright и могут отличаться от байтов сервера. Текст декодируется как UTF-8 по правилам Playwright, если сохранённые байты корректны для этой кодировки. Иначе используется объявленная кодировка. Читаются и сохраняются только тела с поддерживаемым текстовым `Content-Type`. Для двоичных данных, неизвестного или отсутствующего типа сохраняются только метаданные и заголовки без чтения тела. Загрузка браузером не меняется. Размер истории ограничен. Дополнительная заметка объясняет, почему тело не текстовое, слишком большое или недоступно для чтения. Прочитайте нужные данные до закрытия MCP-сессии.
+- **`browser_fetch`**: загружает страницу в открытой скрытной браузерной сессии и извлекает HTML, Markdown, текст или снимок структуры. Снимок может охватывать всю страницу или один элемент и содержит ссылки на элементы, их положение и размеры для последующих действий.
+
+## ::: scrapling.core.ai.server.ScraplingMCPServer
+ handler: python
+ :docstring:
diff --git a/docs/locales/ru/api-reference/proxy-rotation.md b/docs/locales/ru/api-reference/proxy-rotation.md
new file mode 100644
index 0000000..2f00dce
--- /dev/null
+++ b/docs/locales/ru/api-reference/proxy-rotation.md
@@ -0,0 +1,18 @@
+---
+title: "Справочник API ProxyRotator"
+description: "ProxyRotator, выбор прокси и правила их смены для HTTP- и браузерных сессий."
+---
+
+# Смена прокси {#proxy-rotation}
+
+`ProxyRotator` переключает прокси во всех Fetcher и сессиях. Он безопасен для работы из нескольких потоков.
+
+Его можно импортировать напрямую:
+
+```python
+from scrapling.fetchers import ProxyRotator
+```
+
+## ::: scrapling.engines.toolbelt.proxy_rotation.ProxyRotator
+ handler: python
+ :docstring:
diff --git a/docs/locales/ru/api-reference/response.md b/docs/locales/ru/api-reference/response.md
new file mode 100644
index 0000000..f075732
--- /dev/null
+++ b/docs/locales/ru/api-reference/response.md
@@ -0,0 +1,18 @@
+---
+title: "Справочник API Response"
+description: "Статус, заголовки, тело, метаданные, Markdown и follow в Response, а также методы извлечения данных от Selector."
+---
+
+# Класс Response {#response-class}
+
+`Response` представляет HTTP-ответ, который возвращают все Fetcher. В нём доступны статус, заголовки, тело, cookie и методы разбора, унаследованные от `Selector`.
+
+Класс `Response` можно импортировать так:
+
+```python
+from scrapling.engines.toolbelt.custom import Response
+```
+
+## ::: scrapling.engines.toolbelt.custom.Response
+ handler: python
+ :docstring:
diff --git a/docs/locales/ru/api-reference/selector.md b/docs/locales/ru/api-reference/selector.md
new file mode 100644
index 0000000..9bddedf
--- /dev/null
+++ b/docs/locales/ru/api-reference/selector.md
@@ -0,0 +1,24 @@
+---
+title: "Справочник API Selector и Selectors"
+description: "Методы Selector и Selectors для разбора HTML, выбора элементов, извлечения данных, навигации и адаптивного поиска."
+---
+
+# Класс Selector {#selector-class}
+
+`Selector` является основным классом Scrapling для разбора HTML и выбора элементов.
+
+Здесь описаны все аргументы, атрибуты и методы `Selector`.
+
+`Selector` можно импортировать прямо из `scrapling`:
+
+```python
+from scrapling.parser import Selector
+```
+
+## ::: scrapling.parser.Selector
+ handler: python
+ :docstring:
+
+## ::: scrapling.parser.Selectors
+ handler: python
+ :docstring:
diff --git a/docs/locales/ru/api-reference/spiders.md b/docs/locales/ru/api-reference/spiders.md
new file mode 100644
index 0000000..22f1aa2
--- /dev/null
+++ b/docs/locales/ru/api-reference/spiders.md
@@ -0,0 +1,42 @@
+---
+title: "Справочник API Spider, запросов и результатов"
+description: "Хуки Spider, запросы, сессии, статистика обхода и экспорт данных."
+---
+
+# Классы Spider {#spider-classes}
+
+Здесь описаны аргументы, атрибуты и методы классов системы обхода сайтов.
+
+Их можно импортировать напрямую:
+
+```python
+from scrapling.spiders import Spider, Request, CrawlResult, SessionManager, Response
+```
+
+## ::: scrapling.spiders.Spider
+ handler: python
+ :docstring:
+
+## ::: scrapling.spiders.Request
+ handler: python
+ :docstring:
+
+## Классы результатов {#result-classes}
+
+## ::: scrapling.spiders.result.CrawlResult
+ handler: python
+ :docstring:
+
+## ::: scrapling.spiders.result.CrawlStats
+ handler: python
+ :docstring:
+
+## ::: scrapling.spiders.result.ItemList
+ handler: python
+ :docstring:
+
+## Управление сессиями {#session-management}
+
+## ::: scrapling.spiders.session.SessionManager
+ handler: python
+ :docstring:
diff --git a/docs/locales/ru/assets b/docs/locales/ru/assets
new file mode 120000
index 0000000..41aef43
--- /dev/null
+++ b/docs/locales/ru/assets
@@ -0,0 +1 @@
+../../assets
\ No newline at end of file
diff --git a/docs/locales/ru/benchmarks.md b/docs/locales/ru/benchmarks.md
new file mode 100644
index 0000000..2066a75
--- /dev/null
+++ b/docs/locales/ru/benchmarks.md
@@ -0,0 +1,33 @@
+---
+title: "Тесты HTML-парсеров Python: Scrapling и другие библиотеки"
+description: "Сравните Scrapling с другими библиотеками Python в разборе HTML, извлечении текста и поиске похожих элементов."
+---
+
+# Тесты производительности {#performance-benchmarks}
+
+Scrapling не только мощный, но и очень быстрый. Ниже мы сравниваем его парсер с другими популярными библиотеками.
+
+### Скорость извлечения текста: 5 000 вложенных элементов {#text-extraction-speed-test-5000-nested-elements}
+
+| # | Библиотека | Время (мс) | По сравнению со Scrapling |
+|---|:-----------------:|:---------:|:------------:|
+| 1 | Scrapling | 1,99 | 1,0x |
+| 2 | Parsel/Scrapy | 2,06 | 1,035 |
+| 3 | Чистый Lxml | 2,56 | 1,286 |
+| 4 | PyQuery | 23,98 | ~12x |
+| 5 | Selectolax | 197,02 | ~99x |
+| 6 | MechanicalSoup | 1545,15 | ~776,5x |
+| 7 | BS4 + Lxml | 1562,1 | ~785,0x |
+| 8 | BS4 + html5lib | 3412,73 | ~1714,9x |
+
+
+### Поиск похожих элементов и текста {#element-similarity-text-search-performance}
+
+Адаптивный поиск элементов в Scrapling значительно опережает другие решения:
+
+| Библиотека | Время (мс) | По сравнению со Scrapling |
+|-------------|:---------:|:------------:|
+| Scrapling | 2,3 | 1,0x |
+| AutoScraper | 12,58 | 5,47x |
+
+> Каждый результат усреднён по 100 запускам с замером времени. Методика приведена в [benchmarks.py](https://github.com/D4Vinci/Scrapling/blob/main/benchmarks.py).
diff --git a/docs/locales/ru/cli/extract-commands.md b/docs/locales/ru/cli/extract-commands.md
new file mode 100644
index 0000000..083398f
--- /dev/null
+++ b/docs/locales/ru/cli/extract-commands.md
@@ -0,0 +1,326 @@
+---
+title: "Сохранение веб-страниц в Markdown, HTML или текст из CLI"
+description: "Используйте scrapling extract для сохранения результатов HTTP-запросов или браузера. Фильтруйте содержимое с помощью CSS, задавайте параметры запросов и выбирайте формат вывода."
+---
+
+# Команды извлечения Scrapling {#scrapling-extract-command-guide}
+
+**Собирайте данные с сайтов через терминал без программирования!**
+
+Команда `scrapling extract` позволяет скачивать и извлекать содержимое сайтов прямо из терминала, не написав ни строки кода. Она подходит новичкам, исследователям и всем, кому нужно быстро получить данные из интернета.
+
+!!! success "Перед началом"
+
+ 1. Прочитайте [основы Fetcher](../fetching/choosing.md), чтобы понять, что такое [объект Response](../fetching/choosing.md#response-object) и какой Fetcher выбрать.
+ 2. Прочитайте [поиск элементов](../parsing/selection.md), чтобы научиться находить и извлекать элементы из [Selector](../parsing/main_classes.md#selector)/[Response](../fetching/choosing.md#response-object).
+ 3. Прочитайте [основные классы](../parsing/main_classes.md), чтобы узнать, какие свойства и методы [Response](../fetching/choosing.md#response-object) наследует от [Selector](../parsing/main_classes.md#selector).
+ 4. Прочитайте хотя бы одну страницу о Fetcher, который будете использовать: [HTTP-запросы](../fetching/static.md) или [загрузка через браузер](../fetching/stealthy.md).
+
+
+## Что такое группа команд extract {#what-is-the-extract-command-group}
+
+Это набор простых инструментов для терминала, который позволяет:
+
+- **Скачивать веб-страницы** и сохранять содержимое в файлы.
+- **Преобразовывать HTML в удобные форматы**, например Markdown, сохранять исходный HTML или извлекать только текст страницы.
+- **Использовать свои CSS-селекторы**, чтобы извлекать отдельные части страницы.
+- **Отправлять HTTP-запросы и загружать страницы через браузер**.
+- **Подробно настраивать работу**: задавать заголовки, Cookie, прокси и другие параметры. Почти все параметры, доступные в коде, есть и в командной строке.
+
+!!! tip "Режим для ИИ"
+
+ Все команды извлечения поддерживают флаг `--ai-targeted`. Он оставляет только основное содержимое страницы, удаляет служебные теги (script, style, noscript, svg), скрытые элементы, которые могут содержать инструкции для ИИ (элементы со встроенными скрывающими стилями, aria-hidden, скрытые слоты, template), символы Unicode нулевой ширины и HTML-комментарии. В команде браузера (`fetch`) он также автоматически включает блокировку рекламы. Этот режим подходит для передачи результата модели ИИ.
+
+## Быстрый старт {#quick-start}
+
+- **Обычное скачивание страницы**
+
+ Скачайте содержимое сайта в виде чистого, удобного для чтения текста:
+ ```bash
+ scrapling extract get "https://example.com" page_content.txt
+ ```
+ Команда отправит HTTP GET-запрос и сохранит текст страницы в `page_content.txt`.
+
+- **Сохранение в разных форматах**
+
+ Выберите формат вывода, изменив расширение файла:
+ ```bash
+ # Convert the HTML content to Markdown, then save it to the file (great for documentation)
+ scrapling extract get "https://blog.example.com" article.md
+
+ # Save the HTML content as it is to the file
+ scrapling extract get "https://example.com" page.html
+
+ # Save a clean version of the text content of the webpage to the file
+ scrapling extract get "https://example.com" content.txt
+
+ # Or use the Docker image with something like this:
+ docker run -v $(pwd)/output:/output pyd4vinci/scrapling extract get "https://blog.example.com" /output/article.md
+ ```
+
+- **Извлечение нужного содержимого**
+
+ Во всех командах можно передать CSS-селектор через `--css-selector` или `-s`, чтобы извлечь отдельную часть страницы. Ниже приведены примеры.
+
+## Доступные команды {#available-commands}
+
+Команда `scrapling extract --help` показывает следующий список:
+```bash
+Usage: scrapling extract [OPTIONS] COMMAND [ARGS]...
+
+ Fetch web pages using various fetchers and extract full/selected HTML content as HTML, Markdown, or extract text content.
+
+Options:
+ --help Show this message and exit.
+
+Commands:
+ get Perform a GET request and save the content to a file.
+ post Perform a POST request and save the content to a file.
+ put Perform a PUT request and save the content to a file.
+ delete Perform a DELETE request and save the content to a file.
+ fetch Use StealthyFetcher to fetch content with advanced stealth features.
+```
+
+Далее разберём каждую команду подробнее.
+
+### HTTP-запросы {#http-requests}
+
+1. **GET-запрос**
+
+ Самая распространённая команда для скачивания содержимого сайта:
+
+ ```bash
+ scrapling extract get [URL] [OUTPUT_FILE] [OPTIONS]
+ ```
+
+ **Примеры:**
+ ```bash
+ # Basic download
+ scrapling extract get "https://news.site.com" news.md
+
+ # Download with custom timeout
+ scrapling extract get "https://example.com" content.txt --timeout 60
+
+ # Extract only specific content using CSS selectors
+ scrapling extract get "https://blog.example.com" articles.md --css-selector "article"
+
+ # Send a request with cookies
+ scrapling extract get "https://scrapling.requestcatcher.com" content.md --cookies "session=abc123; user=john"
+
+ # Add user agent
+ scrapling extract get "https://api.site.com" data.txt -H "User-Agent: MyBot 1.0"
+
+ # Add multiple headers
+ scrapling extract get "https://site.com" page.html -H "Accept: text/html" -H "Accept-Language: en-US"
+ ```
+ Чтобы увидеть доступные параметры, выполните `scrapling extract get --help`:
+ ```bash
+ Usage: scrapling extract get [OPTIONS] URL OUTPUT_FILE
+
+ Perform a GET request and save the content to a file.
+
+ The output file path can be an HTML file, a Markdown file of the HTML content, or the text content itself. Use file extensions (`.html`/`.md`/`.txt`) respectively.
+
+ Options:
+ -H, --headers TEXT HTTP headers in format "Key: Value" (can be used multiple times)
+ --cookies TEXT Cookies string in format "name1=value1;name2=value2"
+ --timeout INTEGER Request timeout in seconds (default: 30)
+ --proxy TEXT Proxy URL in format "http://username:password@host:port"
+ -s, --css-selector TEXT CSS selector to extract specific content from the page. It returns all matches.
+ -p, --params TEXT Query parameters in format "key=value" (can be used multiple times)
+ --follow-redirects / --no-follow-redirects Whether to follow redirects (default: True)
+ --verify / --no-verify Whether to verify SSL certificates (default: True)
+ --impersonate TEXT Browser to impersonate (e.g., chrome, firefox).
+ --stealthy-headers / --no-stealthy-headers Use stealthy browser headers (default: True)
+ --ai-targeted Extract only main content and sanitize hidden elements for AI consumption (default: False)
+ --help Show this message and exit.
+
+ ```
+ В остальных командах запросов параметры работают так же, поэтому повторять описание не будем.
+
+2. **POST-запрос**
+
+ ```bash
+ scrapling extract post [URL] [OUTPUT_FILE] [OPTIONS]
+ ```
+
+ **Примеры:**
+ ```bash
+ # Submit form data
+ scrapling extract post "https://api.site.com/search" results.html --data "query=python&type=tutorial"
+
+ # Send JSON data
+ scrapling extract post "https://api.site.com" response.txt --json '{"username": "test", "action": "search"}'
+ ```
+ Чтобы увидеть доступные параметры, выполните `scrapling extract post --help`:
+ ```bash
+ Usage: scrapling extract post [OPTIONS] URL OUTPUT_FILE
+
+ Perform a POST request and save the content to a file.
+
+ The output file path can be an HTML file, a Markdown file of the HTML content, or the text content itself. Use file extensions (`.html`/`.md`/`.txt`) respectively.
+
+ Options:
+ -d, --data TEXT Form data to include in the request body (as string, ex: "param1=value1&param2=value2")
+ -j, --json TEXT JSON data to include in the request body (as string)
+ -H, --headers TEXT HTTP headers in format "Key: Value" (can be used multiple times)
+ --cookies TEXT Cookies string in format "name1=value1;name2=value2"
+ --timeout INTEGER Request timeout in seconds (default: 30)
+ --proxy TEXT Proxy URL in format "http://username:password@host:port"
+ -s, --css-selector TEXT CSS selector to extract specific content from the page. It returns all matches.
+ -p, --params TEXT Query parameters in format "key=value" (can be used multiple times)
+ --follow-redirects / --no-follow-redirects Whether to follow redirects (default: True)
+ --verify / --no-verify Whether to verify SSL certificates (default: True)
+ --impersonate TEXT Browser to impersonate (e.g., chrome, firefox).
+ --stealthy-headers / --no-stealthy-headers Use stealthy browser headers (default: True)
+ --ai-targeted Extract only main content and sanitize hidden elements for AI consumption (default: False)
+ --help Show this message and exit.
+
+ ```
+
+3. **PUT-запрос**
+
+ ```bash
+ scrapling extract put [URL] [OUTPUT_FILE] [OPTIONS]
+ ```
+
+ **Примеры:**
+ ```bash
+ # Send data
+ scrapling extract put "https://scrapling.requestcatcher.com/put" results.html --data "update=info" --impersonate "firefox"
+
+ # Send JSON data
+ scrapling extract put "https://scrapling.requestcatcher.com/put" response.txt --json '{"username": "test", "action": "search"}'
+ ```
+ Чтобы увидеть доступные параметры, выполните `scrapling extract put --help`:
+ ```bash
+ Usage: scrapling extract put [OPTIONS] URL OUTPUT_FILE
+
+ Perform a PUT request and save the content to a file.
+
+ The output file path can be an HTML file, a Markdown file of the HTML content, or the text content itself. Use file extensions (`.html`/`.md`/`.txt`) respectively.
+
+ Options:
+ -d, --data TEXT Form data to include in the request body
+ -j, --json TEXT JSON data to include in the request body (as string)
+ -H, --headers TEXT HTTP headers in format "Key: Value" (can be used multiple times)
+ --cookies TEXT Cookies string in format "name1=value1;name2=value2"
+ --timeout INTEGER Request timeout in seconds (default: 30)
+ --proxy TEXT Proxy URL in format "http://username:password@host:port"
+ -s, --css-selector TEXT CSS selector to extract specific content from the page. It returns all matches.
+ -p, --params TEXT Query parameters in format "key=value" (can be used multiple times)
+ --follow-redirects / --no-follow-redirects Whether to follow redirects (default: True)
+ --verify / --no-verify Whether to verify SSL certificates (default: True)
+ --impersonate TEXT Browser to impersonate (e.g., chrome, firefox).
+ --stealthy-headers / --no-stealthy-headers Use stealthy browser headers (default: True)
+ --ai-targeted Extract only main content and sanitize hidden elements for AI consumption (default: False)
+ --help Show this message and exit.
+ ```
+
+4. **DELETE-запрос**
+
+ ```bash
+ scrapling extract delete [URL] [OUTPUT_FILE] [OPTIONS]
+ ```
+
+ **Примеры:**
+ ```bash
+ # Send data
+ scrapling extract delete "https://scrapling.requestcatcher.com/delete" results.html
+
+ # Send JSON data
+ scrapling extract delete "https://scrapling.requestcatcher.com/" response.txt --impersonate "chrome"
+ ```
+ Чтобы увидеть доступные параметры, выполните `scrapling extract delete --help`:
+ ```bash
+ Usage: scrapling extract delete [OPTIONS] URL OUTPUT_FILE
+
+ Perform a DELETE request and save the content to a file.
+
+ The output file path can be an HTML file, a Markdown file of the HTML content, or the text content itself. Use file extensions (`.html`/`.md`/`.txt`) respectively.
+
+ Options:
+ -H, --headers TEXT HTTP headers in format "Key: Value" (can be used multiple times)
+ --cookies TEXT Cookies string in format "name1=value1;name2=value2"
+ --timeout INTEGER Request timeout in seconds (default: 30)
+ --proxy TEXT Proxy URL in format "http://username:password@host:port"
+ -s, --css-selector TEXT CSS selector to extract specific content from the page. It returns all matches.
+ -p, --params TEXT Query parameters in format "key=value" (can be used multiple times)
+ --follow-redirects / --no-follow-redirects Whether to follow redirects (default: True)
+ --verify / --no-verify Whether to verify SSL certificates (default: True)
+ --impersonate TEXT Browser to impersonate (e.g., chrome, firefox).
+ --stealthy-headers / --no-stealthy-headers Use stealthy browser headers (default: True)
+ --ai-targeted Extract only main content and sanitize hidden elements for AI consumption (default: False)
+ --help Show this message and exit.
+ ```
+
+### Загрузка через браузер {#browser-fetching}
+
+Используйте `fetch` для страниц с JavaScript, автоматизации браузера и защищённых сайтов. Команда запускает `StealthyFetcher` со всеми доступными параметрами скрытности.
+
+```bash
+scrapling extract fetch "https://scrapling.requestcatcher.com/" content.md --network-idle
+scrapling extract fetch "https://scrapling.requestcatcher.com/" data.txt --wait-selector ".content-loaded"
+scrapling extract fetch "https://scrapling.requestcatcher.com/" page.html --no-headless --disable-resources
+scrapling extract fetch "https://nopecha.com/demo/cloudflare" data.txt --solve-cloudflare --css-selector "#padded_content a"
+scrapling extract fetch "https://site.com" content.md --proxy "http://proxy-server:8080"
+```
+
+Чтобы включить содержимое открытого Shadow DOM, используйте `--pierce-shadow`. По умолчанию эта возможность выключена; `--no-pierce-shadow` явно отключает её. Примеры селекторов и ограничения описаны в разделе [Shadow DOM](../fetching/stealthy.md#shadow-dom).
+
+```bash
+scrapling extract fetch "https://example.com" content.md --pierce-shadow
+```
+
+Все параметры можно посмотреть командой `scrapling extract fetch --help`:
+
+```text
+Usage: scrapling extract fetch [OPTIONS] URL OUTPUT_FILE
+
+ Use StealthyFetcher to fetch content with advanced stealth features.
+
+Options:
+ --headless / --no-headless Run browser in headless mode (default: True)
+ --disable-resources / --enable-resources Drop unnecessary resources for speed boost (default: False)
+ --block-webrtc / --allow-webrtc Block WebRTC entirely (default: False)
+ --solve-cloudflare / --no-solve-cloudflare Solve Cloudflare challenges (default: False)
+ --allow-webgl / --block-webgl Allow WebGL (default: True)
+ --pierce-shadow / --no-pierce-shadow Include open Shadow DOM content (default: False)
+ --network-idle / --no-network-idle Wait for network idle (default: False)
+ --real-chrome/--no-real-chrome If you have a Chrome browser installed on your device, enable this, and the Fetcher will launch an instance of your browser and use it. (default: False)
+ --timeout INTEGER Timeout in milliseconds (default: 30000)
+ --wait INTEGER Additional wait time in milliseconds after page load (default: 0)
+ -s, --css-selector TEXT CSS selector to extract specific content from the page. It returns all matches.
+ --wait-selector TEXT CSS selector to wait for before proceeding
+ --hide-canvas / --show-canvas Add noise to canvas operations (default: False)
+ --locale TEXT Specify user locale. Defaults to the system default locale.
+ --proxy TEXT Proxy URL in format "http://username:password@host:port"
+ -H, --extra-headers TEXT Extra headers in format "Key: Value" (can be used multiple times)
+ --dns-over-https / --no-dns-over-https Route DNS through Cloudflare's DoH to prevent DNS leaks when using proxies (default: False)
+ --block-ads / --no-block-ads Block requests to known ad and tracker domains (default: False)
+ --executable-path TEXT Path to a custom Chromium-compatible browser executable. Falls back to the SCRAPLING_EXECUTABLE_PATH environment variable when not set.
+ --ai-targeted Extract only main content and sanitize hidden elements for AI consumption (default: False)
+ --help Show this message and exit.
+```
+
+## Как выбрать команду {#when-to-use-each-command}
+
+Если вы пока не уверены, какую команду выбрать, используйте это простое правило:
+
+- **`get`** подходит для простых сайтов, блогов и новостных статей.
+- **`fetch`** подходит для страниц с JavaScript, автоматизации браузера и защищённых сайтов, в том числе с Cloudflare.
+
+## Правовые и этические вопросы {#legal-and-ethical-considerations}
+
+⚠️ **Важные правила:**
+
+- **Проверяйте robots.txt**: откройте `https://website.com/robots.txt`, чтобы узнать правила сбора данных.
+- **Соблюдайте ограничения частоты**: не перегружайте сервер запросами.
+- **Условия использования**: прочитайте правила сайта и следуйте им.
+- **Авторское право**: уважайте права на интеллектуальную собственность.
+- **Конфиденциальность**: учитывайте законы о защите персональных данных.
+- **Коммерческое использование**: убедитесь, что у вас есть нужное разрешение для деловых целей.
+
+---
+
+*Удачного сбора данных! Всегда уважайте правила сайтов и соблюдайте применимые законы и нормы.*
diff --git a/docs/locales/ru/cli/interactive-shell.md b/docs/locales/ru/cli/interactive-shell.md
new file mode 100644
index 0000000..5bc7cb0
--- /dev/null
+++ b/docs/locales/ru/cli/interactive-shell.md
@@ -0,0 +1,237 @@
+---
+title: "Проверка сбора данных в интерактивной оболочке Scrapling"
+description: "Загружайте страницы, пробуйте селекторы и изучайте результаты в IPython. Преобразуйте команды curl, повторно используйте недавние ответы и проверяйте код сбора данных."
+---
+
+# Интерактивная оболочка Scrapling {#scrapling-interactive-shell-guide}
+
+<script src="https://asciinema.org/a/736339.js" id="asciicast-736339" async data-autoplay="1" data-loop="1" data-cols="225" data-rows="40" data-start-at="00:06" data-speed="1.5" data-theme="tango"></script>
+
+**Среда REPL для разработчиков и специалистов по данным, работающих с веб-скрейпингом**
+
+Интерактивная оболочка Scrapling расширяет IPython для задач сбора данных с сайтов. Все возможности Scrapling доступны сразу. В ней есть удобные сокращения, автоматическое управление страницами и инструменты вроде преобразования команд curl.
+
+!!! success "Перед началом"
+
+ 1. Прочитайте [основы Fetcher](../fetching/choosing.md), чтобы понять, что такое [объект Response](../fetching/choosing.md#response-object) и какой Fetcher выбрать.
+ 2. Прочитайте [поиск элементов](../parsing/selection.md), чтобы научиться находить и извлекать элементы из [Selector](../parsing/main_classes.md#selector)/[Response](../fetching/choosing.md#response-object).
+ 3. Прочитайте [основные классы](../parsing/main_classes.md), чтобы узнать, какие свойства и методы [Response](../fetching/choosing.md#response-object) наследует от [Selector](../parsing/main_classes.md#selector).
+ 4. Прочитайте хотя бы одну страницу о Fetcher, который будете использовать: [HTTP-запросы](../fetching/static.md) или [загрузка через браузер](../fetching/stealthy.md).
+
+
+## Зачем нужна интерактивная оболочка {#why-use-the-interactive-shell}
+
+Оболочка позволяет быстро пробовать разные подходы, вместо того чтобы каждый раз писать и запускать скрипт. Она подходит для следующих задач:
+
+- **Быстрые прототипы**: сразу проверяйте способы сбора данных.
+- **Изучение данных**: переходите по сайту и извлекайте данные в диалоге с оболочкой.
+- **Изучение Scrapling**: пробуйте функции на практике.
+- **Отладка**: выполняйте запросы по шагам и проверяйте результаты.
+- **Преобразование рабочих запросов**: превращайте команду curl из DevTools браузера в запрос Fetcher одной строкой.
+
+## Начало работы {#getting-started}
+
+### Запуск оболочки {#launch-the-shell}
+
+```bash
+# Start the interactive shell
+scrapling shell
+
+# Execute code and exit (useful for scripting)
+scrapling shell -c "get('https://quotes.toscrape.com'); print(len(page.css('.quote')))"
+
+# Set logging level
+scrapling shell --loglevel info
+```
+
+После запуска появится баннер Scrapling. Можно сразу начинать сбор данных, как в видео выше:
+
+```python
+# No imports needed - everything is ready!
+get('https://news.ycombinator.com')
+
+# Explore the page structure
+page.css('a')[:5] # Look at first 5 links
+
+# Refine your selectors
+stories = page.css('.titleline>a')
+len(stories) # 30
+
+# Extract specific data
+for story in stories[:3]:
+ title = story.text
+ url = story['href']
+ print(f"{title}: {url}")
+
+# Try different approaches
+titles = page.css('.titleline>a::text') # Direct text extraction
+urls = page.css('.titleline>a::attr(href)') # Direct attribute extraction
+```
+
+## Встроенные сокращения {#built-in-shortcuts}
+
+Оболочка предоставляет сокращения, чтобы не писать повторяющийся код:
+
+- **`get(url, **kwargs)`**: HTTP GET-запрос вместо `Fetcher.get`.
+- **`post(url, **kwargs)`**: HTTP POST-запрос вместо `Fetcher.post`.
+- **`put(url, **kwargs)`**: HTTP PUT-запрос вместо `Fetcher.put`.
+- **`delete(url, **kwargs)`**: HTTP DELETE-запрос вместо `Fetcher.delete`.
+- **`fetch(url, **kwargs)`**: загрузка через скрытный браузер вместо `StealthyFetcher.fetch`.
+
+Часто используемые классы уже доступны без импорта, в том числе `Fetcher`, `AsyncFetcher`, `StealthyFetcher` и `Selector`.
+
+### Автоматическое управление страницами {#smart-page-management}
+
+Оболочка автоматически отслеживает запросы и страницы:
+
+- **Доступ к текущей странице**
+
+ `page` и `response` автоматически обновляются и содержат последнюю загруженную страницу:
+
+ ```python
+ get('https://quotes.toscrape.com')
+ # 'page' and 'response' both refer to the last fetched page
+ page.url # 'https://quotes.toscrape.com'
+ response.status # Prints 200; Same as page.status
+ ```
+
+- **История страниц**
+
+ `pages` хранит последние пять страниц в объекте `Selectors`:
+
+ ```python
+ get('https://site1.com')
+ get('https://site2.com')
+ get('https://site3.com')
+
+ # Access last 5 pages
+ len(pages) # `Selectors` object with `page` history -> 3
+ pages[0].url # First page in history -> 'https://site1.com'
+ pages[-1].url # Most recent page -> 'https://site3.com'
+
+ # Work with historical pages
+ for i, old_page in enumerate(pages):
+ print(f"Page {i}: {old_page.url} - {old_page.status}")
+ ```
+
+## Другие полезные команды {#additional-helpful-commands}
+
+### Просмотр страницы {#page-visualization}
+
+Откройте загруженную страницу в браузере:
+
+```python
+get('https://quotes.toscrape.com')
+view(page) # Opens the page HTML in your default browser
+```
+
+### Работа с командами curl {#curl-command-integration}
+
+Для преобразования команд curl из DevTools браузера в запросы `Fetcher` есть функции `uncurl` и `curl2fetcher`.
+
+Сначала скопируйте запрос как команду curl:
+
+<img src="../assets/scrapling_shell_curl.png" title="Копирование запроса из Chrome в виде команды curl" alt="Копирование запроса из Chrome в виде команды curl" style="width: 70%;"/>
+
+- **Преобразование команды curl в объект Request**
+
+ ```python
+ curl_cmd = '''curl 'https://scrapling.requestcatcher.com/post' \
+ -X POST \
+ -H 'Content-Type: application/json' \
+ -d '{"name": "test", "value": 123}' '''
+
+ request = uncurl(curl_cmd)
+ request.method # -> 'post'
+ request.url # -> 'https://scrapling.requestcatcher.com/post'
+ request.headers # -> {'Content-Type': 'application/json'}
+ ```
+
+- **Прямое выполнение команды curl**
+
+ ```python
+ # Convert and execute in one step
+ curl2fetcher(curl_cmd)
+ page.status # -> 200
+ ```
+
+### Возможности IPython {#ipython-features}
+
+Оболочка поддерживает все возможности IPython:
+
+```python
+# Magic commands
+%time page = get('https://example.com') # Time execution
+%history # Show command history
+%save filename.py 1-10 # Save commands 1-10 to file
+
+# Tab completion works everywhere
+page.c<TAB> # Shows: css, cookies, headers, etc.
+Fetcher.<TAB> # Shows all Fetcher methods
+
+# Object inspection
+get? # Show get documentation
+```
+
+## Примеры {#examples}
+
+Несколько примеров, созданных с помощью ИИ:
+
+#### Сбор данных интернет-магазина {#e-commerce-data-collection}
+
+```python
+# Start with product listing page
+catalog = get('https://shop.example.com/products')
+
+# Find product links
+product_links = catalog.css('.product-link::attr(href)').getall()
+print(f"Found {len(product_links)} products")
+
+# Sample a few products first
+for link in product_links[:3]:
+ product = get(catalog.urljoin(link))
+ name = product.css('.product-name::text').get('')
+ price = product.css('.price::text').get('')
+ print(f"{name}: {price}")
+
+# Scale up with sessions for efficiency
+from scrapling.fetchers import FetcherSession
+with FetcherSession() as session:
+ products = []
+ for link in product_links:
+ product = session.get(catalog.urljoin(link))
+ products.append({
+ 'name': product.css('.product-name::text').get(''),
+ 'price': product.css('.price::text').get(''),
+ 'url': link
+ })
+```
+
+#### Интеграция и проверка API {#api-integration-and-testing}
+
+```python
+>>> # Test API endpoints interactively
+>>> response = get('https://jsonplaceholder.typicode.com/posts/1')
+>>> response.json()
+{'userId': 1, 'id': 1, 'title': 'sunt aut...', 'body': 'quia et...'}
+
+>>> # Test POST requests
+>>> new_post = post('https://jsonplaceholder.typicode.com/posts',
+... json={'title': 'Test Post', 'body': 'Test content', 'userId': 1})
+>>> new_post.json()['id']
+101
+
+>>> # Test with different data
+>>> updated = put('https://jsonplaceholder.typicode.com/posts/1',
+... json={'title': 'Updated Title'})
+```
+
+## Помощь {#getting-help}
+
+Если встроенной справки терминала недостаточно, используйте:
+
+- [Документацию Scrapling](https://scrapling.readthedocs.io/en/latest/ru/)
+- [Сообщество в Discord](https://discord.gg/EMgGbDceNQ)
+- [GitHub Issues](https://github.com/D4Vinci/Scrapling/issues)
+
+На этом всё. Удачного сбора данных! Оболочка позволяет работать с сайтами так же просто, как вести беседу.
diff --git a/docs/locales/ru/cli/overview.md b/docs/locales/ru/cli/overview.md
new file mode 100644
index 0000000..5501cfd
--- /dev/null
+++ b/docs/locales/ru/cli/overview.md
@@ -0,0 +1,35 @@
+---
+title: "Scrapling CLI: сбор данных из терминала"
+description: "Установите инструменты Scrapling для терминала и выберите команды извлечения, интерактивную оболочку или MCP-сервер. Откройте руководство для своей задачи."
+---
+
+# Интерфейс командной строки {#command-line-interface}
+
+Начиная с v0.3, в Scrapling есть интерфейс командной строки с тремя основными возможностями:
+
+1. **Интерактивная оболочка**: среда на основе IPython для сбора данных с сайтов, с удобными сокращениями и инструментами.
+2. **Команды извлечения**: сбор данных с сайтов из терминала без программирования.
+3. **Служебные команды**: инструменты установки и управления.
+
+```bash
+# Launch interactive shell
+scrapling shell
+
+# Convert the content of a page to markdown and save it to a file
+scrapling extract get "https://example.com" content.md
+
+# Get help for any command
+scrapling --help
+scrapling extract --help
+```
+
+## Требования {#requirements}
+Для этого раздела установите дополнительную группу зависимостей `shell`:
+```bash
+pip install "scrapling[shell]"
+```
+Для загрузки страниц через браузер также установите его зависимости:
+```bash
+scrapling install
+```
+Команда скачивает Chromium и его системные зависимости, а также обновляет список TLD. Для HTTP-запросов этот шаг не нужен.
diff --git a/docs/locales/ru/development/adaptive_storage_system.md b/docs/locales/ru/development/adaptive_storage_system.md
new file mode 100644
index 0000000..51ee228
--- /dev/null
+++ b/docs/locales/ru/development/adaptive_storage_system.md
@@ -0,0 +1,73 @@
+---
+title: "Своё хранилище для адаптивного парсинга"
+description: "Реализуйте save и retrieve для адаптивного парсинга Scrapling. Создайте хранилище Redis для сохранения и получения свойств элементов."
+---
+
+# Своя система хранения и поиска {#writing-your-retrieval-system}
+
+По умолчанию Scrapling использует SQLite. Это руководство покажет, как создать свою систему хранения свойств элементов для функции `adaptive`.
+
+Например, можно использовать Firebase и общую базу данных для нескольких пауков на разных компьютерах. Такая удалённая база позволяет паукам обмениваться данными адаптивного парсинга.
+
+Чтобы класс хранилища работал, выполните три условия:
+
+1. Унаследуйте его от абстрактного класса `scrapling.core.storage.StorageSystemMixin`. Принимайте строковый аргумент `url`, чтобы сохранить логику библиотеки.
+2. Добавьте над классом декоратор `functools.lru_cache`, чтобы использовать шаблон Singleton, как в других классах.
+3. Реализуйте методы `save` и `retrieve` с указанными типами:
+ - Метод `save` ничего не возвращает и получает два аргумента от библиотеки.
+ * Первый имеет тип `lxml.html.HtmlElement` и содержит сам элемент. Преобразуйте его в словарь через `element_to_dict` из подмодуля `scrapling.core.utils._StorageTools`, чтобы сохранить общий формат. Затем сохраните словарь в свою базу данных.
+ * Второй представляет собой строковый идентификатор для поиска. Сочетание этого идентификатора и аргумента `url` из конструктора должно быть уникальным для каждой записи. Иначе данные `adaptive` смешаются.
+ - Метод `retrieve` принимает строковый идентификатор. Вместе с `url`, полученным при создании объекта, он используется для поиска словаря элемента в базе данных. Если запись найдена, метод возвращает её, иначе `None`.
+
+> Если нужны подробности, посмотрите реализацию с SQLite3 в файле [storage_adaptors](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/storage.py).
+
+Если класс соответствует этим условиям, остальное несложно. Для многопоточного приложения убедитесь, что класс безопасно работает с несколькими потоками. Класс по умолчанию поддерживает такую работу.
+
+В абстрактном классе есть вспомогательные функции. Подробнее в [коде](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/storage.py), где много пояснений :)
+
+
+## Практический пример: хранилище Redis {#real-world-example-redis-storage}
+
+Вот практический пример с Redis, созданный с помощью ИИ:
+
+```python
+import redis
+import orjson
+from functools import lru_cache
+from scrapling.core.storage import StorageSystemMixin
+from scrapling.core.utils import _StorageTools
+
+@lru_cache(None)
+class RedisStorage(StorageSystemMixin):
+ def __init__(self, host='localhost', port=6379, db=0, url=None):
+ super().__init__(url)
+ self.redis = redis.Redis(
+ host=host,
+ port=port,
+ db=db,
+ decode_responses=False
+ )
+
+ def save(self, element, identifier: str) -> None:
+ # Convert element to dictionary
+ element_dict = _StorageTools.element_to_dict(element)
+
+ # Create key
+ key = f"scrapling:{self._get_base_url()}:{identifier}"
+
+ # Store as JSON
+ self.redis.set(
+ key,
+ orjson.dumps(element_dict)
+ )
+
+ def retrieve(self, identifier: str) -> dict | None:
+ # Get data
+ key = f"scrapling:{self._get_base_url()}:{identifier}"
+ data = self.redis.get(key)
+
+ # Parse JSON if exists
+ if data:
+ return orjson.loads(data)
+ return None
+```
diff --git a/docs/locales/ru/development/scrapling_custom_types.md b/docs/locales/ru/development/scrapling_custom_types.md
new file mode 100644
index 0000000..5387fea
--- /dev/null
+++ b/docs/locales/ru/development/scrapling_custom_types.md
@@ -0,0 +1,27 @@
+---
+title: "Типы текста и атрибутов Scrapling в вашем коде"
+description: "Используйте TextHandler, TextHandlers и AttributesHandler вне парсера. Узнайте об их базовых типах Python, работе с JSON и атрибутах только для чтения."
+---
+
+# Использование типов Scrapling {#using-scraplings-custom-types}
+
+> Типы, созданные для Scrapling, можно использовать и вне библиотеки. Это удобнее, чем копировать их код :)
+
+### Все типы можно импортировать отдельно {#all-current-types-can-be-imported-alone-like-below}
+```python
+from scrapling.core.custom_types import TextHandler, AttributesHandler
+
+somestring = TextHandler('{}')
+parsed = somestring.json()
+somedict_1 = AttributesHandler({'a': 1})
+somedict_2 = AttributesHandler(a=1)
+```
+
+`TextHandler` наследует Python-класс `str`, поэтому поддерживает все стандартные операции и методы строк.
+`parsed` содержит словарь `{}`, а не строку `'{}'`. Для проверки экземпляра используйте `isinstance(somestring, TextHandler)`. Для проверки класса используйте `issubclass(TextHandler, str)`.
+
+`AttributesHandler` наследует `collections.abc.Mapping` и предоставляет неизменяемое отображение, доступное только для чтения. Операции наследуются от базового класса. Переданные данные доступны через свойство `_data`, но оно тоже доступно только для чтения: его тип `types.MappingProxyType` немного быстрее `collections.abc.Mapping`.
+
+Если вы только начинаете изучать Python, достаточно помнить: у `AttributesHandler` работают стандартные операции и методы `dict`, кроме тех, которые меняют данные.
+
+Чтобы изменить данные из `AttributesHandler`, сначала преобразуйте их в обычный словарь, например функцией `dict`, и меняйте уже этот словарь.
diff --git a/docs/locales/ru/donate.md b/docs/locales/ru/donate.md
new file mode 100644
index 0000000..96c9d59
--- /dev/null
+++ b/docs/locales/ru/donate.md
@@ -0,0 +1,37 @@
+---
+title: "Поддержите разработку Scrapling"
+description: "Поддержите Scrapling через GitHub Sponsors или Buy Me a Coffee. Узнайте о рекламных планах и преимуществах для спонсоров."
+---
+
+# Поддержка и реклама {#support-and-advertisement}
+
+Я создаю эти проекты в свободное время и вкладываю много сил и средств, чтобы они были бесплатными для всех. Ваша поддержка пополняет мои запасы кофе, помогает покрывать расходы и даёт возможность улучшать проекты и создавать новые.
+
+Вы можете поддержать меня через [GitHub Sponsors](https://github.com/sponsors/D4Vinci) или [Buy Me a Coffee](https://buymeacoffee.com/d4vinci).
+
+Спасибо! Продолжайте изучать новое и менять мир! ❤️
+
+## Реклама {#advertisement}
+Хотите **рассказать о своей компании** нашей аудитории? Посмотрите [доступные планы](https://github.com/sponsors/D4Vinci):
+
+### 1. [План Silver](https://github.com/sponsors/D4Vinci/sponsorships?tier_id=435495) (100 долларов в месяц) {#1-the-silver-tier-100month}
+Что входит:
+
+1. Ваш логотип [в верхней части страницы проекта Scrapling](https://github.com/D4Vinci/Scrapling?tab=readme-ov-file#sponsors).
+2. Такой же логотип [в верхней части страницы PyPI](https://pypi.org/project/scrapling/) и [страницы образа Docker](https://hub.docker.com/r/pyd4vinci/scrapling), с тем же размещением, что и на странице проекта.
+
+### 2. [План Gold](https://github.com/sponsors/D4Vinci/sponsorships?tier_id=591422) (200 долларов в месяц) {#2-the-gold-tier-200month}
+Что входит:
+
+1. Ваш логотип [в верхней части страницы проекта Scrapling](https://github.com/D4Vinci/Scrapling?tab=readme-ov-file#sponsors).
+2. Такой же логотип [в верхней части страницы PyPI](https://pypi.org/project/scrapling/) и [страницы образа Docker](https://hub.docker.com/r/pyd4vinci/scrapling), с тем же размещением, что и на странице проекта.
+3. Ваш логотип в разделе главных спонсоров на [сайте Scrapling](https://scrapling.readthedocs.io/en/latest/ru/).
+
+### 3. [План Platinum](https://github.com/sponsors/D4Vinci/sponsorships?tier_id=586646) (300 долларов в месяц) {#3-the-platinum-tier-300month}
+Что входит:
+
+1. Особое место для логотипа [в самом верху страницы проекта Scrapling](https://github.com/D4Vinci/Scrapling?tab=readme-ov-file#platinum-sponsors) с описанием до 25 слов.
+2. Такое же размещение логотипа на [странице PyPI](https://pypi.org/project/scrapling/) и [странице Docker](https://hub.docker.com/r/pyd4vinci/scrapling).
+3. Особое место для логотипа среди главных спонсоров на [сайте Scrapling](https://scrapling.readthedocs.io/en/latest/ru/).
+4. Роль партнёра в Discord и объявление в Twitter и Discord.
+5. Упоминание в конце описания каждого выпуска.
\ No newline at end of file
diff --git a/docs/locales/ru/fetching/choosing.md b/docs/locales/ru/fetching/choosing.md
new file mode 100644
index 0000000..9ec6af6
--- /dev/null
+++ b/docs/locales/ru/fetching/choosing.md
@@ -0,0 +1,95 @@
+---
+title: "Выбор между HTTP-запросами и браузером для сбора данных"
+description: "Выберите Fetcher или StealthyFetcher для своей задачи. Узнайте, когда нужны прямые HTTP-запросы, выполнение JavaScript и повторное использование сессий."
+---
+
+# Основы работы с Fetcher {#fetchers-basics}
+
+## Введение {#introduction}
+Fetcher позволяют отправлять запросы и получать страницы одной строкой кода, а затем возвращают объект [Response](#response-object). У них есть много дополнительных возможностей. Начиная с v0.3, у всех Fetcher есть отдельные классы для работы с сессиями. Например, браузерный Fetcher может держать браузер открытым до завершения всех запросов, вместо того чтобы открывать несколько браузеров. Выбор зависит от вашей задачи.
+
+До v0.2 Scrapling был только средством разбора страниц. Эти возможности появились, чтобы постепенно собрать в одной библиотеке всё необходимое для веб-скрейпинга.
+
+> Fetcher не просто оборачивают другие библиотеки. Они используют их как движки для отправки запросов и получения страниц. Каждый Fetcher добавляет возможности, которых нет у самого движка, при этом использует его возможности и настраивает их для сбора данных.
+
+## Обзор Fetcher {#fetchers-overview}
+
+В Scrapling есть HTTP-классы (`Fetcher` и `AsyncFetcher`) и браузерный класс (`StealthyFetcher`), а также классы сессий для повторных запросов.
+
+Эта таблица поможет быстро сравнить их и сделать выбор.
+
+
+| Возможность | Fetcher | StealthyFetcher |
+|--------------------|---------------------------------------------------|--------------------------------------------------------------------------------------------|
+| Относительная скорость | 🐇🐇🐇🐇🐇 | 🐇🐇🐇 |
+| Скрытность | ⭐⭐ | ⭐⭐⭐⭐⭐ |
+| Средства обхода защиты от ботов | ⭐⭐ | ⭐⭐⭐⭐⭐ |
+| Выполнение JavaScript | ❌ | ✅ |
+| Использование памяти | ⭐ | ⭐⭐⭐ |
+| Лучше подходит для | Простого сбора данных, когда достаточно HTTP-запросов | - Сайтов с динамической загрузкой <br/>- Небольших задач автоматизации <br/>- Обхода защиты разной сложности |
+| Браузеры | ❌ | Chromium и Google Chrome |
+| API браузера | ❌ | Playwright |
+| Сложность настройки | Просто | Просто |
+
+На следующих страницах мы подробно рассмотрим каждый из них.
+
+## Настройка парсера во всех Fetcher {#parser-configuration-in-all-fetchers}
+Все Fetcher импортируются одинаково, как вы увидите далее:
+```python
+from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher
+```
+После импорта их можно использовать сразу, без создания экземпляра. Парсер будет работать с настройками по умолчанию:
+```python
+page = StealthyFetcher.fetch('https://example.com')
+```
+Чтобы настроить парсер ([класс Selector](../parsing/main_classes.md#selector)), который обработает ответ перед возвратом, сначала выполните:
+```python
+from scrapling.fetchers import Fetcher
+Fetcher.configure(adaptive=True, keep_comments=False) # and the rest
+```
+или:
+```python
+from scrapling.fetchers import Fetcher
+Fetcher.adaptive=True
+Fetcher.keep_comments=False
+```
+Затем продолжайте писать код как обычно.
+
+Доступны аргументы `adaptive`, `adaptive_domain`, `huge_tree`, `keep_comments`, `storage` и `storage_args`. Это те же аргументы, которые принимает класс [Selector](../parsing/main_classes.md#selector). Текущую конфигурацию можно в любой момент вывести командой `<fetcher_class>.display_config()`.
+
+!!! info "Информация"
+
+ Аргумент `adaptive` по умолчанию выключен. Включите его, чтобы использовать адаптивную функцию.
+
+### Настройка парсера для отдельного запроса {#set-parser-config-per-request}
+Приведённая выше настройка парсера действует на все запросы этого класса. Так проще работать с общими настройками.
+
+Если для каждого запроса нужна своя конфигурация, передайте словарь в аргумент `selector_config` метода запроса (`fetch`/`get`/`post`/...).
+
+## Объект Response {#response-object}
+Объект `Response` основан на классе [Selector](../parsing/main_classes.md#selector), но содержит дополнительные сведения об ответе: заголовки, статус, cookie и другие данные, как показано ниже:
+```python
+from scrapling.fetchers import Fetcher
+page = Fetcher.get('https://example.com')
+
+page.status # HTTP status code
+page.reason # Status message
+page.cookies # Response cookies as a dictionary
+page.headers # Response headers
+page.request_headers # Request headers
+page.history # Response history of redirections, if any
+page.body # Raw response body as bytes
+page.encoding # Response encoding
+page.meta # Response metadata dictionary (e.g., proxy used). Mainly helpful with the spiders system.
+```
+Все Fetcher возвращают объект `Response`. В браузерных сессиях с `record_requests=True` методы `session.network.search(limit=None)` и `session.network.get(request_id)` также возвращают сохранённые объекты `Response`. Подробнее о сохранённых ответах API и переходе на v5 читайте в разделе [История сети](stealthy.md#network-history).
+
+Объект `Response` также позволяет одной строкой преобразовать страницу в очищенный Markdown для LLM:
+```python
+markdown = Fetcher.get('https://example.com').markdown(main_content_only=True)
+```
+Перед преобразованием всегда удаляются скрипты, стили, скрытое содержимое и содержимое с внедрением инструкций. Аргумент `css_selector` позволяет преобразовать только выбранные элементы. Нужен набор зависимостей `rag`, который также входит в `ai`/`shell`/`all`. Подробнее читайте на странице [Создание RAG-систем](../ai/building-rag-systems.md).
+
+!!! note "Примечание"
+
+ В отличие от [Selector](../parsing/main_classes.md#selector), тело ответа класса `Response` начиная с v0.4 всегда хранится в байтах.
diff --git a/docs/locales/ru/fetching/static.md b/docs/locales/ru/fetching/static.md
new file mode 100644
index 0000000..5523ab0
--- /dev/null
+++ b/docs/locales/ru/fetching/static.md
@@ -0,0 +1,449 @@
+---
+title: "Сбор данных по HTTP в Python с Fetcher и FetcherSession"
+description: "Отправляйте синхронные и асинхронные HTTP-запросы с имитацией браузера, cookie, прокси и повторным использованием сессий. Извлекайте данные из ответа с Scrapling."
+---
+
+# HTTP-запросы {#http-requests}
+
+Класс `Fetcher` отправляет быстрые HTTP-запросы с небольшими затратами ресурсов. Он использует высокопроизводительную библиотеку `curl_cffi` и предоставляет много возможностей для скрытной работы.
+
+!!! success "Перед началом"
+
+ 1. Прочитайте [Основы работы с Fetcher](../fetching/choosing.md), чтобы понять, что такое [объект Response](../fetching/choosing.md#response-object) и какой Fetcher выбрать.
+ 2. Прочитайте [Поиск элементов](../parsing/selection.md), чтобы понять, как находить и извлекать элементы из [Selector](../parsing/main_classes.md#selector)/[Response](../fetching/choosing.md#response-object).
+ 3. Прочитайте [Основные классы](../parsing/main_classes.md), чтобы узнать, какие свойства и методы [Response](../fetching/choosing.md#response-object) наследует от [Selector](../parsing/main_classes.md#selector).
+
+## Основы использования {#basic-usage}
+Основной способ импорта этого Fetcher такой же, как и для остальных:
+
+```python
+from scrapling.fetchers import Fetcher
+```
+О настройке парсера читайте [здесь](choosing.md#parser-configuration-in-all-fetchers).
+
+### Общие аргументы {#shared-arguments}
+У всех методов отправки запросов есть общие аргументы. Начнём с них.
+
+- **url**: URL назначения.
+- **stealthy_headers**: при включении (по умолчанию) создаёт и добавляет заголовки настоящего браузера, а также заголовок Referer для Google.
+- **follow_redirects**: управляет перенаправлениями. **По умолчанию `"safe"`**: перенаправления разрешены, но переходы на внутренние и частные IP-адреса отклоняются для защиты от SSRF. `True` разрешает все перенаправления без ограничений, а `False` полностью их отключает.
+- **timeout**: время ожидания завершения каждого запроса в секундах. **По умолчанию 30 секунд**.
+- **retries**: максимальное число попыток при ошибках запроса, включая первую попытку. **По умолчанию 3**.
+- **retry_delay**: пауза между повторными попытками в секундах. **По умолчанию 1 секунда**.
+- **impersonate**: имитирует TLS-отпечатки браузеров. Принимает имя браузера или список имён. Значения вроде `"chrome110"`, `"firefox102"`, `"safari15_5"` выбирают конкретные версии, а `"chrome"`, `"firefox"`, `"safari"`, `"edge"` выбирают последние доступные версии. На уровне TLS запрос выглядит как запрос настоящего браузера. Если передан список, для каждого запроса случайно выбирается один браузер. **По умолчанию используется последняя доступная версия Chrome.**
+- **http3**: использует HTTP/3. **По умолчанию False**. При совместном использовании с `impersonate` возможны проблемы.
+- **cookies**: cookie для запроса. Можно передать словарь `name→value` или список словарей.
+- **proxy**: прокси, через который идёт весь HTTP- и HTTPS-трафик запроса. Формат: `http://username:password@localhost:8030`.
+- **proxy_auth**: HTTP Basic-аутентификация для прокси, кортеж (username, password).
+- **proxies**: словарь прокси в формате `{"http": proxy_url, "https": proxy_url}`.
+- **proxy_rotator**: экземпляр `ProxyRotator` для автоматической смены прокси. Нельзя использовать вместе с `proxy` или `proxies`.
+- **headers**: заголовки запроса. Могут переопределить любой заголовок, созданный через `stealthy_headers`.
+- **max_redirects**: максимальное число перенаправлений. **По умолчанию 30**. Значение -1 убирает ограничение.
+- **verify**: проверять ли сертификаты HTTPS. **По умолчанию True**.
+- **cert**: кортеж имён файлов (cert, key) для клиентского сертификата.
+- **selector_config**: словарь настроек парсера для создания итогового объекта `Selector`/`Response`.
+
+!!! note "Примечания"
+
+ 1. Сейчас доступны следующие браузеры для имитации: `"edge"`, `"chrome"`, `"chrome_android"`, `"safari"`, `"safari_beta"`, `"safari_ios"`, `"safari_ios_beta"`, `"firefox"`, `"tor"`.<br/>
+ 2. Браузеры и их версии показываются в автодополнении аргументов и обновляются вместе с `curl_cffi`.<br/>
+ 3. Если включён `impersonate` или `stealthy_headers`, Fetcher автоматически создаёт заголовки настоящего браузера, соответствующие выбранной версии.
+
+Для более тонкой настройки можно передать любому методу дополнительные аргументы, которые поддерживает `curl_cffi` и которые ещё не обрабатывает сам метод.
+
+### Кодировка текста {#text-encoding}
+
+Если на странице не в UTF-8 текст отображается неправильно, передайте в запросе `default_encoding="shift_jis"` или нужную кодировку страницы. Это задаёт запасную кодировку на случай, если в `Content-Type` нет charset. Кодировка, указанная сервером, не переопределяется.
+
+Если сервер указал неверную кодировку, задайте правильную принудительно через `selector_config={"encoding": "shift_jis"}`.
+
+### HTTP-методы {#http-methods}
+У каждого метода есть свои дополнительные аргументы, например `params` для GET и `data`/`json` для POST/PUT/DELETE.
+
+Лучше всего это видно на примерах:
+
+> Методы `OPTIONS` и `HEAD` не поддерживаются.
+#### GET {#get}
+```python
+from scrapling.fetchers import Fetcher
+# Basic GET
+page = Fetcher.get('https://example.com')
+page = Fetcher.get('https://scrapling.requestcatcher.com/get', stealthy_headers=True)
+page = Fetcher.get('https://scrapling.requestcatcher.com/get', proxy='http://username:password@localhost:8030')
+# With parameters
+page = Fetcher.get('https://example.com/search', params={'q': 'query'})
+
+# With headers
+page = Fetcher.get('https://example.com', headers={'User-Agent': 'Custom/1.0'})
+# Basic HTTP authentication
+page = Fetcher.get("https://example.com", auth=("my_user", "password123"))
+# Browser impersonation
+page = Fetcher.get('https://example.com', impersonate='chrome')
+# HTTP/3 support
+page = Fetcher.get('https://example.com', http3=True)
+```
+Для асинхронных запросов достаточно небольшого изменения:
+```python
+from scrapling.fetchers import AsyncFetcher
+# Basic GET
+page = await AsyncFetcher.get('https://example.com')
+page = await AsyncFetcher.get('https://scrapling.requestcatcher.com/get', stealthy_headers=True)
+page = await AsyncFetcher.get('https://scrapling.requestcatcher.com/get', proxy='http://username:password@localhost:8030')
+# With parameters
+page = await AsyncFetcher.get('https://example.com/search', params={'q': 'query'})
+# With headers
+page = await AsyncFetcher.get('https://example.com', headers={'User-Agent': 'Custom/1.0'})
+# Basic HTTP authentication
+page = await AsyncFetcher.get("https://example.com", auth=("my_user", "password123"))
+# Browser impersonation
+page = await AsyncFetcher.get('https://example.com', impersonate='chrome110')
+# HTTP/3 support
+page = await AsyncFetcher.get('https://example.com', http3=True)
+```
+Во всех случаях `page` является объектом [Response](choosing.md#response-object), основанным на [Selector](../parsing/main_classes.md#selector). Его можно сразу использовать для разбора:
+```python
+page.css('.something.something')
+
+page = Fetcher.get('https://api.github.com/events')
+>>> page.json()
+[{'id': '<redacted>',
+ 'type': 'PushEvent',
+ 'actor': {'id': '<redacted>',
+ 'login': '<redacted>',
+ 'display_login': '<redacted>',
+ 'gravatar_id': '',
+ 'url': 'https://api.github.com/users/<redacted>',
+ 'avatar_url': 'https://avatars.githubusercontent.com/u/<redacted>'},
+ 'repo': {'id': '<redacted>',
+...
+```
+#### POST {#post}
+```python
+from scrapling.fetchers import Fetcher
+# Basic POST
+page = Fetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, params={'q': 'query'})
+page = Fetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, stealthy_headers=True)
+page = Fetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, proxy='http://username:password@localhost:8030', impersonate="chrome")
+# Another example of form-encoded data
+page = Fetcher.post('https://example.com/submit', data={'username': 'user', 'password': 'pass'}, http3=True)
+# JSON data
+page = Fetcher.post('https://example.com/api', json={'key': 'value'})
+```
+Для асинхронных запросов достаточно небольшого изменения:
+```python
+from scrapling.fetchers import AsyncFetcher
+# Basic POST
+page = await AsyncFetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'})
+page = await AsyncFetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, stealthy_headers=True)
+page = await AsyncFetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, proxy='http://username:password@localhost:8030', impersonate="chrome")
+# Another example of form-encoded data
+page = await AsyncFetcher.post('https://example.com/submit', data={'username': 'user', 'password': 'pass'}, http3=True)
+# JSON data
+page = await AsyncFetcher.post('https://example.com/api', json={'key': 'value'})
+```
+#### PUT {#put}
+```python
+from scrapling.fetchers import Fetcher
+# Basic PUT
+page = Fetcher.put('https://example.com/update', data={'status': 'updated'})
+page = Fetcher.put('https://example.com/update', data={'status': 'updated'}, stealthy_headers=True, impersonate="chrome")
+page = Fetcher.put('https://example.com/update', data={'status': 'updated'}, proxy='http://username:password@localhost:8030')
+# Another example of form-encoded data
+page = Fetcher.put("https://scrapling.requestcatcher.com/put", data={'key': ['value1', 'value2']})
+```
+Для асинхронных запросов достаточно небольшого изменения:
+```python
+from scrapling.fetchers import AsyncFetcher
+# Basic PUT
+page = await AsyncFetcher.put('https://example.com/update', data={'status': 'updated'})
+page = await AsyncFetcher.put('https://example.com/update', data={'status': 'updated'}, stealthy_headers=True, impersonate="chrome")
+page = await AsyncFetcher.put('https://example.com/update', data={'status': 'updated'}, proxy='http://username:password@localhost:8030')
+# Another example of form-encoded data
+page = await AsyncFetcher.put("https://scrapling.requestcatcher.com/put", data={'key': ['value1', 'value2']})
+```
+
+#### DELETE {#delete}
+```python
+from scrapling.fetchers import Fetcher
+page = Fetcher.delete('https://example.com/resource/123')
+page = Fetcher.delete('https://example.com/resource/123', stealthy_headers=True, impersonate="chrome")
+page = Fetcher.delete('https://example.com/resource/123', proxy='http://username:password@localhost:8030')
+```
+Для асинхронных запросов достаточно небольшого изменения:
+```python
+from scrapling.fetchers import AsyncFetcher
+page = await AsyncFetcher.delete('https://example.com/resource/123')
+page = await AsyncFetcher.delete('https://example.com/resource/123', stealthy_headers=True, impersonate="chrome")
+page = await AsyncFetcher.delete('https://example.com/resource/123', proxy='http://username:password@localhost:8030')
+```
+
+## Управление сессиями {#session-management}
+
+Для нескольких запросов с общими настройками используйте `FetcherSession`. Этот класс работает и в синхронном, и в асинхронном коде. Он сам определяет тип сессии, поэтому менять импорт не нужно.
+
+`FetcherSession` принимает почти все аргументы методов запросов. Можно задать настройки всей сессии, а затем легко изменить их для отдельного запроса, как в примерах ниже.
+
+```python
+from scrapling.fetchers import FetcherSession
+
+# Create a session with default configuration
+with FetcherSession(
+ impersonate='chrome',
+ http3=True,
+ stealthy_headers=True,
+ timeout=30,
+ retries=3
+) as session:
+ # Make multiple requests with the same settings and the same cookies
+ page1 = session.get('https://scrapling.requestcatcher.com/get')
+ page2 = session.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'})
+ page3 = session.get('https://api.github.com/events')
+
+ # All requests share the same session and connection pool
+```
+
+Для автоматической смены прокси между запросами используйте `ProxyRotator` вместе с `FetcherSession`:
+
+```python
+from scrapling.fetchers import FetcherSession, ProxyRotator
+
+rotator = ProxyRotator([
+ 'http://proxy1:8080',
+ 'http://proxy2:8080',
+ 'http://proxy3:8080',
+])
+
+with FetcherSession(proxy_rotator=rotator, impersonate='chrome') as session:
+ # Each request automatically uses the next proxy in rotation
+ page1 = session.get('https://example.com/page1')
+ page2 = session.get('https://example.com/page2')
+
+ # You can check which proxy was used via the response metadata
+ print(page1.meta['proxy'])
+```
+
+Для отдельного запроса можно переопределить прокси сессии или механизм его смены, передав `proxy=` прямо в метод запроса:
+
+```python
+with FetcherSession(proxy='http://default-proxy:8080') as session:
+ # Uses the session proxy
+ page1 = session.get('https://example.com/page1')
+
+ # Override the proxy for this specific request
+ page2 = session.get('https://example.com/page2', proxy='http://special-proxy:9090')
+```
+
+Пример для асинхронного кода:
+
+```python
+async with FetcherSession(impersonate='firefox', http3=True) as session:
+ # All standard HTTP methods available
+ response = await session.get('https://example.com')
+ response = await session.post('https://scrapling.requestcatcher.com/post', json={'data': 'value'})
+ response = await session.put('https://scrapling.requestcatcher.com/put', data={'update': 'info'})
+ response = await session.delete('https://scrapling.requestcatcher.com/delete')
+```
+Или более удобный вариант:
+```python
+import asyncio
+from scrapling.fetchers import FetcherSession
+
+# Async session usage
+async with FetcherSession(impersonate="safari") as session:
+ urls = ['https://example.com/page1', 'https://example.com/page2']
+
+ tasks = [
+ session.get(url) for url in urls
+ ]
+
+ pages = await asyncio.gather(*tasks)
+```
+
+Класс `Fetcher` использует `FetcherSession` для создания временной сессии при каждом запросе.
+
+### Преимущества сессий {#session-benefits}
+
+- **Выше скорость**: в 10 раз быстрее, чем создавать отдельную сессию для каждого запроса.
+- **Сохранение cookie**: автоматическая обработка cookie между запросами.
+- **Экономия ресурсов**: меньше затрат памяти и процессора при нескольких запросах.
+- **Общие настройки**: все настройки запросов в одном месте.
+
+## Примеры {#examples}
+Несколько полных примеров для тех, кто только начинает собирать данные с сайтов.
+
+### Простой HTTP-запрос {#basic-http-request}
+
+```python
+from scrapling.fetchers import Fetcher
+
+# Make a request
+page = Fetcher.get('https://example.com')
+
+# Check the status
+if page.status == 200:
+ # Extract title
+ title = page.css('title::text').get()
+ print(f"Page title: {title}")
+
+ # Extract all links
+ links = page.css('a::attr(href)').getall()
+ print(f"Found {len(links)} links")
+```
+
+### Сбор данных о товарах {#product-scraping}
+
+```python
+from scrapling.fetchers import Fetcher
+
+def scrape_products():
+ page = Fetcher.get('https://example.com/products')
+
+ # Find all product elements
+ products = page.css('.product')
+
+ results = []
+ for product in products:
+ results.append({
+ 'title': product.css('.title::text').get(),
+ 'price': product.css('.price::text').re_first(r'\d+\.\d{2}'),
+ 'description': product.css('.description::text').get(),
+ 'in_stock': product.has_class('in-stock')
+ })
+
+ return results
+```
+
+### Скачивание файлов {#downloading-files}
+
+```python
+from scrapling.fetchers import Fetcher
+
+page = Fetcher.get('https://raw.githubusercontent.com/D4Vinci/Scrapling/main/docs/assets/main_cover.png')
+with open(file='main_cover.png', mode='wb') as f:
+ f.write(page.body)
+```
+
+### Переход по страницам {#pagination-handling}
+
+```python
+from scrapling.fetchers import Fetcher
+
+def scrape_all_pages():
+ base_url = 'https://example.com/products?page={}'
+ page_num = 1
+ all_products = []
+
+ while True:
+ # Get current page
+ page = Fetcher.get(base_url.format(page_num))
+
+ # Find products
+ products = page.css('.product')
+ if not products:
+ break
+
+ # Process products
+ for product in products:
+ all_products.append({
+ 'name': product.css('.name::text').get(),
+ 'price': product.css('.price::text').get()
+ })
+
+ # Next page
+ page_num += 1
+
+ return all_products
+```
+
+### Отправка формы {#form-submission}
+
+```python
+from scrapling.fetchers import Fetcher
+
+# Submit login form
+response = Fetcher.post(
+ 'https://example.com/login',
+ data={
+ 'username': '[email protected]',
+ 'password': 'password123'
+ }
+)
+
+# Check login success
+if response.status == 200:
+ # Extract user info
+ user_name = response.css('.user-name::text').get()
+ print(f"Logged in as: {user_name}")
+```
+
+### Извлечение таблицы {#table-extraction}
+
+```python
+from scrapling.fetchers import Fetcher
+
+def extract_table():
+ page = Fetcher.get('https://example.com/data')
+
+ # Find table
+ table = page.css('table')[0]
+
+ # Extract headers
+ headers = [
+ th.text for th in table.css('thead th')
+ ]
+
+ # Extract rows
+ rows = []
+ for row in table.css('tbody tr'):
+ cells = [td.text for td in row.css('td')]
+ rows.append(dict(zip(headers, cells)))
+
+ return rows
+```
+
+### Меню навигации {#navigation-menu}
+
+```python
+from scrapling.fetchers import Fetcher
+
+def extract_menu():
+ page = Fetcher.get('https://example.com')
+
+ # Find navigation
+ nav = page.css('nav')[0]
+
+ menu = {}
+ for item in nav.css('li'):
+ links = item.css('a')
+ if links:
+ link = links[0]
+ menu[link.text] = {
+ 'url': link['href'],
+ 'has_submenu': bool(item.css('.submenu'))
+ }
+
+ return menu
+```
+
+## Когда использовать {#when-to-use}
+
+Используйте `Fetcher`, если:
+
+- Нужны быстрые HTTP-запросы.
+- Важны небольшие затраты ресурсов.
+- Не требуется выполнение JavaScript: данные можно получить обычными запросами.
+- Нужны некоторые средства скрытной работы. Например, на сайте есть защита, но нет проверок через JavaScript.
+
+Используйте `FetcherSession`, если:
+
+- Отправляете несколько запросов на один или разные сайты.
+- Нужно сохранять cookie и авторизацию между запросами.
+- Хотите повторно использовать соединения для повышения скорости.
+- Нужны одинаковые настройки для нескольких запросов.
+- Работаете с API, которое требует сохранения состояния сессии.
+
+Используйте другие Fetcher, если:
+
+- Нужна автоматизация браузера.
+- Нужны расширенные средства обхода защиты от ботов и скрытной работы.
+- Нужно выполнять JavaScript или взаимодействовать с динамическим содержимым.
diff --git a/docs/locales/ru/fetching/stealthy.md b/docs/locales/ru/fetching/stealthy.md
new file mode 100644
index 0000000..cc77f81
--- /dev/null
+++ b/docs/locales/ru/fetching/stealthy.md
@@ -0,0 +1,536 @@
+---
+title: "Сбор данных с JavaScript-сайтов через StealthyFetcher"
+description: "Загружайте страницы, ждите данные, повторно используйте состояние входа и читайте фоновые ответы API через браузерные сессии Scrapling. Настраивайте прокси и обработку проверок."
+---
+
+# Получение страниц через StealthyFetcher {#browser-fetching-with-stealthyfetcher}
+
+Класс `StealthyFetcher` загружает JavaScript-страницы и управляет Chromium или Google Chrome с функциями обхода защиты от ботов. Он использует [API Playwright](https://playwright.dev/python/docs/intro) с изменениями для скрытной работы.
+
+Для автоматизации страницы, которую мы рассмотрим позже, нужно немного знать [Page API Playwright](https://playwright.dev/python/docs/api/class-page).
+
+!!! success "Перед началом"
+
+ 1. Прочитайте [Основы работы с Fetcher](../fetching/choosing.md), чтобы понять, что такое [объект Response](../fetching/choosing.md#response-object) и какой Fetcher выбрать.
+ 2. Прочитайте [Поиск элементов](../parsing/selection.md), чтобы понять, как находить и извлекать элементы из [Selector](../parsing/main_classes.md#selector)/[Response](../fetching/choosing.md#response-object).
+ 3. Прочитайте [Основные классы](../parsing/main_classes.md), чтобы узнать, какие свойства и методы [Response](../fetching/choosing.md#response-object) наследует от [Selector](../parsing/main_classes.md#selector).
+
+## Основы использования {#basic-usage}
+Основной способ импорта этого Fetcher такой же, как и для остальных:
+
+```python
+from scrapling.fetchers import StealthyFetcher
+```
+О настройке парсера читайте [здесь](choosing.md#parser-configuration-in-all-fetchers).
+
+Теперь рассмотрим основные аргументы по отдельности на примерах. Для быстрой справки можно сразу перейти к [полной таблице аргументов](#full-list-of-arguments).
+
+!!! abstract "Кратко"
+
+ Асинхронная версия метода `fetch` называется `async_fetch`.
+
+
+Сейчас этот Fetcher предоставляет три основных варианта запуска, которые можно сочетать по необходимости.
+
+Вот эти варианты:
+
+### 1. Chromium из комплекта {#1-bundled-chromium}
+```python
+StealthyFetcher.fetch('https://example.com')
+```
+Этот вариант открывает поставляемый с библиотекой Chromium с настройками скрытной работы по умолчанию и загружает страницу.
+
+### 2. Установленный Chrome {#2-real-chrome}
+```python
+StealthyFetcher.fetch('https://example.com', real_chrome=True)
+```
+Если у вас установлен Google Chrome, используйте этот вариант. Он работает как первый, но запускает ваш Google Chrome вместо Chromium. Запросы больше похожи на обычные действия браузера и менее заметны для защиты.
+
+Если Google Chrome ещё не установлен, его можно установить для библиотеки следующей командой в терминале вместо ручной установки:
+```commandline
+playwright install chrome
+```
+
+### 3. Подключение по CDP {#3-cdp-connection}
+```python
+StealthyFetcher.fetch('https://example.com', cdp_url='ws://localhost:9222')
+```
+Вместо локального запуска Chromium или Google Chrome можно подключиться к удалённому браузеру через [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
+
+URL может быть адресом WebSocket (`ws://`/`wss://`), который выдают браузерные сервисы, или HTTP-адресом браузера, например `http://localhost:9222`.
+
+
+## Что он умеет? {#what-does-it-do}
+
+StealthyFetcher предоставляет следующие средства обхода защиты от ботов:
+
+1. Автоматически проходит все виды Cloudflare Turnstile/Interstitial при `solve_cloudflare=True`.
+2. Предотвращает утечки через CDP Runtime и WebRTC.
+3. Изолирует выполнение JavaScript, убирает многие признаки Playwright и предотвращает обнаружение по известным особенностям поведения ботов.
+4. Добавляет шум в Canvas, чтобы помешать получению отпечатка через него.
+5. Автоматически противодействует известным способам обнаружения режима без окна и предлагает настройку для защиты от проверок несовпадения часовых поясов.
+6. Предоставляет и другие возможности обхода защиты.
+
+## Все аргументы {#full-list-of-arguments}
+У этого Fetcher и его классов сессий много настроек. Перед переходом к [примерам](#examples) приведём полный список аргументов.
+
+
+| Аргумент | Описание | Необязательный |
+|:---------------------:|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|
+| url | URL назначения. | ❌ |
+| headless | Передайте `True` для работы браузера без видимого окна (**по умолчанию**) или `False`, чтобы показывать окно. | ✔️ |
+| disable_resources | Пропускает запросы ненужных ресурсов для ускорения работы. Пропускаются типы `font`, `image`, `media`, `beacon`, `object`, `imageset`, `texttrack`, `websocket`, `csp_report` и `stylesheet`. | ✔️ |
+| cookies | Cookie для следующего запроса. | ✔️ |
+| useragent | Строка User-Agent. **Если не указана, Fetcher создаёт и использует User-Agent настоящего браузера того же вида и версии.** | ✔️ |
+| network_idle | Ждёт, пока на странице не будет сетевых соединений хотя бы 500 мс. | ✔️ |
+| load_dom | По умолчанию включено. Ждёт загрузки и выполнения всего JavaScript на странице, то есть состояния `domcontentloaded`. | ✔️ |
+| pierce_shadow | Включает содержимое открытых Shadow DOM в HTML ответа. По умолчанию `False`. Можно задать для сессии и переопределить для отдельного запроса. | ✔️ |
+| timeout | Тайм-аут в миллисекундах для всех операций и ожиданий на странице. По умолчанию 30 000 мс (30 секунд). | ✔️ |
+| wait | Время в миллисекундах, которое Fetcher ждёт после всех операций, прежде чем закрыть страницу и вернуть объект `Response`. | ✔️ |
+| page_action | Функция автоматизации. Принимает объект `page` и выполняет нужные действия после перехода на страницу. | ✔️ |
+| page_setup | Функция, которая принимает `page` и выполняется до перехода на страницу. Используйте её для регистрации обработчиков событий или маршрутов до загрузки страницы. | ✔️ |
+| wait_selector | Ждёт, пока элемент по CSS-селектору достигнет указанного состояния. | ✔️ |
+| init_script | Абсолютный путь к JavaScript-файлу, который запускается при создании каждой страницы в этой сессии. | ✔️ |
+| wait_selector_state | Состояние, которого Scrapling ждёт для селектора из `wait_selector`. _По умолчанию `attached`._ | ✔️ |
+| google_search | По умолчанию включено. Scrapling устанавливает заголовок Referer для Google. | ✔️ |
+| extra_headers | Словарь дополнительных заголовков запроса. _При совместном использовании Referer от `google_search` имеет приоритет над Referer из этого словаря._ | ✔️ |
+| proxy | Прокси для запросов. Строка или словарь только с ключами 'server', 'username' и 'password'. | ✔️ |
+| real_chrome | Если на устройстве установлен Chrome, включите эту настройку, и Fetcher запустит ваш браузер. | ✔️ |
+| locale | Локаль, например `en-GB` или `de-DE`. Влияет на `navigator.language`, заголовок запроса `Accept-Language`, а также формат чисел и дат. По умолчанию используется системная локаль. | ✔️ |
+| timezone_id | Меняет часовой пояс браузера. По умолчанию используется системный часовой пояс. | ✔️ |
+| cdp_url | Подключается к браузеру по этому CDP URL вместо запуска нового экземпляра. | ✔️ |
+| user_data_dir | Путь к каталогу пользовательских данных браузера, например cookie и local storage. По умолчанию создаётся временный каталог. **Работает только с сессиями.** | ✔️ |
+| extra_flags | Список дополнительных флагов, передаваемых браузеру при запуске. | ✔️ |
+| solve_cloudflare | При включении Fetcher проходит все виды Cloudflare Turnstile/Interstitial перед возвратом ответа. По умолчанию `False`. | ✔️ |
+| block_webrtc | Заставляет WebRTC учитывать настройки прокси, чтобы избежать утечки локального IP-адреса. | ✔️ |
+| hide_canvas | Добавляет случайный шум к операциям Canvas, чтобы помешать получению отпечатка. | ✔️ |
+| allow_webgl | По умолчанию включено. Отключение полностью убирает поддержку WebGL и WebGL 2.0. Отключать не рекомендуется, так как многие WAF проверяют наличие WebGL. | ✔️ |
+| additional_args | Дополнительные настройки контекста Playwright. Имеют приоритет над настройками Scrapling. | ✔️ |
+| selector_config | Словарь настроек парсера для создания итогового объекта `Selector`/`Response`. | ✔️ |
+| blocked_domains | Множество доменов, запросы к которым нужно блокировать. Поддомены тоже учитываются: `"example.com"` блокирует и `"sub.example.com"`. | ✔️ |
+| block_ads | Блокирует запросы примерно к 3 500 известным рекламным и отслеживающим доменам. Можно использовать вместе с `blocked_domains`. | ✔️ |
+| dns_over_https | Направляет DNS-запросы через Cloudflare DNS-over-HTTPS, чтобы избежать утечек DNS при использовании прокси. | ✔️ |
+| proxy_rotator | Экземпляр `ProxyRotator` для автоматической смены прокси. Нельзя использовать вместе с `proxy`. | ✔️ |
+| retries | Число повторных попыток при ошибке запроса. По умолчанию 3. | ✔️ |
+| retry_delay | Пауза между повторными попытками в секундах. По умолчанию 1. | ✔️ |
+| record_requests | Сохраняет завершённые запросы и ответы в `session.network`. Только для сессий, по умолчанию `False`. | ✔️ |
+| max_recorded_requests | Максимальное число сохранённых запросов в сессии. По умолчанию 1 000. Для сохранённых тел ответов также есть фиксированные ограничения размера. | ✔️ |
+| executable_path | Абсолютный путь к своему исполняемому файлу браузера вместо Chromium из комплекта. Полезно для нестандартной установки или собственной сборки браузера. | ✔️ |
+
+В классах сессий все эти аргументы можно задать для всей сессии. Некоторые настройки уровня вкладки можно также передавать отдельно в каждом запросе: `google_search`, `timeout`, `wait`, `page_action`, `page_setup`, `extra_headers`, `disable_resources`, `wait_selector`, `wait_selector_state`, `network_idle`, `load_dom`, `pierce_shadow`, `solve_cloudflare`, `blocked_domains`, `proxy` и `selector_config`.
+
+!!! note "Примечания"
+
+ 1. В моих тестах `disable_resources` ускорял запросы примерно на 25% для некоторых сайтов. Он также помогает сократить трафик через прокси. Но будьте осторожны: некоторые сайты с этой настройкой могут так и не завершить загрузку.
+ 2. Аргумент `google_search` включён по умолчанию для всех запросов и задаёт Referer `https://www.google.com/`. При использовании с `extra_headers` он имеет приоритет над Referer из этого словаря.
+ 3. Если User-Agent не задан, а режим без окна включён, Fetcher создаст User-Agent настоящего браузера той же версии. Если User-Agent не задан и режим без окна не включён, используется стандартный User-Agent браузера. В последних версиях он совпадает с обычными браузерами.
+ 4. `init_script` регистрируется в контексте браузера и выполняется при создании страниц. Режим скрытной работы по умолчанию использует изолированный контекст выполнения Patchright. Если `page_action` должен читать глобальные переменные, которые скрипт добавил в `window`, вызывайте внутри него `page.evaluate(..., isolated_context=False)`.
+
+## Управление сессиями {#session-management}
+
+Чтобы держать браузер открытым для нескольких запросов с общими настройками, используйте `StealthySession`/`AsyncStealthySession`. Эти классы принимают все аргументы функции `fetch`, поэтому можно настроить всю сессию сразу.
+
+```python
+from scrapling.fetchers import StealthySession
+
+
+with StealthySession(
+ headless=True,
+ disable_resources=True,
+ real_chrome=True
+) as session:
+
+ page1 = session.fetch('https://example1.com')
+ page2 = session.fetch('https://example2.com')
+ page3 = session.fetch('https://dynamic-site.com')
+
+
+```
+
+### Асинхронные сессии {#async-session-usage}
+
+```python
+import asyncio
+from scrapling.fetchers import AsyncStealthySession
+
+async def scrape_multiple_sites():
+ async with AsyncStealthySession(
+ network_idle=True,
+ timeout=30000,
+ max_pages=3
+ ) as session:
+
+ pages = await asyncio.gather(
+ session.fetch('https://spa-app1.com'),
+ session.fetch('https://spa-app2.com'),
+ session.fetch('https://dynamic-content.com')
+ )
+ return pages
+```
+
+Аргумент `max_pages` задаёт максимальный размер **пула вкладок браузера**, то есть число вкладок, которые могут быть открыты одновременно. После запроса вкладки остаются открытыми. Для каждого следующего запроса библиотека выполняет такие действия:
+
+1. Повторно использует свободную вкладку, если она есть. Запрос применяет свои настройки уровня вкладки (`timeout`, `extra_headers`, `disable_resources`, `blocked_domains` и другие), поэтому настройки предыдущего запроса не сохраняются.
+2. Если свободных вкладок нет, а их число меньше `max_pages`, открывает новую.
+3. Иначе проверяет наличие свободной вкладки чаще одного раза в секунду в течение 60 секунд, а затем вызывает `TimeoutError`. Это может произойти, если сайт перестал отвечать.
+
+Вкладки с ошибками закрываются и заменяются. В любой момент можно закрыть все открытые вкладки через `session.close_pages()`. Следующий запрос откроет новую.
+
+Так можно получать несколько URL одновременно в одном браузере. Это заметно экономит ресурсы и, что особенно приятно, работает быстро :)
+
+Открытая вкладка сохраняет загруженную страницу до следующего запроса. Его функция `page_setup` запускается на этой странице до перехода по новому адресу. Это позволяет связывать автоматические действия между запросами.
+
+В версиях с 0.3.2 по 0.4.14 каждая вкладка закрывалась после запроса, потому что при повторном использовании сохранялись старые настройки. Начиная с 0.4.15, настройки сбрасываются при каждом использовании, поэтому вкладки остаются открытыми.
+
+### Сохранение и загрузка состояния сессии {#save-and-load-session-state}
+
+Метод `save_state(path)` сохраняет cookie, local storage и IndexedDB в JSON-файл. Метод `load_state(path)` восстанавливает их в другой сессии или заменяет сохранённое состояние текущей сессии. Оба принимают строку или `pathlib.Path` и возвращают `None`. Формат совместим с файлами состояния хранилища Playwright.
+
+```python
+from scrapling.fetchers import StealthySession
+
+with StealthySession() as session:
+ session.fetch('https://example.com')
+ session.save_state('state.json')
+
+with StealthySession() as session:
+ session.load_state('state.json')
+ page = session.fetch('https://example.com')
+```
+
+Сохраняйте состояние после входа или завершения других действий браузера. Оба метода вызывайте внутри запущенной сессии, когда все текущие запросы завершены. Загрузка заменяет существующие cookie, local storage и IndexedDB. Чтобы использовать восстановленный вход, получите или перезагрузите страницу. Сама загрузка состояния не меняет адрес открытых вкладок.
+
+С `AsyncStealthySession` используйте `await`:
+
+```python
+from scrapling.fetchers import AsyncStealthySession
+
+async def restore_session():
+ async with AsyncStealthySession() as session:
+ await session.load_state('state.json')
+ page = await session.fetch('https://example.com')
+ await session.save_state('state.json')
+ return page
+```
+
+Эти методы сохраняют и восстанавливают только общий контекст браузера. Они не затрагивают временные контексты для прокси отдельных запросов. У сессий с `proxy_rotator` нет общего контекста, поэтому методы вызывают `RuntimeError`. Фиксированный `proxy` сессии работает как обычно.
+
+Файл не содержит `sessionStorage`, открытые вкладки или настройки браузера. Сохранение перезаписывает файл, а его родительский каталог должен уже существовать. Ошибки файла и JSON передаются вызывающему коду.
+
+### Преимущества сессий {#session-benefits}
+
+- **Повторное использование браузера**: следующие запросы намного быстрее, потому что используется тот же экземпляр браузера.
+- **Сохранение cookie**: автоматическая работа с cookie и состоянием сессии, как в обычном браузере.
+- **Постоянный отпечаток**: один и тот же отпечаток браузера для всех запросов.
+- **Экономия памяти**: меньше затрат ресурсов, чем при запуске нового браузера для каждого запроса.
+
+
+## Примеры {#examples}
+На примерах разобраться проще, поэтому перейдём к ним.
+
+### Управление ресурсами {#resource-control}
+
+```python
+
+page = StealthyFetcher.fetch('https://example.com', disable_resources=True)
+```
+
+### Shadow DOM {#shadow-dom}
+
+Некоторые страницы хранят содержимое в открытых корнях Shadow DOM. Оно не входит в обычный HTML страницы. Включите `pierce_shadow`, чтобы добавить его в ответ, а затем используйте CSS- и XPath-селекторы как обычно:
+
+```python
+from scrapling.fetchers import StealthyFetcher
+
+page = StealthyFetcher.fetch('https://example.com', pierce_shadow=True)
+titles = page.css('product-card .title::text').getall()
+```
+
+По умолчанию установлено `False`. Можно включить настройку для всей сессии и отключить для отдельного запроса:
+
+```python
+from scrapling.fetchers import StealthySession
+
+with StealthySession(pierce_shadow=True) as session:
+ page = session.fetch('https://example.com')
+ plain_page = session.fetch('https://example.com', pierce_shadow=False)
+```
+
+Эта настройка также работает с `async_fetch` и асинхронными сессиями.
+
+Включаются только корни Shadow DOM в открытом режиме. Закрытые корни и документы iframe не обходятся. Если компонент загружается позже самой страницы, используйте `wait_selector`.
+
+Каждый открытый корень превращается в обёртку `<shadow-root>` в ответе. Слоты сохраняют свои теги и атрибуты и содержат назначенные им узлы либо запасное содержимое, если ничего не назначено. Неназначенные дочерние элементы Light DOM пропускаются. Живая страница в браузере не меняется.
+
+```html
+<product-card>
+ <shadow-root>
+ <div class="title">Product name</div>
+ <slot name="price"><span class="price">20</span></slot>
+ </shadow-root>
+</product-card>
+```
+
+Селекторы потомков работают через эти элементы. Селекторы прямых дочерних элементов должны учитывать обёртки и слоты:
+
+```python
+titles = page.css('product-card .title::text').getall()
+titles = page.css('product-card > shadow-root > .title::text').getall()
+prices = page.css('product-card > shadow-root > slot[name="price"] > .price::text').getall()
+```
+
+Обёртки и слоты появляются в XPath-путях, `.children`, `response.body` и HTML-экспорте. Извлечение Markdown и текста возвращает их содержимое без тегов. Атрибуты скрытых слотов сохраняются и доступны при очистке содержимого.
+
+Снимок сохраняет порядок содержимого, но не рассчитывает видимость по CSS или расположение элементов. Селекторы с `<shadow-root>` относятся к ответу Scrapling, а не к странице в браузере. Другие HTML-парсеры могут иначе обрабатывать необычную вложенность.
+
+### Блокировка доменов {#domain-blocking}
+
+```python
+
+page = StealthyFetcher.fetch('https://example.com', blocked_domains={"ads.example.com", "tracker.net"})
+```
+
+### Управление сетью {#network-control}
+
+```python
+
+page = StealthyFetcher.fetch('https://example.com', network_idle=True)
+
+
+page = StealthyFetcher.fetch('https://example.com', timeout=30000)
+
+
+page = StealthyFetcher.fetch('https://example.com', proxy='http://username:password@host:port')
+```
+
+### Скачивание файлов {#downloading-files}
+
+```python
+page = StealthyFetcher.fetch('https://raw.githubusercontent.com/D4Vinci/Scrapling/main/docs/assets/main_cover.png')
+
+with open(file='main_cover.png', mode='wb') as f:
+ f.write(page.body)
+```
+
+Атрибут `body` объекта `Response` всегда возвращает `bytes`.
+
+### Подготовка до перехода на страницу {#pre-navigation-setup}
+Если обработчики событий, маршруты или скрипты нужно зарегистрировать до перехода на страницу, используйте `page_setup`. Функция получает объект `page` и выполняется до вызова `page.goto()`.
+
+```python
+from patchright.sync_api import Page
+
+def capture_websockets(page: Page):
+ page.on("websocket", lambda ws: print(f"WebSocket opened: {ws.url}"))
+
+page = StealthyFetcher.fetch('https://example.com', page_setup=capture_websockets)
+```
+Асинхронная версия:
+```python
+from patchright.async_api import Page
+
+async def capture_websockets(page: Page):
+ page.on("websocket", lambda ws: print(f"WebSocket opened: {ws.url}"))
+
+page = await StealthyFetcher.async_fetch('https://example.com', page_setup=capture_websockets)
+```
+
+Можно сочетать её с `page_action`: `page_setup` выполняется до перехода, а `page_action` после него.
+
+### Cloudflare и скрытная работа {#cloudflare-and-stealth-options}
+
+```python
+
+page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare', solve_cloudflare=True)
+
+
+page = StealthyFetcher.fetch(
+ 'https://protected-site.com',
+ solve_cloudflare=True,
+ block_webrtc=True,
+ real_chrome=True,
+ hide_canvas=True,
+ google_search=True,
+ proxy='http://username:password@host:port', # It can also be a dictionary with only the keys 'server', 'username', and 'password'.
+)
+```
+
+Параметр `solve_cloudflare` включает автоматическое обнаружение и прохождение всех видов проверок Cloudflare Turnstile/Interstitial:
+
+- Проверки JavaScript (managed).
+- Интерактивные проверки с нажатием на поле подтверждения.
+- Невидимые проверки, выполняемые автоматически в фоне.
+
+Он также проходит проверки на нестандартных страницах со встроенной CAPTCHA.
+
+!!! notes "**Важные примечания**"
+
+ 1. На сайтах с собственной реализацией защиты иногда нужен `wait_selector`, чтобы дождаться настоящего содержимого сайта после прохождения CAPTCHA. Мы стараемся сделать обработчик универсальным, но встречаются очень необычные случаи.
+ 2. При использовании обработчика Cloudflare тайм-аут должен быть не меньше 60 секунд, чтобы дать достаточно времени на проверку.
+ 3. Эта возможность работает вместе с прокси и другими настройками скрытной работы.
+
+### Автоматизация браузера {#browser-automation}
+Здесь пригодятся знания [Page API Playwright](https://playwright.dev/python/docs/api/class-page). Переданная функция получает объект страницы Playwright и выполняет нужные действия, после чего Fetcher продолжает работу.
+
+Функция запускается сразу после ожидания `network_idle`, если оно включено, и до ожидания `wait_selector`. Поэтому её можно использовать не только для автоматизации, но и для любых нужных изменений страницы.
+
+В следующем примере я использую [события мыши](https://playwright.dev/python/docs/api/class-mouse), чтобы прокрутить страницу колёсиком, а затем переместить мышь:
+```python
+from patchright.sync_api import Page
+
+def scroll_page(page: Page):
+ page.mouse.wheel(10, 0)
+ page.mouse.move(100, 400)
+ page.mouse.up()
+
+page = StealthyFetcher.fetch('https://example.com', page_action=scroll_page)
+```
+Если используется асинхронный метод получения страницы, функция тоже должна быть асинхронной.
+```python
+from patchright.async_api import Page
+
+async def scroll_page(page: Page):
+ await page.mouse.wheel(10, 0)
+ await page.mouse.move(100, 400)
+ await page.mouse.up()
+
+page = await StealthyFetcher.async_fetch('https://example.com', page_action=scroll_page)
+```
+
+### Условия ожидания {#wait-conditions}
+
+```python
+
+page = StealthyFetcher.fetch(
+ 'https://quotes.toscrape.com/js-delayed/',
+ wait_selector='.quote',
+ wait_selector_state='visible'
+)
+```
+Если эта настройка включена, Fetcher ждёт указанное условие перед возвратом ответа. Передайте CSS-селектор в `wait_selector`, и Fetcher дождётся состояния из `wait_selector_state`. По умолчанию используется `attached`: ожидание появления элемента в DOM.
+
+Затем, если `load_dom` включён (по умолчанию), Fetcher ещё раз проверяет завершение загрузки и выполнения JavaScript, то есть состояние `domcontentloaded`, и при необходимости продолжает ждать. Если включён `network_idle`, он снова ждёт выполнения условия `network_idle`, как описано выше.
+
+Можно ждать следующие состояния ([источник](https://playwright.dev/python/docs/api/class-page#page-wait-for-selector)):
+
+- `attached`: элемент присутствует в DOM.
+- `detached`: элемент отсутствует в DOM.
+- `visible`: у элемента непустая ограничивающая рамка и нет `visibility:hidden`. Элемент без содержимого или с `display:none` имеет пустую рамку и не считается видимым.
+- `hidden`: элемент удалён из DOM, имеет пустую ограничивающую рамку или `visibility:hidden`. Это противоположность `'visible'`.
+
+### История сети {#network-history}
+
+Включите `record_requests` в браузерной сессии, чтобы просматривать завершённые запросы при загрузке страниц, выполнении действий и работе с разными вкладками. История охватывает контексты сессии, включая временные контексты прокси, и сохраняет ответы как объекты Scrapling `Response`. Можно найти вызовы API, HTTP-ошибки и перенаправления без повторной отправки запросов. Сохранённые заголовки и тела доступны даже после закрытия сессии. Неудачные и незавершённые запросы пропускаются, но завершённые HTTP-ответы 4xx и 5xx включаются.
+
+```python
+from scrapling.fetchers import StealthySession
+
+with StealthySession(record_requests=True, max_recorded_requests=1000) as session:
+ session.fetch('https://example.com', network_idle=True)
+
+for response in session.network.search(resource_type='document', limit=None):
+ print(response.meta['network_id'], response.url, response.status)
+ if note := response.meta.get('body_note'):
+ print(note)
+ else:
+ print(response.body)
+ print(response.css('title::text').get())
+
+session.network.clear()
+```
+
+Этот API работает и с `AsyncStealthySession`. По умолчанию запись выключена. При создании сессии задайте `record_requests=True` и при необходимости `max_recorded_requests`.
+
+- `session.network.search(url_pattern=None, method=None, resource_type=None, status=None, after_id=0, limit=100, include_static=True)` возвращает сохранённые объекты `Response` в порядке сетевых ID. `limit=None` возвращает все сохранённые совпадения. `url_pattern` задаёт регулярное выражение, применяемое при поиске. Неверный шаблон вызывает ошибку именно в этот момент. `after_id` выбирает ответы с большим сетевым ID. `include_static=False` оставляет только XHR/fetch-запросы и HTTP-ошибки. Используйте `True`, чтобы включить все типы ресурсов и сохранённые перенаправления.
+- `session.network.get(request_id)` возвращает один сохранённый `Response` или `None`, если он больше не хранится.
+- `session.network.clear()` очищает историю. ID запросов продолжают увеличиваться и не используются повторно.
+
+Каждый сохранённый `Response` предоставляет `.url`, `.method`, `.status`, `.headers`, `.request_headers`, байты `.body`, `.json()` и методы CSS/XPath напрямую. В `.meta` находятся `network_id`, `resource_type` и `request_body` (байты или `None`). Заголовки могут быть неполными, если чтение полного набора не удалось. Это локальные операции даже в асинхронных сессиях: не используйте для них await и не вызывайте `.body()`. Если сохранённое содержимое нельзя разобрать, его байты остаются, но методы CSS/XPath работают с пустым документом.
+
+Для поиска API-трафика по URL используйте `session.network.search(url_pattern=r'https://api\.example\.com/.*', limit=None)`. Если нужен определённый тип запроса, добавьте `resource_type='fetch'` или `resource_type='xhr'`.
+
+Записываются только тела с поддерживаемыми текстовыми значениями `Content-Type`: `text/*`, типы `+json`/`+xml` (включая SVG), JSON, XML, JavaScript, GraphQL и данные формы в URL-кодировке. Для двоичных и неизвестных типов, а также ответов без `Content-Type`, сохраняются метаданные, но не байты тела. Браузер продолжает загружать ресурсы как обычно.
+
+Сохранённые байты ответа получены от Playwright и могут отличаться от исходных байтов сервера. Если они являются корректным UTF-8, текст декодируется как UTF-8, как в Playwright. В противном случае используется объявленная кодировка. Заголовки ответа не меняются.
+
+Для пропущенных, слишком больших или нечитаемых тел возвращается `b''`, а причина указана в `response.meta.get('body_note')`. Для нетекстовых тел используется `Non-text body; not saved.`. Метаданные и доступные заголовки сохраняются. У сохранённого текста, включая пустой, примечания нет. Ответы HEAD и статусы 204, 205 и 304 остаются пустыми без примечания.
+
+Методы истории `search`, `get` и `clear` всегда локальные и синхронные, даже в асинхронной сессии. Запись появляется после преобразования и сохранения ответа. События браузера обрабатываются, пока активен Playwright. Для асинхронной записи также должен работать цикл событий. Чтение истории не ждёт завершения записи.
+
+Закрытие сессии тоже не ждёт завершения записи. Ответы, которые ещё записывались при переходе на другую страницу или закрытии контекста, могут быть пропущены. Уже сохранённые ответы доступны и после закрытия.
+
+По умолчанию история хранит до 1 000 запросов. Размер каждого сохранённого тела ограничен 1 MiB, а общий размер тел ограничен 20 MiB. При достижении лимитов старые записи удаляются. Ограничения размера тел фиксированы и не меняются настройками сессии. Они относятся к сохранённым записям и байтам ответов, но не к общей памяти браузера, одновременным записям, временному чтению полного тела, разобранному HTML или телам запросов.
+
+#### Переход на v5 {#migrating-in-v5}
+
+В v5 удалены `capture_xhr` и `response.captured_xhr`. Создайте браузерную сессию с `record_requests=True`, затем читайте `session.network.search(url_pattern=..., limit=None)`. Этот способ также заменяет запись API через одноразовые Fetcher, поэтому сохраняйте экземпляр сессии. Фильтры применяются к сохранённой истории всей сессии, а не во время записи или только к одному получению страницы. Сохраняются только поддерживаемые текстовые тела ответов. `search()` по умолчанию возвращает не больше 100 совпадений. `limit=None` возвращает все сохранённые совпадения, не меняя лимиты хранения истории.
+
+### Заголовки и локаль браузера {#browser-headers-and-locale}
+
+```python
+page = StealthyFetcher.fetch(
+ 'https://example.com',
+ google_search=True,
+ useragent='Mozilla/5.0...',
+ locale='en-US',
+)
+```
+
+### Полный пример {#general-example}
+```python
+from scrapling.fetchers import StealthyFetcher
+
+def scrape_dynamic_content():
+
+ page = StealthyFetcher.fetch(
+ 'https://example.com/dynamic',
+ network_idle=True,
+ wait_selector='.content'
+ )
+
+
+ content = page.css('.content')
+
+ return {
+ 'title': content.css('h1::text').get(),
+ 'items': [
+ item.text for item in content.css('.item')
+ ]
+ }
+```
+
+### Смена прокси {#proxy-rotation}
+
+```python
+from scrapling.fetchers import StealthySession, ProxyRotator
+
+
+rotator = ProxyRotator([
+ "http://proxy1:8080",
+ "http://proxy2:8080",
+ "http://proxy3:8080",
+])
+
+
+with StealthySession(proxy_rotator=rotator, headless=True) as session:
+ page1 = session.fetch('https://example1.com')
+ page2 = session.fetch('https://example2.com')
+
+
+ page3 = session.fetch('https://example3.com', proxy='http://specific-proxy:8080')
+```
+
+!!! warning "Внимание"
+
+ По умолчанию все браузерные Fetcher и сессии используют постоянный контекст браузера с пулом вкладок. Но браузеры не позволяют задать прокси для отдельной вкладки. Поэтому при использовании `ProxyRotator` Fetcher создаёт отдельный контекст для каждого прокси, с одной вкладкой в каждом. Когда вкладка завершает работу, закрываются и она, и её контекст.
+
+## Когда использовать {#when-to-use}
+
+Используйте StealthyFetcher, если:
+
+- Нужно обходить защиту от ботов.
+- Нужен надёжный отпечаток браузера.
+- Требуется полная поддержка JavaScript.
+- Нужны автоматические функции скрытной работы.
+- Нужна автоматизация браузера.
+- Нужно работать с защитой Cloudflare.
diff --git a/docs/locales/ru/index.md b/docs/locales/ru/index.md
new file mode 100644
index 0000000..e461b24
--- /dev/null
+++ b/docs/locales/ru/index.md
@@ -0,0 +1,243 @@
+---
+title: "Scrapling: фреймворк для веб-скрапинга на Python"
+description: "Scrapling: простой веб-скрапинг для современного интернета!"
+---
+
+<style>
+.md-typeset h1 {
+ display: none;
+}
+[data-md-color-scheme="default"] .only-dark { display: none; }
+[data-md-color-scheme="slate"] .only-light { display: none; }
+</style>
+
+<br/>
+<div align="center">
+ <a href="index.html" alt="Обложка">
+ <img alt="Scrapling" src="assets/cover_light.svg" class="only-light">
+ <img alt="Scrapling" src="assets/cover_dark.svg" class="only-dark">
+ </a>
+</div>
+
+<h2 align="center"><i>Простой веб-скрапинг для современного интернета</i></h2><br>
+
+Scrapling объединяет быстрые HTTP-запросы, скрытные браузеры, мощный разбор страниц и параллельный обход сайтов в одной библиотеке Python.
+
+Загружайте статические страницы, выполняйте JavaScript, работайте с сайтами и извлекайте данные из API этих сайтов. Создавайте краулеры с повторным использованием сессий, сменой прокси, автоматическими повторами, паузой и продолжением работы, а также готовым экспортом данных.
+
+Используйте Scrapling из Python, терминала или AI-агента через MCP-сервер и Agent Skill. Библиотека помогает на всех этапах: от извлечения нескольких полей до сохранения целого сайта в виде чистых Markdown-файлов.
+
+## Что можно сделать со Scrapling {#what-you-can-do-with-scrapling}
+
+- **[Загрузка и работа с сайтами](fetching/choosing.md)**: быстрые HTTP-запросы, скрытные браузеры, выполнение JavaScript, прохождение Cloudflare Turnstile и Interstitial, постоянные сессии и запись фоновых API-ответов.
+- **[Разбор и извлечение данных](parsing/selection.md)**: CSS, XPath, поиск по тексту и регулярным выражениям, поиск элементов после изменений страницы, поиск похожих элементов и чистый Markdown.
+- **[Обход и экспорт](spiders/getting-started.md)**: параллельные Spider, смена прокси, повторы, AutoThrottle, пауза и продолжение, потоковая выдача, готовые шаблоны и экспорт в JSON, JSONL, CSV и XML.
+- **[Сбор данных с AI или из терминала](ai/mcp-server.md)**: MCP-сервер для работы AI-агентов с сайтами и данными, Agent Skill, команды CLI и интерактивная оболочка.
+
+Начните с одной страницы:
+
+```python
+from scrapling.fetchers import Fetcher
+
+page = Fetcher.get('https://quotes.toscrape.com/')
+quotes = page.css('.quote .text::text').getall()
+print(quotes)
+```
+
+Или используйте Spider для обхода многих страниц:
+
+```python
+from scrapling.spiders import Spider, Response
+
+class QuotesSpider(Spider):
+ name = "quotes"
+ start_urls = ["https://quotes.toscrape.com/"]
+
+ async def parse(self, response: Response):
+ for quote in response.css('.quote'):
+ yield {
+ "text": quote.css('.text::text').get(),
+ "author": quote.css('.author::text').get(),
+ }
+
+result = QuotesSpider().start()
+print(len(result.items))
+result.items.to_json("quotes.json")
+```
+
+Код выведет `10` и сохранит цитаты с авторами в `quotes.json`.
+
+## Главные спонсоры {#top-sponsors}
+
+--8<-- "sponsors.html"
+
+<i><sub>Хотите разместить здесь рекламу? Выберите план [здесь](https://github.com/sponsors/D4Vinci) и получите все его преимущества!</sub></i>
+
+## Основные возможности {#key-features}
+
+### Spider: всё для обхода сайтов {#spiders-a-full-crawling-framework}
+- 🕷️ **API Spider в стиле Scrapy**: задайте `start_urls`, асинхронные обработчики `parse` и объекты `Request`/`Response`.
+- ⚡ **Параллельный обход**: настройте число одновременных запросов, ограничения для каждого домена и задержки между загрузками.
+- 🔄 **Несколько сессий**: используйте HTTP-запросы и скрытные браузеры без окна в одном Spider. Выбирайте сессию для запроса по её ID.
+- 💾 **Пауза и продолжение**: сохраняйте ожидающие запросы и посещённые URL с помощью `crawldir`. Нажмите Ctrl+C для корректной остановки, затем запустите Spider с той же папкой.
+- 📡 **Потоковая выдача**: получайте данные сразу после извлечения через `async for item in spider.stream()` и следите за статистикой в реальном времени. Удобно для интерфейсов, обработки данных и долгих обходов.
+- 🛡️ **Обнаружение блокировок**: заблокированные запросы автоматически обнаруживаются и повторяются. Логику можно настроить.
+- 🚦 **AutoThrottle**: больше не нужно угадывать задержки. Spider сам меняет задержку для каждого домена по скорости ответа сайта. При блокировках или ограничении частоты запросов он удваивает её либо ждёт время из `Retry-After`, а затем снова ускоряется.
+- 🤖 **Соблюдение robots.txt**: включите `robots_txt_obey`, чтобы учитывать `Disallow`, `Crawl-delay` и `Request-rate`. Правила кешируются для каждого домена.
+- 🧪 **Режим разработки**: сохраните ответы на диск при первом запуске и используйте их снова. Меняйте логику `parse()` без повторных обращений к серверам.
+- 🧩 **Готовые шаблоны Spider**: `CrawlSpider` обходит ссылки по правилам, `SitemapSpider` использует sitemap и robots.txt, `XMLFeedSpider`/`CSVFeedSpider` читают ленты XML/RSS и CSV, а `ShopifySpider` собирает товары из открытых магазинов Shopify, по одной записи на вариант.
+- 🔗 **Извлечение ссылок**: `LinkExtractor` поддерживает разрешающие и запрещающие шаблоны, фильтры доменов и расширений, выбор области через CSS/XPath и приведение URL к единому виду. Используйте его в шаблонах или отдельно.
+- 📦 **Готовый экспорт**: сохраняйте результаты через хуки и собственную обработку либо в JSON, JSONL, CSV и XML через `result.items.to_json()`, `to_jsonl()`, `to_csv()` и `to_xml()`.
+
+### Загрузка сайтов с поддержкой сессий {#advanced-websites-fetching-with-session-support}
+- **HTTP-запросы**: `Fetcher` отправляет быстрые и скрытные запросы. Он умеет имитировать TLS-отпечаток и заголовки браузера, а также использовать HTTP/3.
+- **Динамические страницы**: `StealthyFetcher` загружает сайты с полной автоматизацией браузера. Поддерживаются Chromium из Playwright и Google Chrome.
+- **Обход защиты от ботов**: `StealthyFetcher` скрывает признаки автоматизации и подменяет отпечаток браузера. Он автоматически проходит все виды проверок Cloudflare Turnstile и Interstitial.
+- **Управление сессиями**: `FetcherSession` и `StealthySession` сохраняют cookie и состояние между запросами.
+- **Смена прокси**: `ProxyRotator` перебирает прокси по кругу или по вашим правилам во всех типах сессий. Для отдельного запроса можно указать другой прокси.
+- **Блокировка доменов и рекламы**: блокируйте запросы к выбранным доменам и их поддоменам. В браузерных Fetcher можно включить блокировку рекламы, которая охватывает около 3 500 рекламных и отслеживающих доменов.
+- **Защита от утечек DNS**: включите DNS-over-HTTPS, чтобы отправлять DNS-запросы через DoH от Cloudflare и не допускать утечек DNS при работе с прокси.
+- **Удалённые браузеры**: подключайтесь к уже запущенному браузеру через CDP с помощью `cdp_url`. Браузер может работать на том же компьютере, другом сервере или у провайдера браузерных услуг. Параметр `executable_path` позволяет указать собственную сборку Chromium для любого браузерного Fetcher.
+- **Запись фоновых API-ответов**: включите `record_requests=True` в браузерной сессии, затем ищите сохранённые ответы через `session.network.search(limit=None)`. Читайте API-данные и HTTP-ошибки от разных загрузок страниц без повторной отправки запросов. История имеет ограниченный размер и сохраняет текстовые тела ответов.
+- **Асинхронная работа**: все Fetcher поддерживают асинхронные вызовы. Есть и отдельные классы асинхронных сессий.
+
+### Разбор и извлечение данных {#parsing-and-data-extraction}
+- 🔄 **Поиск элементов после изменений**: алгоритмы сходства находят элементы снова, даже если сайт изменился.
+- 🎯 **Гибкий поиск**: используйте CSS, XPath, фильтры, текст, регулярные выражения и другие способы.
+- 🔍 **Похожие элементы**: автоматически находите элементы, похожие на уже найденные.
+
+### Возможности для AI {#ai-features}
+- 🤖 **MCP-сервер**: AI-боты и агенты, такие как Claude и Cursor, могут собирать данные через Scrapling. Им доступны HTTP-запросы, действия в браузере, снимки экрана, сохранённый вход и фоновые API-ответы. Скрытный браузер и нужные инструменты позволяют подходящим AI-моделям проходить любые CAPTCHA во время работы, а проверки Cloudflare обрабатываются встроенным решением. Сервер уменьшает объём данных для модели, блокирует рекламу и защищает от Prompt Injection. Есть подключение к удалённым браузерам по CDP и HTTP-транспорт с настройками аутентификации. ([Демонстрация](https://www.youtube.com/watch?v=qyFk3ZNwOxE))
+- 🧠 **Agent Skill**: готовый к установке [Agent Skill](ai/agent-skill.md) знакомит агента со всей библиотекой. Он помогает писать код под текущий API без догадок.
+- 📚 **Markdown для RAG**: одна строка (`page.markdown()`) превращает страницу в чистый и безопасный Markdown для LLM. Шаблон `ContentSpider` сохраняет целый сайт в набор Markdown-файлов. Для самого сбора и преобразования LLM не нужна. ([Документация](ai/building-rag-systems.md))
+
+### Высокая скорость, проверенная на практике {#high-performance-battle-tested-architecture}
+- 🚀 **Быстрая работа**: оптимизации позволяют опережать большинство библиотек Python для скрапинга.
+- 🔋 **Мало памяти**: оптимизированные структуры данных и загрузка только по мере необходимости.
+- ⚡ **Быстрое преобразование в JSON**: в 10 раз быстрее стандартной библиотеки.
+- 🏗️ **Проверено на практике**: 92% покрытия тестами и аннотации типов для всего кода. За последний год сотни специалистов ежедневно использовали Scrapling для сбора данных.
+
+### Удобные инструменты для разработчиков {#developerweb-scraper-friendly-experience}
+- 🎯 **Интерактивная оболочка**: дополнительная оболочка IPython со Scrapling, сокращёнными командами и инструментами для быстрой разработки. Преобразуйте curl-запросы в запросы Scrapling и просматривайте результаты в браузере.
+- 🚀 **Работа из терминала**: собирайте данные по URL, не написав ни строки кода!
+- 🛠️ **Навигация по DOM**: переходите к родителям, соседним и дочерним элементам.
+- 🧬 **Обработка текста**: регулярные выражения, очистка текста и быстрые операции со строками.
+- 📝 **Создание селекторов**: получайте надёжные CSS- и XPath-селекторы для любого элемента.
+- 🔌 **Знакомый API**: подход похож на Scrapy и BeautifulSoup, с теми же псевдоэлементами, что и в Scrapy/Parsel.
+- 🤝 **Интеграция со Scrapy**: добавьте декоратор `scrapling_response` к обработчику, чтобы разбирать уже загруженные ответы парсером Scrapling. Переписывать проект не нужно.
+- 📘 **Полные аннотации типов**: удобная работа в редакторе и автодополнение. При каждом изменении весь код автоматически проверяется **PyRight** и **MyPy**.
+- 🔋 **Готовый образ Docker**: с каждым выпуском автоматически собирается и публикуется образ со всеми браузерами.
+
+
+## История звёзд GitHub {#star-history}
+С момента выпуска число звёзд Scrapling на GitHub постоянно растёт. Это видно на графике ниже.
+
+<div id="chartContainer">
+ <a href="https://github.com/D4Vinci/Scrapling">
+ <img id="chartImage" alt="График числа звёзд GitHub" loading="lazy" src="https://api.star-history.com/svg?repos=D4Vinci/Scrapling&type=Date" height="400"/>
+ </a>
+</div>
+
+<script>
+const observer = new MutationObserver((mutations) => {
+ mutations.forEach((mutation) => {
+ if (mutation.attributeName === 'data-md-color-media') {
+ const colorMedia = document.body.getAttribute('data-md-color-media');
+ const isDarkScheme = document.body.getAttribute('data-md-color-scheme') === 'slate';
+ const chartImg = document.querySelector('#chartImage');
+ const baseUrl = 'https://api.star-history.com/svg?repos=D4Vinci/Scrapling&type=Date';
+
+ if (colorMedia === '(prefers-color-scheme)' ? isDarkScheme : colorMedia.includes('dark')) {
+ chartImg.src = `${baseUrl}&theme=dark`;
+ } else {
+ chartImg.src = baseUrl;
+ }
+ }
+ });
+});
+
+observer.observe(document.body, {
+ attributes: true,
+ attributeFilter: ['data-md-color-media', 'data-md-color-scheme']
+});
+</script>
+
+
+## Установка {#installation}
+Для Scrapling нужен Python 3.10 или новее:
+
+```bash
+pip install scrapling
+```
+
+!!! warning "Внимание"
+
+ Эта команда устанавливает только парсер и его зависимости. Fetcher и инструменты командной строки в неё не входят. Поэтому импорт из `scrapling.fetchers` или `scrapling.spiders`, как в примерах выше, вызовет `ModuleNotFoundError`. Чтобы использовать Fetcher или Spider, сначала установите зависимости для загрузки страниц, как показано ниже.
+
+### Дополнительные зависимости {#optional-dependencies}
+
+1. Для Fetcher, их классов и дополнительных функций ниже установите зависимости для загрузки страниц и браузеров:
+ ```bash
+ pip install "scrapling[fetchers]"
+
+ scrapling install # normal install
+ scrapling install --force # force reinstall
+ ```
+
+ Команда загрузит все браузеры, нужные системные пакеты и средства изменения отпечатков браузера.
+
+ Вместо команды можно запустить установку из кода:
+ ```python
+ from scrapling.cli import install
+
+ install([], standalone_mode=False) # normal install
+ install(["--force"], standalone_mode=False) # force reinstall
+ ```
+
+2. Дополнительные функции:
+
+
+ - MCP-сервер:
+ ```bash
+ pip install "scrapling[ai]"
+ ```
+ - Зависимости для [создания RAG-систем](ai/building-rag-systems.md):
+ ```bash
+ pip install "scrapling[rag]"
+ ```
+ - Интерактивная оболочка и команда `extract`:
+ ```bash
+ pip install "scrapling[shell]"
+ ```
+ - Все возможности:
+ ```bash
+ pip install "scrapling[all]"
+ ```
+ Выполните `scrapling install`, если нужны браузерные Fetcher. Для HTTP-запросов устанавливать браузер не нужно.
+
+### Docker {#docker}
+Образ Docker со всеми дополнениями и браузерами можно скачать из DockerHub:
+```bash
+docker pull pyd4vinci/scrapling
+```
+Или из реестра GitHub:
+```bash
+docker pull ghcr.io/d4vinci/scrapling:latest
+```
+Образ автоматически собирается и публикуется через GitHub Actions из основной ветки репозитория.
+
+## Как устроена документация {#how-the-documentation-is-organized}
+У Scrapling много документации, поэтому мы стараемся следовать подходу [Diátaxis](https://diataxis.fr/).
+
+## Поддержка {#support}
+
+Если вам нравится Scrapling, поддержите его развитие:
+
+- ⭐ Поставьте звезду [репозиторию на GitHub](https://github.com/D4Vinci/Scrapling).
+- 🚀 Подпишитесь на нас в [Twitter](https://x.com/Scrapling_dev) и присоединитесь к [Discord](https://discord.gg/EMgGbDceNQ).
+- 💝 [Станьте спонсором проекта или угостите меня кофе](donate.md). :wink:
+- 🐛 Сообщайте об ошибках и предлагайте идеи через [GitHub Issues](https://github.com/D4Vinci/Scrapling/issues).
+
+## Лицензия {#license}
+
+Проект распространяется по лицензии BSD-3. Подробности в файле [LICENSE](https://github.com/D4Vinci/Scrapling/blob/main/LICENSE).
diff --git a/docs/locales/ru/integrations/scrapy.md b/docs/locales/ru/integrations/scrapy.md
new file mode 100644
index 0000000..37d05f1
--- /dev/null
+++ b/docs/locales/ru/integrations/scrapy.md
@@ -0,0 +1,64 @@
+---
+title: "Парсинг Scrapling в Spider на Scrapy"
+description: "Преобразуйте ответы Scrapy в Scrapling или добавьте декоратор к обработчику. Сохраните свой краулер Scrapy и используйте селекторы и адаптивный парсинг Scrapling."
+---
+
+# Интеграция Scrapling со Scrapy {#integrating-scrapling-into-scrapy}
+
+Если у вас уже есть проект Scrapy, его не нужно переписывать, чтобы использовать API парсинга Scrapling. Интеграция преобразует ответы Scrapy в объекты [Response](../fetching/choosing.md#response-object) Scrapling прямо в обработчиках Spider. Scrapy продолжает выполнять обход, а Scrapling отвечает за парсинг.
+
+!!! note "Установка"
+
+ Интеграция работает с обычной установкой Scrapling (`pip install scrapling`), без дополнительных групп зависимостей. Нужен только установленный Scrapy, который уже есть в проекте Scrapy.
+
+## Использование {#usage}
+
+Добавьте декоратор `scrapling_response` к любому обработчику Spider. Получаемый аргумент `response` станет объектом `Response` Scrapling:
+
+```python
+import scrapy
+from scrapling.integrations.scrapy import scrapling_response
+
+
+class QuotesSpider(scrapy.Spider):
+ name = "quotes"
+ start_urls = ["https://quotes.toscrape.com"]
+
+ @scrapling_response
+ def parse(self, response): # `response` is now a Scrapling Response
+ first_quote = response.find_by_text("The world as we have created it", partial=True)
+ for quote in [first_quote, *first_quote.find_similar()]:
+ card = quote.parent
+ yield {
+ "text": quote.get_all_text(strip=True),
+ "author": card.find("small", class_="author").text,
+ "tags": [tag.text for tag in card.find_all("a", class_="tag")],
+ }
+ next_page = response.css("li.next a::attr(href)").get()
+ if next_page:
+ yield scrapy.Request(response.urljoin(next_page), callback=self.parse)
+```
+
+Декоратор работает со всеми видами обработчиков Scrapy: обычными функциями, генераторами, корутинами и асинхронными генераторами. Обёртка сохраняет вид, имя и строку документации обработчика, поэтому проверка обработчиков и контракты Scrapy продолжают работать.
+
+Декоратору можно передать настройки [Selector](../parsing/main_classes.md#selector). Они попадут в создаваемый `Response`:
+
+```python
+ @scrapling_response(adaptive=True, keep_comments=True)
+ def parse_product(self, response):
+ ...
+```
+
+Если ответ Scrapy доступен вне обработчика, например в middleware или конвейере обработки, используйте преобразователь напрямую:
+
+```python
+from scrapling.integrations.scrapy import convert_response
+
+scrapling_response = convert_response(scrapy_response, keep_comments=False)
+```
+
+## Примечания {#notes}
+
+- Для следующих страниц возвращайте через yield `scrapy.Request(response.urljoin(href))`, как в примере выше. Метод `Response.follow()` Scrapling создаёт запросы для [системы Spider в Scrapling](../spiders/getting-started.md), которые Scrapy не понимает.
+- Словарь `meta` ответа копируется поверхностно, поэтому объекты, сохранённые другими middleware, остаются доступны. Например, при использовании `scrapy-playwright` страница по-прежнему находится в `response.meta["playwright_page"]`.
+- Cookie извлекаются из исходных заголовков `Set-Cookie` и помещаются в словарь `cookies` ответа.
diff --git a/docs/locales/ru/overview.md b/docs/locales/ru/overview.md
new file mode 100644
index 0000000..2a46f70
--- /dev/null
+++ b/docs/locales/ru/overview.md
@@ -0,0 +1,341 @@
+---
+title: "Обзор Scrapling: разбор страниц, HTTP-запросы и скрытные браузеры"
+description: "Познакомьтесь со Scrapling на примерах CSS, XPath, поиска по тексту, HTTP-запросов и скрытных браузеров."
+---
+
+# Начало работы со Scrapling {#get-started-with-scrapling}
+
+## Выберите свою задачу {#pick-your-path}
+
+Не знаете, с чего начать? Выберите подходящую задачу:
+
+| Я хочу... | С чего начать |
+|:---|:---|
+| **Разобрать HTML**, который уже есть | [Поиск элементов](parsing/selection.md): CSS, XPath и текст |
+| **Быстро получить страницу** и проверить идею | Выберите [Fetcher](fetching/choosing.md) или запустите [интерактивную оболочку](cli/interactive-shell.md) |
+| **Создать краулер** для множества страниц | [Spider](spiders/getting-started.md): параллельный обход, несколько сессий, пауза и продолжение |
+| **Собрать данные без кода** | [Команды CLI](cli/extract-commands.md) или [MCP-сервер](ai/mcp-server.md), подключённый к вашему AI-инструменту |
+| **Перейти** с другой библиотеки | [Переход с BeautifulSoup](tutorials/migrating_from_beautifulsoup.md) или [сравнение со Scrapy](spiders/architecture.md#comparison-with-scrapy) |
+
+---
+
+Сначала посмотрим, как разбирать страницы. Затем загрузим сайты через браузеры, отправим запросы и разберём ответы.
+
+В примерах на этой странице будем использовать HTML, который создал ChatGPT:
+```python
+html_doc = """<html>
+ <head>
+ <title>Complex Web Page</title>
+ <style>
+ .hidden { display: none; }
+ </style>
+ </head>
+ <body>
+ <header>
+ <nav>
+ <ul>
+ <li> <a href="#home">Home</a> </li>
+ <li> <a href="#about">About</a> </li>
+ <li> <a href="#contact">Contact</a> </li>
+ </ul>
+ </nav>
+ </header>
+ <main>
+ <section id="products" schema='{"jsonable": "data"}'>
+ <h2>Products</h2>
+ <div class="product-list">
+ <article class="product" data-id="1">
+ <h3>Product 1</h3>
+ <p class="description">This is product 1</p>
+ <span class="price">$10.99</span>
+ <div class="hidden stock">In stock: 5</div>
+ </article>
+
+ <article class="product" data-id="2">
+ <h3>Product 2</h3>
+ <p class="description">This is product 2</p>
+ <span class="price">$20.99</span>
+ <div class="hidden stock">In stock: 3</div>
+ </article>
+
+ <article class="product" data-id="3">
+ <h3>Product 3</h3>
+ <p class="description">This is product 3</p>
+ <span class="price">$15.99</span>
+ <div class="hidden stock">Out of stock</div>
+ </article>
+ </div>
+ </section>
+
+ <section id="reviews">
+ <h2>Customer Reviews</h2>
+ <div class="review-list">
+ <div class="review" data-rating="5">
+ <p class="review-text">Great product!</p>
+ <span class="reviewer">John Doe</span>
+ </div>
+ <div class="review" data-rating="4">
+ <p class="review-text">Good value for money.</p>
+ <span class="reviewer">Jane Smith</span>
+ </div>
+ </div>
+ </section>
+ </main>
+ <script id="page-data" type="application/json">
+ {
+ "lastUpdated": "2024-09-22T10:30:00Z",
+ "totalProducts": 3
+ }
+ </script>
+ </body>
+</html>"""
+```
+Сначала загрузим этот HTML:
+```python
+import re
+from scrapling.parser import Selector
+page = Selector(html_doc)
+page # <data='<html><head><title>Complex Web Page</tit...'>
+```
+Получим весь текст страницы, включая вложенные элементы:
+```python
+page.get_all_text(ignore_tags=('script', 'style'))
+# 'Complex Web Page\nHome\nAbout\nContact\nProducts\nProduct 1\nThis is product 1\n$10.99\nIn stock: 5\nProduct 2\nThis is product 2\n$20.99\nIn stock: 3\nProduct 3\nThis is product 3\n$15.99\nOut of stock\nCustomer Reviews\nGreat product!\nJohn Doe\nGood value for money.\nJane Smith'
+```
+
+## Поиск элементов {#finding-elements}
+Нужный элемент найдётся! Комбинируйте способы поиска под свою задачу.
+
+Найдём первый HTML-элемент `section`:
+```python
+section_element = page.find('section')
+# <data='<section id="products" schema='{"jsonabl...' parent='<main><section id="products" schema='{"j...'>
+```
+Найдём все элементы `section`:
+```python
+section_elements = page.find_all('section')
+# [<data='<section id="products" schema='{"jsonabl...' parent='<main><section id="products" schema='{"j...'>, <data='<section id="reviews"><h2>Customer Revie...' parent='<main><section id="products" schema='{"j...'>]
+```
+Найдём все элементы `section`, у которых атрибут `id` равен `products`:
+```python
+section_elements = page.find_all('section', {'id':"products"})
+# Same as
+section_elements = page.find_all('section', id="products")
+# [<data='<section id="products" schema='{"jsonabl...' parent='<main><section id="products" schema='{"j...'>]
+```
+Найдём все элементы `section`, у которых атрибут `id` содержит `product`:
+```python
+section_elements = page.find_all('section', {'id*':"product"})
+```
+Найдём элементы `h3`, текст которых соответствует регулярному выражению `Product \d`:
+```python
+page.find_all('h3', re.compile(r'Product \d'))
+# [<data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>, <data='<h3>Product 2</h3>' parent='<article class="product" data-id="2"><h3...'>, <data='<h3>Product 3</h3>' parent='<article class="product" data-id="3"><h3...'>]
+```
+Найдём элементы `h3` и `h2`, текст которых соответствует регулярному выражению `Product`:
+```python
+page.find_all(['h3', 'h2'], re.compile(r'Product'))
+# [<data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>, <data='<h3>Product 2</h3>' parent='<article class="product" data-id="2"><h3...'>, <data='<h3>Product 3</h3>' parent='<article class="product" data-id="3"><h3...'>, <data='<h2>Products</h2>' parent='<section id="products" schema='{"jsonabl...'>]
+```
+Найдём элементы с текстом, точно равным `Products`. Пробелы не учитываются:
+```python
+page.find_by_text('Products', first_match=False)
+# [<data='<h2>Products</h2>' parent='<section id="products" schema='{"jsonabl...'>]
+```
+Или найдём элементы, текст которых соответствует регулярному выражению `Product \d`:
+```python
+page.find_by_regex(r'Product \d', first_match=False)
+# [<data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>, <data='<h3>Product 2</h3>' parent='<article class="product" data-id="2"><h3...'>, <data='<h3>Product 3</h3>' parent='<article class="product" data-id="3"><h3...'>]
+```
+Найдём элементы, похожие на выбранный:
+```python
+target_element = page.find_by_regex(r'Product \d', first_match=True)
+# <data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>
+target_element.find_similar()
+# [<data='<h3>Product 2</h3>' parent='<article class="product" data-id="2"><h3...'>, <data='<h3>Product 3</h3>' parent='<article class="product" data-id="3"><h3...'>]
+```
+Найдём первый элемент по CSS-селектору:
+```python
+page.css('.product-list [data-id="1"]')[0]
+# <data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>
+```
+Найдём все элементы по CSS-селектору:
+```python
+page.css('.product-list article')
+# [<data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>, <data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>, <data='<article class="product" data-id="3"><h3...' parent='<div class="product-list"> <article clas...'>]
+```
+Найдём первый элемент по XPath-селектору:
+```python
+page.xpath("//*[@id='products']/div/article")[0]
+# <data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>
+```
+Найдём все элементы по XPath-селектору:
+```python
+page.xpath("//*[@id='products']/div/article")
+# [<data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>, <data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>, <data='<article class="product" data-id="3"><h3...' parent='<div class="product-list"> <article clas...'>]
+```
+
+Это только начало. Дополнительные возможности этих методов описаны дальше.
+## Чтение данных элементов {#accessing-elements-data}
+Это просто:
+```pycon
+>>> section_element.tag
+'section'
+>>> print(section_element.attrib)
+{'id': 'products', 'schema': '{"jsonable": "data"}'}
+>>> section_element.attrib['schema'].json() # If an attribute value can be converted to json, then use `.json()` to convert it
+{'jsonable': 'data'}
+>>> section_element.text # Direct text content
+''
+>>> section_element.get_all_text() # All text content recursively
+'Products\nProduct 1\nThis is product 1\n$10.99\nIn stock: 5\nProduct 2\nThis is product 2\n$20.99\nIn stock: 3\nProduct 3\nThis is product 3\n$15.99\nOut of stock'
+>>> section_element.html_content # The HTML content of the element
+'<section id="products" schema=\'{"jsonable": "data"}\'><h2>Products</h2>\n <div class="product-list">\n <article class="product" data-id="1"><h3>Product 1</h3>\n <p class="description">This is product 1</p>\n <span class="price">$10.99</span>\n <div class="hidden stock">In stock: 5</div>\n </article><article class="product" data-id="2"><h3>Product 2</h3>\n <p class="description">This is product 2</p>\n <span class="price">$20.99</span>\n <div class="hidden stock">In stock: 3</div>\n </article><article class="product" data-id="3"><h3>Product 3</h3>\n <p class="description">This is product 3</p>\n <span class="price">$15.99</span>\n <div class="hidden stock">Out of stock</div>\n </article></div>\n </section>'
+>>> print(section_element.prettify()) # The prettified version
+'''
+<section id="products" schema='{"jsonable": "data"}'><h2>Products</h2>
+ <div class="product-list">
+ <article class="product" data-id="1"><h3>Product 1</h3>
+ <p class="description">This is product 1</p>
+ <span class="price">$10.99</span>
+ <div class="hidden stock">In stock: 5</div>
+ </article><article class="product" data-id="2"><h3>Product 2</h3>
+ <p class="description">This is product 2</p>
+ <span class="price">$20.99</span>
+ <div class="hidden stock">In stock: 3</div>
+ </article><article class="product" data-id="3"><h3>Product 3</h3>
+ <p class="description">This is product 3</p>
+ <span class="price">$15.99</span>
+ <div class="hidden stock">Out of stock</div>
+ </article>
+ </div>
+</section>
+'''
+>>> section_element.path # All the ancestors in the DOM tree of this element
+[<data='<main><section id="products" schema='{"j...' parent='<body> <header><nav><ul><li> <a href="#h...'>,
+ <data='<body> <header><nav><ul><li> <a href="#h...' parent='<html><head><title>Complex Web Page</tit...'>,
+ <data='<html><head><title>Complex Web Page</tit...'>]
+>>> section_element.generate_css_selector
+'#products'
+>>> section_element.generate_full_css_selector
+'body > main > #products'
+>>> section_element.generate_xpath_selector
+"//*[@id='products']"
+>>> section_element.generate_full_xpath_selector
+"//body/main/*[@id='products']"
+```
+
+## Навигация {#navigation}
+Используем найденные выше элементы:
+
+```pycon
+>>> section_element.parent
+<data='<main><section id="products" schema='{"j...' parent='<body> <header><nav><ul><li> <a href="#h...'>
+>>> section_element.parent.tag
+'main'
+>>> section_element.parent.parent.tag
+'body'
+>>> section_element.children
+[<data='<h2>Products</h2>' parent='<section id="products" schema='{"jsonabl...'>,
+ <data='<div class="product-list"> <article clas...' parent='<section id="products" schema='{"jsonabl...'>]
+>>> section_element.siblings
+[<data='<section id="reviews"><h2>Customer Revie...' parent='<main><section id="products" schema='{"j...'>]
+>>> section_element.next # gets the next element, the same logic applies to `quote.previous`.
+<data='<section id="reviews"><h2>Customer Revie...' parent='<main><section id="products" schema='{"j...'>
+>>> section_element.children.css('h2::text').getall()
+['Products']
+>>> page.css('[data-id="1"]')[0].has_class('product')
+True
+```
+Если нужен не только родитель, можно пройти по всем предкам элемента:
+```python
+for ancestor in section_element.iterancestors():
+ print(ancestor.tag)
+```
+Можно найти предка, который подходит под условие. Передайте функцию, которая принимает `Selector` и возвращает `True`, если условие выполнено, или `False` в противном случае:
+```pycon
+>>> section_element.find_ancestor(lambda ancestor: ancestor.css('nav'))
+<data='<body> <header><nav><ul><li> <a href="#h...' parent='<html><head><title>Complex Web Page</tit...'>
+```
+
+## Загрузка сайтов {#fetching-websites}
+Вместо передачи готового HTML можно получить ответ сайта через HTTP-запрос или браузер.
+
+Для каждой задачи есть подходящий Fetcher.
+
+### HTTP-запросы {#http-requests}
+Для обычных HTTP-запросов импортируйте класс `Fetcher`:
+```python
+from scrapling.fetchers import Fetcher
+page = Fetcher.get('https://scrapling.requestcatcher.com/get', impersonate="chrome")
+```
+Вот как использовать разные HTTP-методы:
+```python
+from scrapling.fetchers import Fetcher
+page = Fetcher.get('https://scrapling.requestcatcher.com/get', stealthy_headers=True)
+page = Fetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, proxy='http://username:password@localhost:8030')
+page = Fetcher.put('https://scrapling.requestcatcher.com/put', data={'key': 'value'})
+page = Fetcher.delete('https://scrapling.requestcatcher.com/delete')
+```
+Для асинхронных запросов замените импорт:
+```python
+from scrapling.fetchers import AsyncFetcher
+page = await AsyncFetcher.get('https://scrapling.requestcatcher.com/get', stealthy_headers=True)
+page = await AsyncFetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, proxy='http://username:password@localhost:8030')
+page = await AsyncFetcher.put('https://scrapling.requestcatcher.com/put', data={'key': 'value'})
+page = await AsyncFetcher.delete('https://scrapling.requestcatcher.com/delete')
+```
+
+!!! note "Примечания"
+
+ 1. Параметр `stealthy_headers` создаёт и использует заголовки настоящего браузера, включая Referer от Google. По умолчанию он включён.
+ 2. Параметр `impersonate` позволяет имитировать TLS-отпечаток определённой версии браузера.
+ 3. Параметр `http3` включает HTTP/3, чтобы запросы больше походили на запросы настоящего браузера.
+
+Это лишь часть возможностей. Остальные описаны в [руководстве по HTTP-запросам](fetching/static.md).
+
+### Динамическая загрузка {#dynamic-loading}
+Scrapling справится и с динамическими сайтами!
+
+`StealthyFetcher` предлагает много настроек для загрузки страниц через браузеры на основе Chromium.
+```python
+from scrapling.fetchers import StealthyFetcher
+page = StealthyFetcher.fetch('https://quotes.toscrape.com/js/', disable_resources=True, block_ads=True, wait_selector='.quote')
+print(len(page.css(".quote"))) # -> 10
+
+# The async version of fetch
+page = await StealthyFetcher.async_fetch('https://quotes.toscrape.com/js/', disable_resources=True, block_ads=True, wait_selector='.quote')
+print(len(page.css(".quote"))) # -> 10
+```
+Он использует [Playwright](https://playwright.dev/python/) с изменениями, которые скрывают автоматизацию. Можно работать со встроенным Chromium, установленным Google Chrome через `real_chrome=True` или уже запущенным браузером через `cdp_url`.
+
+### Обход защиты от ботов {#anti-bot-features}
+
+Вот некоторые возможности:
+
+1. Автоматическое прохождение всех видов Cloudflare Turnstile и Interstitial с `solve_cloudflare=True`.
+2. Защита от утечек CDP Runtime и WebRTC.
+3. Изоляция JavaScript, удаление многих признаков Playwright и защита от обнаружения по известным действиям ботов.
+4. Добавление шума в Canvas, чтобы не дать определить отпечаток браузера.
+5. Исправления против известных способов обнаружения режима без окна и настройка для защиты от проверки часового пояса.
+6. И другие средства обхода защиты.
+
+```python
+from scrapling.fetchers import StealthyFetcher
+page = StealthyFetcher.fetch('https://www.browserscan.net/bot-detection') # Running headless by default
+page.status == 200 # -> True
+
+page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare', solve_cloudflare=True) # Solve Cloudflare captcha automatically if presented
+page.status == 200 # -> True
+
+page = StealthyFetcher.fetch('https://www.browserscan.net/bot-detection', block_webrtc=True, hide_canvas=True, dns_over_https=True) # and the rest of arguments...
+# The async version of fetch
+page = await StealthyFetcher.async_fetch('https://www.browserscan.net/bot-detection')
+page.status == 200 # -> True
+```
+
+Все возможности и полный список аргументов описаны в [руководстве по браузеру](fetching/stealthy.md).
+
+---
+
+Так выглядит Scrapling в общих чертах. Продолжайте со следующего раздела, чтобы узнать больше.
diff --git a/docs/locales/ru/parsing/adaptive.md b/docs/locales/ru/parsing/adaptive.md
new file mode 100644
index 0000000..36f73d7
--- /dev/null
+++ b/docs/locales/ru/parsing/adaptive.md
@@ -0,0 +1,232 @@
+---
+title: "Поиск HTML-элементов после изменений с адаптивным разбором"
+description: "Сохраняйте признаки элементов и находите их после изменений HTML. Узнайте, как включить адаптивный разбор и использовать save, retrieve и relocate."
+---
+
+# Адаптивный сбор данных {#adaptive-scraping}
+
+!!! success "Перед началом"
+
+ 1. Прочитайте страницу [Поиск элементов](../parsing/selection.md), чтобы понять, как находить и извлекать элементы из объекта [Selector](../parsing/main_classes.md#selector).
+ 2. Прочитайте страницу [Основные классы](../parsing/main_classes.md), чтобы разобраться в классе [Selector](../parsing/main_classes.md#selector).
+
+Адаптивный сбор данных, ранее известный как automatch, относится к самым полезным возможностям Scrapling. Он отслеживает элементы и находит их заново, чтобы ваш скрейпер продолжал работать после изменений сайта.
+
+Допустим, вы собираете данные со страницы с такой структурой:
+```html
+<div class="container">
+ <section class="products">
+ <article class="product" id="p1">
+ <h3>Product 1</h3>
+ <p class="description">Description 1</p>
+ </article>
+ <article class="product" id="p2">
+ <h3>Product 2</h3>
+ <p class="description">Description 2</p>
+ </article>
+ </section>
+</div>
+```
+Чтобы получить первый товар с ID `p1`, вы, скорее всего, напишете такой селектор:
+```python
+page.css('#p1')
+```
+Если владельцы сайта изменят структуру следующим образом:
+```html
+<div class="new-container">
+ <div class="product-wrapper">
+ <section class="products">
+ <article class="product new-class" data-id="p1">
+ <div class="product-info">
+ <h3>Product 1</h3>
+ <p class="new-description">Description 1</p>
+ </div>
+ </article>
+ <article class="product new-class" data-id="p2">
+ <div class="product-info">
+ <h3>Product 2</h3>
+ <p class="new-description">Description 2</p>
+ </div>
+ </article>
+ </section>
+ </div>
+</div>
+```
+Селектор перестанет работать, и код придётся исправлять. Здесь и пригодится функция `adaptive` в Scrapling.
+
+В Scrapling можно включить `adaptive` при первом выборе элемента. Если при следующем выборе элемент не найдётся, Scrapling вспомнит его признаки и найдёт на сайте наиболее похожий элемент. Всё это без ИИ :)
+
+```python
+from scrapling import Selector, Fetcher
+# Before the change
+page = Selector(page_source, adaptive=True, url='example.com')
+# or
+Fetcher.adaptive = True
+page = Fetcher.get('https://example.com')
+# then
+element = page.css('#p1', auto_save=True)
+if not element: # One day website changes?
+ element = page.css('#p1', adaptive=True) # Scrapling still finds it!
+# the rest of your code...
+```
+Ниже я покажу пример, а затем подробно объясню, как использовать эту функцию и как она работает. Она доступна для всех способов выбора элементов, а не только CSS/XPath.
+
+## Пример с реальным сайтом {#real-world-scenario}
+Возьмём реальный сайт и получим его исходный код через один из Fetcher. Для этого нужно найти сайт, который вот-вот изменит дизайн или структуру, сохранить его исходный код и дождаться изменений. Узнать об этом заранее почти невозможно, если только я не знаком с владельцем сайта. Но тогда тест был бы постановочным :)
+
+Поэтому я воспользуюсь [Wayback Machine](https://web.archive.org/) от [The Web Archive](https://archive.org/). Вот копия [сайта StackOverFlow за 2010 год](https://web.archive.org/web/20100102003420/http://stackoverflow.com/). Довольно старая, правда?</br>Проверим, сможет ли адаптивная функция найти одну и ту же кнопку в дизайне 2010 года и в текущем дизайне с помощью одного селектора :)
+
+Чтобы найти кнопку Questions в старом дизайне, можно использовать селектор `#hmenus > div:nth-child(1) > ul > li:nth-child(1) > a`. Он слишком подробный, потому что его создал Google Chrome.
+
+
+Теперь проверим этот селектор в обеих версиях:
+```python
+from scrapling import Fetcher
+selector = '#hmenus > div:nth-child(1) > ul > li:nth-child(1) > a'
+old_url = "https://web.archive.org/web/20100102003420/http://stackoverflow.com/"
+new_url = "https://stackoverflow.com/"
+Fetcher.configure(adaptive = True, adaptive_domain='stackoverflow.com')
+page = Fetcher.get(old_url, timeout=30)
+element1 = page.css(selector, auto_save=True)[0]
+# Same selector but used in the updated website
+page = Fetcher.get(new_url)
+element2 = page.css(selector, adaptive=True)[0]
+
+if element1.text == element2.text:
+ print('Scrapling found the same element in the old and new designs!') # Spoiler alert: it does!
+```
+Здесь появился новый аргумент `adaptive_domain`. Для Scrapling это два разных домена (`archive.org` и `stackoverflow.com`), поэтому их данные `adaptive` хранятся отдельно. Чтобы указать, что это один сайт, нужно передать одинаковый пользовательский домен для сохранения данных `adaptive` в обоих случаях.
+
+В реальной задаче код будет таким же, но оба запроса будут использовать один URL, поэтому аргумент `adaptive_domain` не понадобится. Это самый близкий к реальности пример, который я могу привести. Надеюсь, он вас не запутал :)
+
+В двух примерах выше я использовал классы `Selector` и `Fetcher`, чтобы показать: адаптивный поиск работает одинаково в обоих случаях.
+
+!!! info "Информация"
+
+ Аргумент `adaptive_domain` в первую очередь нужен, если сайт меняет URL вместе с дизайном или структурой. Он позволяет использовать ранее сохранённые адаптивные данные для нового URL. Без него Scrapling сочтёт сайт новым и не будет использовать старые данные.
+
+## Как работает адаптивный сбор данных {#how-the-adaptive-scraping-feature-works}
+Адаптивный сбор данных состоит из двух этапов:
+
+1. **Сохранение**: запись отличительных признаков элементов.
+2. **Сопоставление**: поиск элементов с похожими признаками при следующем обращении.
+
+Допустим, вы выбрали элемент любым способом и хотите, чтобы библиотека нашла его при следующем сборе данных, даже если структура или дизайн сайта изменятся.
+
+Если не вдаваться в технические детали, процесс выглядит так:
+
+ 1. Вы просите Scrapling сохранить отличительные признаки элемента одним из способов, описанных ниже.
+ 2. Scrapling сохраняет признаки каждого элемента в настроенную базу данных. По умолчанию это SQLite.
+ 3. Владельцы сайта могут изменить или удалить любое свойство элемента. Поэтому ни одно из них нельзя использовать как постоянный идентификатор в базе данных. Для решения этой задачи система хранения использует два значения:
+ 1. Домен текущего сайта. Для класса `Selector` передайте его при создании объекта. Fetcher автоматически возьмёт домен из URL.
+ 2. `identifier`, по которому можно получить признаки элемента из базы данных. Не всегда нужно задавать его вручную. К этому мы ещё вернёмся.
+
+ Вместе эти значения позволяют позже получить из базы сохранённые признаки элемента.
+
+ 4. После изменения структуры сайта включите `adaptive`, чтобы найти элемент. Scrapling получит его сохранённые признаки и сравнит с ними все элементы страницы. Для каждого будет рассчитана степень сходства с нужным элементом. При сравнении учитывается всё, как вы увидите ниже.
+ 5. Scrapling вернёт элемент или элементы с наибольшим сходством.
+
+### Отличительные признаки {#the-unique-properties}
+Может возникнуть вопрос: какие признаки мы считаем отличительными, если все свойства элемента могут измениться или исчезнуть?
+
+Scrapling использует следующие признаки:
+
+- Имя тега, текст, атрибуты (имена и значения), соседние элементы с тем же родителем (только имена тегов) и путь элемента (только имена тегов).
+- Имя тега, атрибуты (имена и значения) и текст родителя элемента.
+
+При этом не требуется точное совпадение. Важно, насколько похожи значения. Учитывается даже их порядок: например, порядок имён классов элемента до изменений и после них.
+
+## Как использовать адаптивную функцию {#how-to-use-adaptive-feature}
+Адаптивную функцию можно применить к любому найденному элементу. В методах выбора по CSS/XPath она доступна через аргументы, как в примерах выше. Мы ещё к ним вернёмся.
+
+Сначала включите `adaptive`: передайте `adaptive=True` при создании [Selector](main_classes.md#selector) или включите эту настройку в используемом Fetcher, как показано ниже.
+
+Примеры:
+```python
+from scrapling import Selector, Fetcher
+page = Selector(html_doc, adaptive=True)
+# OR
+Fetcher.adaptive = True
+page = Fetcher.get('https://example.com')
+```
+При работе с классом [Selector](main_classes.md#selector) передайте URL сайта в аргументе `url`, чтобы Scrapling разделял сохранённые признаки элементов по доменам.
+
+Если URL не передан, при сохранении признаков вместо него используется слово `default`. Проблема возникнет, только если позже использовать тот же идентификатор для другого сайта и снова не передать URL при создании объекта. Сохранение перезаписывает прежние данные, а `adaptive` использует только последние сохранённые признаки.
+
+Аргументы `storage` и `storage_args` задают подключение к базе данных. По умолчанию используется класс SQLite из библиотеки. Эти аргументы нужны, только если вы хотите создать свою систему хранения. Этому посвящена [отдельная страница в разделе разработки](../development/adaptive_storage_system.md).
+
+После включения `adaptive` на уровне класса можно использовать функцию двумя основными способами.
+
+### Через CSS/XPath {#the-cssxpath-selection-way}
+Как в примере выше, сначала передайте `auto_save` при выборе элемента, который ещё есть на странице:
+```python
+element = page.css('#p1', auto_save=True)
+```
+Если элемент больше не находится, используйте тот же селектор с аргументом `adaptive`, и библиотека найдёт его:
+```python
+element = page.css('#p1', adaptive=True)
+```
+Довольно просто, правда?
+
+При этом внутри происходит немало работы. Помните идентификатор, который нужен для получения признаков элемента? Методы `css`/`xpath` автоматически используют переданный селектор как идентификатор, чтобы вам было проще :)
+
+Во всех этих методах можно задать свой `identifier`. Это полезно в некоторых задачах, в том числе при сохранении признаков с аргументом `auto_save`.
+
+### Вручную {#the-manual-way}
+Можно вручную сохранить признаки элемента, получить их и найти элемент заново с помощью `adaptive`, как показано ниже. Так вы можете повторно находить элементы, выбранные любым способом.
+
+Допустим, вы нашли элемент по тексту:
+```python
+element = page.find_by_text('Tipping the Velvet', first_match=True)
+```
+Сохраните его отличительные признаки методом `save`. Здесь идентификатор нужно задать самостоятельно. В примере я выбрал `my_special_element`, но в своём коде лучше использовать понятное имя, как и для переменных :)
+```python
+page.save(element, 'my_special_element')
+```
+Позже, чтобы получить признаки и найти элемент на странице с помощью `adaptive`, выполните:
+```python
+>>> element_dict = page.retrieve('my_special_element')
+>>> page.relocate(element_dict, selector_type=True)
+[<data='<a href="catalogue/tipping-the-velvet_99...' parent='<h3><a href="catalogue/tipping-the-velve...'>]
+>>> page.relocate(element_dict, selector_type=True).css('::text').getall()
+['Tipping the Velvet']
+```
+Для этого используются методы `retrieve` и `relocate`.
+
+Если нужно оставить результат объектом `lxml.etree`, не передавайте аргумент `selector_type`:
+```python
+>>> page.relocate(element_dict)
+[<Element a at 0x105a2a7b0>]
+```
+
+## Решение проблем {#troubleshooting}
+
+### Совпадения не найдены {#no-matches-found}
+```python
+# 1. Check if data was saved
+element_data = page.retrieve('identifier')
+if not element_data:
+ print("No data saved for this identifier")
+
+# 2. Try with different identifier
+products = page.css('.product', adaptive=True, identifier='old_selector')
+
+# 3. Save again with new identifier
+products = page.css('.new-product', auto_save=True, identifier='new_identifier')
+```
+
+### Найдены не те элементы {#wrong-elements-matched}
+```python
+# Use more specific selectors
+products = page.css('.product-list .product', auto_save=True)
+
+# Or save with more context
+product = page.find_by_text('Product Name').parent
+page.save(product, 'specific_product')
+```
+
+## Известные ограничения {#known-issues}
+При сохранении через `adaptive` записываются признаки только первого элемента результата. Поэтому, если селектор выбирает разные элементы в нескольких местах страницы, при повторном поиске `adaptive` вернёт только первый. Это не касается составных CSS-селекторов, например селекторов, объединённых запятыми: каждый из них обрабатывается отдельно.
+
+## В заключение {#final-thoughts}
+Подробно и просто объяснить эту функцию оказалось непросто. Если что-то осталось неясным, напишите в [обсуждениях](https://github.com/D4Vinci/Scrapling/discussions), на сервере Discord или лично мне. Постараюсь ответить как можно скорее :)
\ No newline at end of file
diff --git a/docs/locales/ru/parsing/main_classes.md b/docs/locales/ru/parsing/main_classes.md
new file mode 100644
index 0000000..e4f5d27
--- /dev/null
+++ b/docs/locales/ru/parsing/main_classes.md
@@ -0,0 +1,573 @@
+---
+title: "Selector и Selectors в Scrapling: данные и навигация"
+description: "Узнайте, как Selector и Selectors хранят HTML, текст и атрибуты. Извлекайте значения, преобразуйте URL и переходите к родителям, дочерним и соседним элементам."
+---
+
+# Основные классы парсера {#parsing-main-classes}
+
+!!! success "Перед началом"
+
+ - Прочитайте страницу [Поиск элементов](../parsing/selection.md), чтобы понять, как находить и извлекать элементы из объекта [Selector](../parsing/main_classes.md#selector).
+
+Теперь, когда мы рассмотрели способы выбора элементов в Scrapling, разберём класс [Selector](#selector) и связанные объекты. Это поможет лучше понять работу парсера.
+
+Класс [Selector](#selector) составляет основу парсера Scrapling: он разбирает HTML и позволяет выбирать элементы. Его можно импортировать любым из следующих способов:
+```python
+from scrapling import Selector
+from scrapling.parser import Selector
+```
+Затем используйте его напрямую, как показано на странице [Обзор](../overview.md):
+```python
+page = Selector(
+ '<html>...</html>',
+ url='https://example.com'
+)
+
+# Then select elements as you like
+elements = page.css('.product')
+```
+После передачи HTML или получения страницы основным объектом в Scrapling становится [Selector](#selector). Выбор элементов, навигация и другие операции возвращают объект [Selector](#selector) или [Selectors](#selectors), если результатом является один или несколько элементов страницы, а не текст или подобные данные.
+
+Другими словами, сама страница является объектом [Selector](#selector), и каждый её элемент тоже является объектом [Selector](#selector). Любой текст, включая содержимое элементов и значения их атрибутов, представлен объектом [TextHandler](#texthandler). Атрибуты каждого элемента хранятся в [AttributesHandler](#attributeshandler). К этим двум объектам мы вернёмся позже, а пока рассмотрим [Selector](#selector).
+
+## Selector {#selector}
+### Аргументы {#arguments-explained}
+Самый важный аргумент, `content`, принимает HTML для разбора в виде `str` или `bytes`.
+
+Аргумент `url` задаёт URL страницы для преобразования относительных ссылок и разделения сохранённых адаптивных данных по доменам. Аргументы `adaptive`, `storage` и `storage_args` относятся к [адаптивной функции](adaptive.md) и не влияют на работу, если вы её не используете.
+
+Следующие аргументы управляют разбором и обработкой HTML:
+
+- **encoding**: кодировка HTML. По умолчанию `UTF-8`.
+- **keep_comments**: сохранять ли HTML-комментарии при разборе страницы. По умолчанию выключено, так как комментарии могут мешать сбору данных.
+
+Я намеренно пропустил аргументы `huge_tree` и `root`, чтобы не усложнять эту страницу.
+Возможно, вы заметили, что я часто так поступаю с расширенными возможностями, которые не нужны для начала работы. Подробнее о них можно узнать в разделе разработки.
+
+Большинство свойств страницы и её элементов загружаются только при первом обращении. Например, текст страницы или элемента обрабатывается, когда он вам понадобится. Это одна из причин высокой скорости Scrapling :)
+
+### Свойства {#properties}
+Многое из этого уже было на странице [Обзор](../overview.md), но здесь мы разберём свойства подробнее и рассмотрим более сложные примеры. Свойства для перемещения по элементам вынесены в раздел [Навигация](#traversal).
+
+Для примера разберём такую HTML-страницу:
+```html
+<html>
+ <head>
+ <title>Some page</title>
+ </head>
+ <body>
+ <div class="product-list">
+ <article class="product" data-id="1">
+ <h3>Product 1</h3>
+ <p class="description">This is product 1</p>
+ <span class="price">$10.99</span>
+ <div class="hidden stock">In stock: 5</div>
+ </article>
+
+ <article class="product" data-id="2">
+ <h3>Product 2</h3>
+ <p class="description">This is product 2</p>
+ <span class="price">$20.99</span>
+ <div class="hidden stock">In stock: 3</div>
+ </article>
+
+ <article class="product" data-id="3">
+ <h3>Product 3</h3>
+ <p class="description">This is product 3</p>
+ <span class="price">$15.99</span>
+ <div class="hidden stock">Out of stock</div>
+ </article>
+ </div>
+
+ <script id="page-data" type="application/json">
+ {
+ "lastUpdated": "2024-09-22T10:30:00Z",
+ "totalProducts": 3
+ }
+ </script>
+ </body>
+</html>
+```
+Загрузим страницу, как показано ранее:
+```python
+from scrapling import Selector
+page = Selector(html_doc)
+```
+Получим весь текст страницы, включая вложенные элементы:
+```python
+>>> page.get_all_text()
+'Some page\n\n \n\n \nProduct 1\nThis is product 1\n$10.99\nIn stock: 5\nProduct 2\nThis is product 2\n$20.99\nIn stock: 3\nProduct 3\nThis is product 3\n$15.99\nOut of stock'
+```
+Получим первый элемент article и используем его в примерах:
+```python
+article = page.find('article')
+```
+Таким же способом получим весь текст элемента, включая вложенные элементы:
+```python
+>>> article.get_all_text()
+'Product 1\nThis is product 1\n$10.99\nIn stock: 5'
+```
+Но если запросить только непосредственный текст элемента, результат будет пустым: в HTML выше у него нет собственного текста.
+```python
+>>> article.text
+''
+```
+Метод `get_all_text` принимает следующие необязательные аргументы:
+
+1. **separator**: разделитель для объединения найденных строк. По умолчанию '\n'.
+2. **strip**: удалять пробельные символы по краям строк перед объединением. По умолчанию выключено.
+3. **ignore_tags**: кортеж имён тегов, которые нужно пропустить вместе со всем вложенным содержимым. По умолчанию `('script', 'style',)`.
+4. **valid_values**: собирать только элементы с непустым текстом. Пустой текст и текст только из пробельных символов пропускаются. По умолчанию включено.
+
+Возвращаемый текст имеет тип [TextHandler](#texthandler), а не обычной строки. Позже мы разберём его подробнее. Если текст содержит JSON, его можно преобразовать методом `.json()`:
+```python
+>>> script = page.find('script')
+>>> script.json()
+{'lastUpdated': '2024-09-22T10:30:00Z', 'totalProducts': 3}
+```
+Теперь получим имя тега элемента:
+```python
+>>> article.tag
+'article'
+```
+Если обратиться к этому свойству у самой страницы, вы увидите, что работаете с корневым элементом `html`:
+```python
+>>> page.tag
+'html'
+```
+Думаю, связь между `page` и `element` теперь понятна, поэтому больше не будем к ней возвращаться.
+
+Получим атрибуты элемента:
+```python
+>>> print(article.attrib)
+{'class': 'product', 'data-id': '1'}
+```
+К отдельному атрибуту можно обратиться любым из этих способов:
+```python
+article.attrib['class']
+article.attrib.get('class')
+article['class'] # new in v0.3
+```
+Проверить наличие атрибута можно так:
+```python
+'class' in article.attrib
+'class' in article # new in v0.3
+```
+Получим HTML элемента:
+```python
+>>> article.html_content
+'<article class="product" data-id="1"><h3>Product 1</h3>\n <p class="description">This is product 1</p>\n <span class="price">$10.99</span>\n <div class="hidden stock">In stock: 5</div>\n </article>'
+```
+Получим красиво отформатированный HTML элемента:
+```python
+print(article.prettify())
+```
+```html
+<article class="product" data-id="1"><h3>Product 1</h3>
+ <p class="description">This is product 1</p>
+ <span class="price">$10.99</span>
+ <div class="hidden stock">In stock: 5</div>
+</article>
+```
+Свойство `.body` возвращает исходное содержимое страницы. Начиная с v0.4, у объектов `Response`, полученных через Fetcher, `.body` всегда возвращает `bytes`.
+```python
+>>> page.body
+'<html>\n <head>\n <title>Some page</title>\n </head>\n ...'
+```
+Получим всех предков элемента в дереве DOM:
+```python
+>>> article.path
+[<data='<div class="product-list"> <article clas...' parent='<body> <div class="product-list"> <artic...'>,
+ <data='<body> <div class="product-list"> <artic...' parent='<html><head><title>Some page</title></he...'>,
+ <data='<html><head><title>Some page</title></he...'>]
+```
+Создадим сокращённый CSS-селектор, если это возможно, или полный селектор:
+```python
+>>> article.generate_css_selector
+'body > div > article'
+>>> article.generate_full_css_selector
+'body > div > article'
+```
+То же самое для XPath:
+```python
+>>> article.generate_xpath_selector
+"//body/div/article"
+>>> article.generate_full_xpath_selector
+"//body/div/article"
+```
+
+### Навигация {#traversal}
+На найденных выше элементах подробно рассмотрим свойства и методы для перемещения по странице.
+
+Если вы не знакомы с деревом DOM или структурой данных «дерево», этот раздел может быть непонятен. Советую сначала прочитать об этих понятиях.
+
+А если хотите сразу продолжить, вот краткое объяснение.<br/>
+Элемент `html` является корнем дерева сайта: каждая страница начинается с элемента `html`.<br/>
+Непосредственно под ним находятся такие элементы, как `head` и `body`. Они считаются дочерними элементами `html`, а `html` является их родителем. Элементы `body` и `head` считаются соседними, так как у них один родитель.
+
+Получим родителя элемента:
+```python
+>>> article.parent
+<data='<div class="product-list"> <article clas...' parent='<body> <div class="product-list"> <artic...'>
+>>> article.parent.tag
+'div'
+```
+Обращения можно объединять в цепочки. Это относится и к остальным похожим свойствам и методам ниже.
+```python
+>>> article.parent.parent.tag
+'body'
+```
+Получим дочерние элементы:
+```python
+>>> article.children
+[<data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>,
+ <data='<p class="description">This is product 1...' parent='<article class="product" data-id="1"><h3...'>,
+ <data='<span class="price">$10.99</span>' parent='<article class="product" data-id="1"><h3...'>,
+ <data='<div class="hidden stock">In stock: 5</d...' parent='<article class="product" data-id="1"><h3...'>]
+```
+Получим все элементы ниже текущего, включая вложенные. Это похоже на свойство `children`, но для всех уровней вложенности:
+```python
+>>> article.below_elements
+[<data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>,
+ <data='<p class="description">This is product 1...' parent='<article class="product" data-id="1"><h3...'>,
+ <data='<span class="price">$10.99</span>' parent='<article class="product" data-id="1"><h3...'>,
+ <data='<div class="hidden stock">In stock: 5</d...' parent='<article class="product" data-id="1"><h3...'>]
+```
+Здесь результат совпадает со свойством `children`, потому что у дочерних элементов нет своих дочерних элементов.
+
+Пример с элементом класса `product-list` лучше показывает разницу между `children` и `below_elements`:
+```python
+>>> products_list = page.css('.product-list')[0]
+>>> products_list.children
+[<data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>,
+ <data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>,
+ <data='<article class="product" data-id="3"><h3...' parent='<div class="product-list"> <article clas...'>]
+
+>>> products_list.below_elements
+[<data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>,
+ <data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>,
+ <data='<p class="description">This is product 1...' parent='<article class="product" data-id="1"><h3...'>,
+ <data='<span class="price">$10.99</span>' parent='<article class="product" data-id="1"><h3...'>,
+ <data='<div class="hidden stock">In stock: 5</d...' parent='<article class="product" data-id="1"><h3...'>,
+ <data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>,
+...]
+```
+Получим соседние элементы с тем же родителем:
+```python
+>>> article.siblings
+[<data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>,
+ <data='<article class="product" data-id="3"><h3...' parent='<div class="product-list"> <article clas...'>]
+```
+Получим следующий соседний элемент:
+```python
+>>> article.next
+<data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>
+```
+Свойство `previous` работает аналогично:
+```python
+>>> article.previous # It's the first child, so it doesn't have a previous element
+>>> second_article = page.css('.product[data-id="2"]')[0]
+>>> second_article.previous
+<data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>
+```
+Можно быстро проверить, есть ли у элемента определённый класс:
+```python
+>>> article.has_class('product')
+True
+```
+Если одного родителя недостаточно, можно перебрать всех предков элемента:
+```python
+for ancestor in article.iterancestors():
+ # do something with it...
+```
+Также можно найти предка, который удовлетворяет условию. Передайте функцию, которая принимает объект [Selector](#selector) и возвращает `True`, если условие выполнено, или `False` в противном случае:
+```python
+>>> article.find_ancestor(lambda ancestor: ancestor.has_class('product-list'))
+<data='<div class="product-list"> <article clas...' parent='<body> <div class="product-list"> <artic...'>
+
+>>> article.find_ancestor(lambda ancestor: ancestor.css('.product-list')) # Same result, different approach
+<data='<div class="product-list"> <article clas...' parent='<body> <div class="product-list"> <artic...'>
+```
+## Selectors {#selectors}
+Класс `Selectors` представляет список объектов [Selector](#selector). Он наследует стандартный тип Python `List`, поэтому содержит все свойства и методы `List`, а также дополнительные методы для удобной работы с объектами [Selector](#selector) внутри него.
+
+Все методы и свойства [Selector](#selector), которые возвращают несколько элементов, возвращают экземпляр [Selectors](#selectors).
+
+Начиная с v0.4, все методы выбора возвращают объекты [Selector](#selector)/[Selectors](#selectors), даже для текстовых узлов и значений атрибутов. Текстовые узлы, выбранные через `::text`, `/text()`, `::attr()` или `/@attr`, оборачиваются в объекты [Selector](#selector). У них `tag` равен `"#text"`, а свойство `text` возвращает текстовое значение. Текст по-прежнему доступен напрямую, а остальные свойства возвращают пустые значения или значения по умолчанию.
+
+```python
+page.css('a::text') # -> Selectors (of text node Selectors)
+page.xpath('//a/text()') # -> Selectors
+page.css('a::text').get() # -> TextHandler (the first text value)
+page.css('a::text').getall() # -> TextHandlers (all text values)
+page.css('a::attr(href)') # -> Selectors
+page.xpath('//a/@href') # -> Selectors
+page.css('.price_color') # -> Selectors
+```
+
+### Методы извлечения данных {#data-extraction-methods}
+Начиная с v0.4, [Selector](#selector) и [Selectors](#selectors) предоставляют методы `get()`, `getall()` и их псевдонимы `extract_first` и `extract`, как в Scrapy. Старый метод `get_all()` удалён.
+
+**У объекта [Selector](#selector):**
+
+- `get()` возвращает `TextHandler`: для текстовых узлов это текстовое значение, для HTML-элементов это строка с внешним HTML элемента.
+- `getall()` возвращает список `TextHandlers` с одной строкой представления элемента.
+- `extract_first` является псевдонимом `get()`, а `extract` является псевдонимом `getall()`.
+
+```python
+>>> page.css('h3')[0].get() # Outer HTML of the element
+'<h3>Product 1</h3>'
+
+>>> page.css('h3::text')[0].get() # Text value of the text node
+'Product 1'
+```
+
+**У объекта [Selectors](#selectors):**
+
+- `get(default=None)` возвращает строковое представление **первого** элемента или `default`, если список пуст.
+- `getall()` преобразует **все** элементы в строки и возвращает список `TextHandlers`.
+- `extract_first` является псевдонимом `get()`, а `extract` является псевдонимом `getall()`.
+
+```python
+>>> page.css('.price::text').get() # First price text
+'$10.99'
+
+>>> page.css('.price::text').getall() # All price texts
+['$10.99', '$20.99', '$15.99']
+
+>>> page.css('.price::text').get('') # With default value
+'$10.99'
+```
+
+Эти методы работают со всеми способами выбора: CSS, XPath, `find` и другими. Это рекомендуемый способ извлекать текст и значения атрибутов в стиле Scrapy.
+
+Теперь посмотрим, какие ещё возможности добавляет класс [Selectors](#selectors).
+### Свойства {#properties_1}
+Помимо обычных операций со списками Python, таких как перебор и срезы, доступны следующие возможности:
+
+Можно выполнять CSS- и XPath-запросы прямо для содержащихся в списке объектов [Selector](#selector). Типы результатов такие же, как у методов `css` и `xpath` класса [Selector](#selector). Аргументы тоже совпадают, кроме отсутствующего здесь `adaptive`. Благодаря этому методы легко объединять в цепочки.
+```pycon
+>>> page.css('.product h3::text').getall()
+['Product 1', 'Product 2', 'Product 3']
+>>> page.css('.product').css('h3::text').getall()
+['Product 1', 'Product 2', 'Product 3']
+```
+Можно напрямую вызывать `re` и `re_first`. Они принимают те же аргументы, что и в классе [Selector](#selector). Подробнее о них читайте ниже в разделе [TextHandler](#texthandler).
+
+Однако здесь `re_first` работает иначе: вызывает `re` для каждого [Selector](#selector) и возвращает первый найденный результат. Метод `re` возвращает обычный объект [TextHandlers](#texthandlers), объединяя все экземпляры [TextHandler](#texthandler) в один [TextHandlers](#texthandlers).
+```pycon
+>>> page.css('.price::text').re(r'[\d.]+')
+['10.99', '20.99', '15.99']
+>>> page.css('.product h3::text').re(r'Product (\d+)')
+['1', '2', '3']
+```
+Метод `search` позволяет быстро искать среди объектов [Selector](#selector). Переданная функция должна принимать [Selector](#selector) первым аргументом и возвращать True/False. Метод вернёт первый [Selector](#selector), для которого условие выполнено, или `None`, если совпадений нет.
+
+```pycon
+>>> product = page.css('.product').search(lambda p: p.css('.price::text').get() == '$20.99')
+>>> product.css('h3::text').get()
+'Product 2'
+```
+Метод `filter` тоже принимает функцию, как `search`, но возвращает объект `Selectors` со всеми экземплярами [Selector](#selector), которые удовлетворяют условию.
+
+```pycon
+>>> products = page.css('.product').filter(lambda p: float(p.css('.price::text').re_first(r'[\d.]+')) > 15)
+>>> products.css('h3::text').getall()
+['Product 2', 'Product 3']
+```
+К первому и последнему элементу можно безопасно обращаться без риска ошибки индекса:
+```python
+>>> page.css('.product').first # First Selector or None
+<data='<article class="product" data-id="1"><h3...'>
+>>> page.css('.product').last # Last Selector or None
+<data='<article class="product" data-id="3"><h3...'>
+>>> page.css('.nonexistent').first # Returns None instead of raising IndexError
+```
+
+Если вам, как и мне, хочется короче записать число объектов [Selector](#selector) в [Selectors](#selectors), можно сделать так:
+```python
+page.css('.product').length
+```
+Это равнозначно следующей записи:
+```python
+len(page.css('.product'))
+```
+Да, как в JavaScript :)
+
+## TextHandler {#texthandler}
+Этот класс важно знать: все методы и свойства, которые должны вернуть строку, возвращают `TextHandler`. А вместо списка строк они возвращают [TextHandlers](#texthandlers).
+
+TextHandler наследует стандартную строку Python, поэтому поддерживает все обычные операции со строками. Зачем тогда отдельное имя?
+
+TextHandler добавляет методы и свойства, которых нет у стандартных строк Python. Мы сейчас их рассмотрим. Помните, что все классы возвращают строки как TextHandler. Это позволяет писать более короткий и удобный код. Можно также импортировать класс и применять его к любой строке, как описано [далее](../development/scrapling_custom_types.md).
+### Использование {#usage}
+Срезы, доступ по индексу и методы вроде `split`, `replace` и `strip` снова возвращают `TextHandler`. Поэтому их можно объединять в цепочки. Если найдёте метод или свойство, которое возвращает обычную строку вместо `TextHandler`, создайте issue, и мы исправим его.
+
+Начнём с методов `re` и `re_first`. Они есть и в классах [Selector](#selector), [Selectors](#selectors) и [TextHandlers](#texthandlers) и везде принимают одинаковые аргументы.
+
+- Метод `re` принимает первым аргументом строку или скомпилированное регулярное выражение. Он находит все совпадения и возвращает их как [TextHandlers](#texthandlers). Метод `re_first` принимает те же аргументы и работает похожим образом, но возвращает только первый результат как `TextHandler`.
+
+ Есть и другие полезные аргументы:
+
+ - **replace_entities**: по умолчанию включён. Заменяет HTML-сущности соответствующими символами.
+ - **clean_match**: по умолчанию выключен. Позволяет игнорировать пробельные символы, в том числе последовательности пробелов, при поиске совпадений.
+ - **case_sensitive**: по умолчанию включён. При отключении регулярное выражение компилируется без учёта регистра.
+
+ Вы уже видели эти примеры. Результат имеет тип [TextHandlers](#texthandlers), так как мы использовали `re`.
+ ```pycon
+ >>> page.css('.price::text').re(r'[\d.]+')
+ ['10.99', '20.99', '15.99']
+ >>> page.css('.product h3::text').re(r'Product (\d+)')
+ ['1', '2', '3']
+ ```
+ Чтобы показать остальные аргументы, возьмём отдельную строку для каждого примера:
+ ```python
+ >>> from scrapling import TextHandler
+ >>> test_string = TextHandler('hi there') # Hence the two spaces
+ >>> test_string.re('hi there')
+ >>> test_string.re('hi there', clean_match=True) # Using `clean_match` will clean the string before matching the regex
+ ['hi there']
+
+ >>> test_string2 = TextHandler('Oh, Hi Mark')
+ >>> test_string2.re_first('oh, hi Mark')
+ >>> test_string2.re_first('oh, hi Mark', case_sensitive=False) # Hence disabling `case_sensitive`
+ 'Oh, Hi Mark'
+
+ # Mixing arguments
+ >>> test_string.re('hi there', clean_match=True, case_sensitive=False)
+ ['hi there']
+ ```
+ Ещё одно преимущество использования `TextHandler`: свойство `html_content` тоже возвращает `TextHandler`, поэтому можно искать регулярным выражением прямо в HTML:
+ ```python
+ >>> page.html_content.re('div class=".*">(.*)</div')
+ ['In stock: 5', 'In stock: 3', 'Out of stock']
+ ```
+
+- Метод `.json()` быстро преобразует содержимое в объект JSON, если это возможно. Иначе он вызывает ошибку.
+ ```python
+ >>> page.css('#page-data::text').get()
+ '\n {\n "lastUpdated": "2024-09-22T10:30:00Z",\n "totalProducts": 3\n }\n '
+ >>> page.css('#page-data::text').get().json()
+ {'lastUpdated': '2024-09-22T10:30:00Z', 'totalProducts': 3}
+ ```
+ Если при выборе элемента вы не указали текстовый узел, например текст элемента или значение атрибута, текст элемента будет выбран автоматически:
+ ```python
+ >>> page.css('#page-data')[0].json()
+ {'lastUpdated': '2024-09-22T10:30:00Z', 'totalProducts': 3}
+ ```
+ Класс [Selector](#selector) добавляет ещё одну возможность. Допустим, мы работаем с такой страницей:
+ ```html
+ <html>
+ <body>
+ <div>
+ <script id="page-data" type="application/json">
+ {
+ "lastUpdated": "2024-09-22T10:30:00Z",
+ "totalProducts": 3
+ }
+ </script>
+ </div>
+ </body>
+ </html>
+ ```
+ У класса [Selector](#selector) есть уже знакомый метод `get_all_text`, который возвращает `TextHandler`.<br/><br/>
+ Если выполнить следующее:
+ ```python
+ >>> page.css('div::text').get().json()
+ ```
+ Возникнет ошибка: у тега `div` нет собственного текста, который можно преобразовать в JSON. У него вообще нет непосредственного текстового содержимого.<br/><br/>
+ В этом случае поможет метод `get_all_text`:
+ ```python
+ >>> page.css('div')[0].get_all_text(ignore_tags=[]).json()
+ {'lastUpdated': '2024-09-22T10:30:00Z', 'totalProducts': 3}
+ ```
+ Здесь я указал `ignore_tags`, потому что его значение по умолчанию равно `('script', 'style',)`.<br/><br/>
+ Ещё один связанный случай возникает при работе с Fetcher, которые мы рассмотрим позже. Допустим, вы получили такой JSON-ответ:
+ ```python
+ >>> page = Selector("""{"some_key": "some_value"}""")
+ ```
+ Класс [Selector](#selector) предназначен для HTML-страниц. Он воспринимает такой ответ как повреждённый HTML и исправляет его. Поэтому свойство `html_content` вернёт следующее:
+ ```python
+ >>> page.html_content
+ '<html><body><p>{"some_key": "some_value"}</p></body></html>'
+ ```
+ При этом метод `json` можно вызвать напрямую, и он сработает:
+ ```python
+ >>> page.json()
+ {'some_key': 'some_value'}
+ ```
+ Как это возможно, если у тега `html` нет непосредственного текста?<br/>
+ Для таких случаев, как JSON-ответы, класс [Selector](#selector) сохраняет исходную копию полученного содержимого. Метод `.json()` сначала проверяет эту копию и преобразует её в JSON. Если копии нет, как у отдельных элементов, он проверяет текст текущего элемента, а затем при необходимости использует `get_all_text`.<br/>
+
+- Полезный метод `.clean()` удаляет пробельные символы и последовательности пробелов и возвращает новый экземпляр `TextHandler`.
+```python
+>>> TextHandler('\n wonderful idea, \reh?').clean()
+'wonderful idea, eh?'
+```
+Аргумент `remove_entities` позволяет методу `clean` заменять HTML-сущности соответствующими символами.
+
+- Метод `.sort()` сортирует символы строки, как при сортировке списка:
+```python
+>>> TextHandler('acb').sort()
+'abc'
+```
+Можно сортировать и в обратном порядке:
+```python
+>>> TextHandler('acb').sort(reverse=True)
+'cba'
+```
+
+Со временем появятся и другие методы и свойства. Главное помнить: почти везде в библиотеке этот класс используется вместо обычных строк.
+
+## TextHandlers {#texthandlers}
+Как вы, наверное, догадались, этот класс похож на [Selectors](#selectors) и [Selector](#selector), но наследует поведение стандартного списка. Дополнительно он предоставляет методы `re` и `re_first`.
+
+Метод `re_first` здесь вызывает `re` для каждого [TextHandler](#texthandler) и возвращает первый результат или `None`. В остальном новых особенностей пока нет, но позже будут добавлены новые методы.
+
+## AttributesHandler {#attributeshandler}
+Это версия стандартного словаря Python, `dict`, доступная только для чтения. Она хранит атрибуты каждого элемента, то есть экземпляра [Selector](#selector).
+```python
+>>> print(page.find('script').attrib)
+{'id': 'page-data', 'type': 'application/json'}
+>>> type(page.find('script').attrib).__name__
+'AttributesHandler'
+```
+Благодаря режиму только для чтения этот класс использует меньше ресурсов, чем обычный словарь. При этом у него те же методы и свойства, кроме тех, которые изменяют или перезаписывают данные.
+
+Сейчас он добавляет две простые возможности:
+
+- Метод `search_values`.
+
+ В обычном словаре можно проверить наличие ключа через `dict.get("key_name")`. Но для поиска по значениям нужен дополнительный код. Этот метод делает это за вас: ищет среди значений атрибутов и возвращает словарь для каждого совпадения.
+
+ Простой пример:
+ ```python
+ >>> for i in page.find('script').attrib.search_values('page-data'):
+ print(i)
+ {'id': 'page-data'}
+ ```
+ Аргумент `partial` позволяет искать по части значения:
+ ```python
+ >>> for i in page.find('script').attrib.search_values('page', partial=True):
+ print(i)
+ {'id': 'page-data'}
+ ```
+ Предыдущие примеры условны. В реальной задаче метод можно использовать вместе с `find_all`, чтобы найти все элементы с определённым значением атрибута:
+ ```python
+ >>> page.find_all(lambda element: list(element.attrib.search_values('product')))
+ [<data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>,
+ <data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>,
+ <data='<article class="product" data-id="3"><h3...' parent='<div class="product-list"> <article clas...'>]
+ ```
+ У всех этих элементов значение атрибута `class` равно 'product'.
+
+ Здесь используется `list`, потому что `search_values` возвращает генератор. Сам генератор дал бы `True` для каждого элемента.
+
+- Свойство `json_string`.
+
+ Преобразует текущие атрибуты в строку JSON, если это возможно. Иначе вызывает ошибку.
+
+ ```python
+ >>>page.find('script').attrib.json_string
+ b'{"id":"page-data","type":"application/json"}'
+ ```
\ No newline at end of file
diff --git a/docs/locales/ru/parsing/selection.md b/docs/locales/ru/parsing/selection.md
new file mode 100644
index 0000000..1f5b2fa
--- /dev/null
+++ b/docs/locales/ru/parsing/selection.md
@@ -0,0 +1,521 @@
+---
+title: "Извлечение HTML-данных через CSS, XPath, текст и регулярные выражения"
+description: "Выбирайте HTML-элементы с помощью CSS, XPath, текста и регулярных выражений. Находите похожие элементы и извлекайте поля по примерам Scrapling."
+---
+
+# Поиск элементов {#querying-elements}
+Класс `Selector` разбирает HTML. Это сделано потому, что адаптивная функция не работает с XML. Для лент XML, RSS и Atom используйте [XMLFeedSpider](../spiders/generic-templates.md#xmlfeedspider): он применяет XML-парсер и передаёт вам каждый узел ленты напрямую.
+
+В Scrapling есть пять основных способов поиска элементов:
+
+1. CSS3-селекторы.
+2. XPath-селекторы.
+3. Поиск по фильтрам и условиям.
+4. Поиск элементов, содержимое которых содержит заданный текст.
+5. Поиск элементов, содержимое которых соответствует регулярному выражению.
+
+Есть и другие, косвенные способы поиска, но здесь мы подробно рассмотрим основные. Также разберём одну из самых полезных возможностей Scrapling: поиск элементов, похожих на уже найденный. К этому разделу можно перейти [сразу](#finding-similar-elements).
+
+Если вы только начинаете собирать данные с сайтов и ещё не умеете писать селекторы, советую начать с методов `find`/`find_all` [здесь](#filters-based-searching).
+
+## CSS/XPath-селекторы {#cssxpath-selectors}
+
+### Что такое CSS-селекторы? {#what-are-css-selectors}
+[CSS](https://en.wikipedia.org/wiki/CSS) задаёт стили HTML-документов. Селекторы связывают эти стили с определёнными HTML-элементами.
+
+Scrapling поддерживает CSS3-селекторы по [спецификации W3C](http://www.w3.org/TR/2011/REC-css3-selectors-20110929/). Для этого используется `cssselect`, поэтому список [поддерживаемых селекторов](https://cssselect.readthedocs.io/en/latest/#supported-selectors), псевдофункций и псевдоэлементов лучше смотреть в его документации.
+
+Scrapling также поддерживает несколько нестандартных псевдоэлементов:
+
+* ``::text`` выбирает текстовые узлы.
+* ``::attr(name)`` выбирает значения атрибута, где name обозначает имя нужного атрибута.
+
+Если вы работали со Scrapy или Parsel, правила будут знакомыми. Нет смысла менять то, к чему многие из нас уже привыкли :)
+
+Для выбора через CSS используйте метод `css`, который возвращает `Selectors`. Через `[0]` можно получить первый элемент, а через `.get()` / `.getall()` извлечь текст из результатов текстовых селекторов или селекторов атрибутов.
+
+### Что такое XPath-селекторы? {#what-are-xpath-selectors}
+[XPath](https://en.wikipedia.org/wiki/XPath) служит для выбора узлов XML-документов и также работает с HTML. Эта [шпаргалка](https://devhints.io/xpath) поможет освоить [XPath](https://en.wikipedia.org/wiki/XPath). Scrapling использует XPath напрямую через [lxml](https://lxml.de/).
+
+Как и с CSS, пользователям Scrapy и Parsel многое будет знакомо. Но Scrapling не реализует их дополнительную XPath-функцию `has-class`. Вместо неё у найденных элементов есть метод `has_class` с тем же назначением.
+
+Для выбора через XPath используйте метод `xpath`. Он работает по тем же правилам, что и описанный выше метод для CSS.
+
+> У методов `css` и `xpath` есть дополнительные аргументы для адаптивной функции. Здесь мы их не разбираем: этой возможности посвящена отдельная страница.
+
+### Примеры селекторов {#selectors-examples}
+Рассмотрим одинаковые задачи с CSS и XPath.
+
+Выберем все элементы с классом `product`:
+```python
+products = page.css('.product')
+products = page.xpath('//*[@class="product"]')
+```
+!!! info "Примечание"
+
+ XPath-вариант не даст точного результата, если у элемента есть ещё один класс. **Для выбора по классу лучше использовать CSS.**
+
+Выберем первый элемент с классом `product`:
+```python
+product = page.css('.product')[0]
+product = page.xpath('//*[@class="product"]')[0]
+```
+Получим текст первого элемента с тегом `h1`:
+```python
+title = page.css('h1::text').get()
+title = page.xpath('//h1//text()').get()
+```
+Это то же самое, что:
+```python
+title = page.css('h1')[0].text
+title = page.xpath('//h1')[0].text
+```
+Получим атрибут `href` первого элемента с тегом `a`:
+```python
+link = page.css('a::attr(href)').get()
+link = page.xpath('//a/@href').get()
+```
+Выберем текст первого элемента `h1`, который содержит `Phone` и находится внутри элемента с классом `product`:
+```python
+title = page.css('.product h1:contains("Phone")::text').get()
+title = page.xpath('//*[@class="product"]//h1[contains(text(),"Phone")]/text()').get()
+```
+Селекторы можно вкладывать и объединять в цепочки, если они находят результаты:
+```python
+page.css('.product')[0].css('h1:contains("Phone")::text').get()
+page.xpath('//*[@class="product"]')[0].xpath('.//h1[contains(text(),"Phone")]/text()').get()
+page.xpath('//*[@class="product"]')[0].css('h1:contains("Phone")::text').get()
+```
+Для XPath относительно текущего элемента используйте `.//`. Начальный `//` ищет во всём документе, даже если перед этим вы выбрали отдельный товар.
+
+Ещё один пример:
+
+Все ссылки, у которых атрибут 'href' содержит 'image':
+```python
+links = page.css('a[href*="image"]')
+links = page.xpath('//a[contains(@href, "image")]')
+for index, link in enumerate(links):
+ link_value = link.attrib['href'] # Cleaner than link.css('::attr(href)').get()
+ link_text = link.text
+ print(f'Link number {index} points to this url {link_value} with text content as "{link_text}"')
+```
+
+## Выбор по тексту {#text-content-selection}
+Scrapling умеет выбирать элементы по их непосредственному тексту двумя способами:
+
+1. Метод `find_by_text` ищет элементы, чей текст содержит заданную строку, и предоставляет дополнительные настройки.
+2. Метод `find_by_regex` ищет элементы, чей текст соответствует заданному регулярному выражению, и также предоставляет дополнительные настройки.
+
+Если хорошо знать регулярные выражения, всё, что делает `find_by_text`, можно сделать через `find_by_regex`. Но отдельные методы удобнее для пользователей с разным опытом.
+
+В `find_by_text` первым аргументом передаётся текст, а в `find_by_regex` регулярное выражение. Оба метода принимают следующие аргументы:
+
+* **first_match**: при `True` (по умолчанию) возвращается только первый найденный результат.
+* **case_sensitive**: при `True` учитывается регистр букв.
+* **clean_match**: при `True` пробельные символы и последовательности пробелов заменяются одним пробелом перед сравнением.
+
+По умолчанию `find_by_text` ищет точное совпадение: текст элемента должен полностью совпадать с переданной строкой. Для изменения этого поведения есть ещё один аргумент:
+
+* **partial**: при включении `find_by_text` возвращает элементы, которые содержат заданный текст. Полное совпадение больше не требуется.
+
+!!! abstract "Примечание"
+
+ Метод `find_by_regex` принимает первым аргументом обычную строку или скомпилированное регулярное выражение. Примеры приведены ниже.
+
+### Поиск похожих элементов {#finding-similar-elements}
+Одна из самых полезных возможностей Scrapling позволяет найти элементы, похожие на уже найденный. Идея взята из AutoScraper, но в Scrapling она работает с элементами, найденными любым способом. Часто её используют после поиска по тексту, как в AutoScraper, поэтому рассмотрим её здесь.
+
+Как это работает?
+
+Допустим, вы нашли товар по названию и хотите получить остальные товары из той же таблицы или контейнера. Вызовите `.find_similar()` у найденного элемента, и Scrapling выполнит следующие шаги:
+
+1. Найдёт все элементы страницы на той же глубине дерева DOM.
+2. Отбросит элементы, у которых не совпадает имя тега, тег родителя или тег родителя второго уровня.
+3. На этом этапе мы уже примерно на 99% уверены, что нашли нужные элементы. Для последней проверки Scrapling сравнит их атрибуты с атрибутами исходного элемента и отбросит недостаточно похожие. Порог сходства можно настроить, но советую менять его, только если настройки по умолчанию не дают нужного результата.
+
+Объяснение получилось длинным, но детали важны. Примеры будут в следующем разделе. Сначала перечислим аргументы метода:
+
+* **similarity_threshold**: порог сходства атрибутов из шага 3. По умолчанию 0,2, то есть атрибуты должны быть похожи хотя бы на 20%. Значение 0 отключает эту проверку. Но сначала советую прочитать об остальных аргументах.
+* **ignore_attributes**: имена атрибутов, которые нужно пропустить при последнем сравнении. По умолчанию `('href', 'src',)`, потому что URL у разных элементов могут сильно различаться.
+* **match_text**: при `True` текст элемента тоже учитывается в сравнении на шаге 3. Обычно это не требуется, но зависит от задачи.
+
+Теперь рассмотрим примеры.
+
+### Примеры {#examples}
+Посмотрим, как находить элементы по обычному тексту и регулярным выражениям.
+
+В этих примерах используется класс `Fetcher`. Подробнее о нём расскажем позже.
+```python
+from scrapling.fetchers import Fetcher
+page = Fetcher.get('https://books.toscrape.com/index.html')
+```
+Найдём первый элемент, текст которого полностью совпадает с заданной строкой:
+```python
+>>> page.find_by_text('Tipping the Velvet')
+<data='<a href="catalogue/tipping-the-velvet_99...' parent='<h3><a href="catalogue/tipping-the-velve...'>
+```
+С помощью `page.urljoin` получим полный URL из относительного `href`:
+```python
+>>> page.find_by_text('Tipping the Velvet').attrib['href']
+'catalogue/tipping-the-velvet_999/index.html'
+>>> page.urljoin(page.find_by_text('Tipping the Velvet').attrib['href'])
+'https://books.toscrape.com/catalogue/tipping-the-velvet_999/index.html'
+```
+Получим все совпадения, если их несколько. Обратите внимание, что возвращается список:
+```python
+>>> page.find_by_text('Tipping the Velvet', first_match=False)
+[<data='<a href="catalogue/tipping-the-velvet_99...' parent='<h3><a href="catalogue/tipping-the-velve...'>]
+```
+Получим все элементы, содержащие слово `the`, с помощью частичного совпадения:
+```python
+>>> results = page.find_by_text('the', partial=True, first_match=False)
+>>> [i.text for i in results]
+['A Light in the ...',
+ 'Tipping the Velvet',
+ 'The Requiem Red',
+ 'The Dirty Little Secrets ...',
+ 'The Coming Woman: A ...',
+ 'The Boys in the ...',
+ 'The Black Maria',
+ 'Mesaerion: The Best Science ...',
+ "It's Only the Himalayas"]
+```
+Поиск не учитывает регистр, поэтому результаты содержат и `The`, и строчное `the`. Ограничим поиск элементами с `the`:
+```python
+>>> results = page.find_by_text('the', partial=True, first_match=False, case_sensitive=True)
+>>> [i.text for i in results]
+['A Light in the ...',
+ 'Tipping the Velvet',
+ 'The Boys in the ...',
+ "It's Only the Himalayas"]
+```
+Получим первый элемент, текст которого соответствует регулярному выражению для цены:
+```python
+>>> page.find_by_regex(r'£[\d\.]+')
+<data='<p class="price_color">£51.77</p>' parent='<div class="product_price"> <p class="pr...'>
+>>> page.find_by_regex(r'£[\d\.]+').text
+'£51.77'
+```
+Можно также передать скомпилированное выражение. Scrapling распознает тип аргумента:
+```python
+>>> import re
+>>> regex = re.compile(r'£[\d\.]+')
+>>> page.find_by_regex(regex)
+<data='<p class="price_color">£51.77</p>' parent='<div class="product_price"> <p class="pr...'>
+>>> page.find_by_regex(regex).text
+'£51.77'
+```
+Получим все элементы, соответствующие регулярному выражению:
+```python
+>>> page.find_by_regex(r'£[\d\.]+', first_match=False)
+[<data='<p class="price_color">£51.77</p>' parent='<div class="product_price"> <p class="pr...'>,
+ <data='<p class="price_color">£53.74</p>' parent='<div class="product_price"> <p class="pr...'>,
+ <data='<p class="price_color">£50.10</p>' parent='<div class="product_price"> <p class="pr...'>,
+ <data='<p class="price_color">£47.82</p>' parent='<div class="product_price"> <p class="pr...'>,
+ ...]
+```
+И так далее.
+
+Найдём все элементы, похожие на текущий по расположению и атрибутам. В этом примере пропустим атрибут 'title' при сравнении:
+```python
+>>> element = page.find_by_text('Tipping the Velvet')
+>>> element.find_similar(ignore_attributes=['title'])
+[<data='<a href="catalogue/a-light-in-the-attic_...' parent='<h3><a href="catalogue/a-light-in-the-at...'>,
+ <data='<a href="catalogue/soumission_998/index....' parent='<h3><a href="catalogue/soumission_998/in...'>,
+ <data='<a href="catalogue/sharp-objects_997/ind...' parent='<h3><a href="catalogue/sharp-objects_997...'>,
+...]
+```
+Обратите внимание: найдено 19 элементов, а не 20. Сам текущий элемент не входит в результаты.
+```python
+>>> len(element.find_similar(ignore_attributes=['title']))
+19
+```
+Получим атрибут `href` всех похожих элементов:
+```python
+>>> [
+ element.attrib['href']
+ for element in element.find_similar(ignore_attributes=['title'])
+]
+['catalogue/a-light-in-the-attic_1000/index.html',
+ 'catalogue/soumission_998/index.html',
+ 'catalogue/sharp-objects_997/index.html',
+ ...]
+```
+Немного усложним задачу: получим данные всех книг, используя найденный элемент как отправную точку.
+```python
+>>> first_product = element.parent.parent
+>>> for product in [first_product, *first_product.find_similar()]:
+ print({
+ "name": product.css('h3 a::text').get(),
+ "price": product.css('.price_color')[0].re_first(r'[\d\.]+'),
+ "stock": product.css('.availability::text').getall()[-1].clean()
+ })
+{'name': 'Tipping the Velvet', 'price': '53.74', 'stock': 'In stock'}
+{'name': 'A Light in the ...', 'price': '51.77', 'stock': 'In stock'}
+{'name': 'Soumission', 'price': '50.10', 'stock': 'In stock'}
+{'name': 'Sharp Objects', 'price': '47.82', 'stock': 'In stock'}
+...
+```
+### Расширенные примеры {#advanced-examples}
+Вот более сложные и практические примеры с методом `find_similar`.
+
+Извлечение товаров интернет-магазина:
+```python
+def extract_product_grid(page):
+ # Find the first product card
+ first_product = page.find_by_text('Add to Cart').find_ancestor(
+ lambda e: e.has_class('product-card')
+ )
+
+ # Find similar product cards
+ products = [first_product, *first_product.find_similar()]
+
+ return [
+ {
+ 'name': p.css('h3::text').get(),
+ 'price': p.css('.price::text').re_first(r'\d+\.\d{2}'),
+ 'stock': 'In stock' in p.get_all_text(),
+ 'rating': p.css('.rating')[0].attrib.get('data-rating')
+ }
+ for p in products
+ ]
+```
+Извлечение строк таблицы:
+```python
+def extract_table_data(page):
+ # Find the first data row
+ first_row = page.css('table tbody tr')[0]
+
+ # Find similar rows
+ rows = [first_row, *first_row.find_similar()]
+
+ return [
+ {
+ 'column1': row.css('td:nth-child(1)::text').get(),
+ 'column2': row.css('td:nth-child(2)::text').get(),
+ 'column3': row.css('td:nth-child(3)::text').get()
+ }
+ for row in rows
+ ]
+```
+Извлечение полей формы:
+```python
+def extract_form_fields(page):
+ # Find first form field container
+ first_field = page.css('input')[0].find_ancestor(
+ lambda e: e.has_class('form-field')
+ )
+
+ # Find similar field containers
+ fields = [first_field, *first_field.find_similar()]
+
+ return [
+ {
+ 'label': f.css('label::text').get(),
+ 'type': f.css('input')[0].attrib.get('type'),
+ 'required': 'required' in f.css('input')[0].attrib
+ }
+ for f in fields
+ ]
+```
+Извлечение отзывов с сайта:
+```python
+def extract_reviews(page):
+ # Find first review
+ first_review = page.find_by_text('Great product!')
+ review_container = first_review.find_ancestor(
+ lambda e: e.has_class('review')
+ )
+
+ # Find similar reviews
+ all_reviews = [review_container, *review_container.find_similar()]
+
+ return [
+ {
+ 'text': r.css('.review-text::text').get(),
+ 'rating': r.attrib.get('data-rating'),
+ 'author': r.css('.reviewer::text').get()
+ }
+ for r in all_reviews
+ ]
+```
+## Поиск по фильтрам {#filters-based-searching}
+Это один из самых удобных способов поиска в Scrapling. Он обладает широкими возможностями, а новичкам его проще освоить, чем написание селекторов.
+
+Методы `find_all` и `find` созданы по образцу `find_all` из BeautifulSoup. Они принимают несколько фильтров и находят элементы страницы, которые удовлетворяют всем условиям.
+
+Аргументы обрабатываются так:
+
+* Строка считается именем тега.
+* Перебираемый объект, например List/Tuple/Set, считается набором имён тегов.
+* Словарь задаёт имена атрибутов HTML-элементов и их значения.
+* Регулярные выражения фильтруют элементы по содержимому, как метод `find_by_regex`.
+* Функции используются для фильтрации элементов.
+* Именованный аргумент задаёт имя HTML-атрибута и его значение.
+
+Метод собирает все переданные аргументы. Каждый фильтр передаёт свой результат следующему фильтру.
+
+Элементы текущей страницы или элемента фильтруются в таком порядке:
+
+1. Выбираются элементы с заданными именами тегов.
+2. Выбираются элементы, соответствующие всем заданным атрибутам. Если первый фильтр уже применялся, проверяются только его результаты.
+3. Выбираются элементы, соответствующие всем регулярным выражениям. Если предыдущие фильтры применялись, проверяются только их результаты.
+4. Выбираются элементы, удовлетворяющие всем переданным функциям. Если предыдущие фильтры применялись, проверяются только их результаты.
+
+!!! note "Примечания"
+
+ 1. Обработка начинается с первого доступного фильтра в этом порядке. Если имена тегов не переданы, но заданы атрибуты, поиск начинается с шага 2.
+ 2. Порядок передачи аргументов не имеет значения. Используется только порядок, описанный выше.
+
+Примеры помогут разобраться :)
+
+### Примеры {#examples_1}
+```python
+from scrapling.fetchers import Fetcher
+page = Fetcher.get('https://quotes.toscrape.com/')
+```
+Найдём все элементы с тегом `div`:
+```python
+>>> page.find_all('div')
+[<data='<div class="container"> <div class="row...' parent='<body> <div class="container"> <div clas...'>,
+ <data='<div class="row header-box"> <div class=...' parent='<div class="container"> <div class="row...'>,
+...]
+```
+Найдём все элементы div с классом `quote`:
+```python
+>>> page.find_all('div', class_='quote')
+[<data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,
+ <data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,
+...]
+```
+То же самое другим способом:
+```python
+>>> page.find_all('div', {'class': 'quote'})
+[<data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,
+ <data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,
+...]
+```
+Найдём все элементы с классом `quote`:
+```python
+>>> page.find_all({'class': 'quote'})
+[<data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,
+ <data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,
+...]
+```
+Найдём все элементы div с классом `quote`, внутри которых есть элемент `.text`, содержащий слово 'world':
+```python
+>>> page.find_all('div', {'class': 'quote'}, lambda e: "world" in e.css('.text::text').get())
+[<data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>]
+```
+Найдём все элементы с дочерними элементами:
+```python
+>>> page.find_all(lambda element: len(element.children) > 0)
+[<data='<html lang="en"><head><meta charset="UTF...'>,
+ <data='<head><meta charset="UTF-8"><title>Quote...' parent='<html lang="en"><head><meta charset="UTF...'>,
+ <data='<body> <div class="container"> <div clas...' parent='<html lang="en"><head><meta charset="UTF...'>,
+...]
+```
+Найдём все элементы, содержащие слово 'world':
+```python
+>>> page.find_all(lambda element: "world" in element.text)
+[<data='<span class="text" itemprop="text">“The...' parent='<div class="quote" itemscope itemtype="h...'>,
+ <data='<a class="tag" href="/tag/world/page/1/"...' parent='<div class="tags"> Tags: <meta class="ke...'>]
+```
+Найдём все элементы span, соответствующие регулярному выражению:
+```python
+>>> page.find_all('span', re.compile(r'world'))
+[<data='<span class="text" itemprop="text">“The...' parent='<div class="quote" itemscope itemtype="h...'>]
+```
+Найдём все элементы div и span с классом 'quote'. Таких span нет, поэтому вернутся только div:
+```python
+>>> page.find_all(['div', 'span'], {'class': 'quote'})
+[<data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,
+ <data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,
+...]
+```
+Объединим разные условия:
+```python
+>>> page.find_all({'itemtype':"http://schema.org/CreativeWork"}, 'div').css('.author::text').getall()
+['Albert Einstein',
+ 'J.K. Rowling',
+...]
+```
+Полезный приём: найдём все элементы, у которых значение `href` заканчивается словом 'Einstein':
+```python
+>>> page.find_all({'href$': 'Einstein'})
+[<data='<a href="/author/Albert-Einstein">(about...' parent='<span>by <small class="author" itemprop=...'>,
+ <data='<a href="/author/Albert-Einstein">(about...' parent='<span>by <small class="author" itemprop=...'>,
+ <data='<a href="/author/Albert-Einstein">(about...' parent='<span>by <small class="author" itemprop=...'>]
+```
+Ещё один приём: найдём все элементы, у которых `href` содержит '/author/':
+```python
+>>> page.find_all({'href*': '/author/'})
+[<data='<a href="/author/Albert-Einstein">(about...' parent='<span>by <small class="author" itemprop=...'>,
+ <data='<a href="/author/J-K-Rowling">(about)</a...' parent='<span>by <small class="author" itemprop=...'>,
+ <data='<a href="/author/Albert-Einstein">(about...' parent='<span>by <small class="author" itemprop=...'>,
+...]
+```
+И так далее.
+
+## Создание селекторов {#generating-selectors}
+Для любого элемента можно создать CSS- или XPath-селектор и использовать его здесь или в другом месте. При этом неважно, каким способом вы нашли элемент.
+
+Создадим короткий CSS-селектор для `url_element`. Если сократить его нельзя, получится полный селектор:
+```python
+>>> url_element = page.find({'href*': '/author/'})
+>>> url_element.generate_css_selector
+'body > div > div:nth-of-type(2) > div > div > span:nth-of-type(2) > a'
+```
+Создадим полный CSS-селектор для `url_element` от начала страницы:
+```python
+>>> url_element.generate_full_css_selector
+'body > div > div:nth-of-type(2) > div > div > span:nth-of-type(2) > a'
+```
+Создадим короткий XPath-селектор для `url_element`. Если сократить его нельзя, получится полный селектор:
+```python
+>>> url_element.generate_xpath_selector
+'//body/div/div[2]/div/div/span[2]/a'
+```
+Создадим полный XPath-селектор для `url_element` от начала страницы:
+```python
+>>> url_element.generate_full_xpath_selector
+'//body/div/div[2]/div/div/span[2]/a'
+```
+!!! abstract "Примечание"
+
+ При создании короткого селектора Scrapling ищет уникальный элемент, например с атрибутом `id`, на котором можно остановить путь. В нашем случае такого элемента нет, поэтому короткий и полный селекторы совпадают.
+
+## Селекторы и регулярные выражения {#using-selectors-with-regular-expressions}
+Как в `parsel`/`scrapy`, методы `re` и `re_first` извлекают данные с помощью регулярных выражений. Но в Scrapling они доступны почти во всех классах, включая `Selector`/`Selectors`/`TextHandler` и `TextHandlers`. Поэтому их можно вызывать прямо у элемента, даже если вы не выбрали текстовый узел.
+
+Подробно мы разберём их при изучении класса [TextHandler](main_classes.md#texthandler). Пока посмотрим на общие примеры:
+```python
+>>> page.css('.price_color')[0].re_first(r'[\d\.]+')
+'51.77'
+
+>>> page.css('.price_color').re_first(r'[\d\.]+')
+'51.77'
+
+>>> page.css('.price_color').re(r'[\d\.]+')
+['51.77',
+ '53.74',
+ '50.10',
+ '47.82',
+ '54.23',
+...]
+
+>>> page.css('.product_pod h3 a::attr(href)').re(r'catalogue/(.*)/index.html')
+['a-light-in-the-attic_1000',
+ 'tipping-the-velvet_999',
+ 'soumission_998',
+ 'sharp-objects_997',
+...]
+
+>>> filtering_function = lambda e: e.parent.tag == 'h3' and e.parent.parent.has_class('product_pod') # As above selector
+>>> page.find('a', filtering_function).attrib['href'].re(r'catalogue/(.*)/index.html')
+['a-light-in-the-attic_1000']
+
+>>> page.find_by_text('Tipping the Velvet').attrib['href'].re(r'catalogue/(.*)/index.html')
+['tipping-the-velvet_999']
+```
+Думаю, основная идея понятна. На следующей странице мы подробнее рассмотрим эти методы вместе с классом [TextHandler](main_classes.md#texthandler).
\ No newline at end of file
diff --git a/docs/locales/ru/spiders/advanced.md b/docs/locales/ru/spiders/advanced.md
new file mode 100644
index 0000000..e2928d8
--- /dev/null
+++ b/docs/locales/ru/spiders/advanced.md
@@ -0,0 +1,430 @@
+---
+title: "Управление обходом: AutoThrottle, контрольные точки, кеш и потоковая выдача"
+description: "Настройте скорость и число одновременных запросов. Узнайте о кеше ответов, паузе и возобновлении, потоковой выдаче записей и сохранении состояния."
+---
+
+# Расширенные возможности {#advanced-usages}
+
+## Введение {#introduction}
+
+!!! success "Что нужно знать"
+
+ 1. Прочитайте страницу [Начало работы](getting-started.md), чтобы научиться создавать и запускать простого паука.
+
+Здесь описаны расширенные возможности пауков: управление одновременными запросами, пауза и возобновление, потоковая выдача, хуки жизненного цикла, статистика и журналирование.
+
+## Число одновременных запросов {#concurrency-control}
+
+Следующие атрибуты класса управляют нагрузкой при обходе:
+
+| Атрибут | По умолчанию | Описание |
+|----------------------------------|---------|------------------------------------------------------------------|
+| `concurrent_requests` | `4` | Максимальное число запросов, которые обрабатываются одновременно |
+| `concurrent_requests_per_domain` | `0` | Максимальное число одновременных запросов к одному домену. 0 означает отсутствие ограничения для домена |
+| `download_delay` | `0.0` | Задержка перед каждым запросом в секундах |
+| `robots_txt_obey` | `False` | Соблюдать правила robots.txt: Disallow, Crawl-delay, Request-rate |
+
+```python
+class PoliteSpider(Spider):
+ name = "polite"
+ start_urls = ["https://example.com"]
+
+ # Be gentle with the server
+ concurrent_requests = 4
+ concurrent_requests_per_domain = 2
+ download_delay = 1.0 # Wait 1 second between requests
+
+ async def parse(self, response: Response):
+ yield {"title": response.css("title::text").get("")}
+```
+
+При заданном `concurrent_requests_per_domain` каждый домен получает своё ограничение в дополнение к общему. Это удобно при обходе нескольких доменов: можно выполнять много запросов в целом, не перегружая отдельный сайт.
+
+!!! tip
+
+ `download_delay` добавляет постоянную задержку перед каждым запросом независимо от домена. Это простой способ ограничить частоту запросов.
+
+## AutoThrottle {#autothrottle}
+
+Постоянную задержку `download_delay` приходится подбирать: слишком малая приводит к блокировкам, слишком большая затягивает обход. AutoThrottle измеряет скорость ответов сайта и сам меняет задержку для каждого домена. Быстрые серверы обходятся быстрее, а медленные или блокирующие запросы получают меньше нагрузки.
+
+| Атрибут | По умолчанию | Описание |
+|------------------------------------|---------|-------------------------------------------------------------------|
+| `autothrottle_enabled` | `False` | Включить адаптивную задержку |
+| `autothrottle_start_delay` | `5.0` | Задержка перед первым запросом к домену |
+| `autothrottle_max_delay` | `60.0` | Наибольшая допустимая задержка |
+| `autothrottle_target_concurrency` | `None` | Целевое число одновременных запросов к домену, см. ниже |
+| `autothrottle_block_backoff` | `True` | Удваивать задержку домена при каждой блокировке |
+
+```python
+class AdaptiveSpider(Spider):
+ name = "adaptive"
+ start_urls = ["https://example.com"]
+
+ concurrent_requests = 8
+ concurrent_requests_per_domain = 1
+
+ autothrottle_enabled = True
+ autothrottle_start_delay = 2.0
+ autothrottle_max_delay = 30.0
+
+ async def parse(self, response: Response):
+ yield {"title": response.css("title::text").get("")}
+```
+
+После каждого ответа задержка приближается к времени ответа сервера. Если сайт отвечает за 0,5 секунды, задержка устанавливается примерно на 0,5 секунды. Это соответствует примерно одному выполняемому запросу. Целевое число запросов к домену выбирается так: заданный `autothrottle_target_concurrency`, затем `concurrent_requests_per_domain`, иначе 1. Поэтому отдельную цель обычно задавать не нужно: используется уже настроенное ограничение для домена, и задержка делится на это число. Резкое увеличение времени ответа учитывается сразу, без усреднения. Паук сразу замедляется при проблемах на сервере, а ускоряется постепенно.
+
+### Замедление при блокировке {#backing-off-when-blocked}
+
+По одному времени ответа нельзя обнаружить ограничение частоты. Ответ `429`, `403` или страница с CAPTCHA обычно приходят *быстрее* обычного содержимого. Если учитывать только время, это выглядит как повод ускориться. Поэтому любой ответ со статусом вне диапазона 2xx или ответ, который `is_blocked()` считает заблокированным, **удваивает** задержку домена:
+
+```
+0.5s -> 1s -> 2s -> 4s -> 8s ... (up to autothrottle_max_delay)
+```
+
+Паук продолжает замедляться, пока сайт отказывает в доступе. Когда нормальные ответы возвращаются, обычное усреднение постепенно снижает задержку до скорости сервера. Работа восстанавливается без перезапуска.
+
+Если сайт передаёт точное время ожидания в заголовке `Retry-After` ответа `429` или `503`, оно используется вместо удвоения. Поддерживается число (`Retry-After: 120`) и дата в формате HTTP.
+
+Установите `autothrottle_block_backoff = False`, чтобы отключить это поведение и учитывать только время ответа. Тогда блокировка лишь не даст пауку ускориться.
+
+Итоговая задержка для каждого домена доступна в статистике:
+
+```python
+result = AdaptiveSpider().start()
+print(result.stats.autothrottle_delays) # {'example.com': 0.62}
+```
+
+!!! note "Примечания"
+
+ * `download_delay` и задержки robots.txt задают нижнюю границу, но `autothrottle_max_delay` ограничивает и её. Максимум должен быть не меньше задержки из настройки или robots.txt, которую нужно соблюдать.<br/>
+ * `concurrent_requests_per_domain` выполняет две задачи: ограничивает число запросов к домену и служит целью AutoThrottle. Поэтому отдельная цель обычно не нужна. Рекомендуется задать этот параметр: пока запрос ожидает задержку домена, он занимает место в общем ограничении. Без ограничения для домена такие ожидающие запросы используют места, общие для всех доменов.<br/>
+ * Измеряется полное время загрузки, включая внутренние повторы, а для браузерных сессий и время отрисовки страницы.<br/>
+ * `autothrottle_max_delay` ограничивает всё, включая `Retry-After`. Если сайт просит ждать дольше этого максимума, увеличьте `autothrottle_max_delay`.<br/>
+ * Вычисленные задержки не входят в контрольную точку. После паузы и возобновления каждый домен снова начинает с `autothrottle_start_delay`.
+
+## Использование uvloop {#using-uvloop}
+
+Метод `start()` принимает параметр `use_uvloop`, чтобы использовать более быстрый цикл событий [uvloop](https://github.com/MagicStack/uvloop)/[winloop](https://github.com/nicktimko/winloop), если он доступен:
+
+```python
+result = MySpider().start(use_uvloop=True)
+```
+
+Это может ускорить обход с большим объёмом ввода-вывода. Установите `uvloop` (Linux/macOS) или `winloop` (Windows) отдельно.
+
+## Пауза и возобновление {#pause-resume}
+
+Паук поддерживает корректную остановку и возобновление через контрольные точки. Чтобы включить их, передайте каталог `crawldir` в конструктор паука:
+
+```python
+spider = MySpider(crawldir="crawl_data/my_spider")
+result = spider.start()
+
+if result.paused:
+ print("Crawl was paused. Run again to resume.")
+else:
+ print("Crawl completed!")
+```
+
+### Как это работает {#how-it-works}
+
+1. **Пауза**: нажмите `Ctrl+C` во время обхода. Паук дождётся завершения всех текущих запросов, сохранит контрольную точку с ожидающими запросами и множеством отпечатков уже встреченных запросов, затем завершит работу.
+2. **Принудительная остановка**: нажмите `Ctrl+C` ещё раз, чтобы сразу остановиться, не дожидаясь активных задач.
+3. **Возобновление**: запустите паука с тем же `crawldir`. Он найдёт контрольную точку, восстановит очередь и множество отпечатков, затем продолжит работу с места остановки, пропустив `start_requests()`.
+4. **Очистка**: после обычного завершения обхода, а не паузы, файлы контрольных точек удаляются автоматически.
+
+**Контрольные точки также сохраняются периодически во время обхода. По умолчанию каждые 5 минут.**
+
+Интервал можно изменить:
+
+```python
+# Save checkpoint every 2 minutes
+spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)
+```
+
+Запись на диск атомарная, что защищает файл от частичной записи.
+
+!!! tip
+
+ При использовании `start()` нажатие `Ctrl+C` корректно завершает паука, даже если контрольные точки не включены. Повторное нажатие сразу останавливает его.
+
+### Как узнать, что обход возобновлён {#knowing-if-youre-resuming}
+
+Хук `on_start()` получает флаг `resuming`:
+
+```python
+async def on_start(self, resuming: bool = False):
+ if resuming:
+ self.logger.info("Resuming from checkpoint!")
+ else:
+ self.logger.info("Starting fresh crawl")
+```
+
+## Режим разработки {#development-mode}
+
+При доработке `parse()` повторная загрузка страниц на каждом запуске занимает время и создаёт лишнюю нагрузку. Режим разработки сохраняет каждый ответ на диск при первом запуске, а затем читает ответы с диска. Можно менять селекторы и запускать паука сколько угодно раз без повторной загрузки тех же страниц.
+
+Установите у паука `development_mode = True`:
+
+```python
+class MySpider(Spider):
+ name = "my_spider"
+ start_urls = ["https://example.com"]
+ development_mode = True
+
+ async def parse(self, response: Response):
+ yield {"title": response.css("title::text").get("")}
+```
+
+Первый запуск загружает страницы как обычно и сохраняет ответы на диск. Последующие запуски берут ответы на те же запросы из кеша, без загрузки страниц. При `robots_txt_obey=True` правила robots.txt проверяются перед поиском в кеше.
+
+### Расположение кеша {#cache-location}
+
+По умолчанию ответы сохраняются в `.scrapling_cache/{spider.name}/` относительно текущего рабочего каталога. Это каталог, из которого вы запустили паука, **а не** каталог его скрипта. Путь можно изменить через `development_cache_dir`:
+
+```python
+class MySpider(Spider):
+ name = "my_spider"
+ start_urls = ["https://example.com"]
+ development_mode = True
+ development_cache_dir = "/tmp/my_spider_cache"
+```
+
+### Как это работает {#how-it-works_1}
+
+1. **Ключ кеша**: отпечаток запроса. Изменение влияющих на него атрибутов (`fp_include_kwargs`, `fp_include_headers`, `fp_keep_fragments`) приводит к новой загрузке.
+2. **Формат хранения**: отдельный JSON-файл `{fingerprint_hex}.json` для каждого ответа. Тело кодируется в base64 для точного сохранения двоичных данных. Запись атомарная: временный файл и переименование.
+3. **Чтение из кеша**: при совпадении движок пропускает загрузку страницы, включая `download_delay`, ограничение частоты и повторы через `is_blocked()`. Ответ из кеша сразу передаётся обработчику.
+4. **Статистика**: запросы из кеша по-прежнему учитываются в `requests_count`, `response_bytes` и счётчиках статусов. Поэтому статистика выглядит как при обычном обходе. Дополнительные счётчики `cache_hits` и `cache_misses` показывают работу кеша.
+
+### Очистка кеша {#clearing-the-cache}
+
+Автоматического срока действия нет. Чтобы заново загрузить страницы, удалите каталог кеша или напрямую вызовите `clear()` у менеджера.
+
+!!! warning
+
+ Режим разработки предназначен только для разработки. Срок действия ответов в кеше не ограничен, а чтение из него пропускает ограничение частоты и повторы заблокированных запросов. Не оставляйте `development_mode = True` у паука в рабочей среде.
+
+## Потоковая выдача {#streaming}
+
+Для долгих обходов или приложений, которым нужны записи сразу после извлечения, используйте `stream()` вместо `start()`:
+
+```python
+import anyio
+
+async def main():
+ spider = MySpider()
+ async for item in spider.stream():
+ print(f"Got item: {item}")
+ # Access real-time stats
+ print(f"Items so far: {spider.stats.items_scraped}")
+ print(f"Requests made: {spider.stats.requests_count}")
+
+anyio.run(main)
+```
+
+Главные отличия от `start()`:
+
+- `stream()` нужно вызывать из асинхронного контекста.
+- Записи выдаются по одной сразу после извлечения, а не собираются в список.
+- Во время перебора доступен `spider.stats` с текущей статистикой.
+
+!!! abstract
+
+ Все показатели, доступные через `spider.stats`, описаны [ниже](#results-statistics).
+
+Потоковую выдачу можно совместить с контрольными точками. Так удобно создавать интерфейсы с текущими данными и возможностью поставить обход на паузу или возобновить его.
+
+```python
+import anyio
+
+async def main():
+ spider = MySpider(crawldir="crawl_data/my_spider")
+ async for item in spider.stream():
+ print(f"Got item: {item}")
+ # Access real-time stats
+ print(f"Items so far: {spider.stats.items_scraped}")
+ print(f"Requests made: {spider.stats.requests_count}")
+
+anyio.run(main)
+```
+В этом примере можно вызвать `spider.pause()`, чтобы остановить паука. Без включённых контрольных точек этот вызов просто завершит обход.
+
+## Хуки жизненного цикла {#lifecycle-hooks}
+
+Паук предоставляет хуки, которые можно переопределить для своей логики на разных этапах обхода:
+
+### on_start {#on_start}
+
+Вызывается перед началом обхода. Подходит для подготовки, например загрузки данных или создания ресурсов:
+
+```python
+async def on_start(self, resuming: bool = False):
+ self.logger.info("Spider starting up")
+ # Load seed URLs from a database, initialize counters, etc.
+```
+
+### on_close {#on_close}
+
+Вызывается после завершения или приостановки обхода. Подходит для освобождения ресурсов:
+
+```python
+async def on_close(self):
+ self.logger.info("Spider shutting down")
+ # Close database connections, flush buffers, etc.
+```
+
+### on_error {#on_error}
+
+Вызывается, когда запрос завершается исключением. Подходит для учёта ошибок и своей логики восстановления:
+
+```python
+async def on_error(self, request: Request, error: Exception):
+ self.logger.error(f"Failed: {request.url} - {error}")
+ # Log to error tracker, save failed URL for later, etc.
+```
+
+### on_scraped_item {#on_scraped_item}
+
+Вызывается для каждой извлечённой записи перед добавлением в результаты. Верните запись с изменениями или без них, чтобы сохранить её, либо `None`, чтобы отбросить:
+
+```python
+async def on_scraped_item(self, item: dict) -> dict | None:
+ # Drop items without a title
+ if not item.get("title"):
+ return None
+
+ # Modify items (e.g., add timestamps)
+ item["scraped_at"] = "2026-01-01"
+ return item
+```
+
+!!! tip
+
+ Через этот хук можно передавать записи в свои цепочки обработки и удалять их из результатов паука.
+
+### start_requests {#start_requests}
+
+Переопределите `start_requests()`, чтобы создавать начальные запросы своей логикой вместо `start_urls`:
+
+```python
+async def start_requests(self):
+ # POST request to log in first
+ yield Request(
+ "https://example.com/login",
+ method="POST",
+ data={"user": "admin", "pass": "secret"},
+ callback=self.after_login,
+ )
+
+async def after_login(self, response: Response):
+ # Now crawl the authenticated pages
+ yield response.follow("/dashboard", callback=self.parse)
+```
+
+## Результаты и статистика {#results-statistics}
+
+`CrawlResult`, возвращаемый `start()`, содержит извлечённые записи и подробную статистику:
+
+```python
+result = MySpider().start()
+
+# Items
+print(f"Total items: {len(result.items)}")
+result.items.to_json("output.json", indent=True)
+
+# Did the crawl complete?
+print(f"Completed: {result.completed}")
+print(f"Paused: {result.paused}")
+
+# Statistics
+stats = result.stats
+print(f"Requests: {stats.requests_count}")
+print(f"Failed: {stats.failed_requests_count}")
+print(f"Blocked: {stats.blocked_requests_count}")
+print(f"Offsite filtered: {stats.offsite_requests_count}")
+print(f"Robots.txt disallowed: {stats.robots_disallowed_count}")
+print(f"Cache hits: {stats.cache_hits}")
+print(f"Cache misses: {stats.cache_misses}")
+print(f"Items scraped: {stats.items_scraped}")
+print(f"Items dropped: {stats.items_dropped}")
+print(f"Response bytes: {stats.response_bytes}")
+print(f"Duration: {stats.elapsed_seconds:.1f}s")
+print(f"Speed: {stats.requests_per_second:.1f} req/s")
+```
+
+### Подробная статистика {#detailed-stats}
+
+Объект `CrawlStats` содержит подробные показатели:
+
+```python
+stats = result.stats
+
+# Status code distribution
+print(stats.response_status_count)
+# {'status_200': 150, 'status_404': 3, 'status_403': 1}
+
+# Bytes downloaded per domain
+print(stats.domains_response_bytes)
+# {'example.com': 1234567, 'api.example.com': 45678}
+
+# Requests per session
+print(stats.sessions_requests_count)
+# {'http': 120, 'stealth': 34}
+
+# Proxies used during the crawl
+print(stats.proxies)
+# ['http://proxy1:8080', 'http://proxy2:8080']
+
+# Log level counts
+print(stats.log_levels_counter)
+# {'debug': 200, 'info': 50, 'warning': 3, 'error': 1, 'critical': 0}
+
+# Timing information
+print(stats.start_time) # Unix timestamp when crawl started
+print(stats.end_time) # Unix timestamp when crawl finished
+print(stats.download_delay) # The download delay used (seconds)
+
+# Concurrency settings used
+print(stats.concurrent_requests) # Global concurrency limit
+print(stats.concurrent_requests_per_domain) # Per-domain concurrency limit
+
+# AutoThrottle
+print(stats.autothrottle_enabled) # Whether the adaptive delay was on
+print(stats.autothrottle_delays) # Final delay per domain, {'example.com': 0.62}
+
+# Custom stats (set by your spider code)
+print(stats.custom_stats)
+# {'login_attempts': 3, 'pages_with_errors': 5}
+
+# Export everything as a dict
+print(stats.to_dict())
+```
+
+## Журналирование {#logging}
+
+У паука есть встроенный logger, доступный через `self.logger`. В нём уже указано имя паука, а поведение можно настроить:
+
+| Атрибут | По умолчанию | Описание |
+|-----------------------|--------------------------------------------------------------|----------------------------------------------------|
+| `logging_level` | `logging.DEBUG` | Минимальный уровень сообщений |
+| `logging_format` | `"[%(asctime)s]:({spider_name}) %(levelname)s: %(message)s"` | Формат сообщения |
+| `logging_date_format` | `"%Y-%m-%d %H:%M:%S"` | Формат даты в сообщениях |
+| `log_file` | `None` | Путь к файлу журнала в дополнение к выводу в консоль |
+
+```python
+import logging
+
+class MySpider(Spider):
+ name = "my_spider"
+ start_urls = ["https://example.com"]
+ logging_level = logging.INFO
+ log_file = "logs/my_spider.log"
+
+ async def parse(self, response: Response):
+ self.logger.info(f"Processing {response.url}")
+ yield {"title": response.css("title::text").get("")}
+```
+
+Каталог файла журнала создаётся автоматически, если его нет. Консоль и файл используют один формат.
diff --git a/docs/locales/ru/spiders/architecture.md b/docs/locales/ru/spiders/architecture.md
new file mode 100644
index 0000000..fdf8f85
--- /dev/null
+++ b/docs/locales/ru/spiders/architecture.md
@@ -0,0 +1,107 @@
+---
+title: "Как работают веб-краулеры Scrapling"
+description: "Узнайте, как связаны пауки, запросы, сессии, планировщик и движок обхода. Сравните работу со Scrapy и выберите, с чего начать."
+---
+
+# Архитектура пауков {#spiders-architecture}
+
+!!! success "Что нужно знать"
+
+ 1. Прочитайте страницу [Основы Fetcher](../fetching/choosing.md), чтобы узнать о разных типах Fetcher и понять, когда их использовать.
+ 2. Прочитайте страницу [Основные классы](../parsing/main_classes.md), чтобы познакомиться с классами [Selector](../parsing/main_classes.md#selector) и [Response](../fetching/choosing.md#response-object).
+
+Система пауков Scrapling представляет собой асинхронный фреймворк для обхода сайтов, вдохновлённый Scrapy. Она поддерживает одновременные запросы, несколько сессий, паузу и возобновление работы. Система объединяет парсер и Fetcher в общий API для обхода, а также добавляет планирование запросов, управление их одновременным выполнением и контрольные точки.
+
+Если вы знакомы со Scrapy, многие приёмы будут привычны. Если нет, система всё равно проста в освоении.
+
+## Поток данных {#data-flow}
+
+На схеме показан путь данных в системе пауков во время обхода:
+
+<img src="../assets/spider_architecture.png" title="Схема архитектуры паука от @TrueSkills" alt="Схема архитектуры паука от @TrueSkills" style="width: 70%;"/>
+
+Вот что происходит при запуске паука, без лишних подробностей:
+
+1. **Паук** создаёт первую группу объектов `Request`. По умолчанию для каждого URL в `start_urls` создаётся один запрос. Для своей логики можно переопределить `start_requests()`.
+2. **Планировщик** принимает запросы, помещает их в очередь с приоритетами и создаёт их отпечатки. Запросы с более высоким приоритетом извлекаются первыми.
+3. **Движок обхода** просит **планировщик** выдать следующий запрос, соблюдая общие ограничения числа одновременных запросов, ограничения для каждого домена и задержки загрузки. Если включён `robots_txt_obey`, движок сначала проверяет правила robots.txt домена. Запрещённые запросы отбрасываются без уведомления. Полученный запрос **движок обхода** передаёт **менеджеру сессий**, который выбирает сессию по полю `sid` запроса (ID сессии).
+4. **Сессия** загружает страницу и возвращает объект [Response](../fetching/choosing.md#response-object) **движку обхода**. Движок собирает статистику и проверяет, не заблокирован ли ответ. При блокировке запрос повторяется до `max_blocked_retries` раз. Обнаружение блокировок и логику повторных попыток можно настроить.
+5. **Движок обхода** передаёт [Response](../fetching/choosing.md#response-object) обработчику запроса. Обработчик выдаёт либо словарь с извлечённой записью, либо следующий запрос, который передаётся планировщику и попадает в очередь.
+6. Цикл повторяется с шага 2, пока очередь не опустеет и не завершатся все задачи, либо пока паук не будет поставлен на паузу.
+7. Если при запуске задан `crawldir`, **движок обхода** периодически сохраняет на диск контрольную точку: ожидающие запросы и множество уже встреченных URL. При корректной остановке (Ctrl+C) сохраняется последняя контрольная точка. При следующем запуске с тем же `crawldir` паук продолжает работу с места остановки: пропускает `start_requests()` и восстанавливает состояние планировщика.
+
+
+## Компоненты {#components}
+
+### Spider {#spider}
+
+Основной класс, с которым вы работаете. Создайте подкласс `Spider`, задайте `start_urls` и метод `parse()`. При необходимости настройте сессии и переопределите хуки жизненного цикла.
+
+```python
+from scrapling.spiders import Spider, Response, Request
+
+class MySpider(Spider):
+ name = "my_spider"
+ start_urls = ["https://example.com"]
+
+ async def parse(self, response: Response):
+ for link in response.css("a::attr(href)").getall():
+ yield response.follow(link, callback=self.parse_page)
+
+ async def parse_page(self, response: Response):
+ yield {"title": response.css("h1::text").get("")}
+```
+
+### Движок обхода {#crawler-engine}
+
+Движок управляет всем обходом: главным циклом, ограничениями одновременных запросов, отправкой запросов через менеджер сессий и обработкой результатов. Напрямую работать с ним не нужно. Это делают методы `Spider.start()` и `Spider.stream()`.
+
+### Планировщик {#scheduler}
+
+Очередь с приоритетами и встроенным удалением повторных URL. Отпечаток запроса строится на основе URL, HTTP-метода, тела и ID сессии. Планировщик поддерживает `snapshot()` и `restore()` для системы контрольных точек, чтобы сохранять состояние обхода и возобновлять его.
+
+### Менеджер сессий {#session-manager}
+
+Управляет одним или несколькими именованными экземплярами сессий. Каждая сессия имеет один из типов:
+
+- [FetcherSession](../fetching/static.md)
+- [AsyncStealthySession](../fetching/stealthy.md)
+
+При получении запроса менеджер выбирает сессию по полю `sid`. Сессии могут запускаться вместе с пауком (по умолчанию) или при первом использовании.
+
+### Система контрольных точек {#checkpoint-system}
+
+Необязательная система, которая сохраняет состояние краулера в pickle-файл на диске: ожидающие запросы и отпечатки уже встреченных URL. Запись атомарная: сначала во временный файл, затем переименование. Это защищает от повреждения данных. Контрольные точки сохраняются с заданным интервалом и при корректной остановке. После успешного завершения обхода, а не паузы, файлы удаляются автоматически.
+
+### Кеш ответов {#response-cache}
+
+Необязательный кеш в режиме разработки. Он сохраняет каждый загруженный ответ на диск и использует его при следующих запусках. Ключом служит отпечаток запроса. Ответ сохраняется как JSON, а тело кодируется в base64 для сохранения двоичных данных. Кеш нужен для доработки `parse()` без повторных обращений к серверу, а не для рабочего обхода.
+
+### Результаты {#output}
+
+Извлечённые записи собираются в `ItemList`: подкласс списка с методами экспорта `to_json()`, `to_jsonl()`, `to_csv()` и `to_xml()`. Статистика обхода хранится в dataclass `CrawlStats` и содержит много полезных данных.
+
+
+## Сравнение со Scrapy {#comparison-with-scrapy}
+
+Если вы переходите со Scrapy, эта таблица поможет сопоставить возможности:
+
+| Понятие | Scrapy | Scrapling |
+|--------------------|-------------------------------|-----------------------------------------------------------------|
+| Определение паука | Подкласс `scrapy.Spider` | Подкласс `scrapling.spiders.Spider` |
+| Начальные запросы | `start_requests()` | `async start_requests()` |
+| Обработчики | `def parse(self, response)` | `async def parse(self, response)` |
+| Переход по ссылкам | `response.follow(url)` | `response.follow(url)` |
+| Выдача записей | `yield dict` или `yield Item` | `yield dict` |
+| Планирование запросов | Scheduler + Dupefilter | Планировщик со встроенным удалением дубликатов |
+| Загрузка | Downloader + Middlewares | Менеджер с поддержкой нескольких сессий |
+| Обработка записей | Item Pipelines | Хук `on_scraped_item()` |
+| Обнаружение блокировок | Через свои middleware | Встроенные хуки `is_blocked()` + `retry_blocked_request()` |
+| Одновременные запросы | Настройка `CONCURRENT_REQUESTS` | Атрибут класса `concurrent_requests` |
+| Ограничение доменов | `allowed_domains` | `allowed_domains` |
+| Robots.txt | Настройка `ROBOTSTXT_OBEY` | Атрибут класса `robots_txt_obey` |
+| Пауза и возобновление | Настройка `JOBDIR` | Аргумент конструктора `crawldir` |
+| Экспорт | Feed exports | `result.items.to_json()` / `to_jsonl()` / `to_csv()` / `to_xml()` или свой экспорт через хуки |
+| Запуск | `scrapy crawl spider_name` | `MySpider().start()` |
+| Потоковая выдача | Нет | `async for item in spider.stream()` |
+| Несколько сессий | Нет | Несколько сессий разных типов в одном пауке |
diff --git a/docs/locales/ru/spiders/generic-templates.md b/docs/locales/ru/spiders/generic-templates.md
new file mode 100644
index 0000000..13801fd
--- /dev/null
+++ b/docs/locales/ru/spiders/generic-templates.md
@@ -0,0 +1,278 @@
+---
+title: "Шаблоны пауков для ссылок, карт сайта, фидов и Markdown"
+description: "Выберите CrawlSpider, SitemapSpider, XMLFeedSpider, CSVFeedSpider или ContentSpider. Задайте правила для сбора страниц, записей фидов или набора документов Markdown."
+---
+
+# Общие шаблоны пауков {#generic-spider-templates}
+
+Большинство обходов строится по одному из двух правил: переходить по ссылкам заданного вида или обходить все URL из карты сайта. В Scrapling есть шаблоны для обоих вариантов, чтобы не писать один и тот же `parse()` каждый раз.
+
+`CrawlSpider` и `SitemapSpider` используют `LinkExtractor`, который извлекает URL из `Response` или проверяет отдельный URL через `matches()`. `SitemapSpider` также сам разбирает sitemap.xml / sitemap_index.xml, в том числе сжатые gzip.
+
+`LinkExtractor` можно использовать прямо в любом `Spider.parse()`. Шаблоны лишь связывают готовые компоненты за вас.
+
+## CrawlSpider {#crawlspider}
+
+`CrawlSpider` автоматически переходит по ссылкам на основе заданных правил.
+
+```python
+from scrapling.spiders import CrawlSpider, CrawlRule, LinkExtractor
+
+class QuotesSpider(CrawlSpider):
+ name = "blog"
+ start_urls = ["https://quotes.toscrape.com/"]
+
+ def rules(self):
+ return [
+ CrawlRule(LinkExtractor(allow=r"/author/"), callback=self.parse_author),
+ CrawlRule(LinkExtractor(allow=r"/page/\d+/")), # follow pagination, no callback
+ ]
+
+ async def parse_author(self, response):
+ yield {
+ '.author-title': response.css('.author-title::text').get(),
+ "birthday": response.css('.author-born-date::text').get(),
+ "url": response.url,
+ }
+
+result = QuotesSpider().start()
+```
+
+`CrawlRule` связывает `LinkExtractor` с необязательным `callback` (методом паука), необязательным `priority` для создаваемого `Request` и необязательным `process_request` (методом, который меняет каждый `Request` перед выдачей). По умолчанию `parse()` применяет все правила к каждому ответу и выдаёт `Request` для каждого подходящего URL.
+
+Если в правиле не указан обработчик, подходящие URL передаются в обычный `parse()` паука. Это удобно для перехода между страницами: извлекайте ссылки на следующую страницу и продолжайте обход без отдельного обработчика.
+
+### Порядок обхода {#crawl-order}
+
+Задайте `crawl_strategy` у `CrawlSpider` или его подклассов, включая `ContentSpider`, чтобы выбрать порядок ожидающих запросов:
+
+| `crawl_strategy` | Порядок при одинаковом `Request.priority` |
+|------------------|------------------------------------------|
+| `"bfs"` (по умолчанию) | Сначала запрос, раньше попавший в очередь |
+| `"dfs"` | Сначала запрос, позже попавший в очередь |
+
+Планировщик сначала берёт запросы с большим `Request.priority`. Стратегия определяет порядок только для запросов с одинаковым приоритетом.
+
+Установите `concurrent_requests = 1`, чтобы обрабатывать запросы по одному в выбранном порядке. Повторные URL по-прежнему отбрасываются: повторное обнаружение URL не перемещает его запрос в очереди. При одновременных запросах страницы могут завершаться в другом порядке, а уровни и ветви обхода могут пересекаться.
+
+При возобновлении с контрольной точки сохраняйте прежнее значение `crawl_strategy`.
+
+### Правила вместе со своей логикой {#combining-rules-with-custom-logic}
+
+Переопределите `parse()` и вызовите `super().parse(response)`, чтобы совместить правила со своими результатами:
+
+```python
+class MySpider(CrawlSpider):
+ def rules(self):
+ return [CrawlRule(LinkExtractor(allow=r"/posts/"), callback=self.parse_post)]
+
+ async def parse(self, response):
+ yield {"page_url": response.url}
+ async for req in super().parse(response):
+ yield req
+```
+
+### Изменение запросов через `process_request` {#mutating-requests-with-process_request}
+
+```python
+def add_priority(self, request, response):
+ request.priority = 10
+ return request
+
+def rules(self):
+ return [CrawlRule(
+ LinkExtractor(allow=r"/posts/"),
+ callback=self.parse_post,
+ process_request=self.add_priority,
+ )]
+```
+
+## SitemapSpider {#sitemapspider}
+
+`SitemapSpider` начинает обход с URL из sitemap.xml. Он использует тот же API `rules()`, что и `CrawlSpider`, поэтому принцип работы одинаковый.
+
+```python
+from scrapling.spiders import SitemapSpider, CrawlRule, LinkExtractor
+
+class MySitemap(SitemapSpider):
+ name = "sm"
+ sitemap_urls = ["https://example.com/sitemap.xml"]
+
+ def rules(self):
+ return [
+ CrawlRule(LinkExtractor(allow=r"/posts/"), callback=self.parse_post),
+ CrawlRule(LinkExtractor(allow=r"/products/"), callback=self.parse_product),
+ ]
+
+ async def parse_post(self, response):
+ yield {"title": response.css("h1::text").get()}
+
+ async def parse_product(self, response):
+ yield {"sku": response.css(".sku::text").get()}
+
+result = MySitemap().start()
+```
+
+### Как выбирается обработчик URL {#how-urls-are-dispatched}
+
+Для каждого URL из карты сайта `SitemapSpider` по порядку вызывает `LinkExtractor.matches(url)` каждого правила. Выбирается первое совпадение, и выдаётся `Request` с обработчиком этого правила. Если совпадений нет, а `rules()` не пуст, URL отбрасывается. Если `rules()` возвращает пустой список, все URL передаются в `parse()` паука. Без переопределения этот метод по умолчанию вызывает `NotImplementedError`.
+
+### Индексы карт сайта {#sitemap-indexes}
+
+Если `SitemapSpider` встречает `<sitemapindex>` (список карт сайта), он автоматически переходит в каждую вложенную карту. Чтобы выбрать только нужные вложенные карты, задайте `sitemap_follow` как `LinkExtractor`:
+
+```python
+class MySitemap(SitemapSpider):
+ name = "sm"
+ sitemap_urls = ["https://example.com/sitemap.xml"]
+ sitemap_follow = LinkExtractor(allow=r"/posts-sitemap-\d+\.xml") # only post sitemaps
+```
+
+### Поддержка robots.txt {#robotstxt-support}
+
+Укажите URL `robots.txt` прямо в `sitemap_urls`. `SitemapSpider` распознает файл, извлечёт все указанные карты сайта и обойдёт их:
+
+```python
+class MySitemap(SitemapSpider):
+ name = "sm"
+ sitemap_urls = ["https://example.com/robots.txt"]
+```
+
+### URL на других языках {#alternate-language-urls}
+
+Установите `sitemap_alternate_links = True`, чтобы передавать в правила также URL из `<xhtml:link rel="alternate" hreflang="...">`.
+
+## XMLFeedSpider {#xmlfeedspider}
+
+`XMLFeedSpider` перебирает узлы XML-фида: RSS, Atom, товарного фида и других. Задайте нужное имя узла в `itertag` (по умолчанию `"item"`) и переопределите `parse_node()`. Этот метод вызывается для каждого подходящего узла:
+
+```python
+from scrapling.spiders import XMLFeedSpider
+
+class RSSSpider(XMLFeedSpider):
+ name = "rss"
+ start_urls = ["https://example.com/feed.xml"]
+ itertag = "item"
+
+ async def parse_node(self, response, node):
+ yield {
+ "title": node.findtext("title"),
+ "link": node.findtext("link"),
+ "date": node.findtext("pubDate"),
+ }
+
+result = RSSSpider().start()
+```
+
+Как и другие обработчики, `parse_node()` может выдавать объекты `Request`, например `response.follow(node.findtext("link"), callback=self.parse_post)`, чтобы обходить страницы, на которые ссылается фид.
+
+### Выбор и разбор узлов {#how-nodes-are-matched-and-parsed}
+
+В `parse_node()` передаётся элемент `lxml` без пространств имён. Поэтому `node.findtext("title")`, `node.find("thumbnail").get("url")` и чувствительный к регистру `node.xpath(...)` работают с любым фидом без карты пространств имён. Простое значение `itertag`, например `"entry"`, выбирает узлы по имени независимо от пространства имён. Это подходит для Atom и большинства фидов с пространствами имён. Чтобы выбрать узел из определённого пространства имён, используйте `itertag` с префиксом и задайте этот префикс в `namespaces`:
+
+```python
+class ThumbnailSpider(XMLFeedSpider):
+ name = "thumbs"
+ start_urls = ["https://example.com/feed.xml"]
+ itertag = "media:thumbnail"
+ namespaces = (("media", "http://search.yahoo.com/mrss/"),)
+
+ async def parse_node(self, response, node):
+ yield {"thumbnail": node.get("url")}
+```
+
+Фиды gzip (`.xml.gz` или с типом содержимого gzip) распаковываются автоматически с той же защитой, что и у паука для карт сайта. Некорректный XML вызывает предупреждение в журнале, а не остановку обхода.
+
+## CSVFeedSpider {#csvfeedspider}
+
+`CSVFeedSpider` перебирает строки CSV-фида. Переопределите `parse_row()`, который получает каждую строку как словарь с именами столбцов в качестве ключей:
+
+```python
+from scrapling.spiders import CSVFeedSpider
+
+class PriceSpider(CSVFeedSpider):
+ name = "prices"
+ start_urls = ["https://example.com/products.csv"]
+
+ async def parse_row(self, response, row):
+ yield {"product": row["title"], "price": float(row["price"])}
+
+result = PriceSpider().start()
+```
+
+По умолчанию первая строка служит заголовком. Если заголовка нет, задайте имена столбцов через `headers`. Для фидов с нестандартными разделителями используйте `delimiter`/`quotechar`:
+
+```python
+class PriceSpider(CSVFeedSpider):
+ name = "prices"
+ start_urls = ["https://example.com/products.csv"]
+ headers = ["title", "price", "url"]
+ delimiter = ";"
+```
+
+Фиды gzip здесь также распаковываются автоматически, как показано выше для **XMLFeedSpider**.
+
+<a id="sitetomarkdownspider"></a>
+
+## ContentSpider {#contentspider}
+
+`ContentSpider` основан на **CrawlSpider**. Он обходит сайт и преобразует каждую страницу в очищенный Markdown для LLM. На каждую страницу выдаётся одна запись, а при необходимости создаётся отдельный Markdown-файл:
+
+```python
+from scrapling.spiders import ContentSpider
+
+class DocsSpider(ContentSpider):
+ name = "docs"
+ start_urls = ["https://example.com/docs/"]
+ allowed_domains = {"example.com"}
+ output_dir = "docs_markdown"
+
+result = DocsSpider().start()
+```
+
+Нужно задать `allowed_domains`, чтобы ограничить обход целевым сайтом. Полное руководство со всеми параметрами и передачей результатов в RAG находится на странице [Создание RAG-систем](../ai/building-rag-systems.md).
+
+## Прямое использование `LinkExtractor` {#using-linkextractor-directly}
+
+Шаблоны необязательны. `LinkExtractor` работает в любом обычном `Spider`:
+
+```python
+from scrapling.spiders import Spider, LinkExtractor
+
+class CustomSpider(Spider):
+ name = "custom"
+ start_urls = ["https://example.com"]
+
+ def __init__(self):
+ super().__init__()
+ self._links = LinkExtractor(allow=r"/posts/", deny_domains="ads.example.com")
+
+ async def parse(self, response):
+ for url in self._links.extract(response):
+ yield response.follow(url, callback=self.parse_post)
+
+ async def parse_post(self, response):
+ yield {"title": response.css("h1::text").get()}
+```
+
+## Справочник LinkExtractor {#linkextractor-reference}
+
+| Аргумент | По умолчанию | Описание |
+|-------------------|----------------------|---------------------------------------------------------------------------------------------------|
+| `allow` | `()` | Шаблоны URL, которые нужно оставить. Пустое значение допускает все URL. Строка, скомпилированный `Pattern` или перебираемый объект с такими значениями |
+| `deny` | `()` | Шаблоны URL, которые нужно отбросить. Всегда имеют приоритет над `allow` |
+| `allow_domains` | `()` | Разрешённые имена хостов. Поддомены учитываются автоматически: `example.com` разрешает `api.example.com` |
+| `deny_domains` | `()` | Запрещённые имена хостов |
+| `restrict_css` | `()` | CSS-селекторы, ограничивающие область поиска ссылок в DOM |
+| `restrict_xpath` | `()` | XPath-селекторы, ограничивающие область поиска ссылок в DOM |
+| `tags` | `("a", "area")` | Теги элементов, в которых нужно искать ссылки |
+| `attrs` | `("href",)` | Атрибуты этих тегов, из которых читаются URL |
+| `canonicalize` | `True` | Сортировать параметры запроса и нормализовать путь |
+| `strip` | `True` | Удалять пробельные символы по краям извлечённых URL |
+| `keep_fragment` | `False` | Сохранять `#fragment` при нормализации |
+| `deny_extensions` | `IGNORED_EXTENSIONS` | Исключаемые расширения файлов: pdf, zip, изображения, видео и другие |
+| `process` | `None` | Необязательный вызываемый объект для каждого извлечённого URL перед фильтрацией. Верните значение, которое считается ложным, чтобы отбросить URL |
+
+`LinkExtractor.extract(response)` возвращает `list[str]` с абсолютными URL после фильтрации и удаления дубликатов.
+
+`LinkExtractor.matches(url)` возвращает `bool`. Это фильтр по самому URL: allow/deny/домен/расширение. `SitemapSpider` использует его для выбора URL без `Response`.
diff --git a/docs/locales/ru/spiders/getting-started.md b/docs/locales/ru/spiders/getting-started.md
new file mode 100644
index 0000000..45363f9
--- /dev/null
+++ b/docs/locales/ru/spiders/getting-started.md
@@ -0,0 +1,199 @@
+---
+title: "Создайте первый веб-краулер на Python со Scrapling"
+description: "Создайте паука, который извлекает данные, переходит по страницам и экспортирует результаты. Узнайте о начальных URL, обработчиках, ограничениях доменов и robots.txt."
+---
+
+# Начало работы {#getting-started}
+
+## Введение {#introduction}
+
+!!! success "Что нужно знать"
+
+ 1. Прочитайте страницу [Основы Fetcher](../fetching/choosing.md), чтобы узнать о разных типах Fetcher и понять, когда их использовать.
+ 2. Прочитайте страницу [Основные классы](../parsing/main_classes.md), чтобы познакомиться с классами [Selector](../parsing/main_classes.md#selector) и [Response](../fetching/choosing.md#response-object).
+ 3. Прочитайте страницу [Архитектура](architecture.md), чтобы понять, как устроена система пауков.
+
+Система пауков позволяет создать краулер, который обходит много страниц и выполняет запросы одновременно, всего в нескольких строках кода. Если вы работали со Scrapy, многие приёмы будут знакомы. Если нет, это руководство поможет начать.
+
+## Ваш первый паук {#your-first-spider}
+
+Паук представляет собой класс, который определяет, как обходить сайты и извлекать данные. Вот самый простой пример:
+
+```python
+from scrapling.spiders import Spider, Response
+
+class QuotesSpider(Spider):
+ name = "quotes"
+ start_urls = ["https://quotes.toscrape.com"]
+
+ async def parse(self, response: Response):
+ for quote in response.css("div.quote"):
+ yield {
+ "text": quote.css("span.text::text").get(""),
+ "author": quote.css("small.author::text").get(""),
+ }
+```
+
+Каждому пауку нужны три элемента:
+
+1. **`name`** - уникальное имя паука.
+2. **`start_urls`** - список URL, с которых начинается обход.
+3. **`parse()`** - метод с асинхронным генератором, который обрабатывает каждый ответ и выдаёт результаты.
+
+Основная работа происходит в методе `parse()`. В нём доступны те же методы выбора элементов, что и в [Selector](../parsing/main_classes.md#selector)/[Response](../fetching/choosing.md#response-object). Чтобы выдать извлечённые записи, используйте `yield` со словарями.
+
+## Запуск паука {#running-the-spider}
+
+Создайте экземпляр паука и вызовите `start()`:
+
+```python
+result = QuotesSpider().start()
+```
+
+Метод `start()` сам управляет асинхронным выполнением, поэтому настраивать цикл событий не нужно. Во время работы все события записываются в терминал. В конце обхода вы получите подробную статистику.
+
+Она находится в возвращённом объекте `CrawlResult`, вместе с результатами обхода:
+
+```python
+result = QuotesSpider().start()
+
+# Access scraped items
+for item in result.items:
+ print(item["text"], "-", item["author"])
+
+# Check statistics
+print(f"Scraped {result.stats.items_scraped} items")
+print(f"Made {result.stats.requests_count} requests")
+print(f"Took {result.stats.elapsed_seconds:.1f} seconds")
+
+# Did the crawl finish or was it paused?
+print(f"Completed: {result.completed}")
+```
+
+## Переход по ссылкам {#following-links}
+
+При обходе обычно нужно переходить по ссылкам между страницами. Создавайте следующие запросы с помощью `response.follow()`:
+
+```python
+from scrapling.spiders import Spider, Response
+
+class QuotesSpider(Spider):
+ name = "quotes"
+ start_urls = ["https://quotes.toscrape.com"]
+
+ async def parse(self, response: Response):
+ # Extract items from the current page
+ for quote in response.css("div.quote"):
+ yield {
+ "text": quote.css("span.text::text").get(""),
+ "author": quote.css("small.author::text").get(""),
+ }
+
+ # Follow the "next page" link
+ next_page = response.css("li.next a::attr(href)").get()
+ if next_page:
+ yield response.follow(next_page, callback=self.parse)
+```
+
+`response.follow()` автоматически объединяет относительные URL с URL текущей страницы. По умолчанию он также указывает текущую страницу в заголовке `Referer`.
+
+Для разных типов страниц можно назначить разные методы-обработчики:
+
+```python
+async def parse(self, response: Response):
+ for link in response.css("a.product-link::attr(href)").getall():
+ yield response.follow(link, callback=self.parse_product)
+
+async def parse_product(self, response: Response):
+ yield {
+ "name": response.css("h1::text").get(""),
+ "price": response.css(".price::text").get(""),
+ }
+```
+
+!!! note
+
+ Все обработчики должны быть асинхронными генераторами с `async def` и `yield`.
+
+## Экспорт данных {#exporting-data}
+
+Объект `ItemList` в `result.items` содержит встроенные методы экспорта:
+
+```python
+result = QuotesSpider().start()
+
+# Export as JSON
+result.items.to_json("quotes.json")
+
+# Export as JSON with pretty-printing
+result.items.to_json("quotes.json", indent=True)
+
+# Export as JSON Lines (one JSON object per line)
+result.items.to_jsonl("quotes.jsonl")
+
+# Export as CSV or XML
+result.items.to_csv("quotes.csv")
+result.items.to_xml("quotes.xml")
+```
+
+Все эти методы автоматически создают родительские каталоги, если их ещё нет.
+
+`to_csv()` создаёт столбец для каждого ключа, найденного в записях. Поэтому записи с разными наборами ключей тоже попадают в файл, а ячейки без значений остаются пустыми. Передайте `fields=[...]`, чтобы выбрать столбцы и их порядок, или `delimiter="\t"`, чтобы получить TSV-файл. `to_xml()` помещает каждую запись в элемент `<item>` внутри корневого элемента `<items>`. Их имена можно изменить через `root_tag` и `item_tag`.
+
+В обоих форматах сложные значения, такие как вложенный словарь или список, записываются как JSON. Данные не отбрасываются без уведомления.
+
+## Ограничение доменов {#filtering-domains}
+
+Используйте `allowed_domains`, чтобы ограничить обход заданными доменами. Это не даст пауку случайно перейти на сторонний сайт:
+
+```python
+class MySpider(Spider):
+ name = "my_spider"
+ start_urls = ["https://example.com"]
+ allowed_domains = {"example.com"}
+
+ async def parse(self, response: Response):
+ for link in response.css("a::attr(href)").getall():
+ # Links to other domains are silently dropped
+ yield response.follow(link, callback=self.parse)
+```
+
+Поддомены разрешаются автоматически. Например, `allowed_domains = {"example.com"}` также разрешает `sub.example.com`, `blog.example.com` и другие поддомены.
+
+Отброшенные запросы учитываются в `stats.offsite_requests_count`, где можно посмотреть их число.
+
+## Соблюдение robots.txt {#robotstxt-compliance}
+
+Установите `robots_txt_obey = True`, чтобы паук проверял правила robots.txt перед обходом каждого домена:
+
+```python
+class PoliteSpider(Spider):
+ name = "polite"
+ start_urls = ["https://example.com"]
+ robots_txt_obey = True
+
+ async def parse(self, response: Response):
+ for link in response.css("a::attr(href)").getall():
+ yield response.follow(link, callback=self.parse)
+```
+
+При включённой настройке паук:
+
+1. **Заранее загружает robots.txt** для всех доменов из `start_urls` перед началом обхода. Загрузка идёт одновременно.
+2. **Проверяет каждый запрос** по правилам `Disallow` в robots.txt домена. Запрещённые запросы отбрасываются без уведомления и учитываются в `stats.robots_disallowed_count`.
+3. **Соблюдает директивы `Crawl-delay` и `Request-rate`**, выбирая наибольшее значение между задержкой из директивы и настройкой `download_delay`. Поэтому правила robots.txt могут только увеличить заданную задержку. Если включён AutoThrottle, его максимальная задержка также ограничивает это значение. Задайте достаточно большое значение `autothrottle_max_delay`, чтобы соблюдать требуемую задержку.
+
+Файлы robots.txt загружаются через сессию паука по умолчанию и хранятся в кеше для каждого домена до конца обхода. Для доменов, найденных во время обхода и отсутствующих в `start_urls`, robots.txt загружается при первом запросе к домену.
+
+**Примечание:** `robots_txt_obey` по умолчанию выключен, чтобы не менять поведение неожиданно. Если его включить, настройки числа одновременных запросов (`concurrent_requests`, `concurrent_requests_per_domain`) не изменятся. Меняется только задержка между запросами.
+
+Если вы не хотите выбирать `download_delay` вручную, установите `autothrottle_enabled = True`. Паук сам подберёт задержку для каждого домена по скорости его ответов и увеличит её при блокировке. Подробнее в разделе [AutoThrottle](advanced.md#autothrottle).
+
+## Что дальше {#whats-next}
+
+Теперь можно перейти к следующим темам:
+
+- [Запросы и ответы](requests-responses.md): приоритет запросов, удаление дубликатов, метаданные и другие возможности.
+- [Сессии](sessions.md): разные типы Fetcher (HTTP, браузер, stealth) в одном пауке.
+- [Прокси и блокировки](proxy-blocking.md): смена прокси между запросами и обработка блокировок.
+- [Расширенные возможности](advanced.md): число одновременных запросов, AutoThrottle, пауза и возобновление, потоковая выдача, хуки жизненного цикла и журналирование.
diff --git a/docs/locales/ru/spiders/platform-templates.md b/docs/locales/ru/spiders/platform-templates.md
new file mode 100644
index 0000000..026567b
--- /dev/null
+++ b/docs/locales/ru/spiders/platform-templates.md
@@ -0,0 +1,59 @@
+---
+title: "Сбор данных о товарах Shopify на Python"
+description: "Собирайте каталог магазина Shopify с ShopifySpider. Задайте адрес магазина, получите варианты товаров и изучите поля каждой записи."
+---
+
+# Шаблоны пауков для платформ {#platform-spider-templates}
+
+Общие шаблоны описывают *схемы обхода*: переход по ссылкам или картам сайта. Шаблоны платформ предназначены для *платформ*, то есть конструкторов сайтов с одинаковой машиночитаемой структурой на множестве независимых сайтов. Паук уже знает, где искать данные. Вам нужно лишь указать домен.
+
+## ShopifySpider {#shopifyspider}
+
+`ShopifySpider` извлекает все товары из магазина на Shopify через JSON API платформы, не обращаясь к HTML сайта.
+
+```python
+from scrapling.spiders import ShopifySpider
+
+class MyStore(ShopifySpider):
+ target_website = "example.com"
+
+result = MyStore().start()
+print(result.items[0])
+```
+
+Задайте домен магазина в `target_website`. Если он пуст, паук берёт первую запись из `start_urls`, затем из `allowed_domains`. Если все три значения пусты, возникает `ValueError`. Полные URL автоматически преобразуются в домен.
+
+### Как это работает {#how-it-works}
+
+1. Загружаются страницы `https://<store>/collections.json`, по 250 коллекций на страницу. Это предел платформы.
+2. Для каждой коллекции, в которой есть товары, загружаются страницы `/collections/<handle>/products.json`.
+3. Для каждого варианта товара выдаётся одна запись. Варианты, встречающиеся в нескольких коллекциях, не дублируются.
+
+### Поля записи {#item-fields}
+
+| Поле | Источник |
+|---------------|---------------------------------------------------------------------------|
+| `name` | Название товара и название варианта, если это не вариант по умолчанию |
+| `price` | Цена варианта: строка в том виде, в котором её возвращает Shopify |
+| `category` | Часть URL с именем коллекции, преобразованная в слова с заглавной буквы: `summer-sale` становится `Summer Sale` |
+| `brand` | Поставщик товара |
+| `identifier` | ID варианта |
+| `sku` | SKU варианта или `""`, если магазин его не задаёт |
+| `stock` | `None`, если вариант доступен, и `0`, если его нет в наличии |
+| `image_url` | Первое изображение товара или `""` |
+| `url` | Страница товара внутри коллекции |
+| `description` | `body_html` товара с удалёнными HTML-тегами |
+| `old_price` | `compare_at_price`, если это настоящая цена до скидки, иначе `""` |
+| `barcode` | Штрихкод варианта или `""`. Большинство магазинов не возвращают его в этих API |
+
+Этот набор полей необязателен. Переопределите `_process_product()` в своём подклассе, чтобы изменить структуру записи или извлекать другие поля товара.
+
+### Примечания и ограничения {#notes-and-limits}
+
+- JSON API возвращает только товары, опубликованные в канале интернет-магазина. Поэтому `products_count` коллекции может быть больше числа доступных товаров. Паук использует его только как условие: если значение не равно нулю, нужно загрузить коллекцию. Это не ожидаемое число результатов.
+- Шаблон, скорее всего, не будет работать с магазинами за дополнительной защитой или паролем. Даже если работу удастся наладить, потребуется переопределить много методов.
+- Все возможности `Spider` сохраняются: число одновременных запросов, задержки, правила robots.txt, контрольные точки и хуки жизненного цикла.
+
+### Какие платформы подходят для шаблонов {#what-qualifies-as-a-platform-template}
+
+В библиотеку принимаются шаблоны для платформ с единой машиночитаемой структурой на множестве независимых сайтов, как у Shopify. Пауки для одного конкретного сайта не входят в библиотеку, каким бы популярным ни был сайт.
diff --git a/docs/locales/ru/spiders/proxy-blocking.md b/docs/locales/ru/spiders/proxy-blocking.md
new file mode 100644
index 0000000..4bea2f8
--- /dev/null
+++ b/docs/locales/ru/spiders/proxy-blocking.md
@@ -0,0 +1,249 @@
+---
+title: "Смена прокси и повтор заблокированных запросов"
+description: "Используйте прокси и способы их смены в пауках Scrapling. Обнаруживайте блокировки, повторяйте запросы и переходите с HTTP на браузерные сессии."
+---
+
+# Управление прокси и обработка блокировок {#proxy-management-and-handling-blocks}
+
+## Введение {#introduction}
+
+!!! success "Что нужно знать"
+
+ 1. Прочитайте страницу [Начало работы](getting-started.md), чтобы научиться создавать и запускать простого паука.
+ 2. Прочитайте страницу [Сессии](sessions.md), чтобы понять, как настраивать сессии.
+
+При сборе больших объёмов данных часто нужно менять прокси, чтобы избежать ограничений частоты запросов и блокировок. Для этого в Scrapling есть `ProxyRotator`. Он работает со всеми типами сессий и связан с системой повторов заблокированных запросов.
+
+Если вы не знаете, что такое прокси и как его выбрать, поможет [это руководство](https://substack.thewebscraping.club/p/everything-about-proxies).
+
+## ProxyRotator {#proxyrotator}
+
+Класс `ProxyRotator` управляет списком прокси и автоматически меняет их. Передайте его в любую сессию через параметр `proxy_rotator`:
+
+```python
+from scrapling.spiders import Spider, Response
+from scrapling.fetchers import FetcherSession, ProxyRotator
+
+class MySpider(Spider):
+ name = "my_spider"
+ start_urls = ["https://example.com"]
+
+ def configure_sessions(self, manager):
+ rotator = ProxyRotator([
+ "http://proxy1:8080",
+ "http://proxy2:8080",
+ "http://user:pass@proxy3:8080",
+ ])
+ manager.add("default", FetcherSession(proxy_rotator=rotator))
+
+ async def parse(self, response: Response):
+ # Check which proxy was used
+ print(f"Proxy used: {response.meta.get('proxy')}")
+ yield {"title": response.css("title::text").get("")}
+```
+
+Каждый запрос автоматически получает следующий прокси. Использованный прокси сохраняется в `response.meta["proxy"]`, поэтому можно проверить, через какой прокси была загружена каждая страница.
+
+
+Для браузерных сессий потребуются небольшие изменения:
+
+```python
+from scrapling.fetchers import AsyncStealthySession, ProxyRotator
+
+# String proxies work for all session types
+rotator = ProxyRotator([
+ "http://proxy1:8080",
+ "http://proxy2:8080",
+])
+
+# Dict proxies (Playwright format) work for browser sessions
+rotator = ProxyRotator([
+ {"server": "http://proxy1:8080", "username": "user", "password": "pass"},
+ {"server": "http://proxy2:8080"},
+])
+
+# Then inside the spider
+def configure_sessions(self, manager):
+ rotator = ProxyRotator(["http://proxy1:8080", "http://proxy2:8080"])
+ manager.add("browser", AsyncStealthySession(proxy_rotator=rotator))
+```
+
+!!! info
+
+ 1. В одной сессии нельзя использовать `proxy_rotator` вместе с постоянными параметрами `proxy` или `proxies`. Выберите один вариант при настройке сессии. Позже можно переопределить прокси для отдельного запроса, как показано ниже.
+ 2. По умолчанию браузерные сессии используют постоянный контекст браузера с пулом вкладок. Браузер не позволяет задать отдельный прокси для каждой вкладки. Поэтому с `ProxyRotator` Fetcher автоматически создаёт отдельный контекст для каждого прокси с одной вкладкой. Когда задача вкладки завершена, вкладка и её контекст закрываются.
+
+## Свои способы смены прокси {#custom-rotation-strategies}
+
+По умолчанию `ProxyRotator` перебирает прокси по порядку и после последнего возвращается к первому.
+
+Чтобы изменить это поведение, передайте свою функцию с такой сигнатурой:
+
+```python
+from scrapling.core._types import ProxyType
+
+def my_strategy(proxies: list, current_index: int) -> tuple[ProxyType, int]:
+ ...
+```
+
+Она получает список прокси и текущий индекс, а вернуть должна выбранный прокси и следующий индекс.
+
+Ниже приведены примеры своих способов смены прокси.
+
+### Случайный выбор {#random-rotation}
+
+```python
+import random
+from scrapling.fetchers import ProxyRotator
+
+def random_strategy(proxies, current_index):
+ idx = random.randint(0, len(proxies) - 1)
+ return proxies[idx], idx
+
+rotator = ProxyRotator(
+ ["http://proxy1:8080", "http://proxy2:8080", "http://proxy3:8080"],
+ strategy=random_strategy,
+)
+```
+
+### Выбор с весами {#weighted-rotation}
+
+```python
+import random
+
+def weighted_strategy(proxies, current_index):
+ # First proxy gets 60% of traffic, others split the rest
+ weights = [60] + [40 // (len(proxies) - 1)] * (len(proxies) - 1)
+ proxy = random.choices(proxies, weights=weights, k=1)[0]
+ return proxy, current_index # Index doesn't matter for weighted
+
+rotator = ProxyRotator(proxies, strategy=weighted_strategy)
+```
+
+
+## Прокси для отдельного запроса {#per-request-proxy-override}
+
+Для отдельного запроса можно заменить выбор ротатора, передав именованный аргумент `proxy=`:
+
+```python
+async def parse(self, response: Response):
+ # This request uses the rotator's next proxy
+ yield response.follow("/page1", callback=self.parse_page)
+
+ # This request uses a specific proxy, bypassing the rotator
+ yield response.follow(
+ "/special-page",
+ callback=self.parse_page,
+ proxy="http://special-proxy:8080",
+ )
+```
+
+Это удобно, когда странице нужен определённый прокси, например из нужного региона для доступа к местному содержимому.
+
+## Обработка заблокированных запросов {#blocked-request-handling}
+
+Паук умеет обнаруживать блокировки и повторять запросы. По умолчанию заблокированными считаются ответы с HTTP-статусами `401`, `403`, `407`, `429`, `444`, `500`, `502`, `503`, `504`.
+
+Повторные попытки устроены так:
+
+1. После получения ответа паук вызывает `is_blocked(response)`.
+2. При блокировке он копирует запрос и вызывает `retry_blocked_request()`, чтобы вы могли изменить его перед повтором.
+3. Запрос снова попадает в очередь с `dont_filter=True`, чтобы обойти удаление дубликатов, и с пониженным приоритетом, чтобы не повторяться сразу.
+4. Это повторяется до `max_blocked_retries` раз. По умолчанию 3.
+
+!!! tip
+
+ 1. Перед повтором аргументы `proxy`/`proxies` автоматически удаляются из запроса, чтобы ротатор назначил новый прокси.
+ 2. Атрибут `max_blocked_retries` не связан с повторами внутри сессии. У них разные счётчики.
+
+### Своя проверка блокировок {#custom-block-detection}
+
+Переопределите `is_blocked()`, чтобы добавить свои проверки:
+
+```python
+class MySpider(Spider):
+ name = "my_spider"
+ start_urls = ["https://example.com"]
+
+ async def is_blocked(self, response: Response) -> bool:
+ # Check status codes (default behavior)
+ if response.status in {403, 429, 503}:
+ return True
+
+ # Check response content
+ body = response.body.decode("utf-8", errors="ignore")
+ if "access denied" in body.lower() or "rate limit" in body.lower():
+ return True
+
+ return False
+
+ async def parse(self, response: Response):
+ yield {"title": response.css("title::text").get("")}
+```
+
+### Настройка повторных попыток {#customizing-retries}
+
+Переопределите `retry_blocked_request()`, чтобы менять запрос перед повтором. Атрибут `max_blocked_retries` задаёт число повторов заблокированного запроса. По умолчанию их 3:
+
+```python
+from scrapling.spiders import Spider, SessionManager, Request, Response
+from scrapling.fetchers import FetcherSession, AsyncStealthySession
+
+
+class MySpider(Spider):
+ name = "my_spider"
+ start_urls = ["https://example.com"]
+ max_blocked_retries = 5
+
+ def configure_sessions(self, manager: SessionManager) -> None:
+ manager.add('requests', FetcherSession(impersonate=['chrome', 'firefox', 'safari']))
+ manager.add('stealth', AsyncStealthySession(block_webrtc=True), lazy=True)
+
+ async def retry_blocked_request(self, request: Request, response: Response) -> Request:
+ request.sid = "stealth"
+ self.logger.info(f"Retrying blocked request: {request.url}")
+ return request
+
+ async def parse(self, response: Response):
+ yield {"title": response.css("title::text").get("")}
+```
+
+В этом примере проверка блокировок не менялась. Паук использует HTTP-запросы, пока не получит блокировку, затем переключается на stealth-браузер.
+
+
+Объединим всё в одном примере:
+
+```python
+from scrapling.spiders import Spider, SessionManager, Request, Response
+from scrapling.fetchers import FetcherSession, AsyncStealthySession, ProxyRotator
+
+
+cheap_proxies = ProxyRotator([ "http://proxy1:8080", "http://proxy2:8080"])
+
+# A format acceptable by the browser
+expensive_proxies = ProxyRotator([
+ {"server": "http://residential_proxy1:8080", "username": "user", "password": "pass"},
+ {"server": "http://residential_proxy2:8080", "username": "user", "password": "pass"},
+ {"server": "http://mobile_proxy1:8080", "username": "user", "password": "pass"},
+ {"server": "http://mobile_proxy2:8080", "username": "user", "password": "pass"},
+])
+
+
+class MySpider(Spider):
+ name = "my_spider"
+ start_urls = ["https://example.com"]
+ max_blocked_retries = 5
+
+ def configure_sessions(self, manager: SessionManager) -> None:
+ manager.add('requests', FetcherSession(impersonate=['chrome', 'firefox', 'safari'], proxy_rotator=cheap_proxies))
+ manager.add('stealth', AsyncStealthySession(block_webrtc=True, proxy_rotator=expensive_proxies), lazy=True)
+
+ async def retry_blocked_request(self, request: Request, response: Response) -> Request:
+ request.sid = "stealth"
+ self.logger.info(f"Retrying blocked request: {request.url}")
+ return request
+
+ async def parse(self, response: Response):
+ yield {"title": response.css("title::text").get("")}
+```
+Запросы сначала идут через недорогие прокси, например из дата-центров. После блокировки они повторяются через более качественные прокси, например домашние или мобильные.
diff --git a/docs/locales/ru/spiders/requests-responses.md b/docs/locales/ru/spiders/requests-responses.md
new file mode 100644
index 0000000..7392b53
--- /dev/null
+++ b/docs/locales/ru/spiders/requests-responses.md
@@ -0,0 +1,207 @@
+---
+title: "Запросы пауков, обработчики и Response.follow"
+description: "Создавайте запросы для обхода, передавайте метаданные и переходите по ссылкам через response.follow. Узнайте об обработчиках, приоритетах и удалении повторных запросов."
+---
+
+# Запросы и ответы {#requests-responses}
+
+!!! success "Что нужно знать"
+
+ 1. Прочитайте страницу [Начало работы](getting-started.md), чтобы научиться создавать и запускать простого паука.
+
+Здесь подробно описан объект `Request`: создание запросов, передача данных между обработчиками, приоритеты, удаление дубликатов и переход по ссылкам с `response.follow()`.
+
+## Объект Request {#the-request-object}
+
+`Request` представляет URL, который нужно загрузить. Запрос можно создать напрямую или через `response.follow()`:
+
+```python
+from scrapling.spiders import Request
+
+# Direct construction
+request = Request(
+ "https://example.com/page",
+ callback=self.parse_page,
+ priority=5,
+)
+
+# Via response.follow (preferred in callbacks)
+request = response.follow("/page", callback=self.parse_page)
+```
+
+Все аргументы `Request`:
+
+| Аргумент | Тип | По умолчанию | Описание |
+|---------------|------------|------------|-------------------------------------------------------------------------------------------------------|
+| `url` | `str` | *обязателен* | URL для загрузки |
+| `sid` | `str` | `""` | ID сессии, через которую отправляется запрос (см. [Сессии](sessions.md)) |
+| `callback` | `callable` | `None` | Метод с асинхронным генератором для обработки ответа. По умолчанию `parse()` |
+| `priority` | `int` | `0` | Запросы с большим значением обрабатываются первыми |
+| `dont_filter` | `bool` | `False` | При `True` разрешает повторные запросы |
+| `meta` | `dict` | `{}` | Произвольные метаданные, которые передаются в ответ |
+| `**kwargs` | | | Дополнительные именованные аргументы метода загрузки сессии (например, `headers`, `method`, `data`) |
+
+Все дополнительные именованные аргументы передаются прямо в сессию. Например, для POST-запроса:
+
+```python
+yield Request(
+ "https://example.com/api",
+ method="POST",
+ data={"key": "value"},
+ callback=self.parse_result,
+)
+```
+
+## Response.follow() {#responsefollow}
+
+Для создания следующих запросов внутри обработчиков рекомендуется `response.follow()`. У него есть несколько преимуществ перед прямым созданием `Request`:
+
+- **Относительные URL** автоматически объединяются с URL текущей страницы.
+- **Заголовок Referer** по умолчанию содержит URL текущей страницы.
+- **Аргументы сессии** наследуются от исходного запроса (заголовки, настройки прокси и другие), кроме `method`, `params`, `data`, `json`, `files` и `multipart`. Поэтому переход по ссылке использует обычный GET.
+- **Обработчик, ID сессии и приоритет** наследуются от исходного запроса, если не заданы.
+
+```python
+async def parse(self, response: Response):
+ # Minimal - inherits callback, sid, priority from current request
+ yield response.follow("/next-page")
+
+ # Override specific fields
+ yield response.follow(
+ "/product/123",
+ callback=self.parse_product,
+ priority=10,
+ )
+
+ # Pass additional metadata to
+ yield response.follow(
+ "/details",
+ callback=self.parse_details,
+ meta={"category": "electronics"},
+ )
+```
+
+| Аргумент | Тип | По умолчанию | Описание |
+|--------------------|------------|------------|------------------------------------------------------------|
+| `url` | `str` | *обязателен* | URL для перехода: абсолютный или относительный |
+| `sid` | `str` | `""` | ID сессии. Если пустой, наследуется от исходного запроса |
+| `callback` | `callable` | `None` | Метод-обработчик. При `None` наследуется от исходного запроса |
+| `priority` | `int` | `None` | Приоритет. При `None` наследуется от исходного запроса |
+| `dont_filter` | `bool` | `False` | Разрешить повторные запросы |
+| `meta` | `dict` | `None` | Метаданные, которые объединяются с метаданными текущего ответа |
+| **`referer_flow`** | `bool` | `True` | Указать текущий URL в заголовке Referer |
+| `**kwargs` | | | Объединяются с аргументами сессии исходного запроса |
+
+### Отключение передачи Referer {#disabling-referer-flow}
+
+По умолчанию `response.follow()` записывает URL текущей страницы в заголовок `Referer`. Чтобы отключить это:
+
+```python
+yield response.follow("/page", referer_flow=False)
+```
+
+## Обработчики {#callbacks}
+
+Обработчики представляют собой методы паука с асинхронными генераторами, которые обрабатывают ответы. Они должны выдавать через `yield` один из трёх типов:
+
+- **`dict`**: извлечённая запись, которая добавляется в результаты.
+- **`Request`**: следующий запрос, который добавляется в очередь.
+- **`None`**: игнорируется без уведомления.
+
+```python
+class MySpider(Spider):
+ name = "my_spider"
+ start_urls = ["https://example.com"]
+
+ async def parse(self, response: Response):
+ # Yield items (dicts)
+ yield {"url": response.url, "title": response.css("title::text").get("")}
+
+ # Yield follow-up requests
+ for link in response.css("a::attr(href)").getall():
+ yield response.follow(link, callback=self.parse_page)
+
+ async def parse_page(self, response: Response):
+ yield {"content": response.css("article::text").get("")}
+```
+
+!!! tip "Примечание"
+
+ Все обработчики должны использовать `async def` и `yield`, а не `return`. Даже если обработчик выдаёт только записи без следующих запросов, он всё равно должен быть асинхронным генератором.
+
+## Приоритет запросов {#request-priority}
+
+Запросы с более высоким значением приоритета обрабатываются первыми. Это удобно, если одни страницы нужно обработать раньше других:
+
+```python
+async def parse(self, response: Response):
+ # High priority - process product pages first
+ for link in response.css("a.product::attr(href)").getall():
+ yield response.follow(link, callback=self.parse_product, priority=10)
+
+ # Low priority - pagination links processed after products
+ next_page = response.css("a.next::attr(href)").get()
+ if next_page:
+ yield response.follow(next_page, callback=self.parse, priority=0)
+```
+
+В `response.follow()` приоритет наследуется от исходного запроса, если вы не зададите новый.
+
+## Удаление дубликатов {#deduplication}
+
+Паук автоматически удаляет повторные запросы по отпечатку, который вычисляется из URL, HTTP-метода, тела запроса и ID сессии. Если два запроса имеют одинаковый отпечаток, второй отбрасывается без уведомления.
+
+Чтобы разрешить повторы, например для повторного посещения страницы после входа, установите `dont_filter=True`:
+
+```python
+yield Request("https://example.com/dashboard", dont_filter=True, callback=self.parse_dashboard)
+
+# Or with response.follow
+yield response.follow("/dashboard", dont_filter=True, callback=self.parse_dashboard)
+```
+
+Состав отпечатка можно настроить атрибутами класса паука:
+
+| Атрибут | По умолчанию | Действие |
+|----------------------|---------|-----------------------------------------------------------------------------------------------------------------|
+| `fp_include_kwargs` | `False` | Включить дополнительные аргументы запроса, переданные методу загрузки сессии, например заголовки |
+| `fp_keep_fragments` | `False` | Сохранять фрагменты URL (`#section`) при вычислении отпечатка |
+| `fp_include_headers` | `False` | Включить заголовки запроса в отпечаток |
+
+Например, чтобы считать `https://example.com/page#section1` и `https://example.com/page#section2` разными URL:
+
+```python
+class MySpider(Spider):
+ name = "my_spider"
+ fp_keep_fragments = True
+ # ...
+```
+
+## Метаданные запроса {#request-meta}
+
+Словарь `meta` позволяет передавать любые данные между обработчиками. Это полезно, когда для обработки одной страницы нужны данные с другой:
+
+```python
+async def parse(self, response: Response):
+ for product in response.css("div.product"):
+ category = product.css("span.category::text").get("")
+ link = product.css("a::attr(href)").get()
+ if link:
+ yield response.follow(
+ link,
+ callback=self.parse_product,
+ meta={"category": category},
+ )
+
+async def parse_product(self, response: Response):
+ yield {
+ "name": response.css("h1::text").get(""),
+ "price": response.css(".price::text").get(""),
+ # Access meta from the request
+ "category": response.meta.get("category", ""),
+ }
+```
+
+В `response.follow()` метаданные текущего ответа объединяются с новыми. Новые значения имеют приоритет.
+
+Система пауков также сохраняет часть метаданных автоматически. Например, при включённой смене прокси адрес использованного прокси доступен в `response.meta["proxy"]`.
diff --git a/docs/locales/ru/spiders/sessions.md b/docs/locales/ru/spiders/sessions.md
new file mode 100644
index 0000000..2c4fc45
--- /dev/null
+++ b/docs/locales/ru/spiders/sessions.md
@@ -0,0 +1,231 @@
+---
+title: "HTTP- и браузерные сессии в одном краулере"
+description: "Настройте именованные сессии и отправляйте запросы паука через HTTP- или браузерные Fetcher. Сохраняйте cookies, запускайте сессии по мере необходимости и изучайте историю API."
+---
+
+# Сессии пауков {#spiders-sessions}
+
+!!! success "Что нужно знать"
+
+ 1. Прочитайте страницу [Начало работы](getting-started.md), чтобы научиться создавать и запускать простого паука.
+ 2. Познакомьтесь с [основами Fetcher](../fetching/choosing.md) и различиями между HTTP- и Stealthy-сессиями.
+
+Паук может одновременно использовать несколько сессий Fetcher. Например, быструю HTTP-сессию для простых страниц и stealth-браузер для защищённых. Здесь показано, как настроить и использовать сессии.
+
+## Что такое сессия? {#what-are-sessions}
+
+Сессия представляет собой настроенный экземпляр Fetcher, который работает в течение всего обхода. Паук не создаёт новое соединение или браузер для каждого запроса, а повторно использует сессии. Это быстрее и требует меньше ресурсов.
+
+По умолчанию каждый паук создаёт одну [FetcherSession](../fetching/static.md). Чтобы добавить сессии или заменить основную, переопределите `configure_sessions()`. Используйте только асинхронные варианты сессий, как в таблице ниже:
+
+
+| Тип сессии | Назначение |
+|-------------------------------------------------|------------------------------------------|
+| [FetcherSession](../fetching/static.md) | Быстрые HTTP-запросы без JavaScript |
+| [AsyncStealthySession](../fetching/stealthy.md) | JavaScript, управление браузером, обход защиты от ботов |
+
+
+## Настройка сессий {#configuring-sessions}
+
+Переопределите `configure_sessions()` в пауке. Параметр `manager` содержит экземпляр `SessionManager`. Регистрируйте сессии через `manager.add()`:
+
+```python
+from scrapling.spiders import Spider, Response
+from scrapling.fetchers import FetcherSession
+
+class MySpider(Spider):
+ name = "my_spider"
+ start_urls = ["https://example.com"]
+
+ def configure_sessions(self, manager):
+ manager.add("default", FetcherSession())
+
+ async def parse(self, response: Response):
+ yield {"title": response.css("title::text").get("")}
+```
+
+Аргументы `manager.add()`:
+
+| Аргумент | Тип | По умолчанию | Описание |
+|--------------|-----------|------------|----------------------------------------------|
+| `session_id` | `str` | *обязателен* | Имя, по которому сессию можно указать в запросе |
+| `session` | `Session` | *обязателен* | Экземпляр сессии |
+| `default` | `bool` | `False` | Сделать эту сессию основной |
+| `lazy` | `bool` | `False` | Запускать сессию только при первом использовании |
+
+!!! note "Примечания"
+
+ 1. Если сессия не указана в запросе, используется сессия по умолчанию. Она определяется одним из двух способов:
+ 1. Первая добавленная в менеджер сессия автоматически становится основной.
+ 2. Сессия добавляется в менеджер с `default=True`.
+ 2. Переданные экземпляры сессий не обязательно запускать заранее. Паук проверит все сессии и запустит те, которые ещё не работают.
+ 3. Чтобы запускать сессию только при использовании, укажите аргумент `lazy` при её добавлении. Например, так можно открывать браузер только при необходимости, а не вместе с пауком.
+
+## Паук с несколькими сессиями {#multi-session-spider}
+
+Практический пример: быстрая HTTP-сессия для страниц со списками и stealth-браузер для страниц с подробностями, защищённых от ботов:
+
+```python
+from scrapling.spiders import Spider, Response
+from scrapling.fetchers import FetcherSession, AsyncStealthySession
+
+class ProductSpider(Spider):
+ name = "products"
+ start_urls = ["https://shop.example.com/products"]
+
+ def configure_sessions(self, manager):
+ # Fast HTTP for listing pages (default)
+ manager.add("http", FetcherSession())
+
+ self.browser_session = AsyncStealthySession(
+ headless=True,
+ network_idle=True,
+ record_requests=True,
+ )
+ manager.add("stealth", self.browser_session)
+
+ async def parse(self, response: Response):
+ for link in response.css("a.product::attr(href)").getall():
+ # Route product pages through the stealth session
+ yield response.follow(link, sid="stealth", callback=self.parse_product)
+
+ next_page = response.css("a.next::attr(href)").get()
+ if next_page:
+ yield response.follow(next_page)
+
+ async def parse_product(self, response: Response):
+ yield {
+ "name": response.css("h1::text").get(""),
+ "price": response.css(".price::text").get(""),
+ }
+
+ async def on_close(self):
+ for api_response in self.browser_session.network.search(
+ url_pattern=r"https://api\.shop\.example\.com/.*", limit=None
+ ):
+ self.logger.info(f"Saved API response: {api_response.url} ({api_response.status})")
+```
+
+В примере сохраняется экземпляр браузера, а его история API читается один раз в `on_close()` перед закрытием сессий. История охватывает все страницы товаров и остаётся доступной после закрытия. Завершение ещё не записанных запросов не ожидается, а ограничения объёма истории продолжают действовать.
+
+Основную роль играет `sid`: он указывает пауку сессию для каждого запроса. Если вызвать `response.follow()` без `sid`, ID сессии наследуется от исходного запроса.
+
+Сессии не обязательно должны относиться к разным классам. Можно создать несколько экземпляров одного класса с разными настройками:
+
+```python
+from scrapling.spiders import Spider, Response
+from scrapling.fetchers import FetcherSession
+
+class ProductSpider(Spider):
+ name = "products"
+ start_urls = ["https://shop.example.com/products"]
+
+ def configure_sessions(self, manager):
+ chrome_requests = FetcherSession(impersonate="chrome")
+ firefox_requests = FetcherSession(impersonate="firefox")
+
+ manager.add("chrome", chrome_requests)
+ manager.add("firefox", firefox_requests)
+
+ async def parse(self, response: Response):
+ for link in response.css("a.product::attr(href)").getall():
+ yield response.follow(link, callback=self.parse_product)
+
+ next_page = response.css("a.next::attr(href)").get()
+ if next_page:
+ yield response.follow(next_page, sid="firefox")
+
+ async def parse_product(self, response: Response):
+ yield {
+ "name": response.css("h1::text").get(""),
+ "price": response.css(".price::text").get(""),
+ }
+```
+
+Также можно выделить отдельную сессию со своими cookies и состоянием для определённых запросов.
+
+## Аргументы сессии {#session-arguments}
+
+Дополнительные именованные аргументы `Request` или `response.follow(**kwargs)` передаются в метод загрузки сессии. Так можно настроить отдельный запрос, не меняя настройки всей сессии:
+
+```python
+async def parse(self, response: Response):
+ # Pass extra headers for this specific request
+ yield Request(
+ "https://api.example.com/data",
+ headers={"Authorization": "Bearer token123"},
+ callback=self.parse_api,
+ )
+
+ # Use a different HTTP method
+ yield Request(
+ "https://example.com/submit",
+ method="POST",
+ data={"field": "value"},
+ sid="firefox",
+ callback=self.parse_result,
+ )
+```
+
+!!! warning
+
+ Обычно при работе с `FetcherSession`, `Fetcher` или `AsyncFetcher` HTTP-метод выбирается вызовом `.get()`, `.post()` и подобных методов. В пауках с `FetcherSession` это устроено иначе. По умолчанию отправляется _HTTP GET_. Чтобы выбрать другой метод, передайте его через аргумент `method`, как в примере выше. Это позволяет использовать единый интерфейс `Request` для всех типов сессий.
+
+Для сессии `"stealth"` (`AsyncStealthySession`) из примера выше можно передать браузерные аргументы, такие как `wait_selector`, `page_action` и `extra_headers`:
+
+```python
+async def parse(self, response: Response):
+ # Use Cloudflare solver with the `AsyncStealthySession` we configured above
+ yield Request(
+ "https://nopecha.com/demo/cloudflare",
+ sid="stealth",
+ callback=self.parse_result,
+ solve_cloudflare=True,
+ block_webrtc=True,
+ hide_canvas=True,
+ google_search=True,
+ )
+
+ yield response.follow(
+ "/dynamic-page",
+ sid="stealth",
+ callback=self.parse_dynamic,
+ wait_selector="div.loaded",
+ network_idle=True,
+ )
+```
+
+!!! warning
+
+ `response.follow()` наследует аргументы сессии (**kwargs) от исходного запроса, кроме `method`, `params`, `data`, `json`, `files` и `multipart`. Поэтому переход по ссылке после POST отправляет обычный GET. Новые аргументы имеют приоритет над унаследованными.
+
+```python
+from scrapling.spiders import Spider, Response
+from scrapling.fetchers import FetcherSession
+
+class ProductSpider(Spider):
+ name = "products"
+ start_urls = ["https://shop.example.com/products"]
+
+ def configure_sessions(self, manager):
+ manager.add("http", FetcherSession(impersonate='chrome'))
+
+ async def parse(self, response: Response):
+ # I don't want the follow request to impersonate a desktop Chrome like the previous request, but a mobile one
+ # so I override it like this
+ for link in response.css("a.product::attr(href)").getall():
+ yield response.follow(link, impersonate="chrome131_android", callback=self.parse_product)
+
+ next_page = response.css("a.next::attr(href)").get()
+ if next_page:
+ yield response.follow(next_page)
+
+ async def parse_product(self, response: Response):
+ yield {
+ "name": response.css("h1::text").get(""),
+ "price": response.css(".price::text").get(""),
+ }
+```
+!!! info
+
+ При завершении паука менеджер автоматически проверяет, остались ли работающие сессии, и закрывает их перед закрытием паука.
diff --git a/docs/locales/ru/stylesheets b/docs/locales/ru/stylesheets
new file mode 120000
index 0000000..02c6ba6
--- /dev/null
+++ b/docs/locales/ru/stylesheets
@@ -0,0 +1 @@
+../../stylesheets
\ No newline at end of file
diff --git a/docs/locales/ru/tutorials/migrating_from_beautifulsoup.md b/docs/locales/ru/tutorials/migrating_from_beautifulsoup.md
new file mode 100644
index 0000000..5cef9b1
--- /dev/null
+++ b/docs/locales/ru/tutorials/migrating_from_beautifulsoup.md
@@ -0,0 +1,100 @@
+---
+title: "Переход с BeautifulSoup на Scrapling"
+description: "Сравните выбор элементов, работу с текстом, атрибутами и навигацией в BeautifulSoup и Scrapling. Изучите различия API на практических примерах."
+---
+
+# Переход с BeautifulSoup на Scrapling {#migrating-from-beautifulsoup-to-scrapling}
+
+Если вы уже знакомы с BeautifulSoup, освоить Scrapling будет легко. Scrapling работает заметно быстрее, предоставляет те же возможности парсинга и добавляет новые. В нём также есть инструменты загрузки и обработки современных веб-страниц. Это руководство поможет быстро перенести существующий код BeautifulSoup на Scrapling.
+
+В таблице ниже собраны распространённые операции при сборе данных. Каждая строка показывает, как выполнить задачу в BeautifulSoup и как сделать то же в Scrapling.
+
+Некоторых сокращённых записей BeautifulSoup в Scrapling нет. Это одна из причин, по которым Scrapling быстрее. Если функцию уже можно вызвать одной короткой строкой, нет смысла жертвовать скоростью, чтобы сделать эту строку ещё короче :)
+
+
+| Задача | Код BeautifulSoup | Код Scrapling |
+|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
+| Импорт парсера | `from bs4 import BeautifulSoup` | `from scrapling.parser import Selector` |
+| Парсинг HTML из строки | `soup = BeautifulSoup(html, 'html.parser')` | `page = Selector(html)` |
+| Поиск одного элемента | `element = soup.find('div', class_='example')` | `element = page.find('div', class_='example')` |
+| Поиск нескольких элементов | `elements = soup.find_all('div', class_='example')` | `elements = page.find_all('div', class_='example')` |
+| Поиск одного элемента (пример 2) | `element = soup.find('div', attrs={"class": "example"})` | `element = page.find('div', {"class": "example"})` |
+| Поиск одного элемента (пример 3) | `element = soup.find(re.compile("^b"))` | `element = page.find(lambda e: re.search(r"^b", e.tag) is not None)` |
+| Поиск одного элемента (пример 4) | `element = soup.find(lambda e: len(list(e.children)) > 0)` | `element = page.find(lambda e: len(e.children) > 0)` |
+| Поиск одного элемента (пример 5) | `element = soup.find(["a", "b"])` | `element = page.find(["a", "b"])` |
+| Поиск элемента по тексту | `element = soup.find(text="some text")` | `element = page.find_by_text("some text", partial=False)` |
+| Поиск первого совпадения с CSS-селектором | `elements = soup.select_one('div.example')` | `elements = page.css('div.example').first` |
+| Поиск всех совпадений с CSS-селектором | `elements = soup.select('div.example')` | `elements = page.css('div.example')` |
+| Получение отформатированного исходного кода страницы или элемента | `prettified = soup.prettify()` | `prettified = page.prettify()` |
+| Получение исходного кода страницы или элемента без форматирования | `source = str(soup)` | `source = page.html_content` |
+| Получение имени тега элемента | `name = element.name` | `name = element.tag` |
+| Извлечение текста элемента | `string = element.string` | `string = element.text` |
+| Извлечение всего текста документа или содержимого тега | `text = soup.get_text(strip=True)` | `text = page.get_all_text(strip=True)` |
+| Доступ к словарю атрибутов | `attrs = element.attrs` | `attrs = element.attrib` |
+| Извлечение атрибутов | `attr = element['href']` | `attr = element['href']` |
+| Переход к родителю | `parent = element.parent` | `parent = element.parent` |
+| Получение всех предков элемента | `parents = list(element.parents)` | `parents = list(element.iterancestors())` |
+| Поиск элемента среди предков | `target_parent = element.find_parent("a")` | `target_parent = element.find_ancestor(lambda p: p.tag == 'a')` |
+| Получение всех соседних элементов | Нет аналога | `siblings = element.siblings` |
+| Получение следующего соседнего элемента | `next_element = element.next_sibling` | `next_element = element.next` |
+| Поиск одного элемента среди соседних | `target_sibling = element.find_next_sibling("a")`<br/>`target_sibling = element.find_previous_sibling("a")` | `target_sibling = element.siblings.search(lambda s: s.tag == 'a')` |
+| Поиск нескольких элементов среди соседних | `target_sibling = element.find_next_siblings("a")`<br/>`target_sibling = element.find_previous_siblings("a")` | `target_sibling = element.siblings.filter(lambda s: s.tag == 'a')` |
+| Поиск одного элемента среди последующих | `target_parent = element.find_next("a")` | `target_parent = element.below_elements.search(lambda p: p.tag == 'a')` |
+| Поиск нескольких элементов среди последующих | `target_parent = element.find_all_next("a")` | `target_parent = element.below_elements.filter(lambda p: p.tag == 'a')` |
+| Поиск одного элемента среди предков | `target_parent = element.find_previous("a")` ¹ | `target_parent = element.path.search(lambda p: p.tag == 'a')` |
+| Поиск нескольких элементов среди предков | `target_parent = element.find_all_previous("a")` ¹ | `target_parent = element.path.filter(lambda p: p.tag == 'a')` |
+| Получение предыдущего соседнего элемента | `prev_element = element.previous_sibling` | `prev_element = element.previous` |
+| Переход к дочерним элементам | `children = list(element.children)` | `children = element.children` |
+| Получение всех потомков | `children = list(element.descendants)` | `children = element.below_elements` |
+| Выбор ссылок внутри абзацев с классом story | `group = soup.select('p.story a')` | `group = page.css('p.story a')` |
+
+Если передать скомпилированное регулярное выражение прямо в `find()` или `find_all()` Scrapling, оно будет проверять текст элемента, а не имя тега. Для имён тегов используйте lambda из таблицы, а для поиска по тексту можно напрямую вызвать `page.find_by_regex(r"^b")`.
+
+¹ **Примечание:** `find_previous`/`find_all_previous` в BS4 ищут среди всех предыдущих элементов в порядке документа. `path` в Scrapling возвращает только предков, то есть цепочку родителей. Это не полные аналоги, но поиск по предкам покрывает наиболее частый случай.
+
+**Важный момент**: BeautifulSoup позволяет изменять страницу после парсинга. Scrapling сосредоточен на быстром сборе данных, а с извлечённой информацией вы можете работать как угодно. Оба инструмента подходят для веб-скрейпинга, но Scrapling специализируется именно на нём :)
+
+### Полный пример {#putting-it-all-together}
+
+Простой пример извлечения всех ссылок со страницы с помощью BeautifulSoup и Scrapling.
+
+**С BeautifulSoup:**
+
+```python
+import requests
+from bs4 import BeautifulSoup
+
+url = 'https://example.com'
+response = requests.get(url)
+soup = BeautifulSoup(response.text, 'html.parser')
+
+links = soup.find_all('a')
+for link in links:
+ print(link['href'])
+```
+
+**Со Scrapling:**
+
+```python
+from scrapling import Fetcher
+
+url = 'https://example.com'
+page = Fetcher.get(url)
+
+links = page.css('a::attr(href)').getall()
+for link in links:
+ print(link)
+```
+
+Scrapling объединяет загрузку и парсинг в один шаг. Это делает код короче и эффективнее.
+
+!!! abstract "**Дополнительные примечания:**"
+
+ - **Разные парсеры**: BeautifulSoup позволяет выбрать движок, в том числе `lxml`. Scrapling не переключает движки и по умолчанию использует `lxml` ради скорости.
+ - **Типы элементов**: в BeautifulSoup элементы представлены объектами `Tag`, а в Scrapling объектами `Selector`. При этом у них похожие методы и свойства для навигации и извлечения данных.
+ - **Обработка ошибок**: обе библиотеки возвращают `None`, если элемент не найден, например в `soup.find()` или `page.find()`. В Scrapling `page.css()` возвращает пустой список `Selectors`, если совпадений нет. `page.css('.foo').first` безопасно возвращает первое совпадение или `None`. Чтобы избежать ошибок, перед доступом к свойствам проверяйте, что результат не равен `None` и не пуст.
+ - **Извлечение текста**: `TextHandler` в Scrapling предоставляет дополнительные методы работы с текстом. Например, `clean()` помогает удалять лишние пробельные символы, повторяющиеся пробелы и ненужные символы. Полный список есть в документации.
+
+В документации подробно описаны возможности Scrapling и все аргументы его методов.
+
+Надеюсь, это руководство упростит переход с BeautifulSoup на Scrapling. Удачного сбора данных!
diff --git a/docs/locales/ru/tutorials/replacing_ai.md b/docs/locales/ru/tutorials/replacing_ai.md
new file mode 100644
index 0000000..267be66
--- /dev/null
+++ b/docs/locales/ru/tutorials/replacing_ai.md
@@ -0,0 +1,119 @@
+---
+title: "Бесплатная альтернатива ИИ для устойчивого сбора данных с сайтов"
+description: "Scrapling помогает справляться с изменениями страниц, нестабильными селекторами, защитой от ботов и пагинацией без вызова LLM для каждой страницы."
+---
+
+# Scrapling: бесплатная альтернатива ИИ для устойчивого сбора данных с сайтов {#scrapling-a-free-alternative-to-ai-for-robust-web-scraping}
+
+Веб-скрейпинг давно используется для извлечения данных, индексации, подготовки наборов данных и других задач. Но даже опытные пользователи регулярно встречают проблемы, которые мешают работе. В последнее время всё чаще выбирают сбор данных с помощью ИИ, надеясь решить эти проблемы.
+
+В этой статье мы разберём типичные трудности, причины перехода компаний к ИИ, недостатки такого подхода и то, как Scrapling решает эти задачи без затрат на ИИ.
+
+## Типичные проблемы и сложные цели {#common-issues-and-challenging-goals}
+
+Если вы давно собираете данные с сайтов, то наверняка замечали повторяющиеся проблемы:
+
+1. **Частые изменения структуры сайта**: обновления DOM ломают фиксированные XPath/CSS-селекторы.
+2. **Нестабильные селекторы**: имена классов и ID меняются или генерируются случайно. Это ломает код и затрудняет сбор данных.
+3. **Всё более сложная защита от ботов**: CAPTCHA, проверка отпечатка браузера и анализ поведения мешают обычным методам сбора.
+
+И это не весь список.
+
+Пока речь идёт только об известных сайтах, для каждого из которых можно написать отдельный код.
+
+Если же вы хотите собирать данные с большого числа разных сайтов универсальным способом, эти проблемы становятся сложнее. Появляются и новые:
+
+1. **Разнообразие сайтов**: нужно учитывать множество вариантов HTML, CSS, JavaScript-фреймворков и серверных технологий.
+2. **Поиск нужных данных**: как определить, что важно на странице, которую программа видит впервые?
+3. **Разные способы пагинации**: бесконечная прокрутка, номера страниц и кнопки «Загрузить ещё» требуют разных действий.
+
+И это тоже не всё.
+
+Как решить это вручную? Речь идёт об универсальном сборе данных с сайтов, которые не используют общие технологии.
+
+## ИИ помогает, но дорого обходится {#ai-to-the-rescue-but-at-a-high-cost}
+
+ИИ может решить большинство этих задач: понять исходный код страницы, найти нужные поля или создать для них селекторы. Конечно, если защиту от ботов вы уже обошли другими инструментами :)
+
+Подход привлекательный. Мне нравится ИИ, особенно генеративный. Возможно, вы потратите много времени на составление и настройку промптов. Но даже если это вас устраивает, вскоре вы столкнётесь с главной проблемой.
+
+На большинстве сайтов страницы содержат много данных, которые нужно как-то передать ИИ для обработки. Это быстро расходует токены, и стоимость растёт.
+
+Если бюджет не безграничен, вы начнёте искать более дешёвые способы. Здесь и пригодится Scrapling :smile:
+
+## Scrapling поможет {#scrapling-got-you-covered}
+
+Scrapling справляется почти со всеми проблемами, которые возникают при сборе данных с сайтов. Оставшиеся задачи будут постепенно решаться в будущих обновлениях.
+
+### Решение T1: частые изменения структуры сайта {#solving-issue-t1-rapidly-changing-website-structures}
+Именно для этого создана [адаптивная функция](../parsing/adaptive.md). Вы наверняка ожидали, что мы о ней поговорим :)
+
+При включённом `adaptive` можно сохранить особенности любого элемента и найти его позже, когда структура сайта изменится. Главная трудность в том, что у элемента может измениться что угодно, поэтому нельзя полагаться на один постоянный признак.
+
+Адаптивная функция сохраняет все характерные свойства элемента. После изменения структуры сайта она возвращает элемент, наиболее похожий на прежний.
+
+Подробное объяснение и много примеров уже есть [здесь](../parsing/adaptive.md#how-the-adaptive-scraping-feature-works).
+
+### Решение T2: нестабильные селекторы {#solving-issue-t2-unstable-selectors}
+Если вы давно занимаетесь веб-скрейпингом, то, скорее всего, встречали сайты с неудобной структурой: HTML без ID и классов, случайные имена классов и отсутствие других надёжных признаков.
+
+В таких случаях обычные CSS/XPath-селекторы не всегда подходят. Поэтому Scrapling предоставляет ещё три способа выбора элементов:
+
+1. [По содержимому элемента](../parsing/selection.md#text-content-selection): по тексту через `find_by_text` или по регулярному выражению для текста через `find_by_regex`.
+2. [По сходству с другим элементом](../parsing/selection.md#finding-similar-elements): найдите один элемент, а похожие найдёт Scrapling.
+3. [По фильтрам](../parsing/selection.md#filters-based-searching): задайте условия, которым должен соответствовать элемент, и Scrapling найдёт его.
+
+Подробности есть по ссылкам, поэтому здесь не будем повторять объяснения.
+
+### Решение T3: всё более сложная защита от ботов {#solving-issue-t3-increasingly-complex-anti-bot-measures}
+Для защищённых сайтов одних прокси и действий, похожих на человеческие, может быть недостаточно. [StealthyFetcher](../fetching/stealthy.md) сочетает автоматизацию браузера с изменением его отпечатка и настройками для обхода защиты. Для проверок Cloudflare Turnstile и Interstitial включите `solve_cloudflare=True`.
+
+### Решение B1 и B2: разнообразие сайтов и поиск нужных данных {#solving-issues-b1-b2-extreme-website-diversity-identifying-relevant-data}
+
+Это сложная задача, но гибкость Scrapling помогает её решить.
+
+Я разговаривал с человеком, который использовал ИИ для извлечения цен с разных сайтов. Ему нужны были только цены и заголовки, и он поручал поиск цен ИИ.
+
+Я объяснил, что здесь можно обойтись без ИИ, и показал такой пример:
+```python
+price_element = page.find_by_regex(r'£[\d\.,]+', first_match=True) # Get the first element that contains a text that matches price regex eg. £10.50
+# If you want the container/element that contains the price element
+price_element_container = price_element.parent or price_element.find_ancestor(lambda ancestor: ancestor.has_class('product')) # or other methods...
+target_element_selector = price_element_container.generate_css_selector or price_element_container.generate_full_css_selector # or xpath
+```
+Он спросил, что делать в таком случае:
+```html
+<span class='currency'> $ </span> <span class='a-price'> 45,000 </span>
+```
+Тогда я изменил код:
+```python
+price_element_container = page.find_by_regex(r'[\d,]+', first_match=True).parent # Adjusted the regex for this example
+full_price_data = price_element_container.get_all_text(separator="", strip=True) # Returns '$45,000' in this case
+```
+Для его задачи этого хватило. Можно сначала использовать первое регулярное выражение, а если оно ничего не найдёт, пробовать следующее. Сначала покройте самые частые варианты, затем более редкие.
+Это немного скучно, но точно дешевле ИИ.
+
+Пример показывает главную мысль: не всякая задача требует ИИ. Иногда достаточно немного изобретательности, чтобы заметно сэкономить.
+
+### Решение B3: разные способы пагинации {#solving-issue-b3-pagination-variations}
+Сейчас в Scrapling нет отдельного метода, который сам определяет ссылки пагинации. Spider следует по ним через `response.follow()`.
+
+Но для большинства сайтов можно искать распространённые варианты: `page.find_by_text('Next')['href']`, `page.find_by_text('load more')['href']` или селекторы вроде `'a[href*="?page="]'` и `'a[href*="/page/"]'`. Принцип тот же.
+
+## Сравнение затрат и экономия {#cost-comparison-and-savings}
+Краткое сравнение:
+
+| Критерий | Scrapling | Инструменты на основе ИИ, например Browse AI и Oxylabs |
+|----------------|----------------------------------------------------------------------------|----------------------------------------------------------------------------|
+| Стоимость | Бесплатно, без платы за число обращений к библиотеке | Платные планы; цена зависит от поставщика и объёма использования |
+| Настройка | Нужны небольшие технические знания и ручная настройка | Часто не требуют кода и проще для нетехнических пользователей |
+| Способы работы | Через код, терминал или MCP-сервер | Обычно через графический интерфейс или API, в зависимости от сервиса |
+| Масштабирование | Зависит от реализации пользователя | Встроенная поддержка больших объёмов и управляемые сервисы |
+| Адаптация | Гибкая благодаря `adaptive` и выбору элементов без селекторов | Автоматическая за счёт ИИ, но частые изменения повышают расходы |
+
+Текущие цены указаны на страницах [Browse AI](https://www.browse.ai/pricing) и [Oxylabs Web Scraper API](https://oxylabs.io/products/scraper-api/web/pricing).
+
+## Итоги {#conclusion}
+ИИ даёт много возможностей, но для многих задач сбора данных его стоимость слишком высока. Scrapling предлагает надёжные и гибкие инструменты с низкими затратами как для отдельных сайтов, так и для широкого обхода. Часто они позволяют обойтись без дорогих ИИ-сервисов. `adaptive`, разные способы выбора элементов и мощные Fetcher помогают быстрее создавать код, устойчивый к изменениям сайтов.
+
+Изучайте документацию дальше, чтобы узнать, как Scrapling может упростить ваши следующие проекты по сбору данных.
diff --git a/docs/overrides/api/python/material/languages/ru.html.jinja b/docs/overrides/api/python/material/languages/ru.html.jinja
new file mode 100644
index 0000000..a9a68bd
--- /dev/null
+++ b/docs/overrides/api/python/material/languages/ru.html.jinja
@@ -0,0 +1,17 @@
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "АТРИБУТ", "Attributes": "Атрибуты", "Attributes:": "Атрибуты:",
+ "BOUND:": "ВЕРХНЯЯ ГРАНИЦА:", "Bound or Constraints": "Верхняя граница или ограничения",
+ "Classes": "Классы", "Classes:": "Классы:", "CLASS": "КЛАСС",
+ "Class Type Parameters:": "Параметры типа класса:", "CLASS TYPE PARAMETER": "ПАРАМЕТР ТИПА КЛАССА",
+ "CONSTRAINTS:": "ОГРАНИЧЕНИЯ:", "DEFAULT:": "ПО УМОЛЧАНИЮ:", "Default": "По умолчанию", "default:": "по умолчанию:",
+ "DESCRIPTION": "ОПИСАНИЕ", "Description": "Описание", "Examples:": "Примеры:",
+ "Functions": "Функции", "Functions:": "Функции:", "FUNCTION": "ФУНКЦИЯ",
+ "Init Type Parameters:": "Параметры типа конструктора:", "INIT TYPE PARAMETER": "ПАРАМЕТР ТИПА КОНСТРУКТОРА",
+ "Methods:": "Методы:", "METHOD": "МЕТОД", "Modules": "Модули", "Modules:": "Модули:", "MODULE": "МОДУЛЬ",
+ "Name": "Имя", "Other Parameters:": "Другие параметры:", "PARAMETER": "ПАРАМЕТР", "Parameters:": "Параметры:",
+ "RAISES": "ИСКЛЮЧЕНИЯ", "Raises:": "Исключения:", "RECEIVES": "ПОЛУЧАЕТ", "Receives:": "Получает:",
+ "required": "обязательный", "RETURNS": "ВОЗВРАЩАЕТ", "Returns:": "Возвращает:", "Source code in": "Исходный код в",
+ "TYPE:": "ТИП:", "Type": "Тип", "Type Aliases": "Псевдонимы типов", "Type Aliases:": "Псевдонимы типов:",
+ "TYPE ALIAS": "ПСЕВДОНИМ ТИПА", "Type Parameters:": "Параметры типа:", "TYPE PARAMETER": "ПАРАМЕТР ТИПА",
+ "WARNS": "ПРЕДУПРЕЖДЕНИЯ", "Warns:": "Предупреждения:", "YIELDS": "ВЫДАЁТ", "Yields:": "Выдаёт:"
+}.get(key, "") }}{% endmacro %}
diff --git a/docs/overrides/api/python/material/translations/ru.html.jinja b/docs/overrides/api/python/material/translations/ru.html.jinja
new file mode 100644
index 0000000..586c3e3
--- /dev/null
+++ b/docs/overrides/api/python/material/translations/ru.html.jinja
@@ -0,0 +1,369 @@
+{% set translations = {
+ "<p>This class is returned by all engines as a way to unify the response type between different libraries.</p>": "<p>Все движки возвращают этот класс, чтобы использовать единый тип ответа для разных библиотек.</p>",
+ "<p>HTTP status code.</p>": "<p>Код состояния HTTP.</p>",
+ "<p>HTTP status message.</p>": "<p>Сообщение состояния HTTP.</p>",
+ "<p>Response cookies.</p>": "<p>Cookies ответа.</p>",
+ "<p>Response headers.</p>": "<p>Заголовки ответа.</p>",
+ "<p>Request headers sent with the request.</p>": "<p>Заголовки, отправленные с запросом.</p>",
+ "<p>List of redirect responses, if any.</p>": "<p>Список ответов перенаправления, если они были.</p>",
+ "<p>Metadata dictionary (e.g., proxy used).</p>": "<p>Словарь метаданных, например использованный прокси.</p>",
+ "<p>Associated spider Request object (set by crawler, in the spiders framework).</p>": "<p>Связанный объект Request паука. Задаётся краулером в системе пауков.</p>",
+ "<p>The main class that works as a wrapper for the HTML input data. Using this class, you can search for elements\nwith expressions in CSS, XPath, or with simply text. Check the docs for more info.</p>": "<p>Основной класс для работы с входными HTML-данными. Позволяет искать элементы с помощью CSS, XPath или обычного текста. Подробнее в документации.</p>",
+ "<p>Here we try to extend module <code>lxml.html.HtmlElement</code> while maintaining a simpler interface, We are not\ninheriting from the <code>lxml.html.HtmlElement</code> because it's not pickleable, which makes a lot of reference jobs\nnot possible. You can test it here and see code explodes with <code>AssertionError: invalid Element proxy at...</code>.\nIt's an old issue with lxml, see <code>this entry &lt;https://bugs.launchpad.net/lxml/+bug/736708&gt;</code></p>": "<p>Класс расширяет возможности <code>lxml.html.HtmlElement</code>, сохраняя простой интерфейс. Он не наследует <code>lxml.html.HtmlElement</code>, поскольку тот нельзя сохранить через pickle, что мешает многим операциям со ссылками. При попытке возникает ошибка <code>AssertionError: invalid Element proxy at...</code>. Это давняя проблема lxml, см. <code>this entry &lt;https://bugs.launchpad.net/lxml/+bug/736708&gt;</code>.</p>",
+ "<p>HTML content as either string or bytes.</p>": "<p>Содержимое HTML в виде строки или байтов.</p>",
+ "<p>It allows storing a URL with the HTML data for retrieving later.</p>": "<p>Позволяет сохранить URL вместе с HTML-данными для последующего получения.</p>",
+ "<p>The encoding type that will be used in HTML parsing, default is <code>UTF-8</code></p>": "<p>Кодировка для разбора HTML. По умолчанию <code>UTF-8</code>.</p>",
+ "<p>Enabled by default, should always be enabled when parsing large HTML documents. This controls\nthe libxml2 feature that forbids parsing certain large documents to protect from possible memory exhaustion.</p>": "<p>Включено по умолчанию. При разборе больших HTML-документов всегда оставляйте включённым. Управляет функцией libxml2, которая запрещает разбор некоторых больших документов для защиты от нехватки памяти.</p>",
+ "<p>Used internally to pass etree objects instead of text/body arguments, it takes the highest priority.\nDon't use it unless you know what you are doing!</p>": "<p>Внутренний аргумент для передачи объектов etree вместо текста или тела. Имеет наивысший приоритет. Используйте его только если понимаете, как он работает.</p>",
+ "<p>While parsing the HTML body, drop comments or not. Disabled by default for obvious reasons</p>": "<p>Нужно ли сохранять комментарии при разборе HTML. По умолчанию выключено.</p>",
+ "<p>Globally turn off the adaptive feature in all functions, this argument takes higher\npriority over all adaptive related arguments/functions in the class.</p>": "<p>Глобально отключает адаптивные функции во всех методах. Имеет приоритет над всеми связанными с ними аргументами и методами класса.</p>",
+ "<p>The storage class to be passed for adaptive functionalities, see <code>Docs</code> for more info.</p>": "<p>Класс хранилища для адаптивных функций. Подробнее в <code>Docs</code>.</p>",
+ "<p>A dictionary of <code>argument-&gt;value</code> pairs to be passed for the storage class.\nIf empty, default values will be used.</p>": "<p>Словарь пар <code>argument-&gt;value</code> для класса хранилища. Если пуст, используются значения по умолчанию.</p>",
+ "<p>Return the raw body of the current <code>Selector</code> without any processing. Useful for binary and non-HTML requests.</p>": "<p>Возвращает исходное тело текущего <code>Selector</code> без обработки. Полезно для двоичных данных и запросов не к HTML.</p>",
+ "<p>Return the raw body of the response as bytes.</p>": "<p>Возвращает исходное тело ответа в виде байтов.</p>",
+ "<p>Generate a CSS selector for the current element</p>": "<p>Создаёт CSS-селектор для текущего элемента.</p>",
+ "<p>A string of the generated selector.</p>": "<p>Строка с созданным селектором.</p>",
+ "<p>Generate a complete CSS selector for the current element</p>": "<p>Создаёт полный CSS-селектор для текущего элемента.</p>",
+ "<p>Generate an XPath selector for the current element</p>": "<p>Создаёт XPath-селектор для текущего элемента.</p>",
+ "<p>Generate a complete XPath selector for the current element</p>": "<p>Создаёт полный XPath-селектор для текущего элемента.</p>",
+ "<p>Get the tag name of the element</p>": "<p>Получает имя тега элемента.</p>",
+ "<p>Get text content of the element</p>": "<p>Получает текстовое содержимое элемента.</p>",
+ "<p>Get attributes of the element</p>": "<p>Получает атрибуты элемента.</p>",
+ "<p>Return the inner HTML code of the element</p>": "<p>Возвращает внутренний HTML-код элемента.</p>",
+ "<p>Return the direct parent of the element or <code>None</code> otherwise</p>": "<p>Возвращает непосредственный родительский элемент или <code>None</code>, если его нет.</p>",
+ "<p>Return all elements under the current element in the DOM tree</p>": "<p>Возвращает все элементы под текущим элементом в дереве DOM.</p>",
+ "<p>Return the children elements of the current element or empty list otherwise</p>": "<p>Возвращает дочерние элементы текущего элемента или пустой список, если их нет.</p>",
+ "<p>Return other children of the current element's parent or empty list otherwise</p>": "<p>Возвращает другие дочерние элементы того же родителя или пустой список, если их нет.</p>",
+ "<p>Returns a list of type <code>Selectors</code> that contains the path leading to the current element from the root.</p>": "<p>Возвращает список типа <code>Selectors</code> с путём от корня к текущему элементу.</p>",
+ "<p>Returns the next element of the current element in the children of the parent or <code>None</code> otherwise.</p>": "<p>Возвращает следующий элемент среди дочерних элементов того же родителя или <code>None</code>, если его нет.</p>",
+ "<p>Returns the previous element of the current element in the children of the parent or <code>None</code> otherwise.</p>": "<p>Возвращает предыдущий элемент среди дочерних элементов того же родителя или <code>None</code>, если его нет.</p>",
+ "<p>Convert the response content to clean Markdown.</p>": "<p>Преобразует содержимое ответа в очищенный Markdown.</p>",
+ "<p>Scripts, styles, and hidden/prompt-injection content are always removed before conversion, which is\nthe same cleaning the MCP server does. Requires the \"markdownify\" package (<code>pip install \"scrapling[rag]\"</code>).</p>": "<p>Перед преобразованием всегда удаляет скрипты, стили, скрытое содержимое и содержимое с внедрёнными инструкциями для ИИ. Используется та же очистка, что и на MCP-сервере. Требуется пакет markdownify (<code>pip install \"scrapling[rag]\"</code>).</p>",
+ "<p>CSS selector to convert only the matching elements. All matches are concatenated.</p>": "<p>CSS-селектор для преобразования только подходящих элементов. Все совпадения объединяются.</p>",
+ "<p>Convert only the content inside the <code>&lt;body&gt;</code> tag.</p>": "<p>Преобразует только содержимое внутри тега <code>&lt;body&gt;</code>.</p>",
+ "<p>Create a Request to follow a URL.</p>": "<p>Создаёт Request для перехода по URL.</p>",
+ "<p>This is a helper method for spiders to easily follow links found in pages.</p>": "<p>Вспомогательный метод, с которым паукам проще переходить по найденным на странице ссылкам.</p>",
+ "<p><strong>IMPORTANT</strong>: The below arguments if left empty, the corresponding value from the previous request will be used. The only exception is <code>dont_filter</code>.</p>": "<p><strong>Важно</strong>: если следующие аргументы не заданы, используются соответствующие значения предыдущего запроса. Единственное исключение: <code>dont_filter</code>.</p>",
+ "<p>The session kwargs of the previous request are inherited as well, except <code>method</code>, <code>params</code>, <code>data</code>, <code>json</code>, <code>files</code>, and <code>multipart</code>, so a followed link is a plain GET unless you pass them again.</p>": "<p>Аргументы сессии предыдущего запроса тоже наследуются, кроме <code>method</code>, <code>params</code>, <code>data</code>, <code>json</code>, <code>files</code> и <code>multipart</code>. Поэтому переход по ссылке отправляет обычный GET, если не передать эти аргументы снова.</p>",
+ "<p>The URL to follow (can be relative, will be joined with current URL)</p>": "<p>URL для перехода. Может быть относительным: в этом случае он объединяется с текущим URL.</p>",
+ "<p>The session id to use</p>": "<p>ID используемой сессии.</p>",
+ "<p>Spider callback method to use</p>": "<p>Метод-обработчик паука.</p>",
+ "<p>The priority number to use, the higher the number, the higher priority to be processed first.</p>": "<p>Числовой приоритет. Чем выше значение, тем раньше обрабатывается запрос.</p>",
+ "<p>If this request has been done before, disable the filter to allow it again.</p>": "<p>Отключает фильтр, чтобы разрешить запрос, который уже выполнялся.</p>",
+ "<p>Additional meta data to included in the request</p>": "<p>Дополнительные метаданные запроса.</p>",
+ "<p>Enabled by default, set the current response url as referer for the new request url.</p>": "<p>Включено по умолчанию. Указывает URL текущего ответа в заголовке Referer нового запроса.</p>",
+ "<p>Additional Request arguments</p>": "<p>Дополнительные аргументы Request.</p>",
+ "<p>Request object ready to be yielded</p>": "<p>Объект Request, готовый к выдаче через yield.</p>",
+ "<p>Get all child strings of this element, concatenated using the given separator.</p>": "<p>Получает все дочерние строки элемента, объединённые заданным разделителем.</p>",
+ "<p>Strings will be concatenated using this separator.</p>": "<p>Разделитель для объединения строк.</p>",
+ "<p>If True, strings will be stripped before being concatenated.</p>": "<p>При True удаляет пробельные символы по краям строк перед объединением.</p>",
+ "<p>A tuple of all tag names you want to ignore</p>": "<p>Кортеж имён всех тегов, которые нужно игнорировать.</p>",
+ "<p>If enabled, elements with text-content that is empty or only whitespaces will be ignored</p>": "<p>Если включено, игнорирует элементы с пустым текстом или текстом только из пробельных символов.</p>",
+ "<p>A TextHandler</p>": "<p>Объект TextHandler.</p>",
+ "<p>Join this Selector's url with a relative url to form an absolute full URL.</p>": "<p>Объединяет URL этого Selector с относительным URL, чтобы получить полный абсолютный URL.</p>",
+ "<p>Return a prettified version of the element's inner html-code</p>": "<p>Возвращает внутренний HTML-код элемента в читаемом формате.</p>",
+ "<p>Check if the element has a specific class</p>": "<p>Проверяет, есть ли у элемента указанный класс.</p>",
+ "<p>The class name to check for</p>": "<p>Имя класса для проверки.</p>",
+ "<p>True if element has class with that name otherwise False</p>": "<p>True, если у элемента есть класс с таким именем, иначе False.</p>",
+ "<p>Return a generator that loops over all ancestors of the element, starting with the element's parent.</p>": "<p>Возвращает генератор, который перебирает всех предков элемента, начиная с родителя.</p>",
+ "<p>Loop over all ancestors of the element till one match the passed function</p>": "<p>Перебирает предков элемента, пока один из них не подойдёт под условие переданной функции.</p>",
+ "<p>A function that takes each ancestor as an argument and returns True/False</p>": "<p>Функция, которая получает каждого предка как аргумент и возвращает True/False.</p>",
+ "<p>The first ancestor that match the function or <code>None</code> otherwise.</p>": "<p>Первый предок, подходящий под условие функции, или <code>None</code>, если его нет.</p>",
+ "<p>Serialize this element to a string.\nFor text nodes, returns the text value. For HTML elements, returns the outer HTML.</p>": "<p>Преобразует элемент в строку. Для текстовых узлов возвращает текстовое значение, для HTML-элементов возвращает внешний HTML.</p>",
+ "<p>Return a single-element list containing this element's serialized string.</p>": "<p>Возвращает список из одной строки с сериализованным элементом.</p>",
+ "<p>This function will search again for the element in the page tree, used automatically on page structure change</p>": "<p>Повторно ищет элемент в дереве страницы. Используется автоматически при изменении структуры страницы.</p>",
+ "<p>The element we want to relocate in the tree</p>": "<p>Элемент, который нужно снова найти в дереве.</p>",
+ "<p>The minimum percentage to accept and not going lower than that. Be aware that the percentage\ncalculation depends solely on the page structure, so don't play with this number unless you must know\nwhat you are doing!</p>": "<p>Минимальный допустимый процент совпадения. Расчёт зависит только от структуры страницы. Меняйте значение, только если понимаете его влияние.</p>",
+ "<p>If True, the return result will be converted to <code>Selectors</code> object</p>": "<p>При True преобразует результат в объект <code>Selectors</code>.</p>",
+ "<p>List of pure HTML elements that got the highest matching score or 'Selectors' object</p>": "<p>Список исходных HTML-элементов с наибольшим совпадением или объект 'Selectors'.</p>",
+ "<p>Search the current tree with CSS3 selectors</p>": "<p>Ищет в текущем дереве с помощью CSS3-селекторов.</p>",
+ "<p><strong>Important:\nIt's recommended to use the identifier argument if you plan to use a different selector later\nand want to relocate the same element(s)</strong></p>": "<p><strong>Важно: рекомендуется задать аргумент identifier, если позже вы собираетесь использовать другой селектор для поиска тех же элементов.</strong></p>",
+ "<p>The CSS3 selector to be used.</p>": "<p>CSS3-селектор для поиска.</p>",
+ "<p>Enabled will make the function try to relocate the element if it was 'saved' before</p>": "<p>Если включено, пытается снова найти элемент, который был сохранён ранее.</p>",
+ "<p>A string that will be used to save/retrieve element's data in adaptive,\notherwise the selector will be used.</p>": "<p>Строка для сохранения и получения данных элемента в адаптивном режиме. Если не задана, используется селектор.</p>",
+ "<p>Automatically save new elements for <code>adaptive</code> later</p>": "<p>Автоматически сохраняет новые элементы для дальнейшего использования с <code>adaptive</code>.</p>",
+ "<p>The minimum percentage to accept while <code>adaptive</code> is working and not going lower than that.\nBe aware that the percentage calculation depends solely on the page structure, so don't play with this\nnumber unless you must know what you are doing!</p>": "<p>Минимальный допустимый процент совпадения при работе <code>adaptive</code>. Расчёт зависит только от структуры страницы. Меняйте значение, только если понимаете его влияние.</p>",
+ "<p><code>Selectors</code> class.</p>": "<p>Класс <code>Selectors</code>.</p>",
+ "<p>Search the current tree with XPath selectors</p>": "<p>Ищет в текущем дереве с помощью XPath-селекторов.</p>",
+ "<p>Note: <strong>Additional keyword arguments will be passed as XPath variables in the XPath expression!</strong></p>": "<p>Примечание: <strong>дополнительные именованные аргументы передаются как переменные в XPath-выражение.</strong></p>",
+ "<p>The XPath selector to be used.</p>": "<p>XPath-селектор для поиска.</p>",
+ "<p>Find elements by filters of your creations for ease.</p>": "<p>Ищет элементы с помощью ваших фильтров.</p>",
+ "<p>Tag name(s), iterable of tag names, regex patterns, function, or a dictionary of elements' attributes. Leave empty for selecting all.</p>": "<p>Имена тегов, перебираемый объект с именами тегов, регулярные выражения, функция или словарь атрибутов элементов. Пустое значение выбирает все элементы.</p>",
+ "<p>The attributes you want to filter elements based on it.</p>": "<p>Атрибуты для фильтрации элементов.</p>",
+ "<p>The <code>Selectors</code> object of the elements or empty list</p>": "<p>Объект <code>Selectors</code> с элементами или пустой список.</p>",
+ "<p>Find elements by filters of your creations for ease, then return the first result. Otherwise return <code>None</code>.</p>": "<p>Ищет элементы с помощью ваших фильтров и возвращает первый результат. Если совпадений нет, возвращает <code>None</code>.</p>",
+ "<p>The <code>Selector</code> object of the element or <code>None</code> if the result didn't match</p>": "<p>Объект <code>Selector</code> с элементом или <code>None</code>, если совпадений нет.</p>",
+ "<p>Saves the element's unique properties to the storage for retrieval and relocation later</p>": "<p>Сохраняет уникальные свойства элемента в хранилище, чтобы позже получить их и найти элемент снова.</p>",
+ "<p>The element itself that we want to save to storage, it can be a <code>Selector</code> or pure <code>HtmlElement</code></p>": "<p>Элемент для сохранения. Может быть объектом <code>Selector</code> или исходным <code>HtmlElement</code>.</p>",
+ "<p>This is the identifier that will be used to retrieve the element later from the storage. See\nthe docs for more info.</p>": "<p>Идентификатор для последующего получения элемента из хранилища. Подробнее в документации.</p>",
+ "<p>Using the identifier, we search the storage and return the unique properties of the element</p>": "<p>Ищет в хранилище по идентификатору и возвращает уникальные свойства элемента.</p>",
+ "<p>This is the identifier that will be used to retrieve the element from the storage. See\nthe docs for more info.</p>": "<p>Идентификатор для получения элемента из хранилища. Подробнее в документации.</p>",
+ "<p>A dictionary of the unique properties</p>": "<p>Словарь уникальных свойств.</p>",
+ "<p>Return JSON response if the response is jsonable otherwise throws error</p>": "<p>Возвращает ответ в формате JSON, если его можно разобрать как JSON, иначе вызывает ошибку.</p>",
+ "<p>Apply the given regex to the current text and return a list of strings with the matches.</p>": "<p>Применяет регулярное выражение к текущему тексту и возвращает список строк с совпадениями.</p>",
+ "<p>Can be either a compiled regular expression or a string.</p>": "<p>Скомпилированное регулярное выражение или строка.</p>",
+ "<p>If enabled character entity references are replaced by their corresponding character</p>": "<p>Если включено, заменяет HTML-сущности соответствующими символами.</p>",
+ "<p>if enabled, this will ignore all whitespaces and consecutive spaces while matching</p>": "<p>Если включено, игнорирует пробельные символы и последовательности пробелов при сопоставлении.</p>",
+ "<p>if disabled, the function will set the regex to ignore the letters case while compiling it</p>": "<p>Если выключено, компилирует регулярное выражение без учёта регистра.</p>",
+ "<p>Apply the given regex to text and return the first match if found, otherwise return the default value.</p>": "<p>Применяет регулярное выражение к тексту и возвращает первое совпадение. Если совпадений нет, возвращает значение по умолчанию.</p>",
+ "<p>The default value to be returned if there is no match</p>": "<p>Значение по умолчанию, которое возвращается при отсутствии совпадений.</p>",
+ "<p>\n <span class=\"doc-param-default\">\n <b>DEFAULT:</b>\n <code>None</code>\n </span>\n </p>": "<p>\n <span class=\"doc-param-default\">\n <b>ПО УМОЛЧАНИЮ:</b>\n <code>None</code>\n </span>\n </p>",
+ "<p>if enabled character entity references are replaced by their corresponding character</p>": "<p>Если включено, заменяет HTML-сущности соответствующими символами.</p>",
+ "<p>Find elements that are in the same tree depth in the page with the same tag name and same parent tag etc...\nthen return the ones that match the current element attributes with a percentage higher than the input threshold.</p>": "<p>Ищет элементы на той же глубине дерева с тем же именем тега, тегом родителя и другими признаками. Возвращает те, у которых процент совпадения атрибутов с текущим элементом выше заданного порога.</p>",
+ "<p>This function is inspired by AutoScraper and made for cases where you, for example, found a product div inside\na products-list container and want to find other products using that element as a starting point EXCEPT\nthis function works in any case without depending on the element type.</p>": "<p>Функция создана по образцу AutoScraper. Например, если вы нашли div товара внутри списка товаров, его можно взять за основу для поиска остальных товаров. При этом функция не зависит от типа элемента и подходит для других задач.</p>",
+ "<p>The percentage to use while comparing element attributes.\nNote: Elements found before attributes matching/comparison will be sharing the same depth, same tag name,\nsame parent tag name, and same grand parent tag name. So they are 99% likely to be correct unless you are\nextremely unlucky, then attributes matching comes into play, so don't play with this number unless\nyou are getting the results you don't want.\nAlso, if the current element doesn't have attributes and the similar element as well, then it's a 100% match.</p>": "<p>Процент для сравнения атрибутов элементов. До сравнения уже выбраны элементы с одинаковой глубиной, именем тега, тегом родителя и тегом родителя этого родителя. Поэтому с вероятностью 99% это нужные элементы, за исключением крайне неудачных случаев. Затем сравниваются атрибуты. Меняйте число, только если получаете нежелательные результаты. Если у текущего и похожего элемента нет атрибутов, совпадение считается полным, то есть 100%.</p>",
+ "<p>Attribute names passed will be ignored while matching the attributes in the last step.\nThe default value is to ignore <code>href</code> and <code>src</code> as URLs can change a lot between elements, so it's unreliable</p>": "<p>Имена атрибутов, которые нужно игнорировать на последнем шаге сравнения. По умолчанию игнорируются <code>href</code> и <code>src</code>: URL сильно различаются между элементами и ненадёжны для сравнения.</p>",
+ "<p>If True, element text content will be taken into calculation while matching.\nNot recommended to use in normal cases, but it depends.</p>": "<p>При True текстовое содержимое элемента тоже учитывается при сопоставлении. Обычно это не рекомендуется, но зависит от задачи.</p>",
+ "<p>A <code>Selectors</code> container of <code>Selector</code> objects or empty list</p>": "<p>Контейнер <code>Selectors</code> с объектами <code>Selector</code> или пустой список.</p>",
+ "<p>Find elements that its text content fully/partially matches input.</p>": "<p>Ищет элементы, текст которых полностью или частично совпадает с заданным.</p>",
+ "<p>Text query to match</p>": "<p>Текст для поиска совпадений.</p>",
+ "<p>Returns the first element that matches conditions, enabled by default</p>": "<p>Возвращает первый элемент, который подходит под условия. Включено по умолчанию.</p>",
+ "<p>If enabled, the function returns elements that contain the input text</p>": "<p>Если включено, возвращает элементы, содержащие заданный текст.</p>",
+ "<p>if enabled, the letters case will be taken into consideration</p>": "<p>Если включено, учитывается регистр букв.</p>",
+ "<p>Find elements that its text content matches the input regex pattern.</p>": "<p>Находит элементы, текст которых соответствует заданному регулярному выражению.</p>",
+ "<p>Regex query/pattern to match</p>": "<p>Регулярное выражение для поиска совпадений.</p>",
+ "<p>Return the first element that matches conditions; enabled by default.</p>": "<p>Возвращает первый элемент, который удовлетворяет условиям. По умолчанию включено.</p>",
+ "<p>If enabled, the letters case will be taken into consideration in the regex.</p>": "<p>Если включено, регулярное выражение учитывает регистр букв.</p>",
+ "<p>If enabled, this will ignore all whitespaces and consecutive spaces while matching.</p>": "<p>Если включено, при поиске совпадений игнорируются пробельные символы и последовательности пробелов.</p>",
+ "<p>A basic <code>Fetcher</code> class type that can only do basic GET, POST, PUT, and DELETE HTTP requests based on <code>curl_cffi</code>.</p>": "<p>Базовый класс <code>Fetcher</code> для простых HTTP-запросов GET, POST, PUT и DELETE на основе <code>curl_cffi</code>.</p>",
+ "<p>Set multiple arguments for the parser at once globally</p>": "<p>Задаёт несколько общих настроек парсера сразу.</p>",
+ "<p>The keywords can be any arguments of the following: huge_tree, keep_comments, adaptive, storage, storage_args, adaptive_domain</p>": "<p>Доступны следующие именованные аргументы: huge_tree, keep_comments, adaptive, storage, storage_args, adaptive_domain.</p>",
+ "<p>\n <span class=\"doc-param-default\">\n <b>DEFAULT:</b>\n <code>{}</code>\n </span>\n </p>": "<p>\n <span class=\"doc-param-default\">\n <b>ПО УМОЛЧАНИЮ:</b>\n <code>{}</code>\n </span>\n </p>",
+ "<p>A <code>Fetcher</code> class type which is a completely stealthy built on top of Chromium.</p>": "<p>Класс <code>Fetcher</code> на основе Chromium с полным набором функций скрытной работы.</p>",
+ "<p>It works as real browsers passing almost all online tests/protections with many customization options.</p>": "<p>Работает как настоящий браузер, проходит почти все онлайн-тесты и системы защиты и предоставляет много настроек.</p>",
+ "<p>Opens up a browser and do your request based on your chosen options below.</p>": "<p>Открывает браузер и выполняет запрос с выбранными ниже настройками.</p>",
+ "<p>Target url.</p>": "<p>URL назначения.</p>",
+ "<p>Run the browser in headless/hidden (default), or headful/visible mode.</p>": "<p>Запускает браузер без видимого окна (по умолчанию) или с видимым окном.</p>",
+ "<p>Drop requests for unnecessary resources for a speed boost.\nRequests dropped are of type <code>font</code>, <code>image</code>, <code>media</code>, <code>beacon</code>, <code>object</code>, <code>imageset</code>, <code>texttrack</code>, <code>websocket</code>, <code>csp_report</code>, and <code>stylesheet</code>.</p>": "<p>Пропускает запросы ненужных ресурсов для ускорения работы. Пропускаются типы <code>font</code>, <code>image</code>, <code>media</code>, <code>beacon</code>, <code>object</code>, <code>imageset</code>, <code>texttrack</code>, <code>websocket</code>, <code>csp_report</code> и <code>stylesheet</code>.</p>",
+ "<p>A set of domain names to block requests to. Subdomains are also matched (e.g., <code>\"example.com\"</code> blocks <code>\"sub.example.com\"</code> too).</p>": "<p>Множество доменов, запросы к которым нужно блокировать. Поддомены тоже учитываются: <code>\"example.com\"</code> блокирует и <code>\"sub.example.com\"</code>.</p>",
+ "<p>Block requests to ~3,500 known ad/tracking domains. Can be combined with <code>blocked_domains</code>.</p>": "<p>Блокирует запросы примерно к 3 500 известным рекламным и отслеживающим доменам. Можно использовать вместе с <code>blocked_domains</code>.</p>",
+ "<p>Route DNS queries through Cloudflare's DNS-over-HTTPS to prevent DNS leaks when using proxies.</p>": "<p>Направляет DNS-запросы через Cloudflare DNS-over-HTTPS, чтобы избежать утечек DNS при использовании прокси.</p>",
+ "<p>Pass a useragent string to be used. Otherwise the fetcher will generate a real Useragent of the same browser and use it.</p>": "<p>Строка User-Agent. Если не указана, Fetcher создаёт и использует User-Agent настоящего браузера того же вида.</p>",
+ "<p>Set cookies for the next request.</p>": "<p>Задаёт cookie для следующего запроса.</p>",
+ "<p>Wait for the page until there are no network connections for at least 500 ms.</p>": "<p>Ждёт, пока на странице не будет сетевых соединений хотя бы 500 мс.</p>",
+ "<p>The timeout in milliseconds that is used in all operations and waits through the page. The default is 30,000</p>": "<p>Тайм-аут в миллисекундах для всех операций и ожиданий на странице. По умолчанию 30 000.</p>",
+ "<p>The time (milliseconds) the fetcher will wait after everything finishes before closing the page and returning the <code>Response</code> object.</p>": "<p>Время в миллисекундах, которое Fetcher ждёт после всех операций, прежде чем закрыть страницу и вернуть объект <code>Response</code>.</p>",
+ "<p>Added for automation. A function that takes the <code>page</code> object, runs after navigation, and does the automation you need.</p>": "<p>Функция автоматизации. Принимает объект <code>page</code> и выполняет нужные действия после перехода на страницу.</p>",
+ "<p>A function that takes the <code>page</code> object, runs before navigation. Use it to register event listeners or routes that must be set up before the page loads.</p>": "<p>Функция, которая принимает <code>page</code> и выполняется до перехода на страницу. Используйте её для регистрации обработчиков событий или маршрутов до загрузки страницы.</p>",
+ "<p>Wait for a specific CSS selector to be in a specific state.</p>": "<p>Ждёт, пока элемент по CSS-селектору достигнет указанного состояния.</p>",
+ "<p>An absolute path to a JavaScript file to be executed on page creation for all pages in this session.</p>": "<p>Абсолютный путь к JavaScript-файлу, который запускается при создании каждой страницы в этой сессии.</p>",
+ "<p>Specify user locale, for example, <code>en-GB</code>, <code>de-DE</code>, etc. Locale will affect navigator.language value, Accept-Language request header value as well as number and date formatting\nrules. Defaults to the system default locale.</p>": "<p>Локаль, например <code>en-GB</code> или <code>de-DE</code>. Влияет на navigator.language, заголовок запроса Accept-Language, а также формат чисел и дат. По умолчанию используется системная локаль.</p>",
+ "<p>Changes the timezone of the browser. Defaults to the system timezone.</p>": "<p>Меняет часовой пояс браузера. По умолчанию используется системный часовой пояс.</p>",
+ "<p>The state to wait for the selector given with <code>wait_selector</code>. The default state is <code>attached</code>.</p>": "<p>Состояние, которого нужно дождаться для селектора из <code>wait_selector</code>. По умолчанию <code>attached</code>.</p>",
+ "<p>Solves all types of the Cloudflare's Turnstile/Interstitial challenges before returning the response to you.</p>": "<p>Проходит все виды проверок Cloudflare Turnstile/Interstitial перед возвратом ответа.</p>",
+ "<p>If you have a Chrome browser installed on your device, enable this, and the Fetcher will launch an instance of your browser and use it.</p>": "<p>Если на устройстве установлен Chrome, включите эту настройку, и Fetcher запустит ваш браузер.</p>",
+ "<p>Add random noise to canvas operations to prevent fingerprinting.</p>": "<p>Добавляет случайный шум к операциям Canvas, чтобы помешать получению отпечатка.</p>",
+ "<p>Forces WebRTC to respect proxy settings to prevent local IP address leak.</p>": "<p>Заставляет WebRTC учитывать настройки прокси, чтобы избежать утечки локального IP-адреса.</p>",
+ "<p>Enabled by default. Disabling it disables WebGL and WebGL 2.0 support entirely. Disabling WebGL is not recommended as many WAFs now check if WebGL is enabled.</p>": "<p>По умолчанию включено. Отключение полностью убирает поддержку WebGL и WebGL 2.0. Отключать не рекомендуется, так как многие WAF проверяют наличие WebGL.</p>",
+ "<p>Enabled by default, wait for all JavaScript on page(s) to fully load and execute.</p>": "<p>По умолчанию включено. Ждёт полной загрузки и выполнения JavaScript на страницах.</p>",
+ "<p>Include open Shadow DOM content in the response HTML. Defaults to False.</p>": "<p>Включает содержимое открытых Shadow DOM в HTML ответа. По умолчанию False.</p>",
+ "<p>Instead of launching a new browser instance, connect to this CDP URL to control real browsers through CDP.</p>": "<p>Подключается к браузеру по этому CDP URL вместо запуска нового экземпляра.</p>",
+ "<p>Enabled by default, Scrapling will set a Google referer header.</p>": "<p>По умолчанию включено. Scrapling указывает Google в заголовке Referer.</p>",
+ "<p>A dictionary of extra headers to add to the request. <em>The referer set by <code>google_search</code> takes priority over the referer set here if used together.</em></p>": "<p>Словарь дополнительных заголовков запроса. <em>При совместном использовании Referer от <code>google_search</code> имеет приоритет над Referer из этого словаря.</em></p>",
+ "<p>The proxy to be used with requests, it can be a string or a dictionary with the keys 'server', 'username', and 'password' only.</p>": "<p>Прокси для запросов. Строка или словарь только с ключами 'server', 'username' и 'password'.</p>",
+ "<p>Path to a User Data Directory, which stores browser session data like cookies and local storage. The default is to create a temporary directory.</p>": "<p>Путь к каталогу пользовательских данных браузера, например cookie и local storage. По умолчанию создаётся временный каталог.</p>",
+ "<p>A list of additional browser flags to pass to the browser on launch.</p>": "<p>Список дополнительных флагов, передаваемых браузеру при запуске.</p>",
+ "<p>The arguments that will be passed in the end while creating the final Selector's class.</p>": "<p>Аргументы, передаваемые при создании итогового объекта Selector.</p>",
+ "<p>Additional arguments to be passed to Playwright's context as additional settings, and it takes higher priority than Scrapling's settings.</p>": "<p>Дополнительные настройки контекста Playwright. Имеют приоритет над настройками Scrapling.</p>",
+ "<p>A <code>Response</code> object.</p>": "<p>Объект <code>Response</code>.</p>",
+ "<p>A factory context manager that provides configured Fetcher sessions.</p>": "<p>Контекстный менеджер, который создаёт сессии Fetcher с заданными настройками.</p>",
+ "<p>When this manager is used in a 'with' or 'async with' block,\nit yields a new session configured with the manager's defaults.\nA single instance of this manager should ideally be used for one active\nsession at a time (or sequentially). Re-entering a context with the\nsame manager instance while a session is already active is disallowed.</p>": "<p>При использовании в блоке 'with' или 'async with' этот менеджер создаёт новую сессию со своими настройками по умолчанию. Один экземпляр менеджера лучше использовать для одной активной сессии за раз или для нескольких сессий по очереди. Повторно входить в контекст того же менеджера, пока сессия активна, нельзя.</p>",
+ "<p>Browser version to impersonate. Can be a single browser string or a list of browser strings for random selection. (Default: latest available Chrome version)</p>": "<p>Версия браузера для имитации. Можно передать одну строку с браузером или список строк для случайного выбора. По умолчанию используется последняя доступная версия Chrome.</p>",
+ "<p>Whether to use HTTP3. Defaults to False. It might be problematic if used it with <code>impersonate</code>.</p>": "<p>Использовать ли HTTP3. По умолчанию False. При совместном использовании с <code>impersonate</code> возможны проблемы.</p>",
+ "<p>If enabled (default), it creates and adds real browser headers. It also sets a Google referer header.</p>": "<p>При включении (по умолчанию) создаёт и добавляет заголовки настоящего браузера, а также указывает Google в заголовке Referer.</p>",
+ "<p>Dict of proxies to use. Format: {\"http\": proxy_url, \"https\": proxy_url}.</p>": "<p>Словарь прокси в формате {\"http\": proxy_url, \"https\": proxy_url}.</p>",
+ "<p>Proxy URL to use. Format: \"http://username:password@localhost:8030\".\nCannot be used together with the <code>proxies</code> parameter.</p>": "<p>URL прокси в формате \"http://username:password@localhost:8030\". Нельзя использовать вместе с аргументом <code>proxies</code>.</p>",
+ "<p>HTTP basic auth for proxy, tuple of (username, password).</p>": "<p>HTTP Basic-аутентификация для прокси, кортеж (username, password).</p>",
+ "<p>Number of seconds to wait before timing out.</p>": "<p>Время ожидания до тайм-аута в секундах.</p>",
+ "<p>Headers to include in the session with every request.</p>": "<p>Заголовки, включаемые в каждый запрос сессии.</p>",
+ "<p>Number of retry attempts. Defaults to 3.</p>": "<p>Число повторных попыток. По умолчанию 3.</p>",
+ "<p>Number of seconds to wait between retry attempts. Defaults to 1 second.</p>": "<p>Пауза между повторными попытками в секундах. По умолчанию 1 секунда.</p>",
+ "<p>Whether to follow redirects. Defaults to \"safe\", which follows redirects but rejects those targeting internal/private IPs (SSRF protection). Pass True to follow all redirects without restriction.</p>": "<p>Следовать ли перенаправлениям. По умолчанию \"safe\": перенаправления разрешены, но переходы на внутренние и частные IP-адреса отклоняются для защиты от SSRF. Передайте True, чтобы разрешить все перенаправления без ограничений.</p>",
+ "<p>Maximum number of redirects. Default 30, use -1 for unlimited.</p>": "<p>Максимальное число перенаправлений. По умолчанию 30. Значение -1 убирает ограничение.</p>",
+ "<p>Whether to verify HTTPS certificates. Defaults to True.</p>": "<p>Проверять ли сертификаты HTTPS. По умолчанию True.</p>",
+ "<p>Tuple of (cert, key) filenames for the client certificate.</p>": "<p>Кортеж имён файлов (cert, key) для клиентского сертификата.</p>",
+ "<p>Arguments passed when creating the final Selector class.</p>": "<p>Аргументы, передаваемые при создании итогового объекта Selector.</p>",
+ "<p>A ProxyRotator instance for automatic proxy rotation.</p>": "<p>Экземпляр ProxyRotator для автоматической смены прокси.</p>",
+ "<p>Creates and returns a new synchronous Fetcher Session</p>": "<p>Создаёт и возвращает новую синхронную сессию Fetcher.</p>",
+ "<p>Creates and returns a new asynchronous Session.</p>": "<p>Создаёт и возвращает новую асинхронную сессию.</p>",
+ "<p>A Stealthy Browser session manager with page pooling.</p>": "<p>Менеджер сессий скрытного браузера с пулом вкладок.</p>",
+ "<p>A Browser session manager with page pooling, it's using a persistent browser Context by default with a temporary user profile directory.</p>": "<p>Менеджер сессий браузера с пулом вкладок. По умолчанию использует постоянный контекст браузера с временным каталогом профиля пользователя.</p>",
+ "<p>Save completed browser requests and responses. Failed or unfinished requests are omitted. Defaults to False.</p>": "<p>Сохраняет завершённые запросы и ответы браузера. Неудачные и незавершённые запросы пропускаются. По умолчанию False.</p>",
+ "<p>Maximum retained requests per session. Defaults to 1000; older entries are removed.</p>": "<p>Максимальное число сохранённых запросов в сессии. По умолчанию 1 000. Старые записи удаляются.</p>",
+ "<p>Save cookies, local storage and IndexedDB to a Playwright-compatible JSON file.</p>": "<p>Сохраняет cookie, local storage и IndexedDB в JSON-файл, совместимый с Playwright.</p>",
+ "<p>Requires a started session without proxy rotation. Does not save sessionStorage.</p>": "<p>Нужна запущенная сессия без смены прокси. sessionStorage не сохраняется.</p>",
+ "<p>Replace cookies, local storage and IndexedDB from a Playwright-compatible JSON file.</p>": "<p>Заменяет cookie, local storage и IndexedDB данными из JSON-файла, совместимого с Playwright.</p>",
+ "<p>Requires a started session without proxy rotation. Fetch or reload pages to use the restored login.</p>": "<p>Нужна запущенная сессия без смены прокси. Чтобы использовать восстановленный вход, получите или перезагрузите страницы.</p>",
+ "<p>Close every open tab in the session's pool. The next request opens a fresh tab.</p>": "<p>Закрывает все открытые вкладки в пуле сессии. Следующий запрос откроет новую вкладку.</p>",
+ "<p>Close all resources</p>": "<p>Закрывает все ресурсы.</p>",
+ "<p>Get statistics about the current page pool</p>": "<p>Возвращает статистику текущего пула вкладок.</p>",
+ "<p>Create a browser for this instance and context.</p>": "<p>Создаёт браузер для этого экземпляра и контекста.</p>",
+ "<p>Opens up the browser and do your request based on your chosen options.</p>": "<p>Открывает браузер и выполняет запрос с выбранными настройками.</p>",
+ "<p>The Target url.</p>": "<p>URL назначения.</p>",
+ "<p>Static proxy to override rotator and session proxy. A new browser context will be created and used with it.</p>": "<p>Фиксированный прокси, который переопределяет механизм смены и прокси сессии. Для него создаётся отдельный контекст браузера.</p>",
+ "<p>An async Stealthy Browser session manager with page pooling.</p>": "<p>Менеджер асинхронных сессий скрытного браузера с пулом вкладок.</p>",
+ "<p>A thread-safe proxy rotator with pluggable rotation strategies.</p>": "<p>Потокобезопасный механизм смены прокси с возможностью задать свой способ выбора.</p>",
+ "<p>Supports:\n- Cyclic rotation (default)\n- Custom rotation strategies via callable\n- Both string URLs and Playwright-style dict proxies</p>": "<p>Поддерживает:\n- Циклическую смену прокси (по умолчанию)\n- Свои способы выбора через вызываемый объект\n- Прокси в виде URL-строк и словарей в формате Playwright</p>",
+ "<p>Initialize the proxy rotator.</p>": "<p>Инициализирует механизм смены прокси.</p>",
+ "<p>List of proxy URLs or Playwright-style proxy dicts.\n- String format: \"http://proxy1:8080\" or \"http://user:pass@proxy:8080\"\n- Dict format: {\"server\": \"http://proxy:8080\", \"username\": \"user\", \"password\": \"pass\"}</p>": "<p>Список URL прокси или словарей в формате Playwright.\n- Формат строки: \"http://proxy1:8080\" или \"http://user:pass@proxy:8080\"\n- Формат словаря: {\"server\": \"http://proxy:8080\", \"username\": \"user\", \"password\": \"pass\"}</p>",
+ "<p>Rotation strategy function. Takes (proxies, current_index) and returns (proxy, next_index). Defaults to cyclic_rotation.</p>": "<p>Функция выбора прокси. Принимает (proxies, current_index) и возвращает (proxy, next_index). По умолчанию cyclic_rotation.</p>",
+ "<p>Get a copy of all configured proxies.</p>": "<p>Возвращает копию всех настроенных прокси.</p>",
+ "<p>Get the next proxy according to the rotation strategy.</p>": "<p>Возвращает следующий прокси согласно выбранному способу смены.</p>",
+ "<p>Return the total number of configured proxies.</p>": "<p>Возвращает общее число настроенных прокси.</p>",
+ "<p>Extends standard Python string by adding more functionality</p>": "<p>Расширяет стандартную строку Python дополнительными возможностями.</p>",
+ "<p>Return a sorted version of the string</p>": "<p>Возвращает строку с отсортированными символами.</p>",
+ "<p>Return a new version of the string after removing all white spaces and consecutive spaces</p>": "<p>Возвращает новую строку без пробельных символов и последовательностей пробелов.</p>",
+ "<p>Return JSON response if the response is jsonable otherwise throw error</p>": "<p>Преобразует ответ в JSON и возвращает результат. Если преобразование невозможно, вызывает ошибку.</p>",
+ "<p>If enabled, this will ignore all whitespaces and consecutive spaces while matching</p>": "<p>Если включено, при поиске совпадений игнорируются пробельные символы и последовательности пробелов.</p>",
+ "<p>If disabled, function will set the regex to ignore the letters-case while compiling it</p>": "<p>Если выключено, регулярное выражение компилируется без учёта регистра букв.</p>",
+ "<p>Used to quickly check if this regex matches or not without any operations on the results</p>": "<p>Быстро проверяет, есть ли совпадение с регулярным выражением, без обработки результатов.</p>",
+ "<p>The :class:<code>TextHandlers</code> class is a subclass of the builtin <code>List</code> class, which provides a few additional methods.</p>": "<p>Класс :class:<code>TextHandlers</code> наследует встроенный <code>List</code> и добавляет несколько методов.</p>",
+ "<p>Call the <code>.re()</code> method for each element in this list and return\ntheir results flattened as TextHandlers.</p>": "<p>Вызывает <code>.re()</code> для каждого элемента списка, объединяет результаты в один список и возвращает его как TextHandlers.</p>",
+ "<p>if disabled, the function will set the regex to ignore the letters-case while compiling it</p>": "<p>Если выключено, регулярное выражение компилируется без учёта регистра букв.</p>",
+ "<p>Call the <code>.re_first()</code> method for each element in this list and return\nthe first result or the default value otherwise.</p>": "<p>Вызывает <code>.re_first()</code> для каждого элемента списка и возвращает первый результат либо значение по умолчанию.</p>",
+ "<p>Returns the first item of the current list</p>": "<p>Возвращает первый элемент текущего списка.</p>",
+ "<p>the default value to return if the current list is empty</p>": "<p>Значение, которое возвращается, если текущий список пуст.</p>",
+ "<p>A read-only mapping to use instead of the standard dictionary for the speed boost, but at the same time I use it to add more functionalities.\nIf the standard dictionary is needed, convert this class to a dictionary with the <code>dict</code> function</p>": "<p>Отображение только для чтения, которое заменяет обычный словарь для ускорения работы и добавляет новые возможности. Если нужен стандартный словарь, преобразуйте объект функцией <code>dict</code>.</p>",
+ "<p>Convert current attributes to JSON bytes if the attributes are JSON serializable otherwise throws error</p>": "<p>Преобразует текущие атрибуты в байты JSON. Если атрибуты нельзя преобразовать, вызывает ошибку.</p>",
+ "<p>Acts like the standard dictionary <code>.get()</code> method</p>": "<p>Работает как метод <code>.get()</code> стандартного словаря.</p>",
+ "<p>Search current attributes by values and return a dictionary of each matching item</p>": "<p>Ищет среди значений текущих атрибутов и возвращает словарь для каждого совпадения.</p>",
+ "<p>The keyword to search for in the attribute values</p>": "<p>Ключевое слово для поиска в значениях атрибутов.</p>",
+ "<p>If True, the function will search if keyword in each value instead of perfect match</p>": "<p>При True проверяет, содержится ли ключевое слово в каждом значении, вместо точного совпадения.</p>",
+ "<p>Request's response information structure.</p>": "<p>Структура со сведениями об ответе на запрос.</p>",
+ "<p><code>browser_network_requests</code> returns <code>NetworkRequestsModel</code> with <code>requests</code>, <code>next_cursor</code>, <code>has_more</code>, and <code>dropped_count</code>. Each <code>NetworkRequestInfo</code> contains <code>id</code>, <code>url</code>, <code>method</code>, <code>resource_type</code>, and <code>status</code>. Pass <code>next_cursor</code> as <code>after_id</code> to continue; <code>has_more</code> indicates more current matches.</p>": "<p><code>browser_network_requests</code> возвращает <code>NetworkRequestsModel</code> с полями <code>requests</code>, <code>next_cursor</code>, <code>has_more</code> и <code>dropped_count</code>. Каждый <code>NetworkRequestInfo</code> содержит <code>id</code>, <code>url</code>, <code>method</code>, <code>resource_type</code> и <code>status</code>. Чтобы получить продолжение, передайте <code>next_cursor</code> как <code>after_id</code>. Поле <code>has_more</code> показывает, есть ли ещё совпадения в текущей истории.</p>",
+ "<p><code>browser_network_request</code> returns <code>NetworkRequestModel</code> with <code>request_id</code>, <code>part</code>, <code>data</code>, and <code>note</code>. Summaries and headers are objects; the full saved body text is returned as a string, including JSON response text. <code>note</code> explains missing body data or partial headers.</p>": "<p><code>browser_network_request</code> возвращает <code>NetworkRequestModel</code> с полями <code>request_id</code>, <code>part</code>, <code>data</code> и <code>note</code>. Сводки и заголовки возвращаются как объекты. Полный сохранённый текст тела возвращается строкой, даже для JSON-ответов. Поле <code>note</code> объясняет отсутствие тела или неполные заголовки.</p>",
+ "<p>Summary of a recorded browser request.</p>": "<p>Сводка записанного запроса браузера.</p>",
+ "<p>Recorded request summaries and pagination details.</p>": "<p>Сводки записанных запросов и сведения о постраничной выдаче.</p>",
+ "<p>One complete saved request part, with an optional note.</p>": "<p>Одна полная сохранённая часть запроса с необязательным примечанием.</p>",
+ "<p>Model classes for session management:</p>": "<p>Классы моделей для управления сессиями:</p>",
+ "<p>Information about an open browser session.</p>": "<p>Сведения об открытой сессии браузера.</p>",
+ "<p>Response returned when a new session is created.</p>": "<p>Ответ при создании новой сессии.</p>",
+ "<p>Response returned when a session is closed.</p>": "<p>Ответ при закрытии сессии.</p>",
+ "<p>The main MCP server class that provides all web scraping tools:</p>": "<p>Основной класс MCP-сервера, который предоставляет все инструменты сбора данных с сайтов:</p>",
+ "<p><strong><code>browser_fetch_once</code></strong>: Fetch one URL through a stealthy browser with JavaScript rendering and Cloudflare handling, then close the browser. Use a persistent session for later actions or network history.</p>": "<p><strong><code>browser_fetch_once</code></strong>: загружает один URL через скрытный браузер с выполнением JavaScript и обработкой проверок Cloudflare, затем закрывает браузер. Для последующих действий или сетевой истории используйте постоянную сессию.</p>",
+ "<p><strong><code>browser_extract</code></strong>: Read the current page or one element as an AI snapshot, HTML, Markdown, or text without reloading it. Keep results from forms and page actions. Snapshots include element roles, names, references, positions, and sizes; regex search returns matching lines with nearby context and parent nodes.</p>": "<p><strong><code>browser_extract</code></strong>: читает текущую страницу или один элемент как снимок для ИИ, HTML, Markdown или текст без перезагрузки. Сохраняет результаты заполнения форм и действий на странице. Снимки содержат роли, имена, ссылки, координаты и размеры элементов. Поиск по регулярному выражению возвращает совпавшие строки с соседним контекстом и родительскими узлами.</p>",
+ "<p><strong><code>browser_actions</code></strong>: Chain mouse moves, hovers, clicks, scrolling, field filling, keyboard shortcuts, dialog replies, and waits in one call. Accept or dismiss alerts and confirmations, or enter text in prompts. Fill a search box, submit it, wait for results, and open a result without a separate call for each step.</p>": "<p><strong><code>browser_actions</code></strong>: объединяет в одном вызове перемещение мыши, наведение, клики, прокрутку, заполнение полей, сочетания клавиш, ответы на диалоги и ожидания. Можно принять или отклонить уведомления и подтверждения, а также ввести текст в диалог запроса. Заполните строку поиска, отправьте запрос, дождитесь результатов и откройте один из них без отдельного вызова для каждого шага.</p>",
+ "<p>Moves and clicks target selectors, snapshot references, or coordinates; element targets wait and scroll into view. Supports movement in multiple steps, left, right, and middle clicks, double-clicks, and scrolling nested panels.</p>": "<p>Перемещения и клики используют селекторы, ссылки из снимка или координаты. При выборе элемента инструмент ждёт его и прокручивает в видимую область. Поддерживаются перемещение в несколько шагов, клики левой, правой и средней кнопкой, двойные клики и прокрутка вложенных панелей.</p>",
+ "<p>Target fields anywhere on the page through selectors or snapshot references. Fill text, check or uncheck boxes, select radio buttons, and choose one or more native dropdown options by label. Replace or clear text, or type at the current caret. Keyboard shortcuts use the current focus. Slow mode adds random pauses between typed characters and all actions.</p>": "<p>Выбирайте поля в любой части страницы с помощью селекторов или ссылок из снимка. Можно заполнять текст, устанавливать и снимать флажки, выбирать радиокнопки и один или несколько вариантов обычного выпадающего списка по подписи. Текст можно заменить, очистить или дописать в позиции курсора. Сочетания клавиш работают с текущим фокусом. Медленный режим добавляет случайные паузы между вводимыми символами и всеми действиями.</p>",
+ "<p>Wait for content or loading overlays through selectors or snapshot references, wait for page load events or settled network activity, or add a fixed pause before continuing.</p>": "<p>Ожидает нужного состояния содержимого или индикаторов загрузки по селекторам или ссылкам из снимка, событий загрузки страницы, завершения сетевой активности или заданной паузы перед продолжением.</p>",
+ "<p><strong><code>browser_evaluate</code></strong>: Run JavaScript on the current page to extract custom data, calculate results, read application state, or update page content. Supports asynchronous scripts and returns their results as JSON.</p>": "<p><strong><code>browser_evaluate</code></strong>: выполняет JavaScript на текущей странице для извлечения данных по своим правилам, вычислений, чтения состояния приложения или изменения содержимого страницы. Поддерживает асинхронные скрипты и возвращает их результаты в JSON.</p>",
+ "<p>Create a Scrapling MCP server.</p>": "<p>Создаёт MCP-сервер Scrapling.</p>",
+ "<p>Optional global Chromium-compatible browser executable path for browser tools.\nIf omitted, the SCRAPLING_EXECUTABLE_PATH environment variable is used when set.</p>": "<p>Необязательный путь к исполняемому файлу Chromium-совместимого браузера для всех браузерных инструментов. Если не задан, используется переменная окружения SCRAPLING_EXECUTABLE_PATH, если она установлена.</p>",
+ "<p>Optional shared token that clients must send as <code>Authorization: Bearer &lt;token&gt;</code>.\nIf omitted, the SCRAPLING_MCP_AUTH_TOKEN environment variable is used when set. It only applies\nto the streamable-http transport.</p>": "<p>Необязательный общий токен, который клиенты должны отправлять через <code>Authorization: Bearer &lt;token&gt;</code>. Если не задан, используется переменная окружения SCRAPLING_MCP_AUTH_TOKEN, если она установлена. Применяется только к транспорту streamable-http.</p>",
+ "<p>Open a reusable stealthy browser session. Pass per-request options to <code>browser_fetch</code>.</p>": "<p>Открывает сессию скрытного браузера для повторного использования. Параметры отдельных запросов передавайте в <code>browser_fetch</code>.</p>",
+ "<p>Save browser cookies, local storage and IndexedDB as Playwright-compatible JSON. Excludes sessionStorage.</p>": "<p>Сохраняет Cookie браузера, local storage и IndexedDB в JSON, совместимый с Playwright. Не включает sessionStorage.</p>",
+ "<p>Replace browser cookies, local storage and IndexedDB from a Playwright-compatible JSON file.</p>": "<p>Заменяет Cookie браузера, local storage и IndexedDB данными из JSON-файла, совместимого с Playwright.</p>",
+ "<p>Leaves sessionStorage and open tabs unchanged. Fetch or reload pages to use the restored login.</p>": "<p>Не меняет sessionStorage и открытые вкладки. Загрузите или обновите страницы, чтобы использовать восстановленный вход.</p>",
+ "<p>Open a reusable HTTP session for <code>session_make_request</code>, keeping cookies, connections, and request settings.</p>": "<p>Открывает HTTP-сессию для повторных вызовов <code>session_make_request</code>, сохраняя Cookie, соединения и настройки запросов.</p>",
+ "<p>Close a session and free its resources.</p>": "<p>Закрывает сессию и освобождает её ресурсы.</p>",
+ "<p>List registered sessions, their status, and effective settings.</p>": "<p>Показывает зарегистрированные сессии, их состояние и действующие настройки.</p>",
+ "<p>List completed requests across page changes, with IDs and pagination. Recording starts when the browser session opens.</p>": "<p>Показывает завершённые запросы, сохранённые при переходах между страницами, с ID и постраничным выводом. Запись начинается при открытии сессии браузера.</p>",
+ "<p>Read a complete saved request part without resending it, with structured data and availability notes.</p>": "<p>Полностью читает выбранную часть сохранённого запроса без повторной отправки, возвращая структурированные данные и сведения об их доступности.</p>",
+ "<p>Read the current page or one element as snapshot, HTML, Markdown, or text without navigating.\nReturn plain text; snapshot search keeps refs, ancestor paths and three lines of nearby context.</p>": "<p>Читает текущую страницу или один элемент как снимок, HTML, Markdown или текст без перехода на другую страницу. Возвращает обычный текст. Поиск по снимку сохраняет ссылки, пути предков и три строки соседнего контекста.</p>",
+ "<p>Run mouse, field, key, dialog, and wait actions in order; return plain text without a snapshot.\nStop on the first error, identifying its action; partial effects remain. No retries.\nElement mouse targets auto-wait and scroll into view; coordinates and wheel do not wait for navigation or scrolling.\nCancelled/timed-out clicks attempt button release. Load waits observe the current document, not future navigation.</p>": "<p>По порядку выполняет действия мышью, с полями, клавишами, диалогами и ожиданиями. Возвращает обычный текст без снимка. Останавливается при первой ошибке и указывает действие, которое её вызвало. Уже выполненные действия сохраняют результат. Повторных попыток нет. Для действий мышью над элементами автоматически ждёт их появления и прокручивает в видимую область. Действия по координатам и колёсиком не ждут перехода или прокрутки. При отмене клика или тайм-ауте пытается отпустить кнопку. Ожидание загрузки относится к текущему документу, а не к будущему переходу.</p>",
+ "<p>Run JavaScript on the current page, await promises, and return JSON text without a snapshot.\nReturn JSON-compatible values; null/undefined become null. Script effects are not undone on failure.\nCancellation stops waiting, but may not stop the script.</p>": "<p>Выполняет JavaScript на текущей странице, ждёт завершения Promise и возвращает текст JSON без снимка. Скрипт должен вернуть значение, совместимое с JSON; null/undefined становятся null. При ошибке изменения скрипта не отменяются. Отмена прекращает ожидание, но может не остановить скрипт.</p>",
+ "<p>Capture the current page or one element without navigating; return the image and current URL.\nElement capture waits and scrolls into view. Use browser_actions for other waits before capture.</p>": "<p>Снимает текущую страницу или один элемент без перехода, возвращает изображение и текущий URL. При съёмке элемента ждёт его и прокручивает в видимую область. Для других ожиданий перед снимком используйте browser_actions.</p>",
+ "<p>Make an HTTP request without JavaScript. Suitable for low-to-mid protection.</p>": "<p>Выполняет HTTP-запрос без JavaScript. Подходит для сайтов с низким или средним уровнем защиты.</p>",
+ "<p>Fetch a page with a stealth browser and JavaScript rendering.</p>": "<p>Загружает страницу через скрытный браузер с выполнением JavaScript.</p>",
+ "<p>Fetch a URL in an open stealthy browser session. Options apply only to this request.</p>": "<p>Загружает URL в открытой сессии скрытного браузера. Параметры применяются только к этому запросу.</p>",
+ "<p>Make an HTTP request using the session's cookies, connections, impersonation, and proxy. Options apply to this request.</p>": "<p>Выполняет HTTP-запрос с Cookie, соединениями, настройками имитации браузера и прокси сессии. Параметры применяются к этому запросу.</p>",
+ "<p>Serve the MCP server.</p>": "<p>Запускает MCP-сервер.</p>",
+ "<p>Serve over the streamable-http transport instead of stdio.</p>": "<p>Использует транспорт streamable-http вместо stdio.</p>",
+ "<p>The host to bind to when <code>http</code> is enabled.</p>": "<p>Адрес для привязки при включённом <code>http</code>.</p>",
+ "<p>The port to bind to when <code>http</code> is enabled.</p>": "<p>Порт для привязки при включённом <code>http</code>.</p>",
+ "<p>Host names to accept, which turns on DNS-rebinding protection.</p>": "<p>Разрешённые имена хостов. Их указание включает защиту от DNS rebinding.</p>",
+ "<p>Start the streamable-http transport without a token. The transport\nrequires authentication by default, so this is the explicit opt-out.</p>": "<p>Запускает streamable-http без токена. По умолчанию этот транспорт требует аутентификации, поэтому параметр явно отключает её.</p>",
+ "<p>The <code>Selectors</code> class is a subclass of the builtin <code>List</code> class, which provides a few additional methods.</p>": "<p>Класс <code>Selectors</code> наследует встроенный класс <code>List</code> и добавляет несколько методов.</p>",
+ "<p>Returns the first Selector item of the current list or <code>None</code> if the list is empty</p>": "<p>Возвращает первый элемент Selector текущего списка или <code>None</code>, если список пуст.</p>",
+ "<p>Returns the last Selector item of the current list or <code>None</code> if the list is empty</p>": "<p>Возвращает последний элемент Selector текущего списка или <code>None</code>, если список пуст.</p>",
+ "<p>Returns the length of the current list</p>": "<p>Возвращает длину текущего списка.</p>",
+ "<p>Call the <code>.xpath()</code> method for each element in this list and return\ntheir results as another <code>Selectors</code> class.</p>": "<p>Вызывает метод <code>.xpath()</code> для каждого элемента списка и возвращает результаты в другом объекте <code>Selectors</code>.</p>",
+ "<p>A string that will be used to retrieve element's data in adaptive,\notherwise the selector will be used.</p>": "<p>Строка для получения данных элемента в адаптивном режиме. Если не задана, используется селектор.</p>",
+ "<p>Call the <code>.css()</code> method for each element in this list and return\ntheir results flattened as another <code>Selectors</code> class.</p>": "<p>Вызывает метод <code>.css()</code> для каждого элемента списка и объединяет результаты в один объект <code>Selectors</code>.</p>",
+ "<p>Call the <code>.re()</code> method for each element in this list and return\ntheir results flattened as List of TextHandler.</p>": "<p>Вызывает метод <code>.re()</code> для каждого элемента списка и объединяет результаты в List из объектов TextHandler.</p>",
+ "<p>if disabled, function will set the regex to ignore the letters case while compiling it</p>": "<p>Если отключено, функция при компиляции регулярного выражения включает поиск без учёта регистра букв.</p>",
+ "<p>Loop over all current elements and return the first element that matches the passed function</p>": "<p>Перебирает текущие элементы и возвращает первый, который соответствует условию переданной функции.</p>",
+ "<p>A function that takes each element as an argument and returns True/False</p>": "<p>Функция, которая принимает каждый элемент как аргумент и возвращает True/False.</p>",
+ "<p>The first element that match the function or <code>None</code> otherwise.</p>": "<p>Первый элемент, соответствующий условию функции, или <code>None</code>, если такого нет.</p>",
+ "<p>Filter current elements based on the passed function</p>": "<p>Фильтрует текущие элементы с помощью переданной функции.</p>",
+ "<p>The new <code>Selectors</code> object or empty list otherwise.</p>": "<p>Новый объект <code>Selectors</code> или пустой список, если совпадений нет.</p>",
+ "<p>Returns the serialized string of the first element, or <code>default</code> if empty.</p>": "<p>Возвращает сериализованную строку первого элемента или <code>default</code>, если список пуст.</p>",
+ "<p>Serialize all elements and return as a TextHandlers list.</p>": "<p>Сериализует все элементы и возвращает их в списке TextHandlers.</p>",
+ "<p>An abstract base class for creating web spiders.</p>": "<p>Абстрактный базовый класс для создания веб-краулеров Spider.</p>",
+ "<p>Check the documentation website for more information.</p>": "<p>Подробнее см. на сайте документации.</p>",
+ "<p>Initialize the spider.</p>": "<p>Инициализирует Spider.</p>",
+ "<p>Directory for checkpoint files. If provided, enables pause/resume.</p>": "<p>Каталог файлов контрольных точек. Если задан, доступны пауза и возобновление.</p>",
+ "<p>Seconds between periodic checkpoint saves (default 5 minutes).</p>": "<p>Интервал сохранения контрольных точек в секундах. По умолчанию 5 минут.</p>",
+ "<p>Access current crawl stats (works during streaming).</p>": "<p>Доступ к текущей статистике обхода, в том числе при потоковой выдаче.</p>",
+ "<p>Generate initial requests to start the crawl.</p>": "<p>Создаёт начальные запросы для запуска обхода.</p>",
+ "<p>By default, this generates Request objects for each URL in <code>start_urls</code>\nusing the session manager's default session and <code>parse()</code> as callback.</p>": "<p>По умолчанию создаёт объекты Request для каждого URL из <code>start_urls</code>, используя стандартную сессию менеджера и <code>parse()</code> в качестве обработчика.</p>",
+ "<p>Override this method for more control over initial requests\n(e.g., to add custom headers, use different callbacks, etc.)</p>": "<p>Переопределите этот метод, чтобы настроить начальные запросы: добавить свои заголовки, использовать другие обработчики и так далее.</p>",
+ "<p>Default callback for processing responses</p>": "<p>Обработчик ответов по умолчанию.</p>",
+ "<p>Called before crawling starts. Override for setup logic.</p>": "<p>Вызывается перед началом обхода. Переопределите для подготовки к работе.</p>",
+ "<p>It's enabled if the spider is resuming from a checkpoint, left for the user to use.</p>": "<p>Включено, если Spider продолжает работу с контрольной точки. Можно использовать в своём коде.</p>",
+ "<p>Called after crawling finishes. Override for cleanup logic.</p>": "<p>Вызывается после завершения обхода. Переопределите для освобождения ресурсов.</p>",
+ "<p>Handle request errors for all spider requests.</p>": "<p>Обрабатывает ошибки всех запросов Spider.</p>",
+ "<p>Override for custom error handling.</p>": "<p>Переопределите, чтобы задать свою обработку ошибок.</p>",
+ "<p>A hook to be overridden by users to do some processing on scraped items, return <code>None</code> to drop the item silently.</p>": "<p>Хук для обработки собранных записей. Его можно переопределить. Возврат <code>None</code> удаляет запись без сообщения.</p>",
+ "<p>Check if the response is blocked. Users should override this for custom detection logic.</p>": "<p>Проверяет, заблокирован ли ответ. Переопределите для своей проверки.</p>",
+ "<p>Users should override this to prepare the blocked request before retrying, if needed.</p>": "<p>При необходимости переопределите этот метод, чтобы подготовить заблокированный запрос перед повторной попыткой.</p>",
+ "<p>String representation of the spider.</p>": "<p>Строковое представление Spider.</p>",
+ "<p>Configure sessions for this spider.</p>": "<p>Настраивает сессии этого Spider.</p>",
+ "<p>Override this method to add custom sessions.\nThe default implementation creates a FetcherSession session.</p>": "<p>Переопределите метод, чтобы добавить свои сессии. По умолчанию создаётся сессия FetcherSession.</p>",
+ "<p>The first session added becomes the default for <code>start_requests()</code> unless specified otherwise.</p>": "<p>Первая добавленная сессия становится стандартной для <code>start_requests()</code>, если не указано иное.</p>",
+ "<p>SessionManager to configure</p>": "<p>Менеджер SessionManager, который нужно настроить.</p>",
+ "<p>Request graceful shutdown of the crawling process.</p>": "<p>Запрашивает завершение обхода с ожиданием активных задач.</p>",
+ "<p>Run the spider and return results.</p>": "<p>Запускает Spider и возвращает результаты.</p>",
+ "<p>This is the main entry point for running a spider.\nHandles async execution internally via anyio.</p>": "<p>Основная точка входа для запуска Spider. Асинхронное выполнение внутри управляется через anyio.</p>",
+ "<p>Pressing Ctrl+C will initiate graceful shutdown (waits for active tasks to complete).\nPressing Ctrl+C a second time will force immediate stop.</p>": "<p>Нажатие Ctrl+C запускает завершение с ожиданием активных задач. Второе нажатие Ctrl+C немедленно останавливает работу.</p>",
+ "<p>If crawldir is set, a checkpoint will also be saved on graceful shutdown,\nallowing you to resume the crawl later by running the spider again.</p>": "<p>Если задан crawldir, при завершении с ожиданием активных задач также сохраняется контрольная точка. Повторный запуск Spider позволит продолжить обход позже.</p>",
+ "<p>Whether to use the faster uvloop/winloop event loop implementation, if available.</p>": "<p>Использовать ли более быструю реализацию цикла событий uvloop/winloop, если она доступна.</p>",
+ "<p>Asyncio backend options to be used with <code>anyio.run</code></p>": "<p>Параметры бэкенда Asyncio для <code>anyio.run</code>.</p>",
+ "<p>Stream items as they're scraped. Ideal for long-running spiders or building applications on top of the spiders.</p>": "<p>Выдаёт записи потоком по мере сбора. Подходит для долгих обходов или приложений, построенных на Spider.</p>",
+ "<p>Must be called from an async context. Yields items one by one as they are scraped.\nAccess <code>spider.stats</code> during iteration for real-time statistics.</p>": "<p>Нужно вызывать из асинхронного контекста. Выдаёт записи по одной по мере сбора. Во время перебора текущая статистика доступна через <code>spider.stats</code>.</p>",
+ "<p>Note: SIGINT handling for pause/resume is not available in stream mode.</p>": "<p>Примечание: в потоковом режиме обработка SIGINT для паузы и возобновления недоступна.</p>",
+ "<p>Create a copy of this request.</p>": "<p>Создаёт копию этого запроса.</p>",
+ "<p>Generate a unique fingerprint for deduplication.</p>": "<p>Создаёт уникальный отпечаток для удаления дубликатов.</p>",
+ "<p>Caches the result in self._fp after first computation.</p>": "<p>После первого вычисления кеширует результат в self._fp.</p>",
+ "<p>Compare requests by priority</p>": "<p>Сравнивает запросы по приоритету.</p>",
+ "<p>Requests are equal if they have the same fingerprint.</p>": "<p>Запросы равны, если у них одинаковый отпечаток.</p>",
+ "<p>Prepare state for pickling - store callback as name string for pickle compatibility.</p>": "<p>Готовит состояние для pickle: сохраняет имя обработчика строкой для совместимости с pickle.</p>",
+ "<p>Restore state from pickle - callback restored later via _restore_callback().</p>": "<p>Восстанавливает состояние из pickle. Обработчик будет восстановлен позже через _restore_callback().</p>",
+ "<p>Complete result from a spider run.</p>": "<p>Полный результат одного запуска Spider.</p>",
+ "<p>True if the crawl completed normally (not paused).</p>": "<p>True, если обход завершился нормально, без паузы.</p>",
+ "<p>Statistics for a crawl run.</p>": "<p>Статистика одного обхода.</p>",
+ "<p>A list of scraped items with export capabilities.</p>": "<p>Список собранных записей с возможностью экспорта.</p>",
+ "<p>Export items to a JSON file.</p>": "<p>Экспортирует записи в JSON-файл.</p>",
+ "<p>Path to the output file</p>": "<p>Путь к выходному файлу.</p>",
+ "<p>Pretty-print with 2-space indentation (slightly slower)</p>": "<p>Форматирует вывод с отступом в 2 пробела. Немного медленнее.</p>",
+ "<p>Export items as JSON Lines (one JSON object per line).</p>": "<p>Экспортирует записи в JSON Lines, по одному JSON-объекту на строку.</p>",
+ "<p>Export items to a CSV file.</p>": "<p>Экспортирует записи в CSV-файл.</p>",
+ "<p>Items that don't share the same keys are still written, with the missing cells left empty, and any value\nthat isn't a scalar (a nested dictionary or a list) is written as JSON.</p>": "<p>Записи с разными наборами ключей тоже сохраняются. Пропущенные ячейки остаются пустыми, а нескалярные значения, то есть вложенные словари или списки, записываются как JSON.</p>",
+ "<p>The columns to write, defaulting to every key found in the items, in the order they appeared</p>": "<p>Столбцы для записи. По умолчанию используются все ключи, найденные в записях, в порядке первого появления.</p>",
+ "<p>The character separating the columns</p>": "<p>Символ-разделитель столбцов.</p>",
+ "<p>Export items to an XML file.</p>": "<p>Экспортирует записи в XML-файл.</p>",
+ "<p>Each item becomes an element whose children are named after the item's keys. Keys that aren't valid XML\nnames are rewritten and keep the original in a <code>name</code> attribute, and any value that isn't a scalar\n(a nested dictionary or a list) is written as JSON.</p>": "<p>Каждая запись становится элементом, дочерние элементы которого называются по ключам записи. Ключи, недопустимые как имена XML, изменяются, а исходное имя сохраняется в атрибуте <code>name</code>. Нескалярные значения, то есть вложенные словари или списки, записываются как JSON.</p>",
+ "<p>The name of the element wrapping all the items</p>": "<p>Имя элемента, который содержит все записи.</p>",
+ "<p>The name of the element wrapping every item</p>": "<p>Имя элемента, который содержит одну запись.</p>",
+ "<p>Pretty-print the file instead of writing it on a single line</p>": "<p>Форматирует файл для удобного чтения вместо записи всего содержимого в одну строку.</p>",
+ "<p>Manages pre-configured session instances.</p>": "<p>Управляет заранее настроенными экземплярами сессий.</p>",
+ "<p>Register a session instance.</p>": "<p>Регистрирует экземпляр сессии.</p>",
+ "<p>Name to reference this session in requests</p>": "<p>Имя для обращения к этой сессии в запросах.</p>",
+ "<p>Your pre-configured session instance</p>": "<p>Заранее настроенный экземпляр сессии.</p>",
+ "<p>If True, this becomes the default session</p>": "<p>При True эта сессия становится сессией по умолчанию.</p>",
+ "<p>If True, the session will be started only when a request uses its ID.</p>": "<p>При True сессия запускается только тогда, когда запрос использует её ID.</p>",
+ "<p>Removes a session.</p>": "<p>Удаляет сессию.</p>",
+ "<p>ID of session to remove</p>": "<p>ID сессии для удаления.</p>",
+ "<p>Remove and returns a session.</p>": "<p>Удаляет и возвращает сессию.</p>",
+ "<p>Start all sessions that aren't already alive.</p>": "<p>Запускает все сессии, которые ещё не работают.</p>",
+ "<p>Close all registered sessions.</p>": "<p>Закрывает все зарегистрированные сессии.</p>",
+ "<p>Check if a session ID is registered.</p>": "<p>Проверяет, зарегистрирован ли ID сессии.</p>",
+ "<p>Number of registered sessions.</p>": "<p>Число зарегистрированных сессий.</p>"
+} %}
+{% macro translate(value) %}
+ {% set result = namespace(html=value | replace("Bases:", "Базовые классы:")) %}
+ {% for source, target in translations.items() %}
+ {% set result.html = result.html | replace(source, target | safe) %}
+ {% endfor %}
+ {{ result.html | safe }}
+{% endmacro %}
diff --git a/zensical-base.yml b/zensical-base.yml
index 9951700..75a9d52 100644
--- a/zensical-base.yml
+++ b/zensical-base.yml
@@ -138,6 +138,9 @@ extra:
- name: 日本語
link: https://scrapling.readthedocs.io/en/latest/ja/
lang: ja
+ - name: Русский
+ link: https://scrapling.readthedocs.io/en/latest/ru/
+ lang: ru
watch:
- zensical-base.yml
- docs/assets
diff --git a/zensical.ru.yml b/zensical.ru.yml
new file mode 100644
index 0000000..af856ab
--- /dev/null
+++ b/zensical.ru.yml
@@ -0,0 +1,99 @@
+INHERIT: zensical-base.yml
+site_description: Scrapling - Простой веб-скрапинг для современного интернета!
+site_url: https://scrapling.readthedocs.io/en/latest/ru/
+docs_dir: docs/locales/ru
+site_dir: site/ru
+edit_uri: edit/main/docs/locales/ru/
+copyright: Copyright &copy; 2025 Karim Shoair - <a href="#__consent">Изменить настройки cookie</a>
+nav:
+- Введение: index.md
+- Начало работы: overview.md
+- Тесты производительности: benchmarks.md
+- Руководства:
+ - Разбор страниц:
+ - Поиск элементов: parsing/selection.md
+ - Основные классы: parsing/main_classes.md
+ - Адаптивный скрапинг: parsing/adaptive.md
+ - Загрузка страниц:
+ - Выбор Fetcher: fetching/choosing.md
+ - HTTP-запросы: fetching/static.md
+ - Загрузка через браузер: fetching/stealthy.md
+ - Пауки:
+ - Устройство: spiders/architecture.md
+ - Первый паук: spiders/getting-started.md
+ - Запросы и ответы: spiders/requests-responses.md
+ - Сессии: spiders/sessions.md
+ - Прокси и блокировки: spiders/proxy-blocking.md
+ - Общие шаблоны: spiders/generic-templates.md
+ - Шаблоны для платформ: spiders/platform-templates.md
+ - Дополнительные возможности: spiders/advanced.md
+ - Командная строка:
+ - Обзор: cli/overview.md
+ - Интерактивная оболочка: cli/interactive-shell.md
+ - Команды извлечения: cli/extract-commands.md
+ - Интеграция с AI:
+ - MCP-сервер: ai/mcp-server.md
+ - Agent Skill: ai/agent-skill.md
+ - Создание RAG-систем: ai/building-rag-systems.md
+ - Интеграции и переход:
+ - Интеграция со Scrapy: integrations/scrapy.md
+ - Переход с BeautifulSoup: tutorials/migrating_from_beautifulsoup.md
+- Практические примеры:
+ - Бесплатная замена AI-сервисам сбора данных: tutorials/replacing_ai.md
+- Разработка:
+ - Справочник API:
+ - Selector: api-reference/selector.md
+ - Fetcher: api-reference/fetchers.md
+ - MCP-сервер: api-reference/mcp-server.md
+ - Пользовательские типы: api-reference/custom-types.md
+ - Response: api-reference/response.md
+ - Spider: api-reference/spiders.md
+ - Смена прокси: api-reference/proxy-rotation.md
+ - Собственная система хранения: development/adaptive_storage_system.md
+ - Типы Scrapling: development/scrapling_custom_types.md
+- Поддержка и реклама: donate.md
+- Участие в разработке: https://github.com/D4Vinci/Scrapling/blob/main/CONTRIBUTING.md
+- История изменений: https://github.com/D4Vinci/Scrapling/blob/main/CHANGELOG.md
+theme:
+ language: ru
+ palette:
+ - media: '(prefers-color-scheme: light)'
+ scheme: default
+ accent: green
+ primary: deep purple
+ toggle:
+ icon: lucide/sun
+ name: Включить тёмную тему
+ - media: '(prefers-color-scheme: dark)'
+ scheme: slate
+ accent: light green
+ primary: deep purple
+ toggle:
+ icon: lucide/moon
+ name: Включить светлую тему
+markdown_extensions:
+ toc:
+ permalink_title: Ссылка на этот раздел
+plugins:
+ mkdocstrings:
+ locale: ru
+extra:
+ analytics:
+ feedback:
+ title: Эта страница была полезна?
+ ratings:
+ - icon: material/heart
+ name: Да, полезна
+ data: 1
+ note: Спасибо за отзыв!
+ - icon: material/heart-broken
+ name: Нужно улучшить
+ data: 0
+ note: 'Спасибо за отзыв! Помогите нам улучшить страницу: <a href="https://github.com/D4Vinci/Scrapling/issues/new?template=04-docs_issue.yml" target="_blank" rel="noopener">сообщите о проблеме в документации</a>.'
+ consent:
+ title: Использование cookie
+ description: Мы используем cookie, чтобы запоминать ваши настройки и понимать, полезна ли документация. Ваше согласие помогает нам улучшать её.
+ actions:
+ - accept
+ - reject
+ - manage