feat: add language detector & update Chinese README (#127)

* docs: update Chinese README * feat: add language detector
2025-12-24 06:58:48 -05:00 · 2025-09-06 19:39:14 +08:00
parent 8797be9f9e
commit e18e51fb7f
4 changed files with 134 additions and 122 deletions
--- a/docs/README.cn.md
+++ b/docs/README.cn.md
@@ -11,52 +11,6 @@ FossFLOW 是一款功能强大的、开源的渐进式 Web 应用（PWA），专
 - **📝 [FOSSFLOW_TODO.md](https://github.com/stan-smith/FossFLOW/blob/master/ISOFLOW_TODO.md)** - 当前的问题和路线图，包含代码库映射，大多数问题都与 isoflow 库本身有关。
 - **🤝 [CONTRIBUTORS.md](https://github.com/stan-smith/FossFLOW/blob/master/CONTRIBUTORS.md)** - 如何为项目做出贡献。

-## 近期更新 (2025年8月)
-
-### 连接器工具改进
- **点击创建** - 新的默认模式：点击第一个节点，再点击第二个节点即可连接
- **拖拽模式选项** - 原始的拖拽功能仍可通过设置使用
- **模式切换** - 在 Settings → Connectors 标签页中切换点击和拖拽模式
- **更高可靠性** - 点击模式让连接创建更加可预测
-
-### 自定义图标导入
- **导入您的图标** - 上传自定义图标（PNG, JPG, SVG）并在图表中使用
- **自动缩放** - 图标会自动缩放至统一尺寸，确保专业外观
- **等距/平面切换** - 选择导入的图标是显示为 3D 等距效果还是平面 2D 效果
- **智能持久化** - 自定义图标会随图表一同保存，并在所有存储方式中有效
- **图标资源** - 寻找免费图标：
-  - [Iconify Icon Sets](https://icon-sets.iconify.design/) - 数千个免费 SVG 图标
-  - [Flaticon Isometric Icons](https://www.flaticon.com/free-icons/isometric) - 高质量的等距图标包
-
-### 服务器存储支持
- **持久化存储** - 图表保存到服务器文件系统，在浏览器会话之间持久化
- **多设备访问** - 使用 Docker 部署时，可从任何设备访问您的图表
- **自动检测** - 当可用时，界面会自动显示服务器存储选项
- **防覆盖保护** - 使用重复名称保存时会弹出确认对话框
- **Docker 集成** - 在 Docker 部署中默认启用服务器存储
-
-### 交互功能增强
- **可配置快捷键** - 三种配置文件（QWERTY, SMNRCT, 无）用于工具选择，并配有视觉指示器
- **高级平移控制** - 多种平移方式，包括空白区域拖拽、中键/右键点击、修饰键（Ctrl/Alt）以及键盘导航（方向键/WASD/IJKL）
- **切换连接器箭头** - 可选择显示或隐藏单个连接器上的箭头
- **持久化工具选择** - 创建连接后，连接器工具保持激活状态
- **设置对话框** - 集中配置快捷键和平移控制
-
-### Docker & CI/CD 改进
- **自动化 Docker 构建** - 通过 GitHub Actions 工作流，在提交时自动部署到 Docker Hub
- **多架构支持** - 同时支持 `linux/amd64` 和 `linux/arm64` 架构的 Docker 镜像
- **预构建镜像** - 可在 `stnsmith/fossflow:latest` 获取
-
-### Monorepo 架构
- **单一代码库** 用于库和应用程序
- **NPM Workspaces** 简化依赖管理
- **统一构建流程** 在根目录使用 `npm run build`
-
-### UI 修复
- 修复了 Quill 编辑器工具栏图标显示问题
- 解决了上下文菜单中的 React key 警告
- 改进了 Markdown 编辑器样式
-
 ## 功能

 - 🎨 **等距图表** - 创建令人惊叹的 3D 风格技术图表
@@ -66,29 +20,11 @@ FossFLOW 是一款功能强大的、开源的渐进式 Web 应用（PWA），专
 - 📤 **导入/导出** - 以 JSON 文件形式分享图表
 - 🎯 **会话存储** - 快速保存，无需对话框
 - 🌐 **离线支持** - 无需网络连接即可工作
- 🗄️ **服务器存储** - 使用 Docker 时可选的持久化存储（默认启用）

 ## 在线试用

 访问 https://stan-smith.github.io/FossFLOW/

-## 🐳 使用 Docker 快速部署
-
-```bash
-# 使用 Docker Compose（推荐 - 包含持久化存储）
-docker compose up
-
-# 或者直接从 Docker Hub 运行，并带有持久化存储
-docker run -p 80:80 -v $(pwd)/diagrams:/data/diagrams stnsmith/fossflow:latest
-```
-
-在 Docker 中默认启用服务器存储。您的图表将保存到主机上的 `./diagrams` 目录。
-
-要禁用服务器存储，请设置 `ENABLE_SERVER_STORAGE=false`：
-```bash
-docker run -p 80:80 -e ENABLE_SERVER_STORAGE=false stnsmith/fossflow:latest
-```
-
 ## 快速开始 (本地开发)

 ```bash
@@ -99,78 +35,122 @@ cd FossFLOW
 # 安装依赖
 npm install

-# 构建库（首次需要）
-npm run build:lib
-
 # 启动开发服务器
-npm run dev
+npm start
 ```

 在浏览器中打开 [http://localhost:3000](http://localhost:3000)。

-## Monorepo 结构
-
-这是一个包含两个包的 monorepo：
-
- `packages/fossflow-lib` - 用于绘制网络图的 React 组件库（使用 Webpack 构建）
- `packages/fossflow-app` - 用于创建等距图表的渐进式 Web 应用（使用 RSBuild 构建）
-
-### 开发命令
-
-```bash
-# 开发
-npm run dev          # 启动应用开发服务器
-npm run dev:lib      # 库开发的监听模式
-
-# 构建
-npm run build        # 构建库和应用
-npm run build:lib    # 仅构建库
-npm run build:app    # 仅构建应用
-
-# 测试和代码检查
-npm test             # 运行测试
-npm run lint         # 检查代码规范错误
-
-# 发布
-npm run publish:lib  # 将库发布到 npm
-```
-
 ## 使用方法

 ### 创建图表

 1. **添加项目**：
-   - 按下右上角菜单的 "+" 按钮，组件库将出现在左侧
-   - 从库中拖放组件到画布上
-   - 或者右键点击网格并选择 "Add node"
+   - 按下右上角菜单的 "+" 按钮，组件库将出现在左侧。从库中拖放组件到画布上。
+   - 或者右键点击网格并选择 "Add node"，然后点击新创建的节点并从左侧菜单自定义它。
+2. **连接项目**：使用连接器显示组件之间的关系。
+3. **自定义**：更改项目的颜色、标签和属性。
+4. **导航**：平移和缩放以处理不同区域。

-2. **连接项目**：
-   - 选择连接器工具（按 'C' 键或点击连接器图标）
-   - **点击模式**（默认）：点击第一个节点，再点击第二个节点
-   - **拖拽模式**（可选）：点击并从第一个节点拖拽到第二个节点
-   - 在 Settings → Connectors 标签页中切换模式
+### 保存您的工作

-3. **保存您的工作**：
-   - **快速保存** - 保存到浏览器会话
-   - **导出** - 下载为 JSON 文件
-   - **导入** - 从 JSON 文件加载
+- **自动保存**：图表每 5 秒自动保存到浏览器存储。
+- **快速保存**：点击 "Quick Save (Session)" 进行即时保存，无需弹窗。
+- **另存为**：使用 "Save New" 创建具有不同名称的副本。

-### 存储选项
+### 管理图表

- **会话存储**：在浏览器关闭时清除的临时保存
- **导出/导入**：以 JSON 文件形式永久存储
- **自动保存**：每 5 秒自动将更改保存到会话中
+- **加载**：点击 "Load" 查看所有已保存的图表。
+- **导入**：从他人分享的 JSON 文件加载图表。
+- **导出**：将图表下载为 JSON 文件以分享或备份。
+- **存储**：使用 "Storage Manager" 管理浏览器存储空间。
+
+### 键盘快捷键
+
+- `Delete` - 删除选中项
+- 鼠标滚轮 - 放大/缩小
+- 点击并拖动 - 平移画布
+- ***新增*** Ctrl+Z 撤销，Ctrl+Y 重做
+
+## 生产环境构建
+
+```bash
+# 创建优化后的生产环境构建
+npm run build
+
+# 本地运行生产环境构建
+npx serve -s build
+```
+
+`build` 文件夹包含所有部署所需的文件。
+
+如果需要将应用部署到自定义路径（例如非根路径），请使用以下命令：
+```bash
+# 为指定路径创建优化后的生产环境构建
+PUBLIC_URL="https://mydomain.tld/path/to/app" npm run build
+```
+这会将定义的 `PUBLIC_URL` 添加为所有静态文件链接的前缀。
+
+## 部署
+
+### 静态托管
+
+将 `build` 文件夹部署到任何静态托管服务：
+- GitHub Pages
+- Netlify
+- Vercel
+- AWS S3
+- 任何 Web 服务器
+
+### 重要说明
+
+1. **需要 HTTPS**：PWA 功能需要 HTTPS（localhost 除外）
+2. **浏览器存储**：图表保存在浏览器的 localStorage 中（约 5-10MB 限制）
+3. **备份**：定期将重要图表导出为 JSON 文件
+
+## 浏览器支持
+
+- Chrome/Edge（推荐）✅
+- Firefox ✅
+- Safari ✅
+- 支持 PWA 的移动浏览器 ✅
+
+## 问题排查
+
+### 存储已满
+- 使用存储管理器释放空间
+- 导出并删除旧图表
+- 清除浏览器数据（最后手段 - 会删除所有图表）
+
+### 无法安装 PWA
+- 确保使用 HTTPS
+- 尝试使用 Chrome 或 Edge 浏览器
+- 检查是否已安装
+
+### 图表丢失
+- 检查浏览器的 localStorage
+- 查找自动保存的版本
+- 始终导出重要工作
+
+## 技术栈
+
+- **React** - UI 框架
+- **TypeScript** - 类型安全
+- **Isoflow** - 等距图表引擎
+- **PWA** - 离线优先的 Web 应用

 ## 贡献

-我们欢迎您的贡献！请参阅 [CONTRIBUTORS.md](../CONTRIBUTORS.md) 了解指南。
-
-## 文档
-
- [ISOFLOW_ENCYCLOPEDIA.md](../ISOFLOW_ENCYCLOPEDIA.md) - 代码库的综合指南
- [ISOFLOW_TODO.md](../ISOFLOW_TODO.md) - 当前问题和路线图
- [CONTRIBUTORS.md](../CONTRIBUTORS.md) - 贡献指南
+欢迎贡献！请随时提交 Pull Request。

 ## 许可证

-MIT
+Isoflow 使用 MIT 许可证发布。
+
+FossFLOW 使用 Unlicense 许可证发布，您可以随意使用。
+
+## 鸣谢
+
+基于 [Isoflow](https://github.com/markmanx/isoflow) 库构建。
+
+x0z.co
--- a/package-lock.json
+++ b/package-lock.json
@@ -17,6 +17,7 @@
        "@types/node": "^18.19.0",
        "@types/react": "^18.3.1",
        "@types/react-dom": "^18.3.0",
+        "cross-env": "^10.0.0",
        "typescript": "^5.3.3"
      },
      "engines": {
@@ -2034,6 +2035,13 @@
      "resolved": "https://registry.npmjs.org/@emotion/weak-memoize/-/weak-memoize-0.4.0.tgz",
      "integrity": "sha512-snKqtPW01tN0ui7yu9rGv69aJXr/a/Ywvl11sUjNtEcRc+ng/mQriFL0wLXMef74iHa/EkftbDzU9F8iFbH+zg=="
    },
+    "node_modules/@epic-web/invariant": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/@epic-web/invariant/-/invariant-1.0.0.tgz",
+      "integrity": "sha512-lrTPqgvfFQtR/eY/qkIzp98OGdNJu0m5ji3q/nJI8v3SXkRKEnWiOxMmbvcSoAIzv/cGiuvRy57k4suKQSAdwA==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/@eslint-community/eslint-utils": {
      "version": "4.7.0",
      "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.7.0.tgz",
@@ -5377,6 +5385,24 @@
        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
      }
    },
+    "node_modules/cross-env": {
+      "version": "10.0.0",
+      "resolved": "https://registry.npmjs.org/cross-env/-/cross-env-10.0.0.tgz",
+      "integrity": "sha512-aU8qlEK/nHYtVuN4p7UQgAwVljzMg8hB4YK5ThRqD2l/ziSnryncPNn7bMLt5cFYsKVKBh8HqLqyCoTupEUu7Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@epic-web/invariant": "^1.0.0",
+        "cross-spawn": "^7.0.6"
+      },
+      "bin": {
+        "cross-env": "dist/bin/cross-env.js",
+        "cross-env-shell": "dist/bin/cross-env-shell.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
    "node_modules/cross-fetch": {
      "version": "4.0.0",
      "resolved": "https://registry.npmmirror.com/cross-fetch/-/cross-fetch-4.0.0.tgz",
--- a/package.json
+++ b/package.json
@@ -8,6 +8,7 @@
  ],
  "scripts": {
    "dev": "NODE_ENV=development npm run start --workspace=packages/fossflow-app",
+    "dev:win": "cross-env NODE_ENV=development npm run start --workspace=packages/fossflow-app",
    "dev:lib": "npm run dev --workspace=packages/fossflow-lib",
    "dev:backend": "npm run dev --workspace=packages/fossflow-backend",
    "build": "npm run build:lib && npm run build:app",
@@ -24,6 +25,7 @@
    "@types/node": "^18.19.0",
    "@types/react": "^18.3.1",
    "@types/react-dom": "^18.3.0",
+    "cross-env": "^10.0.0",
    "typescript": "^5.3.3"
  },
  "engines": {
--- a/packages/fossflow-app/src/i18n.ts
+++ b/packages/fossflow-app/src/i18n.ts
@@ -1,12 +1,11 @@
 import i18n from 'i18next';
 import { initReactI18next } from 'react-i18next';
 import Backend from 'i18next-http-backend';
-
-// future: add language detector
-// import LanguageDetector from 'i18next-browser-languagedetector';
+import LanguageDetector from 'i18next-browser-languagedetector';

 i18n
    .use(Backend)
+    .use(LanguageDetector)
    .use(initReactI18next)
    .init({
        fallbackLng: 'en-US',
@@ -18,6 +17,11 @@ i18n
        backend: {
            loadPath: '/i18n/{{ns}}/{{lng}}.json'
        },
+        detection: {
+            // configure detection options
+            order: ['navigator', 'htmlTag', 'querystring', 'cookie', 'localStorage'],
+            caches: ['localStorage', 'cookie'],
+        }
    });

 export const supportedLanguages = [