diff --git a/README.md b/README.md
index e5860099f5318355ad91b4556e3225b7d8efc921..2568109b36964501dffcdf002513b4935ba34cd4 100644
--- a/README.md
+++ b/README.md
@@ -179,6 +179,44 @@ oi --agent
 3. 如果系统配置文件不存在或权限不足，工具会显示相应错误信息并退出；
 4. 建议在修改配置前备份原有的配置文件。
 
+## 国际化支持
+
+应用程序内置多语言支持，提供英文和中文界面。
+
+### 支持的语言
+
+- **English (en_US)** - 默认语言
+- **简体中文 (zh_CN)**
+
+### 切换语言
+
+```sh
+# 切换到中文
+oi --locale zh_CN
+
+# 切换到英文
+oi --locale en_US
+```
+
+语言设置会自动保存，下次启动时生效。
+
+### 语言自动检测
+
+应用启动时会按以下优先级确定显示语言：
+
+1. 用户配置文件中的语言设置
+2. 系统环境变量（`LANG`, `LC_ALL` 等）
+3. 默认语言（英语）
+
+如果系统语言为中文，首次运行时会自动使用中文界面。
+
+### 开发者文档
+
+如需为应用程序添加新的翻译或了解国际化实现细节，请参考：
+
+- [国际化快速入门](./docs/development/国际化快速入门.md)
+- [国际化开发指南](./docs/development/国际化开发指南.md)
+
 ## 配置说明
 
 应用程序支持两种后端配置，配置文件会自动保存在 `~/.config/eulerintelli/smart-shell.json`：
