docs: add chinese and portuguese full documentation

Author: thalissonvs

docs/en/deep-dive/architecture/browser-domain.md

@@ -10,23 +10,17 @@ The Browser domain represents the highest level of Pydoll's automation hierarchy
 The Browser domain sits at the intersection of process management, protocol communication, and resource coordination. It orchestrates multiple specialized components to provide a unified interface for browser automation:
 
 ```mermaid
-graph TB
-    subgraph "Browser Domain"
-        Browser[Browser Instance]
-        Browser --> ConnectionHandler[Connection Handler]
-        Browser --> ProcessManager[Process Manager]
-        Browser --> ProxyManager[Proxy Manager]
-        Browser --> TempDirManager[Temp Directory Manager]
-        Browser --> TabRegistry[Tab Registry]
-        Browser --> ContextAuth[Context Proxy Auth]
-    end
+graph LR
+    Browser[Browser Instance]
+    Browser --> ProcessManager[Process Manager]
+    Browser --> ProxyManager[Proxy Manager]
+    Browser --> TempDirManager[Temp Directory Manager]
+    Browser --> TabRegistry[Tab Registry]
+    Browser --> ConnectionHandler[Connection Handler]
     
-    ConnectionHandler <--> |WebSocket| CDP[Chrome DevTools Protocol]
     ProcessManager --> |Manages| BrowserProcess[Browser Process]
-    TabRegistry --> Tab1[Tab Instance 1]
-    TabRegistry --> Tab2[Tab Instance 2]
-    TabRegistry --> Tab3[Tab Instance N]
-    
+    ConnectionHandler <--> |WebSocket| CDP[Chrome DevTools Protocol]
+    TabRegistry --> |Manages| Tabs[Tab Instances]
     CDP <--> BrowserProcess
 ```
 
@@ -143,43 +137,96 @@ class Browser:
 - **Memory efficiency**: Prevents duplicate Tab instances for same target
 - **Event routing**: Ensures events route to correct Tab instance
 
-### Proxy and Context Authentication
+### Proxy Authentication Architecture
+
+Pydoll implements **automatic proxy authentication** via the Fetch domain to avoid exposing credentials in CDP commands. The implementation uses **two distinct mechanisms** depending on proxy scope:
 
-Pydoll implements **automatic proxy authentication** via the Fetch domain to avoid exposing credentials in CDP commands:
+#### Mechanism 1: Browser-Level Proxy Auth (Global Proxy)
+
+When a proxy is configured via `ChromiumOptions` (applies to all tabs in the default context):
 
 ```python
-class Browser:
-    def __init__(self, ...):
-        # Stores proxy credentials per context
-        self._context_proxy_auth: dict[str, tuple[str, str]] = {}
+# In Browser.start() -> _configure_proxy()
+async def _configure_proxy(self, private_proxy, proxy_credentials):
+    # Enable Fetch AT BROWSER LEVEL
+    await self.enable_fetch_events(handle_auth_requests=True)
 
-    async def create_browser_context(self, proxy_server, ...):
-        # Extract credentials from proxy URL
-        sanitized_proxy, (user, pwd) = self._sanitize_proxy_and_extract_auth(proxy_server)
-        
-        # Send sanitized proxy to CDP (no credentials exposed)
-        response = await self._execute_command(
-            TargetCommands.create_browser_context(proxy_server=sanitized_proxy)
-        )
-        context_id = response['result']['browserContextId']
-        
-        # Store credentials for later authentication
-        if user and pwd:
-            self._context_proxy_auth[context_id] = (user, pwd)
-        
-        return context_id
+    # Register callbacks AT BROWSER LEVEL (affects ALL tabs)
+    await self.on(FetchEvent.REQUEST_PAUSED, self._continue_request_callback, temporary=True)
+    await self.on(FetchEvent.AUTH_REQUIRED, 
+                  partial(self._continue_request_with_auth_callback,
+                          proxy_username=credentials[0],
+                          proxy_password=credentials[1]),
+                  temporary=True)
+```
+
+**Scope:** Browser-wide WebSocket connection → affects **all tabs in default context**
+
+#### Mechanism 2: Tab-Level Proxy Auth (Per-Context Proxy)
+
+When a proxy is configured per-context via `create_browser_context(proxy_server=...)`:
+
+```python
+# Store credentials per context
+async def create_browser_context(self, proxy_server, ...):
+    sanitized_proxy, extracted_auth = self._sanitize_proxy_and_extract_auth(proxy_server)
+    
+    response = await self._execute_command(
+        TargetCommands.create_browser_context(proxy_server=sanitized_proxy)
+    )
+    context_id = response['result']['browserContextId']
+    
+    if extracted_auth:
+        self._context_proxy_auth[context_id] = extracted_auth  # Store per context
+    
+    return context_id
+
+# Setup auth for EACH tab in that context
+async def _setup_context_proxy_auth_for_tab(self, tab, browser_context_id):
+    creds = self._context_proxy_auth.get(browser_context_id)
+    if not creds:
+        return
+    
+    # Enable Fetch ON THE TAB (tab-level WebSocket)
+    await tab.enable_fetch_events(handle_auth=True)
+    
+    # Register callbacks ON THE TAB (affects only this tab)
+    await tab.on(FetchEvent.REQUEST_PAUSED, 
+                 partial(self._tab_continue_request_callback, tab=tab), 
+                 temporary=True)
+    await tab.on(FetchEvent.AUTH_REQUIRED,
+                 partial(self._tab_continue_request_with_auth_callback,
+                         tab=tab,
+                         proxy_username=creds[0],
+                         proxy_password=creds[1]),
+                 temporary=True)
 ```
 
