Update Documentation for SUI Structure and Locale Handling

- Revised the README and agent-sui documentation to clarify the directory structure, including the addition of __data.json and __locales directories for global and page-level data.
- Enhanced explanations of the pages directory, emphasizing the organization of global and assistant-specific pages.
- Updated the i18n documentation to detail locale detection and the importance of server-side rendering for translations, including a code snippet for changing locales via JavaScript.

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
+└── pages/                  # All pages go here
-    └── <page>/
+    └── <page>/             # Route = folder name (can be nested)
-        ├── <page>.html     # HTML template
+        ├── <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`

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
+│       ├── __data.json        # Global data (accessible via $global)
-│       ├── __assets/          # Global assets (CSS, JS, images)
+│       ├── __assets/          # Global assets (reference via @assets/)
 │       │   ├── css/
 │       │   ├── js/
 │       │   └── images/
-│       ├── pages/             # Global agent pages (login, error, etc.)
+│       ├── __locales/         # Global locale files
-│       │   └── login/
+│       └── pages/             # Global pages (401, 404, login, etc.)
-│       │       └── login.html
+│           └── <page>/        # Route = folder name
-│       └── __locales/         # Internationalization
+│               ├── <page>.html
+│               ├── <page>.css
+│               ├── <page>.ts
+│               └── __locales/ # Page-level locale files
 │
 └── assistants/                # Assistants directory
-    ├── demo/                  # Assistant: demo
+    └── <name>/                # Assistant
-    │   ├── package.yao        # Assistant configuration
+        ├── package.yao        # Assistant configuration
-    │   └── pages/             # Assistant-specific pages
+        └── pages/             # Assistant pages → /agents/<name>/<route>
-    │       ├── index/
+            └── <page>/        # Route = folder name (can be nested)
-    │       │   ├── index.html
+                ├── <page>.html
-    │       │   ├── index.css
+                ├── <page>.css
-    │       │   └── index.ts
+                ├── <page>.ts
-    │       └── __assets/      # Optional assistant-specific assets
+                └── __locales/
-    │
-    └── another/               # Assistant: another
-        ├── package.yao
-        └── pages/
-            └── settings/
-                └── settings.html
 ```
 
 ## Route Mapping

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`)
+**Important:** `s:trans` translations are server-side rendered. This means:
-2. Browser language
+
-3. Default (`en-us`)
+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