diff --git "a/docs/development/\345\233\275\351\231\205\345\214\226\345\274\200\345\217\221\346\214\207\345\215\227.md" "b/docs/development/\345\233\275\351\231\205\345\214\226\345\274\200\345\217\221\346\214\207\345\215\227.md"
new file mode 100644
index 0000000000000000000000000000000000000000..c2ca8b537985f4a0ce49473ce67b9625a0416752
--- /dev/null
+++ "b/docs/development/\345\233\275\351\231\205\345\214\226\345\274\200\345\217\221\346\214\207\345\215\227.md"
@@ -0,0 +1,430 @@
+# 国际化 (i18n) 开发指南
+
+## 概述
+
+本项目使用 Python 标准库 `gettext` 实现国际化功能，支持多语言界面。目前支持的语言：
+
+- **English (en_US)** - 默认语言
+- **简体中文 (zh_CN)**
+
+## 架构设计
+
+### 目录结构
+
+```text
+src/i18n/
+├── __init__.py          # 模块导出
+├── manager.py           # 国际化管理器
+├── tools.py             # 翻译工具脚本
+└── locales/             # 翻译文件目录
+    ├── messages.pot     # 翻译模板文件
+    ├── en_US/
+    │   └── LC_MESSAGES/
+    │       ├── messages.po   # 英文翻译源文件
+    │       └── messages.mo   # 英文翻译二进制文件
+    └── zh_CN/
+        └── LC_MESSAGES/
+            ├── messages.po   # 中文翻译源文件
+            └── messages.mo   # 中文翻译二进制文件
+```
+
+### 核心组件
+
+1. **I18nManager**: 单例模式的国际化管理器，负责：
+   - 加载和管理翻译文件
+   - 检测系统语言环境
+   - 提供翻译函数接口
+
+2. **翻译工具**: 提供命令行工具用于：
+   - 提取源代码中的可翻译字符串
+   - 更新翻译文件
+   - 编译翻译文件为二进制格式
+
+## 使用方法
+
+### 在代码中使用翻译
+
+#### 1. 导入翻译函数
+
+```python
+from i18n.manager import _
+```
+
+#### 2. 标记需要翻译的字符串
+
+```python
+# 简单字符串翻译
+message = _("Hello, world!")
+
+# 带参数的字符串翻译
+greeting = _("Hello, {name}!").format(name="Alice")
+
+# 多行字符串翻译
+help_text = _(
+    "This is a long help text\n"
+    "that spans multiple lines."
+)
+```
+
+#### 3. 复数形式翻译
+
+```python
+from i18n.manager import _n
+
+# 根据数量选择单复数形式
+message = _n(
+    "Found {n} file",
+    "Found {n} files",
+    file_count
+).format(n=file_count)
+```
+
+### 翻译工作流程
+
+#### 1. 提取可翻译字符串
+
+当你添加或修改了代码中的可翻译字符串后，运行：
+
+```bash
+./scripts/tools/i18n-manager.sh extract
+```
+
+这会扫描 `src/` 目录下的所有 Python 文件，提取标记为可翻译的字符串到 `src/i18n/locales/messages.pot`。
+
+#### 2. 更新翻译文件
+
+将新提取的字符串合并到现有的翻译文件：
+
+```bash
+./scripts/tools/i18n-manager.sh update
+```
+
+这会更新所有语言的 `.po` 文件，添加新的字符串，保留已有的翻译。
+
+#### 3. 编辑翻译文件
+
+使用文本编辑器或专业的 PO 编辑器（如 Poedit）编辑翻译文件：
+
+```bash
+# 编辑中文翻译
+vim src/i18n/locales/zh_CN/LC_MESSAGES/messages.po
+```
+
+翻译文件格式示例：
+
+```po
+#: src/main.py
+msgid "Hello, world!"
+msgstr "你好，世界！"
+
+#: src/main.py
+msgid "Found {n} file"
+msgid_plural "Found {n} files"
+msgstr[0] "找到 {n} 个文件"
+```
+
+#### 4. 编译翻译文件
+
+将 `.po` 文件编译为二进制 `.mo` 文件：
+
+```bash
+./scripts/tools/i18n-manager.sh compile
+```
+
+编译后的 `.mo` 文件会被应用程序加载和使用。
+
+#### 完整流程（推荐）
+
+你也可以一次执行所有步骤：
+
+```bash
+./scripts/tools/i18n-manager.sh all
+```
+
+这会依次执行提取、更新和编译操作。
+
+### 添加新语言
+
+要添加对新语言的支持：
+
+1. **在管理器中注册语言**
+
+   编辑 `src/i18n/manager.py`，在 `SUPPORTED_LOCALES` 中添加新语言：
+
+   ```python
+   SUPPORTED_LOCALES = {
+       "en_US": "English",
+       "zh_CN": "简体中文",
+       "ja_JP": "日本語",  # 新增日语
+   }
+   ```
+
+2. **创建翻译文件目录**
+
+   ```bash
+   mkdir -p src/i18n/locales/ja_JP/LC_MESSAGES
+   ```
+
+3. **初始化翻译文件**
+
+   ```bash
+   # 从模板创建新的 PO 文件
+   msginit -i src/i18n/locales/messages.pot \
+           -o src/i18n/locales/ja_JP/LC_MESSAGES/messages.po \
+           -l ja_JP
+   ```
+
+4. **翻译并编译**
+
+   编辑 `messages.po` 文件添加翻译，然后运行：
+
+   ```bash
+   ./scripts/tools/i18n-manager.sh compile
+   ```
+
+## 配置管理
+
+### 语言设置持久化
+
+用户选择的语言会保存在配置文件中：
+
+```json
+{
+  "locale": "zh_CN"
+}
+```
+
+配置文件位置：
+
+- 用户配置: `~/.config/eulerintelli/smart-shell.json`
+- 全局配置: `/etc/openEuler-Intelligence/smart-shell-template.json`
+
+### 命令行设置语言
+
+```bash
+# 设置为中文
+oi --locale zh_CN
+
+# 设置为英文
+oi --locale en_US
+
+# 查看帮助（会使用当前配置的语言）
+oi --help
+```
+
+### 语言自动检测
+
+应用启动时会按以下优先级确定语言：
+
+1. 用户配置文件中的设置
+2. 系统环境变量（`LANG`, `LC_ALL` 等）
+3. 默认语言（英语）
+
+## 最佳实践
+
+### 1. 字符串提取
+
+✅ **推荐做法：**
+
+```python
+# 使用 _() 函数包裹需要翻译的字符串
+message = _("Operation completed successfully")
+
+# 将参数化的内容单独提取
+name = user.name
+greeting = _("Welcome, {name}!").format(name=name)
+```
+
+❌ **避免：**
+
+```python
+# 不要在 _() 中进行复杂计算
+message = _(f"User {user.name} logged in")  # 这样无法提取
+
+# 不要翻译动态内容
+message = _(user_input)  # 用户输入不应翻译
+```
+
+### 2. 格式化字符串
+
+使用命名参数而非位置参数：
+
+✅ **推荐：**
+
+```python
+_("Found {count} items in {directory}").format(
+    count=item_count,
+    directory=dir_name
+)
+```
+
+❌ **避免：**
+
+```python
+_("Found {} items in {}").format(item_count, dir_name)
+# 不同语言的语序可能不同
+```
+
+### 3. 复数形式
+
+对于涉及数量的字符串，使用复数形式：
+
+✅ **推荐：**
+
+```python
+message = _n(
+    "{n} file deleted",
+    "{n} files deleted",
+    count
+).format(n=count)
+```
+
+❌ **避免：**
+
+```python
+# 不要用条件判断构造复数形式
+if count == 1:
+    message = _("1 file deleted")
+else:
+    message = _("{n} files deleted").format(n=count)
+```
+
+### 4. 上下文信息
+
+为翻译人员提供充足的上下文：
+
+```python
+# 在代码中添加注释，说明字符串的使用场景
+# Translators: This message is shown when the user successfully logs in
+message = _("Login successful")
+```
+
+### 5. 避免拼接字符串
+
+❌ **避免：**
+
+```python
+# 不同语言的语序不同，拼接会导致问题
+message = _("Hello") + ", " + username + "!"
+```
+
+✅ **推荐：**
+
+```python
+message = _("Hello, {name}!").format(name=username)
+```
+
+## 测试
+
+### 测试不同语言
+
+```bash
+# 测试英文
+oi --locale en_US
+oi --help
+
+# 测试中文
+oi --locale zh_CN
+oi --help
+
+# 测试语言切换
+oi --locale zh_CN
+oi --help  # 应显示中文
+
+oi --locale en_US
+oi --help  # 应显示英文
+```
+
+### 验证翻译完整性
+
+```bash
+# 检查未翻译的字符串
+msgfmt --check --statistics src/i18n/locales/zh_CN/LC_MESSAGES/messages.po
+```
+
+## 常见问题
+
+### 1. 翻译不生效
+
+**原因：** 可能是 `.mo` 文件未编译或过时
+
+**解决：**
+
+```bash
+./scripts/tools/i18n-manager.sh compile
+```
+
+### 2. 新字符串未出现在 PO 文件中
+
+**原因：** 未运行提取和更新命令
+
+**解决：**
+
+```bash
+./scripts/tools/i18n-manager.sh extract
+./scripts/tools/i18n-manager.sh update
+```
+
+### 3. 系统语言检测不准确
+
+**原因：** 系统环境变量未正确设置
+
+**解决：** 手动设置语言
+
+```bash
+oi --locale zh_CN
+```
+
+### 4. 工具命令找不到
+
+**原因：** gettext 工具未安装
+
+**解决：**
+
+```bash
+# macOS
+brew install gettext
+
+# Ubuntu/Debian
+sudo apt-get install gettext
+
+# Fedora/RHEL/openEuler
+sudo dnf install gettext
+```
+
+## 开发工具
+
+### 推荐的 PO 编辑器
+
+- **Poedit**: <https://poedit.net/> (跨平台，图形界面)
+- **Lokalize**: KDE 的翻译工具
+- **Gtranslator**: GNOME 的翻译工具
+- **VS Code**: 使用 gettext 扩展
+
+### 在线翻译资源
+
+- Google Translate API
+- DeepL API
+- 机器翻译仅作参考，最终需要人工校对
+
+## 参考资料
+
+- [Python gettext 官方文档](https://docs.python.org/3/library/gettext.html)
+- GNU gettext 手册：可通过命令 `info gettext` 查看完整文档
+- PO 文件格式：可通过命令 `man msgfmt` 或 `info gettext` 查看详细说明
+
+## 贡献翻译
+
+欢迎贡献新的语言翻译或改进现有翻译！
+
+1. Fork 项目仓库
+2. 按照"添加新语言"步骤添加翻译
+3. 测试翻译效果
+4. 提交 Pull Request
+
+翻译时请注意：
+
+- 保持术语一致性
+- 尊重目标语言的习惯用法
+- 保留格式化占位符（如 `{name}`）
+- 测试不同长度的翻译文本在界面上的显示效果
diff --git "a/docs/development/\345\233\275\351\231\205\345\214\226\345\277\253\351\200\237\345\205\245\351\227\250.md" "b/docs/development/\345\233\275\351\231\205\345\214\226\345\277\253\351\200\237\345\205\245\351\227\250.md"
new file mode 100644
index 0000000000000000000000000000000000000000..3d8459d650a270c7bfd769e6d78dcd9c966dcccd
--- /dev/null
+++ "b/docs/development/\345\233\275\351\231\205\345\214\226\345\277\253\351\200\237\345\205\245\351\227\250.md"
@@ -0,0 +1,79 @@
+# 国际化快速入门
+
+## 用户使用
+
+### 查看支持的语言
+
+```bash
+oi --help
+```
+
+在 "Language Settings" 部分可以看到支持的语言列表。
+
+### 切换语言
+
+```bash
+# 切换到中文
+oi --locale zh_CN
+
+# 切换到英文
+oi --locale en_US
+```
+
+语言设置会被保存，下次启动时自动使用。
+
+### 查看帮助（当前语言）
+
+```bash
+oi --help
+```
+
+## 开发者使用
+
+### 在代码中添加翻译
+
+```python
+from i18n.manager import _
+
+# 简单翻译
+message = _("Hello, world!")
+
+# 带参数的翻译
+greeting = _("Hello, {name}!").format(name=username)
+```
+
+### 翻译工作流
+
+```bash
+# 完整流程（推荐）
+./scripts/tools/i18n-manager.sh all
+
+# 或分步执行
+./scripts/tools/i18n-manager.sh extract   # 提取字符串
+./scripts/tools/i18n-manager.sh update    # 更新翻译文件
+# 编辑 .po 文件...
+./scripts/tools/i18n-manager.sh compile   # 编译翻译
+```
+
+### 测试翻译
+
+```bash
+# 测试中文
+oi --locale zh_CN
+oi --help
+
+# 测试英文
+oi --locale en_US
+oi --help
+```
+
+## 详细文档
+
+完整的开发指南请参考：[docs/development/国际化开发指南.md](./docs/development/国际化开发指南.md)
+
+包括：
+
+- 架构设计详解
+- 添加新语言的步骤
+- 最佳实践和注意事项
+- 常见问题解决方案