-When a Tab is created in a context with stored credentials, Pydoll automatically:
+**Scope:** Tab-level WebSocket connection → affects **only that specific tab**
+
+#### Why Two Mechanisms?
+
+| Aspect | Browser-Level | Tab-Level |
+|--------|---------------|-----------|
+| **Trigger** | Proxy in `ChromiumOptions` | Proxy in `create_browser_context()` |
+| **WebSocket** | Browser-level connection | Tab-level connection |
+| **Scope** | All tabs in default context | Only tabs in that context |
+| **Efficiency** | One listener for all tabs | One listener per tab |
+| **Isolation** | No context separation | Each context has different credentials |
+
+**Design rationale for tab-level auth:**
 
-1. Enables Fetch domain on the Tab
-2. Registers `Fetch.requestPaused` handler (continues normal requests)
-3. Registers `Fetch.authRequired` handler (provides credentials, then disables Fetch)
+- **Context isolation**: Each context can have a **different proxy** with **different credentials**
+- **CDP limitation**: Fetch domain cannot be scoped to a specific context at browser level
+- **Tradeoff**: Slightly less efficient (one listener per tab), but necessary for per-context proxy support
 
 This architecture ensures **credentials never appear in CDP logs** and authentication is handled transparently.
 
 !!! warning "Fetch Domain Side Effects"
-    Enabling Fetch for proxy auth temporarily pauses **all requests** in that Tab until the auth callback fires. This is a CDP limitation - Fetch enables global request interception. After authentication completes, Fetch is disabled to minimize overhead.
+    - **Browser-level Fetch**: Temporarily pauses **all requests across all tabs** in the default context until auth completes
+    - **Tab-level Fetch**: Temporarily pauses **all requests in that specific tab** until auth completes
+    
+    This is a CDP limitation - Fetch enables request interception. After authentication completes, Fetch is disabled to minimize overhead.
 
 ## Initialization and Lifecycle
 
@@ -579,16 +626,27 @@ tab = await browser.new_tab()
 
 **Alternative explored:** Auto-close initial tab in `new_tab()`. Rejected because it's surprising behavior (implicit side effects).
 
-### Context-Specific Proxy Auth: Fetch Domain Overhead
+### Proxy Authentication: Two-Level Architecture Tradeoff
 
-Pydoll's proxy authentication uses Fetch domain to hide credentials:
+Pydoll's proxy authentication uses two different Fetch domain strategies:
 
