From 5af8541363790085cfe211f8cbd3f574429ddbf6 Mon Sep 17 00:00:00 2001
From: "LINING-PC\\lining" <lining820125@163.com>
Date: Tue, 23 Dec 2025 12:20:45 +0800
Subject: [PATCH] v1.6.2 - bugfix I18n

---
 CHANGELOG.md                          |   6 +
 README-EN.md                          | 214 ++++++++++++++++++++------
 README.md                             | 212 ++++++++++++++++++++-----
 demo/version-history.json             |  10 ++
 npm-demo/src/components/GanttTest.vue |  20 ++-
 package.json                          |   2 +-
 src/composables/useI18n.ts            |  26 +++-
 src/index.ts                          |   3 +
 8 files changed, 400 insertions(+), 93 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index be1dc89..978e24b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.2] - 2025-12-23
+
+### Fixed
+- 🔧 修复：I18n外部使用的问题
+- 🔧 Fixed: Issue with using I18n externally
+
 ## [1.6.1] - 2025-12-15
 
 ### Fixed
diff --git a/README-EN.md b/README-EN.md
index e4d0c42..793d3c2 100644
--- a/README-EN.md
+++ b/README-EN.md
@@ -2026,7 +2026,7 @@ const handleLanguageChange = (lang: 'zh-CN' | 'en-US') => {
 
 #### Custom Translations
 
-Override or extend default translations via `localeMessages` prop:
+Pass custom multilingual text via the `localeMessages` prop, which will be automatically merged into the default translations:
 
 ```vue
 <template>
@@ -2037,7 +2037,7 @@ Override or extend default translations via `localeMessages` prop:
 const customMessages = {
   "zh-CN": {
     // Task list related
-    name: 'Task Name (Custom)',
+    taskName: 'Task Name (Custom)',
     startDate: 'Start Date',
     endDate: 'End Date',
     duration: 'Duration',
@@ -2045,55 +2045,183 @@ const customMessages = {
     predecessor: 'Predecessors',
     assignee: 'Assignee',
     estimatedHours: 'Estimated Hours',
-    actualHours: 'Actual Hours'
-
-    // Toolbar related
-    addTask: 'New Task',
-    addMilestone: 'New Milestone',
-    today: 'Today',
-    exportCsv: 'Export CSV',
-    exportPdf: 'Export PDF',
-    fullscreen: 'Fullscreen',
-    exitFullscreen: 'Exit Fullscreen',
-    language: 'Language',
-    theme: 'Theme',
-    expandAll: 'Expand All',
-    collapseAll: 'Collapse All'
-
-    // Internal Task editor related
-    title: 'Task Details',
-    titleEdit: 'Edit Task',
-    titleNew: 'New Task',
-    name: 'Task Name',
-    startDate: 'Start Date',
-    endDate: 'End Date',
-    assignee: 'Assignee',
-    predecessor: 'Predecessors',
-    description: 'Description',
-    estimatedHours: 'Estimated Hours',
     actualHours: 'Actual Hours',
-    progress: 'Progress',
-    save: 'Save',
-    cancel: 'Cancel',
-    delete: 'Delete'
 
-    // Other texts
-    days: 'days',
-    hours: 'hours',
-    overtime: 'overtime',
-    overdue: 'overdue',
-    // ... More custom translations
+    // Custom fields (supports nested structure)
+    department: 'Department',
+    status: 'Status',
+    gantt: {
+      planEndDate: 'Plan End Date',
+      planStartDate: 'Plan Start Date'
+    }
   },
-  "en-US": {......}
+  "en-US": {
+    department: 'Department',
+    status: 'Status',
+    gantt: {
+      planEndDate: 'Plan End Date',
+      planStartDate: 'Plan Start Date'
+    }
+  }
 }
 </script>
 ```
 
-> **💡 Tip**：
+> **💡 Tip**:
 >
-> - `localeMessages` adopts **deep merge** strategy, only need to pass fields that need to be overridden
-> - supports nested objects, like `taskList.name`, `toolbar.addTask`, etc.
-> - For complete translation keys, please refer to built-in `messages['zh-CN']` object in component
+> - `localeMessages` uses a **deep merge** strategy, only pass fields that need to be overridden or added
+> - Supports nested object structures, such as `gantt.planEndDate`
+> - For complete built-in translation keys, please refer to `useI18n.ts` in the component source code
+
+##### Using Translations in Custom Slots
+
+The component exports the `useI18n` composable, which can be used in custom slots to access translation text. It supports two access methods:
+
+**Method 1: Reactive Access (`t.field`)**
+
+Access translation text directly through a reactive object, with concise syntax, suitable for use in templates:
+
+```vue
+<script setup>
+import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
+
+const { t } = useI18n()
+
+const customMessages = {
+  'zh-CN': {
+    department: 'Department'
+  }
+}
+</script>
+
+<template>
+  <GanttChart :tasks="tasks" :locale-messages="customMessages" />
+  
+  <!-- Reactive access: directly through the t object -->
+  <TaskListColumn prop="startDate" label="Start Date" width="250">
+    <template #header>
+      <strong style="color: #1890ff;">{{ t.department }}</strong>
+    </template>
+  </TaskListColumn>
+</template>
+```
+
+**Method 2: Function Access (`getTranslation()`)**
+
+Supports nested keys and default values, suitable for accessing deep structures or dynamic keys:
+
+```vue
+<script setup>
+import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
+
+const { getTranslation } = useI18n()
+
+const customMessages = {
+  'en-US': {
+    gantt: {
+      planEndDate: 'Plan End Date'
+    }
+  }
+}
+</script>
+
+<template>
+  <GanttChart :tasks="tasks" :locale-messages="customMessages" />
+  
+  <!-- Function access: supports nested keys and default values -->
+  <TaskListColumn prop="endDate" :label="getTranslation('gantt.planEndDate')" width="250" />
+</template>
+```
+
+**Complete Example (with Language Switching):**
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
+
+// Custom multilingual configuration
+const customMessages = {
+  'zh-CN': {
+    department: '部门',
+    gantt: {
+      planEndDate: '计划结束时间'
+    }
+  },
+  'en-US': {
+    department: 'Department',
+    gantt: {
+      planEndDate: 'Plan End Date'
+    }
+  }
+}
+
+// Use useI18n to access translations
+const { t, getTranslation, locale, setLocale } = useI18n()
+const tasks = ref([...])
+
+// Language switching
+const switchLanguage = () => {
+  setLocale(locale.value === 'zh-CN' ? 'en-US' : 'zh-CN')
+}
+</script>
+
+<template>
+  <button @click="switchLanguage">Switch Language</button>
+  
+  <GanttChart :tasks="tasks" :locale-messages="customMessages" />
+  
+  <!-- Reactive access: directly through the t object -->
+  <TaskListColumn prop="startDate" label="Start Date" width="250">
+    <template #header>
+      <strong style="color: #1890ff;">{{ t.department }}</strong>
+    </template>
+  </TaskListColumn>
+  
+  <!-- Function access: supports nested keys and default values -->
+  <TaskListColumn prop="endDate" :label="getTranslation('gantt.planEndDate')" width="250" />
+</template>
+```
+
+**`useI18n` API Reference:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `t` | `Ref<object>` | Reactive translation object, access via `t.key` or `t.nested.key` |
+| `getTranslation(key, defaultValue?)` | `Function` | Function-based access to translation text<br>• `key`: Translation key, supports nested paths (e.g., `'gantt.planEndDate'`)<br>• `defaultValue`: Optional, default value returned when translation is not found<br>• Returns: Translation text, default value, or the key itself |
+| `formatTranslation(key, params)` | `Function` | Format translation text with parameters<br>• `key`: Translation key<br>• `params`: Parameter object, e.g., `{ name: 'Task1' }`<br>• Returns: Text with placeholders replaced (e.g., `'Task {name}'` → `'Task Task1'`) |
+| `locale` | `Ref<string>` | Current language (`'zh-CN'` or `'en-US'`) |
+| `setLocale(locale)` | `Function` | Switch language, automatically updates all components using `useI18n` |
+| `formatYearMonth(year, month)` | `Function` | Format year-month display<br>• Chinese: `formatYearMonth(2024, 3)` → `'2024年03月'`<br>• English: `formatYearMonth(2024, 3)` → `'2024/03'` |
+| `formatMonth(month)` | `Function` | Format month display<br>• Chinese: `formatMonth(3)` → `'3月'`<br>• English: `formatMonth(3)` → `'03'` |
+
+**Usage Examples:**
+
+```vue
+<script setup>
+import { useI18n } from 'jordium-gantt-vue3'
+
+const { t, getTranslation, formatTranslation, formatYearMonth, formatMonth } = useI18n()
+
+// 1. Basic access
+const text1 = t.taskName  // 'Task Name'
+const text2 = getTranslation('gantt.planEndDate', 'Plan End')  // 'Plan End Date' or default value
+
+// 2. Translation with parameters
+const message = formatTranslation('taskNotFound', { id: '123' })  // 'Task not found for update, ID: 123'
+
+// 3. Date formatting
+const yearMonth = formatYearMonth(2024, 3)  // '2024年03月' (zh-CN) or '2024/03' (en-US)
+const month = formatMonth(3)  // '3月' (zh-CN) or '03' (en-US)
+</script>
+```
+
+> **💡 Usage Tips**:
+>
+> - **Reactive access** (`t.key`): Concise syntax, suitable for direct use in templates
+> - **Function access** (`getTranslation('nested.key', 'default')`): Supports nested keys and default values, suitable for accessing deep structures
+> - Pass custom translations via the `localeMessages` prop, then access via `useI18n` to translate
+> - Language switching is implemented via `setLocale()`, all components will automatically respond to updates
 
 ### Custom Extensions
 
diff --git a/README.md b/README.md
index d972dc4..5f13b00 100644
--- a/README.md
+++ b/README.md
@@ -2017,7 +2017,7 @@ const handleLanguageChange = (lang: 'zh-CN' | 'en-US') => {
 
 #### 自定义翻译
 
-通过 `localeMessages` 属性覆盖或扩展默认翻译：
+通过 `localeMessages` 属性传入自定义多语言文本，组件内部会自动合并到默认翻译中：
 
 ```vue
 <template>
@@ -2028,7 +2028,7 @@ const handleLanguageChange = (lang: 'zh-CN' | 'en-US') => {
 const customMessages = {
   "zh-CN": {
     // 任务列表相关
-    name: '任务名称（自定义）',
+    taskName: '任务名称（自定义）',
     startDate: '开始日期',
     endDate: '结束日期',
     duration: '工期',
@@ -2036,55 +2036,183 @@ const customMessages = {
     predecessor: '前置任务',
     assignee: '负责人',
     estimatedHours: '预估工时',
-    actualHours: '实际工时'
-
-    // 工具栏相关
-    addTask: '新建任务',
-    addMilestone: '新建里程碑',
-    today: '今天',
-    exportCsv: '导出 CSV',
-    exportPdf: '导出 PDF',
-    fullscreen: '全屏',
-    exitFullscreen: '退出全屏',
-    language: '语言',
-    theme: '主题',
-    expandAll: '全部展开',
-    collapseAll: '全部折叠'
-
-    // 内置任务编辑器相关
-    title: '任务详情',
-    titleEdit: '编辑任务',
-    titleNew: '新建任务',
-    name: '任务名称',
-    startDate: '开始日期',
-    endDate: '结束日期',
-    assignee: '负责人',
-    predecessor: '前置任务',
-    description: '描述',
-    estimatedHours: '预估工时',
     actualHours: '实际工时',
-    progress: '进度',
-    save: '保存',
-    cancel: '取消',
-    delete: '删除'
 
-    // 其他文本
-    days: '天',
-    hours: '小时',
-    overtime: '超时',
-    overdue: '逾期',
-    // ... 更多自定义翻译
+    // 自定义字段（支持嵌套结构）
+    department: '部门',
+    status: '状态',
+    gantt: {
+      planEndDate: '计划结束时间',
+      planStartDate: '计划开始时间'
+    }
   },
-  "en-US": {......}
+  "en-US": {
+    department: 'Department',
+    status: 'Status',
+    gantt: {
+      planEndDate: 'Plan End Date',
+      planStartDate: 'Plan Start Date'
+    }
+  }
 }
 </script>
 ```
 
 > **💡 提示**：
 >
-> - `localeMessages` 采用**深度合并**策略，只需传递需要覆盖的字段即可
-> - 支持嵌套对象，如 `taskList.name`、`toolbar.addTask` 等
-> - 完整的翻译键请参考组件内置的 `messages['zh-CN']` 对象
+> - `localeMessages` 采用**深度合并**策略，只需传递需要覆盖或新增的字段即可
+> - 支持嵌套对象结构，如 `gantt.planEndDate`
+> - 完整的内置翻译键请参考组件源码中的 `useI18n.ts`
+
+##### 在自定义插槽中使用翻译
+
+组件导出了 `useI18n` composable，可在自定义插槽中访问翻译文本，支持两种访问方式：
+
+**方式一：引用式访问（`t.field`）**
+
+通过响应式对象直接访问翻译文本，语法简洁，适合模板中使用：
+
+```vue
+<script setup>
+import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
+
+const { t } = useI18n()
+
+const customMessages = {
+  'zh-CN': {
+    department: '部门'
+  }
+}
+</script>
+
+<template>
+  <GanttChart :tasks="tasks" :locale-messages="customMessages" />
+  
+  <!-- 引用式：直接通过 t 对象访问 -->
+  <TaskListColumn prop="startDate" label="开始时间" width="250">
+    <template #header>
+      <strong style="color: #1890ff;">{{ t.department }}</strong>
+    </template>
+  </TaskListColumn>
+</template>
+```
+
+**方式二：函数式访问（`getTranslation()`）**
+
+支持嵌套键和默认值，适合访问深层结构或动态键：
+
+```vue
+<script setup>
+import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
+
+const { getTranslation } = useI18n()
+
+const customMessages = {
+  'zh-CN': {
+    gantt: {
+      planEndDate: '计划结束时间'
+    }
+  }
+}
+</script>
+
+<template>
+  <GanttChart :tasks="tasks" :locale-messages="customMessages" />
+  
+  <!-- 函数式：支持嵌套键和默认值 -->
+  <TaskListColumn prop="endDate" :label="getTranslation('gantt.planEndDate')" width="250" />
+</template>
+```
+
+**完整示例（结合语言切换）：**
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
+
+// 自定义多语言配置
+const customMessages = {
+  'zh-CN': {
+    department: '部门',
+    gantt: {
+      planEndDate: '计划结束时间'
+    }
+  },
+  'en-US': {
+    department: 'Department',
+    gantt: {
+      planEndDate: 'Plan End Date'
+    }
+  }
+}
+
+// 使用 useI18n 访问翻译
+const { t, getTranslation, locale, setLocale } = useI18n()
+const tasks = ref([...])
+
+// 语言切换
+const switchLanguage = () => {
+  setLocale(locale.value === 'zh-CN' ? 'en-US' : 'zh-CN')
+}
+</script>
+
+<template>
+  <button @click="switchLanguage">切换语言</button>
+  
+  <GanttChart :tasks="tasks" :locale-messages="customMessages" />
+  
+  <!-- 引用式：直接通过 t 对象访问 -->
+  <TaskListColumn prop="startDate" label="开始时间" width="250">
+    <template #header>
+      <strong style="color: #1890ff;">{{ t.department }}</strong>
+    </template>
+  </TaskListColumn>
+  
+  <!-- 函数式：支持嵌套键和默认值 -->
+  <TaskListColumn prop="endDate" :label="getTranslation('gantt.planEndDate')" width="250" />
+</template>
+```
+
+**`useI18n` API 说明：**
+
+| 导出项 | 类型 | 说明 |
+|--------|------|------|
+| `t` | `Ref<object>` | 响应式翻译对象，通过 `t.key` 或 `t.nested.key` 访问翻译文本 |
+| `getTranslation(key, defaultValue?)` | `Function` | 函数式访问翻译文本<br>• `key`: 翻译键，支持嵌套路径（如 `'gantt.planEndDate'`）<br>• `defaultValue`: 可选，找不到翻译时返回的默认值<br>• 返回：翻译文本、默认值或 key 本身 |
+| `formatTranslation(key, params)` | `Function` | 格式化带参数的翻译文本<br>• `key`: 翻译键<br>• `params`: 参数对象，如 `{ name: '任务1' }`<br>• 返回：替换占位符后的文本（如 `'任务{name}'` → `'任务任务1'`） |
+| `locale` | `Ref<string>` | 当前语言（`'zh-CN'` 或 `'en-US'`） |
+| `setLocale(locale)` | `Function` | 切换语言，会自动更新所有使用 `useI18n` 的组件 |
+| `formatYearMonth(year, month)` | `Function` | 格式化年月显示<br>• 中文：`formatYearMonth(2024, 3)` → `'2024年03月'`<br>• 英文：`formatYearMonth(2024, 3)` → `'2024/03'` |
+| `formatMonth(month)` | `Function` | 格式化月份显示<br>• 中文：`formatMonth(3)` → `'3月'`<br>• 英文：`formatMonth(3)` → `'03'` |
+
+**使用示例：**
+
+```vue
+<script setup>
+import { useI18n } from 'jordium-gantt-vue3'
+
+const { t, getTranslation, formatTranslation, formatYearMonth, formatMonth } = useI18n()
+
+// 1. 基础访问
+const text1 = t.taskName  // '任务名称'
+const text2 = getTranslation('gantt.planEndDate', '计划结束')  // '计划结束时间' 或默认值
+
+// 2. 带参数的翻译
+const message = formatTranslation('taskNotFound', { id: '123' })  // '未找到要更新的任务，ID：123'
+
+// 3. 日期格式化
+const yearMonth = formatYearMonth(2024, 3)  // '2024年03月' (zh-CN) 或 '2024/03' (en-US)
+const month = formatMonth(3)  // '3月' (zh-CN) 或 '03' (en-US)
+</script>
+```
+
+> **💡 使用提示**：
+>
+> - **引用式** (`t.key`)：语法简洁，适合模板中直接使用
+> - **函数式** (`getTranslation('nested.key', 'default')`)：支持嵌套键和默认值，适合访问深层结构
+> - 通过 `localeMessages` 属性传入自定义翻译，再通过 `useI18n` 访问并翻译
+> - 语言切换通过 `setLocale()` 实现，所有组件会自动响应更新
 
 ### 自定义扩展
 
diff --git a/demo/version-history.json b/demo/version-history.json
index f4383e3..f95f70d 100644
--- a/demo/version-history.json
+++ b/demo/version-history.json
@@ -408,5 +408,15 @@
       "🔧 修复：声明式Task List数据展示问题",
       "🔧 Fixed: Declarative Task List data display issue"
     ]
+  },
+  {
+    "version": "1.6.2",
+    "date": "2025-12-23",
+    "notes": [
+      "🔧 修复：I18n外部使用的问题",
+      "<span style=\"font-weight: bold; color: #f00;\">特别感谢 he-shihao-3687@gitee的使用及反馈</span>",
+      "🔧 Fixed: Issue with external use of I18n",
+      "<span style=\"font-weight: bold; color: #f00;\">Special thanks to he-shihao-3687@gitee for their use and feedback</span>"
+    ]
   }
 ]
