@nocobase/plugin-ai 2.1.0-beta.30 → 2.1.0-beta.33

package/dist/ai/docs/nocobase/ai-employees/scenarios/localization-hy-mt.md

@@ -0,0 +1,241 @@
+---
+pkg: '@nocobase/plugin-ai'
+title: 'Use Lina and local HY-MT to translate localization entries'
+description: 'Deploy the HY-MT1.5 GGUF translation model with llama-server and configure it for Lina to batch translate NocoBase localization entries.'
+keywords: 'Lina,localization,HY-MT,GGUF,llama-server,OpenAI compatible,AI translation,NocoBase'
+---
+
+# Use Lina and local HY-MT1.5-1.8B to translate localization entries
+
+This guide describes a localization translation practice: deploy a translation-specific small model locally, expose it as an OpenAI-compatible service, and configure it for Lina to translate localization entries in batches.
+
+This approach is suitable for translating many system entries, plugin text, menus, collection titles, and field labels. Compared with online models, local models are not affected by external API RPM, TPM, or concurrency limits, and concurrency can be tuned according to machine and model capability.
+
+## Overview
+
+This guide uses:
+
+- Model: `tencent/HY-MT1.5-1.8B-GGUF`
+- Inference service: `llama-server`
+- Integration: OpenAI-compatible API
+- AI Employee: Lina
+- Entry point: Localization Management page
+
+:::info{title=Note}
+HY-MT1.5-1.8B is a translation-specific small model. It is more suitable for short entries, UI text, and batch translation. General chat models are not recommended as the first choice for localization tasks.
+:::
+
+## Prerequisites
+
+Before starting, prepare:
+
+- The **Localization Management** plugin is enabled.
+- Target language is enabled.
+- Localization entries have been synchronized.
+- The local machine or server can run [`llama-server`](https://github.com/ggml-org/llama.cpp).
+- The NocoBase service can access the HTTP address of `llama-server`.
+
+## Deploy HY-MT GGUF
+
+### Install llama.cpp
+
+On macOS, you can install it with Homebrew:
+
+```bash
+brew install llama.cpp
+```
+
+You can also use a prebuilt llama.cpp binary or build it from source. The final requirement is that `llama-server` is available.
+
+### Start an OpenAI-compatible service
+
+Start the service with the GGUF model from Hugging Face:
+
+```bash
+llama-server \
+  -hf tencent/HY-MT1.5-1.8B-GGUF:Q4_K_M \
+  --host 0.0.0.0 \
+  --port 8000 \
+  -c 2048 \
+  -np 4
+```
+
+| Parameter | Description |
+| --- | --- |
+| `-hf` | Load the model from Hugging Face. |
+| `--host` | Listening address. Use `127.0.0.1` for local testing or `0.0.0.0` for container or remote access. |
+| `--port` | HTTP service port. |
+| `-c` | Context length. Localization entries are usually short, so `2048` is usually enough. |
+| `-np` | Number of parallel slots. Adjust according to machine performance. |
+
+:::info{title=Tip}
+If server resources are limited, start with `-np 1` or `-np 2`, then increase gradually after verifying stability.
+:::
+
+## Test the Model Service
+
+After `llama-server` starts, check service health:
+
+```bash
+curl http://127.0.0.1:8000/health
+```
+
+Then test translation through the OpenAI-compatible API:
+
+```bash
+curl http://127.0.0.1:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "tencent/HY-MT1.5-1.8B-GGUF:Q4_K_M",
+    "messages": [
+      {
+        "role": "user",
+        "content": "Translate the following text into Chinese. Output only the translated result without any additional explanation:\n\nSave"
+      }
+    ]
+  }'
+```
+
+If you start from a local model file, change `model` to the actual model name returned or configured by the service.
+
+:::warning{title=Note}
+If a request does not respond for a long time, the model may be too slow, concurrency may be too high, or context may be too large. Lower `-np` and NocoBase translation concurrency first, then observe response time.
+:::
+
+## Configure an LLM Service in NocoBase
+
+Go to `System Settings -> AI Employees -> LLM service` and add an LLM service.
+
+Example configuration:
+
+| Setting | Example |
+| --- | --- |
+| Provider | OpenAI (completions) |
+| Title | HY-MT Local |
+| Base URL | `http://127.0.0.1:8000/v1` |
+| API Key | If llama-server has no authentication, use a placeholder such as `dummy`. |
+| Enabled Models | Select `tencent/HY-MT1.5-1.8B-GGUF:Q4_K_M`, or enter the actual model name. |
+
+After configuration, use `Test flight` to verify the model.
+
+:::info{title=Tip}
+If NocoBase runs in Docker, `127.0.0.1` points to the container itself and may not access the host service. Use the host IP, container network address, or `host.docker.internal`.
+:::
+
+## Configure Lina's Dedicated Model
+
+Go to `System Settings -> AI Employees -> AI employees`, open Lina, and switch to `Model settings`.
+
+1. Enable `Enable dedicated model configuration`.
+2. Select the HY-MT local model in `Models`.
+3. Save the configuration.
+
+After this, Lina uses this model for localization translation tasks, preventing users or tasks from switching to general chat models.
+
+For details, see [Configure AI Employee Models](/ai-employees/features/model-settings).
+
+## Configure Translation Concurrency
+
+Localization translation task concurrency is controlled by `AI_LOCALIZATION_CONCURRENCY`:
+
+```bash
+AI_LOCALIZATION_CONCURRENCY=10
+```
+
+Rules:
+
+- Default: `10`
+- Minimum: `1`
+- Maximum: `20`
+- Values outside the range use the default
+
+The best concurrency depends on CPU, GPU, memory, model quantization, and `llama-server -np`. If the default concurrency causes issues:
+
+1. Start with `AI_LOCALIZATION_CONCURRENCY=1` and verify single-entry translation.
+2. Set both `llama-server -np` and `AI_LOCALIZATION_CONCURRENCY` to `2` or `4`.
+3. Observe response time, CPU/GPU usage, and task progress.
+4. Increase concurrency gradually only if stable.
+
+:::warning{title=Note}
+Do not set concurrency too high at the beginning. If concurrency exceeds actual model capacity, tasks may become slower due to queuing, timeout, or service stalls.
+:::
+
+## Execute Localization Translation
+
+Go to `System Management -> Localization Management`.
+
+1. Switch to the target language.
+2. Click `Synchronize` to ensure entries are synchronized.
+3. Click Lina's avatar.
+4. Choose a task scope:
+   - `Incremental translation`: translate entries without translations.
+   - `Selected translation`: translate selected entries in the table.
+   - `Full translation`: translate all entries in the current language.
+5. Check entry count, provider, and model in the confirmation dialog.
+6. Confirm to create the async task.
+7. Wait for completion, review translations, and publish.
+
+Start with `Selected translation` for a few entries to verify output style and speed before running incremental or full translation.
+
+## How Lina Builds Translation Requests
+
+Lina builds requests from entries and reference translations. For short entries, existing references are used to improve consistency:
+
+- Built-in entries prefer Chinese translations as references.
+- Non-built-in entries prefer the system default language as references.
+- If an English reference exists, English is used as source text.
+- Translation results are written to the target language but are not published automatically.
+
+Prompt semantics are similar to:
+
+```text
+Refer to the following translation:
+{source_term} is translated as {target_term}
+
+Translate the following text into {target_language}. Output only the translated result without any additional explanation:
+
+{source_text}
+```
+
+## Troubleshooting
+
+### No progress after creating a task
+
+Check whether `llama-server` received requests. View service logs or call `/v1/chat/completions` with `curl`.
+
+If the model receives requests but does not return, reduce:
+
+- `AI_LOCALIZATION_CONCURRENCY`
+- `llama-server -np`
+- `llama-server -c`
+
+### The model returns explanations instead of translations
+
+Local translation models are usually more stable than general chat models. If explanations still appear, test the same prompt with `curl` first to verify the model's output style.
+
+You can also translate shorter entries first or reduce sampling parameters such as temperature.
+
+### NocoBase cannot connect to the model service
+
+Check:
+
+- Whether Base URL includes `/v1`.
+- Whether the NocoBase runtime environment can access the address.
+- Whether firewall or container networking blocks the port.
+- Whether `llama-server` is still running.
+
+## Review Before Publishing
+
+After AI translation finishes, review before publishing:
+
+- Filter by module and check short entries such as menus, buttons, field names, and statuses.
+- Check variables, placeholders, HTML tags, and formatting symbols.
+- Check key business terminology consistency.
+- If built-in entry translations are overwritten, resynchronize in Localization Management and select `Reset system built-in entry translations` to restore defaults. To contribute default translations for the system and official plugins, see [Translation Contribution](/get-started/translations).
+- Publish in a test environment first, then sync to production.
+
+## References
+
+- [tencent/HY-MT1.5-1.8B-GGUF](https://huggingface.co/tencent/HY-MT1.5-1.8B-GGUF)
+- [llama-server documentation](https://www.mintlify.com/ggml-org/llama.cpp/inference/server)
+- [Lina: Localization Engineer](/ai-employees/built-in/lina)

package/dist/ai/docs/nocobase/ai-employees/workflow/nodes/employee/configuration.md

@@ -18,7 +18,7 @@ You can refer to the following documents:
 
 - [Workflow](/workflow)
 - [Configure LLM Service](/ai-employees/features/llm-service)
-- [Built-in AI Employees](/ai-employees/features/built-in-employee)
+- [Built-in AI Employees](/ai-employees/built-in/)
 - [New AI Employee](/ai-employees/features/new-ai-employees)
 
 ### Task

package/dist/ai/docs/nocobase/cluster-mode/index.md

@@ -11,6 +11,10 @@ keywords: "cluster mode,multi-instance,load balancing,shared storage,Redis,Kuber
 
 Starting from v1.6.0, NocoBase supports running applications in cluster mode. When an application runs in cluster mode, it can improve its performance in handling concurrent access by using multiple instances and a multi-core mode.
 
+Based on cluster mode, you can achieve application-level high availability: traffic is distributed by a load balancer across multiple NocoBase instances within the same cluster, so if a single instance fails, restarts, or is being released, other instances can continue serving traffic. In practice, a single cluster should usually be deployed within the same low-latency network environment.
+
+It is important to note that NocoBase cluster mode addresses horizontal scaling and high availability of application instances at the application layer. If you need warm standby or disaster recovery across availability zones or regions, you would typically deploy multiple independent clusters, and the operations team would be responsible for the data replication and switchover strategy for the database, shared storage, and other infrastructure.
+
 ## System Architecture
 
 
@@ -33,4 +37,4 @@ This document only introduces the basic concepts and components of NocoBase's cl
   - [Operations](./operations)
 - Advanced
   - [Service Splitting](./services-splitting)
-- [Development Reference](./development)
+- [Development Reference](./development)

package/dist/ai/docs/nocobase/cluster-mode/preparations.md

@@ -25,12 +25,14 @@ First, please ensure you have obtained licenses for the above plugins (you can p
 
 ## System Components
 
-Other system components, besides the application instance itself, can be selected by operations personnel based on the team's operational needs.
+In addition to the application instances themselves, cluster deployment also requires system components such as the database, middleware, shared storage, and load balancing. Different teams can choose the specific implementation of these components based on their own operating model.
 
 ### Database
 
 Since the current cluster mode only targets application instances, the database temporarily supports only a single node. If you have a database architecture like master-slave, you need to implement it yourself through middleware and ensure it is transparent to the NocoBase application.
 
+If you need warm standby or disaster recovery across availability zones or regions, the database synchronization and switchover strategy must be designed and implemented by your operations team.
+
 ### Middleware
 
 NocoBase's cluster mode relies on some middleware to achieve inter-cluster communication and coordination, including:
@@ -49,10 +51,37 @@ When all middleware components use Redis, you can start a single Redis service w
 
 ### Shared Storage
 
-NocoBase needs to use the storage directory to store system-related files. In multi-node mode, you should mount a cloud disk (or NFS) to support shared access across multiple nodes. Otherwise, local storage will not be automatically synchronized, and it will not function properly.
+NocoBase needs to use the `storage` directory to store system-related files, and shared storage is also a required component of cluster deployment. In multi-node mode, you can choose different implementations based on your infrastructure environment, such as cloud disks, NFS, or EFS, to support shared access across multiple nodes. Otherwise, system files will not be synchronized automatically and the application will not work properly.
 
 When deploying with Kubernetes, please refer to the [Kubernetes Deployment: Shared Storage](./kubernetes#shared-storage) section.
 
+#### What is typically stored in the `storage` directory
+
+The contents of the `storage` directory vary depending on the enabled plugins and the deployment method. Based on the current implementation, common contents include:
+
+| Path | Purpose | Usage recommendation |
+| --- | --- | --- |
+| `storage/uploads` | Uploaded files when using local storage mode | In production clusters, prefer object storage such as S3 / OSS / COS |
+| `storage/plugins` | Local plugin packages installed, uploaded, or discovered at runtime | If you rely on local plugins, this directory must be shared; if plugins are built into the image, this dependency can be reduced |
+| `storage/apps/<app>/jwt_secret.dat` | Default token secret generated automatically when `APP_KEY` is not explicitly configured | Do not rely on this file in production; explicitly configure `APP_KEY` instead |
+| `storage/apps/<app>/aes_key.dat` | Default AES key generated automatically when `APP_AES_SECRET_KEY` is not explicitly configured | Do not rely on this file in production; explicitly configure `APP_AES_SECRET_KEY` instead |
+| `storage/environment-variables/<app>/aes_key.dat` | AES key file used in environment-variable plugin scenarios | A read-only mounted key file is recommended |
+| `storage/logs` | Default log directory and some migration logs | It is recommended to integrate with an external logging platform in the future |
+| `storage/tmp` | Temporary files for import, export, migration, etc. | It can be temporary, but if it needs to be reused across nodes, it must be shared, or the operation should be fixed to a single management node |
+| `storage/backups`, `storage/duplicator`, `storage/migration-manager` | Artifacts related to backup, restore, and migration | These should be treated as operations directories, stored persistently, and not modified concurrently across multiple nodes |
+
+The table above is not exhaustive, but it illustrates an important point: `storage` mixes business files, secret files, plugin directories, logs, and operations-related temporary artifacts. Therefore, in cluster deployment, the baseline is usually to persist and share the entire `/app/nocobase/storage`.
+
+#### Storage recommendations
+
+Cluster consistency in NocoBase mainly relies on the database, Redis, message queues, and distributed locks, rather than treating shared file systems as a high-concurrency coordination medium.
+
+Therefore, the following is recommended:
+
+- For high-frequency business files such as attachments, prefer object storage. In production clusters, long-term reliance on local storage is not recommended.
+- Shared storage should mainly be used to host the `storage` directory, rather than as a high-throughput file storage service.
+- Operations such as plugin installation, plugin upgrade, backup, restore, and migration should be performed only after scaling the cluster down to a single node, and the cluster can be scaled out again after completion.
+
 ### Load Balancing
 
 Cluster mode requires a load balancer to distribute requests, as well as for health checks and failover of application instances. This part should be selected and configured according to the team's operational needs.
@@ -61,7 +90,6 @@ Taking a self-hosted Nginx as an example, add the following content to the confi
 
 ```
 upstream myapp {
-    # ip_hash; # Can be used for session persistence. When enabled, requests from the same client are always sent to the same backend server.
     server 172.31.0.1:13000; # Internal node 1
     server 172.31.0.2:13000; # Internal node 2
     server 172.31.0.3:13000; # Internal node 3
@@ -82,10 +110,37 @@ This means that requests are reverse-proxied and distributed to different server
 
 For load balancing middleware provided by other cloud service providers, please refer to the configuration documentation provided by the specific provider.
 
+For high-availability deployments, the following is recommended:
+
+- Run at least 2 application instances within the same cluster, and let the load balancer handle instance failover.
+- The health check of the load balancer should reflect actual application availability, not just whether the port is open.
+- If you need warm standby across availability zones or regions, you would typically deploy multiple independent clusters, and the operations team would be responsible for synchronizing and switching the database, shared storage, and other infrastructure.
+
 ## Environment Variable Configuration
 
 All nodes in the cluster should use the same environment variable configuration. In addition to NocoBase's basic [environment variables](../api/app/env), the following middleware-related environment variables also need to be configured.
 
+### Key Secrets
+
+In addition to the middleware environment variables, all nodes in the cluster should also explicitly configure the same key secrets:
+
+```ini
+APP_KEY=
+APP_AES_SECRET_KEY=
+# Or use a read-only mounted key file
+# APP_AES_SECRET_KEY_PATH=
+```
+
+- `APP_KEY` is used for token / JWT signing. If it is not explicitly configured, the application falls back to the default secret file under `storage`.
+- `APP_AES_SECRET_KEY` is used to decrypt sensitive fields in the database. If it is not explicitly configured, the application also falls back to the default secret file under `storage`.
+- In ephemeral containers or multi-node deployments, relying on automatically generated local secret files can cause tokens to become invalid after restart, or historical encrypted data to become undecryptable.
+
+:::info{title=Tip}
+`APP_AES_SECRET_KEY` must be a 32-byte AES-256 key, represented by 64 hexadecimal characters.
+
+In cloud environments, it is recommended to manage these values centrally through services such as Secrets Manager, SSM Parameter Store, Kubernetes Secret, or a read-only mounted key file.
+:::
+
 ### Multi-core Mode
 
 When the application runs on a multi-core node, you can enable the node's multi-core mode:

package/dist/ai/docs/nocobase/interface-builder/actions/types/js-action.md

@@ -35,7 +35,7 @@ JS Action is used to execute JavaScript when a button is clicked, allowing for c
 ![jsaction-toolbars-20251029](https://static-docs.nocobase.com/jsaction-toolbars-20251029.png)
 
 
-- You can use AI employees to generate/modify scripts: [AI Employee · Nathan: Frontend Engineer](/ai-employees/features/built-in-employee)
+- You can use AI employees to generate/modify scripts: [AI Employee · Nathan: Frontend Engineer](/ai-employees/built-in/)
 
 ## Common Usage (Simplified Examples)
 

package/dist/ai/docs/nocobase/interface-builder/actions/types/js-item.md

@@ -47,7 +47,7 @@ The JS Item runtime injects common capabilities that you can use directly in the
 
 ![](https://static-docs.nocobase.com/JS-Item-03-27-2026_03_35_PM.png)
 
-- You can use AI employees to generate / modify scripts: [AI Employee · Nathan: Frontend Engineer](/ai-employees/features/built-in-employee)
+- You can use AI employees to generate / modify scripts: [AI Employee · Nathan: Frontend Engineer](/ai-employees/built-in/)
 
 ## Common Usage (Simplified Examples)
 

package/dist/ai/docs/nocobase/interface-builder/blocks/other-blocks/js-block.md

@@ -38,7 +38,7 @@ The JS Block's script editor supports syntax highlighting, error hints, and buil
 
 Additionally, you can directly summon the AI employee "Frontend Engineer · Nathan" from the top-right corner of the editor. Nathan can help you write or modify scripts based on the current context. You can then "Apply to editor" with one click and run the code to see the effect. For details, see:
 
-- [AI Employee · Nathan: Frontend Engineer](/ai-employees/features/built-in-employee)
+- [AI Employee · Nathan: Frontend Engineer](/ai-employees/built-in/)
 
 ## Runtime Environment and Security
 

package/dist/ai/docs/nocobase/interface-builder/fields/specific/js-column.md

@@ -37,7 +37,7 @@ The script editor for JS Column supports syntax highlighting, error hints, and b
 
 You can also use an AI Employee to generate code:
 
-- [AI Employee · Nathan: Frontend Engineer](/ai-employees/features/built-in-employee)
+- [AI Employee · Nathan: Frontend Engineer](/ai-employees/built-in/)
 
 ## Common Usage
 

package/dist/ai/docs/nocobase/interface-builder/fields/specific/js-field.md

@@ -58,7 +58,7 @@ The JS Field script editor supports syntax highlighting, error hints, and built-
 
 You can also generate code with the AI Employee:
 
-- [AI Employee · Nathan: Frontend Engineer](/ai-employees/features/built-in-employee)
+- [AI Employee · Nathan: Frontend Engineer](/ai-employees/built-in/)
 
 ## Common Usage
 

package/dist/ai/docs/nocobase/interface-builder/fields/specific/js-item.md

@@ -32,7 +32,7 @@ JS Item is used for "custom items" (not bound to a field) in a form. You can use
 ![jsitem-toolbars-20251029](https://static-docs.nocobase.com/jsitem-toolbars-20251029.png)
 
 
-- Can be used with AI Employee to generate/modify scripts: [AI Employee · Nathan: Frontend Engineer](/ai-employees/features/built-in-employee)
+- Can be used with AI Employee to generate/modify scripts: [AI Employee · Nathan: Frontend Engineer](/ai-employees/built-in/)
 
 ## Common Usage (Simplified Examples)
 

package/dist/ai/docs/nocobase/security/guide.md

@@ -213,6 +213,18 @@ If you need to store sensitive files, it is recommended to use a cloud storage s
 
 ![](https://static-docs.nocobase.com/202501031623549.png)
 
+For local storage or other public storage that can be accessed directly through same-origin application URLs, you should also pay extra attention to the risks introduced by active content files. Files such as `html`, `xhtml`, and `svg` may be parsed and executed directly by the browser. If an attacker can upload such a file and trick a user into opening it, the attacker may use your trusted application domain to host a malicious page or script.
+
+In most cases, we recommend that administrators:
+
+- Prefer private storage, signed URLs, or a separate file domain, so that user-uploaded files are not served directly from the same origin as the main application.
+- Enforce a strict MIME type allowlist for uploads and only allow the file types that are actually required by the business.
+- Be cautious about allowing active content types such as `text/html`, `application/xhtml+xml`, and `image/svg+xml`. Even if the system tries to return these files as downloads, this should not be considered a complete replacement for upload restrictions and origin isolation.
+- Apply consistent security settings to reverse proxies, CDNs, object storage, and any other static file delivery layer, so dangerous files are not returned inline by bypassing application-layer protections.
+- Do not use local/public storage to host untrusted web content. If you really need this capability, use an isolated domain and separately evaluate CSP, download behavior, and access control.
+
+If an administrator explicitly allows dangerous file types to be uploaded, they should assess the resulting phishing, same-origin script execution, and sensitive information leakage risks on their own, and ensure that the Web Server, gateway, CDN, and storage services in the deployment chain enforce consistent restrictions.
+
 
 ### Application Backup
 
@@ -293,4 +305,4 @@ NocoBase provides multiple log types to help users understand the system's runni
 - Request log: API request logs, including accessed URLs, HTTP methods, request parameters, response times, and status codes.
 - System log: Records application running events, including service startup, configuration changes, error messages, and key operations.
 - SQL log: Records database operation statements and their execution times, covering operations such as query, update, insert, and delete.
-- Workflow log: Execution log of the workflow, including execution time, running information, and error information.
+- Workflow log: Execution log of the workflow, including execution time, running information, and error information.

package/dist/ai/docs/nocobase/system-management/localization/index.md

@@ -4,6 +4,8 @@
 
 The Localization Management plugin is used to manage and implement NocoBase's localization resources. It can translate system menus, collections, fields, and all plugins to adapt to the language and culture of specific regions.
 
+If you want to contribute default translations for the system and official plugins to NocoBase, see [Translation Contribution](/get-started/translations).
+
 ## Installation
 
 This plugin is built-in and requires no additional installation.
@@ -36,6 +38,8 @@ After synchronization, the system will list all translatable entries for the cur
 Different modules may have the same original text entries, which need to be translated separately.
 :::
 
+If translations for system or plugin built-in entries are manually changed or overwritten by AI translation, select `Reset system built-in entry translations` during synchronization. After synchronization, the system will overwrite existing built-in entry translations for the current language with translations from the built-in language pack to restore the defaults.
+
 ### Automatically Create Translation Entries
 
 When editing a page, custom text within each block will automatically generate the corresponding i18n entry and simultaneously create the translation for the current language.
@@ -54,6 +58,26 @@ When defining text in code, you need to manually specify the ns (namespace), for
 
 <img src="https://static-docs.nocobase.com/202404202142836.png"/>
 
+### Using AI Translation
+
+Localization Management supports translating entries through the AI Employee Lina. After enabling AI Employees and configuring a model service, you can use AI translation on the Localization Management page to batch generate translations for the current language.
+
+![](https://static-docs.nocobase.com/202605121152196.png)
+
+Supported translation scopes:
+
+- **Full translation**: translate all eligible entries in the current language.
+- **Incremental translation**: only translate entries that do not have translations yet.
+- **Selected translation**: select entries in the table and translate only the selected content.
+
+AI translation creates a background task. You can view progress while the task runs. After completion, translations are written to the corresponding language and should still be reviewed and corrected according to the actual context.
+
+For the complete guide, see [AI Employee - Lina](/ai-employees/built-in/lina).
+
+:::warning{title=Note}
+AI-generated translations may have semantic deviations, inconsistent terminology, or insufficient context understanding. Before publishing, manually review important pages, business terminology, and user-facing copy.
+:::
+
 ### Publishing Translations
 
 After completing the translation, you need to click the "Publish" button to make the changes take effect.
@@ -76,4 +100,4 @@ Synchronize the entries.
 
 Translate and publish.
 
-<img src="https://static-docs.nocobase.com/202404202143135.png"/>
+<img src="https://static-docs.nocobase.com/202404202143135.png"/>