+**Browser-Level (Global Proxy):**
 - **Security benefit**: Credentials never logged in CDP traces
-- **Performance cost**: Fetch pauses **all requests** until auth completes
+- **Performance cost**: Fetch pauses **all requests across all tabs** until auth completes
+- **Efficiency**: Single listener for all tabs in default context
 - **Mitigation**: Fetch is disabled after first auth, minimizing overhead
 
+**Tab-Level (Per-Context Proxy):**
+- **Security benefit**: Credentials never logged in CDP traces
+- **Performance cost**: Fetch pauses **all requests in that tab** until auth completes
+- **Efficiency**: Separate listener per tab (less efficient, but necessary for isolation)
+- **Isolation benefit**: Each context can have different proxy credentials
+- **Mitigation**: Fetch is disabled after first auth per tab
+
 **Why not use Browser.setProxyAuth?** This CDP command doesn't exist. Fetch is the only mechanism for programmatic auth.
 
+**Why tab-level for contexts?** CDP's Fetch domain cannot be scoped to a specific BrowserContext. Since each context can have a different proxy with different credentials, Pydoll must handle auth at the tab level to respect context boundaries.
+
 ### Port Randomization Strategy
 
 Random CDP ports (9223-9322) prevent collisions when running parallel browser instances:

docs/en/deep-dive/architecture/browser-requests-architecture.md

@@ -170,13 +170,13 @@ A common question: if JavaScript can execute the request, why use network events
 
 | Information Source | JavaScript (Fetch API) | Network Events (CDP) |
 |-------------------|------------------------|----------------------|
-| Response status | ✅ Available | ✅ Available |
-| Response body | ✅ Available | ❌ Not available |
-| Response headers | ⚠️ Partial (CORS restricted) | ✅ Complete |
-| Request headers | ❌ Not accessible | ✅ Complete |
-| Set-Cookie headers | ❌ Hidden by browser | ✅ Available |
-| Timing information | ⚠️ Limited | ✅ Comprehensive |
-| Redirect chain | ❌ Only final URL | ✅ Full chain |
+| Response status | Available | Available |
+| Response body | Available | Not available |
+| Response headers | Partial (CORS restricted) | Complete |
+| Request headers | Not accessible | Complete |
+| Set-Cookie headers | Hidden by browser | Available |
+| Timing information | Limited | Comprehensive |
+| Redirect chain | Only final URL | Full chain |
 
 **The Solution:** Combine both sources for complete information.
 
@@ -322,11 +322,11 @@ Network events add overhead to request execution:
 ### Optimization Pattern
 
 ```python
-# ❌ Inefficient - events enabled/disabled repeatedly
+# Inefficient - events enabled/disabled repeatedly
 for url in urls:
     response = await tab.request.get(url)
 
-# ✅ Efficient - events enabled once
+# Efficient - events enabled once
 await tab.enable_network_events()
 for url in urls:
     response = await tab.request.get(url)

docs/en/deep-dive/architecture/event-architecture.md

@@ -151,16 +151,23 @@ When an event arrives via WebSocket:
 Callbacks can be either synchronous or asynchronous. The event system handles both:
 
 ```python
-async def callback_wrapper(event):
-    asyncio.create_task(callback(event))
-
-if asyncio.iscoroutinefunction(callback):
-    function_to_register = callback_wrapper
-else:
-    function_to_register = callback
+async def _trigger_callbacks(self, event_name: str, event_data: dict):
+    for cb_id, cb_data in self._event_callbacks.items():
+        if cb_data['event'] == event_name:
+            if asyncio.iscoroutinefunction(cb_data['callback']):
+                await cb_data['callback'](event_data)
+            else:
+                cb_data['callback'](event_data)
 ```
 
-This ensures callbacks run in background tasks to prevent blocking the event loop.
+Asynchronous callbacks are awaited sequentially. This means each callback completes before the next one executes, which is important for:
+
+- **Predictable Execution Order**: Callbacks execute in registration order
+- **Error Handling**: Exceptions in one callback don't prevent others from executing
+- **State Consistency**: Callbacks can rely on sequential state changes
+
+!!! info "Sequential vs Concurrent Execution"
+    Callbacks execute sequentially within the same event. However, different events can be processed concurrently since the event loop handles multiple connections simultaneously.
 
 ## Event Flow and Lifecycle
 
@@ -294,35 +301,45 @@ The `ConnectionHandler` is the central component managing WebSocket communicatio
 ```python
 class ConnectionHandler:
     def __init__(self, ...):
