diff --git a/sui/README.md b/sui/README.md
index bcd82615..b1472aa0 100644
--- a/sui/README.md
+++ b/sui/README.md
@@ -18,16 +18,18 @@ SUI is a full-stack web development framework that allows you to create web appl
 ```
 /templates/<template_name>/
 ├── __document.html         # Global document template
-├── __assets/               # Static assets
+├── __data.json             # Global data (accessible via $global)
+├── __assets/               # Static assets (reference via @assets/)
 ├── __locales/              # Locale files
-└── <route>/                # Pages
-    └── <page>/
-        ├── <page>.html     # HTML template
+└── pages/                  # All pages go here
+    └── <page>/             # Route = folder name (can be nested)
+        ├── <page>.html     # HTML template (filename must match folder)
         ├── <page>.css      # Styles
         ├── <page>.ts       # Frontend script
         ├── <page>.json     # Data configuration
         ├── <page>.config   # Page configuration
-        └── <page>.backend.ts  # Backend script
+        ├── <page>.backend.ts  # Backend script
+        └── __locales/      # Page-level locale files
 ```
 
 ### Basic Page
@@ -85,13 +87,16 @@ Agent SUI is designed for AI Agent applications with automatic page loading from
 ```
 <app>/
 ├── agent/
-│   └── template/              # Agent SUI template
+│   └── template/              # Agent SUI template (shared)
 │       ├── __document.html
+│       ├── __data.json
 │       ├── __assets/
-│       └── pages/
+│       └── pages/             # Global pages (401, 404, etc.)
+│           └── <page>/
 └── assistants/
     └── <name>/
-        └── pages/             # Assistant pages
+        └── pages/             # Assistant pages → /agents/<name>/<route>
+            └── <page>/
 ```
 
 Build with: `yao sui build agent`
diff --git a/sui/docs/agent-sui.md b/sui/docs/agent-sui.md
index 29ffa803..6207441a 100644
--- a/sui/docs/agent-sui.md
+++ b/sui/docs/agent-sui.md
@@ -11,31 +11,28 @@ Agent SUI is a special SUI configuration designed for AI Agent applications. It
 │   └── template/              # Agent SUI template directory
 │       ├── template.json      # Optional template configuration
 │       ├── __document.html    # Global document template
-│       ├── __data.json        # Global data
-│       ├── __assets/          # Global assets (CSS, JS, images)
+│       ├── __data.json        # Global data (accessible via $global)
+│       ├── __assets/          # Global assets (reference via @assets/)
 │       │   ├── css/
 │       │   ├── js/
 │       │   └── images/
-│       ├── pages/             # Global agent pages (login, error, etc.)
-│       │   └── login/
-│       │       └── login.html
-│       └── __locales/         # Internationalization
+│       ├── __locales/         # Global locale files
+│       └── pages/             # Global pages (401, 404, login, etc.)
+│           └── <page>/        # Route = folder name
+│               ├── <page>.html
+│               ├── <page>.css
+│               ├── <page>.ts
+│               └── __locales/ # Page-level locale files
 │
 └── assistants/                # Assistants directory
-    ├── demo/                  # Assistant: demo
-    │   ├── package.yao        # Assistant configuration
-    │   └── pages/             # Assistant-specific pages
-    │       ├── index/
-    │       │   ├── index.html
-    │       │   ├── index.css
-    │       │   └── index.ts
-    │       └── __assets/      # Optional assistant-specific assets
-    │
-    └── another/               # Assistant: another
-        ├── package.yao
-        └── pages/
-            └── settings/
-                └── settings.html
+    └── <name>/                # Assistant
+        ├── package.yao        # Assistant configuration
+        └── pages/             # Assistant pages → /agents/<name>/<route>
+            └── <page>/        # Route = folder name (can be nested)
+                ├── <page>.html
+                ├── <page>.css
+                ├── <page>.ts
+                └── __locales/
 ```
 
 ## Route Mapping
diff --git a/sui/docs/i18n.md b/sui/docs/i18n.md
index 09da0f24..9245a4ee 100644
--- a/sui/docs/i18n.md
+++ b/sui/docs/i18n.md
@@ -128,11 +128,26 @@ self.Confirm = () => {
 
 ## Locale Detection
 
-SUI detects locale from:
+SUI detects locale from the `locale` HTTP cookie on the server side.
 
-1. Cookie (`locale` or `umi_locale`)
-2. Browser language
-3. Default (`en-us`)
+**Important:** `s:trans` translations are server-side rendered. This means:
+
+1. The translation happens when the page is generated on the server
+2. Changing locale via JavaScript only affects localStorage/client state
+3. To apply locale changes to `s:trans` content, you must reload the page
+
+```javascript
+// To change locale and have s:trans reflect the change:
+document.cookie = "locale=zh-CN;path=/;max-age=31536000";
+location.reload(); // Required for server-side translations
+```
+
+**Cookie Priority:**
+
+1. `locale` cookie (primary)
+2. `umi_locale` cookie (fallback for CUI compatibility)
+3. Browser language
+4. Default (`en-us`)
 
 ### Access Current Locale