diff --git a/npm-demo/src/components/GanttTest.vue b/npm-demo/src/components/GanttTest.vue
index 1206686..09804aa 100644
--- a/npm-demo/src/components/GanttTest.vue
+++ b/npm-demo/src/components/GanttTest.vue
@@ -1,8 +1,10 @@
 <script setup lang="ts">
 import { ref } from 'vue'
-import { GanttChart, TaskListColumn } from 'jordium-gantt-vue3'
+import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
 import 'jordium-gantt-vue3/dist/assets/jordium-gantt-vue3.css'
 
+const { t, getTranslation } = useI18n();
+
 const tasks = ref([
   {
     id: 1,
@@ -35,6 +37,10 @@ const customMessages = {
     hours: '小时111',
     overtime: '超时111',
     overdue: '逾期111',
+    gantt: {
+      planStartDate: '计划开始时间',
+      //planEndDate: '计划结束时间',
+    }
   },
   'en-US': {
     department: 'Department',
@@ -44,6 +50,10 @@ const customMessages = {
     hours: 'Hour111',
     overtime: 'OverTime111',
     overdue: 'OverDue111',
+    gantt: {
+      planStartDate: 'Plan Start Date',
+      planEndDate: 'Plan End Date',
+    }
   }
 }
 // const tasks = ref([])
@@ -228,8 +238,12 @@ const onTaskAdded = (res) => {
           <span style="color: #52c41a;">{{ scope.row.name }}</span>
         </template>
       </TaskListColumn>
-      <TaskListColumn prop="startDate" label="开始时间" width="250" />
-      <TaskListColumn prop="endDate" label="结束时间" width="250" />
+      <TaskListColumn prop="startDate" label="开始时间" width="250">
+        <template #header>
+          <strong style="color: #1890ff;">{{ t.department }}</strong>
+        </template>
+      </TaskListColumn>
+      <TaskListColumn prop="endDate" :label="getTranslation('gantt.planEndDate', '结束的时间')" width="250" />
     </GanttChart>
     </div>
     <!-- 自定义添加任务按钮 -->
diff --git a/package.json b/package.json
index afe4a7e..01fbe72 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "jordium-gantt-vue3",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "type": "module",
   "main": "npm-package/dist/jordium-gantt-vue3.cjs.js",
   "module": "npm-package/dist/jordium-gantt-vue3.es.js",
diff --git a/src/composables/useI18n.ts b/src/composables/useI18n.ts
index 15d7bbb..c5d4c8c 100644
--- a/src/composables/useI18n.ts
+++ b/src/composables/useI18n.ts
@@ -585,10 +585,28 @@ export function useI18n() {
     return messages[currentLocale.value]
   })
 
-  // 安全获取翻译文本的函数
-  const getTranslation = (key: string): string => {
-    const translation = t.value[key as keyof typeof t.value]
-    return typeof translation === 'string' ? translation : key
+  // 安全获取翻译文本的函数 - 支持多级键（如 'taskListConfig.title'）
+  const getTranslation = (key: string, defaultValue?: string): string => {
+    // 分割键路径
+    const keys = key.split('.')
+
+    // 从根对象开始递归访问
+    let value: any = t.value
+
+    for (const k of keys) {
+      if (value && typeof value === 'object' && k in value) {
+        value = value[k]
+      } else {
+        // 如果找不到，优先返回用户传入的 default，否则返回 key
+        return defaultValue || key
+      }
+    }
+
+    // 确保返回的是字符串
+    // 1. 如果找到了值且是字符串，返回该值
+    // 2. 如果值不是字符串，优先返回用户传入的 default
+    // 3. 否则返回 key
+    return typeof value === 'string' ? value : (defaultValue || key)
   }
 
   // 格式化带参数的翻译文本
diff --git a/src/index.ts b/src/index.ts
index afa319e..af7fcf0 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -11,6 +11,9 @@ export { default as TaskRow } from './components/TaskRow.vue'
 export type { Task } from './models/classes/Task.ts' // 导出Task类型
 export { useMessage } from './composables/useMessage.ts' // 导出useMessage组合式函数
 
+// 导出 composables 供外部使用
+export { useI18n } from './composables/useI18n'
+
 // 导出配置类型
 export type {
   TaskListConfig,