-        self._callbacks = {}  # Event name -> list of callbacks
-        self._next_callback_id = 0
+        self._events_handler = EventsManager()
         self._websocket = None
         # ... other attributes
 
     async def register_callback(self, event_name, callback, temporary):
-        callback_id = self._next_callback_id
-        self._next_callback_id += 1
-        
-        if event_name not in self._callbacks:
-            self._callbacks[event_name] = []
-        
-        self._callbacks[event_name].append((callback_id, callback, temporary))
-        return callback_id
+        return self._events_handler.register_callback(event_name, callback, temporary)
+
+class EventsManager:
+    def __init__(self):
+        self._event_callbacks = {}  # Callback ID -> callback data
+        self._callback_id = 0
 
-    async def _dispatch_event(self, event_name, event_data):
-        if event_name not in self._callbacks:
-            return
-        
+    def register_callback(self, event_name, callback, temporary):
+        self._callback_id += 1
+        self._event_callbacks[self._callback_id] = {
+            'event': event_name,
+            'callback': callback,
+            'temporary': temporary
+        }
+        return self._callback_id
+    
+    async def _trigger_callbacks(self, event_name, event_data):
         callbacks_to_remove = []
 
-        for callback_id, callback, temporary in self._callbacks[event_name]:
-            await callback(event_data)
-            
-            if temporary:
-                callbacks_to_remove.append(callback_id)
+        for cb_id, cb_data in self._event_callbacks.items():
+            if cb_data['event'] == event_name:
+                # Execute callback (await if async, call directly if sync)
+                if asyncio.iscoroutinefunction(cb_data['callback']):
+                    await cb_data['callback'](event_data)
+                else:
+                    cb_data['callback'](event_data)
+                
+                # Mark temporary callbacks for removal
+                if cb_data['temporary']:
+                    callbacks_to_remove.append(cb_id)
 
-        for callback_id in callbacks_to_remove:
-            await self.remove_callback(callback_id)
+        # Remove temporary callbacks after all callbacks executed
+        for cb_id in callbacks_to_remove:
+            self.remove_callback(cb_id)
 ```
 
 This architecture ensures:
@@ -374,9 +391,12 @@ Each tab maintains its own:
 
 - Event domain enablement state
 - Callback registry
-- WebSocket connection (or shared connection with target ID)
+- Event communication channel
 - Network logs (if network events enabled)
 
+!!! info "Communication Architecture"
+    Each tab has its own event communication channel to the browser. For technical details on how WebSocket connections and target IDs work at the protocol level, see [Browser Domain Architecture](./browser-domain.md).
+
 ### Shared Browser Context
 
 Multiple tabs can share:

docs/en/deep-dive/architecture/find-elements-mixin.md

@@ -35,7 +35,7 @@ Pydoll faces a specific architectural challenge:
 - **`WebElement`** needs to find elements **relative to itself** (child elements)
 - Both need **identical selector logic** (CSS, XPath, attribute building)
 
-**Option 1: Shared Base Class** ❌
+**Option 1: Shared Base Class**
 
 ```python
 class ElementLocator:
@@ -53,7 +53,7 @@ class WebElement(ElementLocator):
 - Violates Single Responsibility: `Tab` shouldn't inherit from same class as `WebElement`
 - Hard to extend: Adding new capabilities requires modifying base class
 
-**Option 2: Mixin Pattern** ✅
+**Option 2: Mixin Pattern (Chosen Approach)**
 
 ```python
 class FindElementsMixin: