@alicloud/appflow-chat 0.0.4 → 0.0.5-beta.1

package/src/components/HumanVerify/CustomParamsRenderer/FileField.tsx

@@ -10,6 +10,8 @@ import {
   UploadFileResponse 
 } from './types';
 import styled from 'styled-components';
+import { useTranslation } from '../../../i18n';
+import { translate } from '../../../i18n';
 
 // ==================== Styled Components ====================
 
@@ -114,16 +116,17 @@ const getAcceptBySubTypes = (subTypes?: FileSubType[]): string => {
 
 /**
  * 根据文件子类型数组获取上传提示文本
+ * 使用全局 translate（非 hook 版本）以便在组件外调用
  */
 const getUploadHintBySubTypes = (subTypes?: FileSubType[]): string => {
   if (!subTypes || subTypes.length === 0) {
-    return '支持所有文件格式';
+    return translate('humanVerify.file.supportAll');
   }
-  
+
   if (subTypes.includes('default')) {
-    return '支持所有文件格式';
+    return translate('humanVerify.file.supportAll');
   }
-  
+
   const hintMap: Record<FileSubType, string> = {
     'jpg': 'JPG',
     'png': 'PNG',
@@ -134,11 +137,13 @@ const getUploadHintBySubTypes = (subTypes?: FileSubType[]): string => {
     'txt': 'TXT',
     'markdown': 'Markdown',
     'zip': 'ZIP/RAR/7Z',
-    'default': '所有格式',
+    'default': translate('humanVerify.file.supportAll'),
   };
-  
+
   const hints = subTypes.map(subType => hintMap[subType] || subType).filter(Boolean);
-  return hints.length > 0 ? `支持 ${hints.join('、')} 格式` : '支持所有文件格式';
+  return hints.length > 0
+    ? translate('humanVerify.file.supportFormats', { formats: hints.join('、') })
+    : translate('humanVerify.file.supportAll');
 };
 
 /**
@@ -164,6 +169,7 @@ export const FileField: React.FC<FileFieldProps> = ({
   uploadSender,
   fileUploader,
 }) => {
+  const { t } = useTranslation();
   // 优先从 AssociationPropertyMetadata.SubType 读取，兼容旧的 FileSubType 字段
   const subTypes = useMemo((): FileSubType[] => {
     const subTypeArray = schema.AssociationPropertyMetadata?.SubType;
@@ -190,7 +196,7 @@ export const FileField: React.FC<FileFieldProps> = ({
     if (Array.isArray(value)) {
       return value.map((file: any, index: number) => ({
         uid: file.uid || `${index}`,
-        name: file.name || `文件${index + 1}`,
+        name: file.name || `${t('humanVerify.file.defaultFileName')}${index + 1}`,
         status: 'done' as const,
         url: file.url,
         ...file,
@@ -199,7 +205,7 @@ export const FileField: React.FC<FileFieldProps> = ({
     if (typeof value === 'object') {
       return [{
         uid: value.uid || '0',
-        name: value.name || '文件',
+        name: value.name || t('humanVerify.file.defaultFileName'),
         status: 'done' as const,
         url: value.url,
         ...value,
@@ -227,7 +233,7 @@ export const FileField: React.FC<FileFieldProps> = ({
    */
   const getUploadToken = useCallback(async (fileName: string): Promise<UploadTokenResponse | null> => {
     if (!uploadSender) {
-      message.error('上传功能未配置');
+      message.error(t('humanVerify.file.uploaderNotConfigured'));
       return null;
     }
 
@@ -238,7 +244,7 @@ export const FileField: React.FC<FileFieldProps> = ({
       });
 
       if (!response) {
-        message.error('获取上传凭证失败');
+        message.error(t('humanVerify.file.tokenFailed'));
         return null;
       }
 
@@ -255,14 +261,14 @@ export const FileField: React.FC<FileFieldProps> = ({
         return parsedResponse as UploadTokenResponse;
       }
       
-      message.error('获取上传凭证失败');
+      message.error(t('humanVerify.file.tokenFailed'));
       return null;
     } catch (error) {
-      console.error('获取上传凭证失败:', error);
-      message.error('获取上传凭证失败');
+      console.error(t('humanVerify.file.tokenFailed'), error);
+      message.error(t('humanVerify.file.tokenFailed'));
       return null;
     }
-  }, [uploadSender]);
+  }, [uploadSender, t]);
 
   /**
    * 获取文件 ID（文件上传专用）
@@ -298,10 +304,10 @@ export const FileField: React.FC<FileFieldProps> = ({
       
       return null;
     } catch (error) {
-      console.error('获取文件ID失败:', error);
+      console.error(t('humanVerify.file.getFileIdFailed'), error);
       return null;
     }
-  }, [uploadSender]);
+  }, [uploadSender, t]);
 
   /**
    * 图片上传处理
@@ -311,12 +317,12 @@ export const FileField: React.FC<FileFieldProps> = ({
     // 1. 获取预签名 URL
     const tokenResponse = await getUploadToken(file.name);
     if (!tokenResponse) {
-      throw new Error('获取上传凭证失败');
+      throw new Error(t('humanVerify.file.tokenFailed'));
     }
 
     // 2. 上传文件到 OSS
     if (!fileUploader) {
-      throw new Error('文件上传方法未配置');
+      throw new Error(t('humanVerify.file.uploadMethodNotConfigured'));
     }
     const blob = new Blob([file]);
     await fileUploader(blob, tokenResponse.uploadUrl);
@@ -329,7 +335,7 @@ export const FileField: React.FC<FileFieldProps> = ({
       type: file.type,
       size: file.size,
     };
-  }, [getUploadToken, fileUploader]);
+  }, [getUploadToken, fileUploader, t]);
 
   /**
    * 文件上传处理
@@ -339,12 +345,12 @@ export const FileField: React.FC<FileFieldProps> = ({
     // 1. 获取预签名 URL
     const tokenResponse = await getUploadToken(file.name);
     if (!tokenResponse) {
-      throw new Error('获取上传凭证失败');
+      throw new Error(t('humanVerify.file.tokenFailed'));
     }
 
     // 2. 上传文件到 OSS
     if (!fileUploader) {
-      throw new Error('文件上传方法未配置');
+      throw new Error(t('humanVerify.file.uploadMethodNotConfigured'));
     }
     const blob = new Blob([file]);
     await fileUploader(blob, tokenResponse.uploadUrl);
@@ -362,7 +368,7 @@ export const FileField: React.FC<FileFieldProps> = ({
       size: file.size,
       fileType: file.name.split('.').pop(),
     };
-  }, [getUploadToken, fileUploader, getFileId]);
+  }, [getUploadToken, fileUploader, getFileId, t]);
 
   /**
    * 自定义上传逻辑
@@ -379,7 +385,7 @@ export const FileField: React.FC<FileFieldProps> = ({
           onSuccess?.({ url }, new XMLHttpRequest());
         } catch (error) {
           onError?.(error as Error);
-          message.error('文件上传失败');
+          message.error(t('humanVerify.file.uploadFailed'));
         }
         return;
       }
@@ -399,12 +405,12 @@ export const FileField: React.FC<FileFieldProps> = ({
         onSuccess?.(result, new XMLHttpRequest());
       } catch (error) {
         onError?.(error as Error);
-        message.error('文件上传失败');
+        message.error(t('humanVerify.file.uploadFailed'));
       } finally {
         setUploading(false);
       }
     },
-    [uploadSender, fileUploader, isImage, handleImageUpload, handleFileUpload]
+    [uploadSender, fileUploader, isImage, handleImageUpload, handleFileUpload, t]
   );
 
   // 处理文件变化
@@ -440,19 +446,21 @@ export const FileField: React.FC<FileFieldProps> = ({
       // 文件大小限制（默认 10MB）
       const maxSize = 10 * 1024 * 1024;
       if (file.size > maxSize) {
-        message.error('文件大小不能超过 10MB');
+        message.error(t('humanVerify.file.maxSizeError', { size: '10MB' }));
         return Upload.LIST_IGNORE;
       }
       return true;
     },
-    []
+    [t]
   );
 
   // 上传按钮的加载指示器
   const uploadButton = (
     <div>
       {uploading ? <LoadingOutlined /> : <PlusOutlined />}
-      <div style={{ marginTop: 8 }}>{uploading ? '上传中' : '上传'}</div>
+      <div style={{ marginTop: 8 }}>
+        {uploading ? t('humanVerify.file.uploading') : t('humanVerify.file.upload')}
+      </div>
     </div>
   );
 
@@ -498,7 +506,7 @@ export const FileField: React.FC<FileFieldProps> = ({
           disabled={disabled || uploading}
           loading={uploading}
         >
-          {uploading ? '上传中' : '选择文件'}
+          {uploading ? t('humanVerify.file.uploading') : t('humanVerify.file.uploadButton')}
         </Button>
       </Upload>
       <FileHint>{hint}</FileHint>

package/src/components/HumanVerify/CustomParamsRenderer/ObjectField.tsx

@@ -1,6 +1,7 @@
 import React, { useCallback } from 'react';
 import styled from 'styled-components';
 import { ObjectFieldProps, sortPropertiesByOrder } from './types';
+import { useTranslation } from '../../../i18n';
 
 // 前向声明，避免循环依赖
 const FieldRenderer = React.lazy(() => import('./FieldRenderer'));
@@ -71,7 +72,8 @@ export const ObjectField: React.FC<ObjectFieldProps> = ({
 }) => {
   const { Title, Description, Properties, Required: RequiredFields = [] } = schema;
   const displayTitle = Title || name;
-  
+  const { t } = useTranslation();
+
   // 计算当前对象的完整路径
   const currentPath = fieldPath ? `${fieldPath}.${name}` : name;
 
@@ -108,7 +110,7 @@ export const ObjectField: React.FC<ObjectFieldProps> = ({
         {sortedProperties.map(([propertyName, propertySchema]) => {
           const isRequired = RequiredFields.includes(propertyName);
           return (
-            <React.Suspense key={propertyName} fallback={<div>加载中...</div>}>
+            <React.Suspense key={propertyName} fallback={<div>{t('common.loading')}</div>}>
               <FieldRenderer
                 name={propertyName}
                 schema={propertySchema}

package/src/components/HumanVerify/CustomParamsRenderer/TimeField.tsx

@@ -3,6 +3,7 @@ import { DatePicker } from 'antd';
 import dayjs, { Dayjs } from 'dayjs';
 import { TimeFieldProps, TimeSubType } from './types';
 import styled from 'styled-components';
+import { useTranslation } from '../../../i18n';
 
 // ==================== Styled Components ====================
 
@@ -56,6 +57,7 @@ export const TimeField: React.FC<TimeFieldProps> = ({
   onChange,
   disabled = false,
 }) => {
+  const { t } = useTranslation();
   // 优先从 AssociationPropertyMetadata.SubType 读取，取数组第一个元素
   // 兼容旧的 TimeSubType 字段
   const subType = useMemo((): TimeSubType | undefined => {
@@ -95,7 +97,7 @@ export const TimeField: React.FC<TimeFieldProps> = ({
         showTime={showTime ? { format: 'HH:mm:ss' } : false}
         disabled={disabled}
         style={{ width: '100%' }}
-        placeholder={`请选择`}
+        placeholder={t('common.placeholderSelect')}
       />
     </TimeFieldContainer>
   );

package/src/components/HumanVerify/HistoryCard.tsx

@@ -3,6 +3,7 @@ import { Button } from 'antd';
 import styled from 'styled-components';
 import CustomParamsRenderer from './CustomParamsRenderer';
 import { CustomParamSchema } from './CustomParamsRenderer/types';
+import { useTranslation } from '../../i18n';
 
 // ==================== Styled Components ====================
 
@@ -114,6 +115,7 @@ export const convertSchemaToUpperCase = (schema: any): CustomParamSchema | undef
  * 用于展示历史对话中的 card 类型消息（只读模式）
  */
 export const HistoryCard: React.FC<HistoryCardProps> = ({ data }) => {
+  const { t } = useTranslation();
   // 从data中提取需要的参数
   const approvalStatus = data?.approvalStatus;
   
@@ -131,7 +133,7 @@ export const HistoryCard: React.FC<HistoryCardProps> = ({ data }) => {
         <StatusContainer $approved={isApproved}>
           <StatusContent>
             <StatusText>
-              {isApproved ? '已提交' : '待提交'}
+              {isApproved ? t('humanVerify.submitted') : t('humanVerify.pending')}
             </StatusText>
           </StatusContent>
           <Button 
@@ -139,7 +141,7 @@ export const HistoryCard: React.FC<HistoryCardProps> = ({ data }) => {
             variant="filled"
             disabled={true}
           >
-            {isApproved ? '已提交' : '提交'}
+            {isApproved ? t('humanVerify.submitted') : t('common.submit')}
           </Button>
         </StatusContainer>
       </HistoryCardContainer>
@@ -156,7 +158,7 @@ export const HistoryCard: React.FC<HistoryCardProps> = ({ data }) => {
       <StatusContainer $approved={isApproved}>
         <StatusContent>
           <StatusText>
-            {isApproved ? '已提交' : '待提交'}
+            {isApproved ? t('humanVerify.submitted') : t('humanVerify.pending')}
           </StatusText>
         </StatusContent>
         <Button 
@@ -164,7 +166,7 @@ export const HistoryCard: React.FC<HistoryCardProps> = ({ data }) => {
           variant="filled"
           disabled={true}
         >
-          {isApproved ? '已提交' : '提交'}
+          {isApproved ? t('humanVerify.submitted') : t('common.submit')}
         </Button>
       </StatusContainer>
     </HistoryCardContainer>

package/src/components/HumanVerify/HumanVerify.tsx

@@ -2,6 +2,7 @@ import React, { useCallback, useEffect, useState } from 'react';
 import { Button, message } from 'antd';
 import styled from 'styled-components';
 import CustomParamsRenderer, { validateCustomParams, UploadSender, FileUploader } from './CustomParamsRenderer';
+import { useTranslation } from '../../i18n';
 
 // ==================== Styled Components ====================
 
@@ -61,6 +62,7 @@ export const HumanVerify: React.FC<HumanVerifyProps> = ({
   fileUploader,
   onSubmit
 }) => {
+  const { t } = useTranslation();
   // 从 data 中提取需要的参数
   const verifyId = data?.verifyId;
   const sessionWebhook = data?.sessionWebhook;
@@ -110,7 +112,7 @@ export const HumanVerify: React.FC<HumanVerifyProps> = ({
         setValidationErrors(errors);
 
         // 提示用户
-        message.error('请填写所有必填项');
+        message.error(t('humanVerify.requiredAll'));
         return;
       }
 
@@ -143,7 +145,7 @@ export const HumanVerify: React.FC<HumanVerifyProps> = ({
       <StatusContainer $approved={approved}>
         <StatusContent>
           <StatusText>
-            {approved ? '已提交' : '待提交'}
+            {approved ? t('humanVerify.submitted') : t('humanVerify.pending')}
           </StatusText>
         </StatusContent>
         <Button 
@@ -152,7 +154,7 @@ export const HumanVerify: React.FC<HumanVerifyProps> = ({
           onClick={handleApprove}
           disabled={approved}
         >
-          {'提交'}
+          {t('common.submit')}
         </Button>
       </StatusContainer>
     </HumanVerifyContainer>

package/src/components/MessageBubble.tsx

@@ -11,7 +11,10 @@ import { loadEchartsScript } from '@/utils/loadEcharts';
 import { DocReferences, DocReferenceItem } from './DocReferences';
 import { WebSearchPanel } from './WebSearchPanel';
 import { HumanVerify, HistoryCard, CustomParamSchema } from './HumanVerify';
+import { A2UISurface } from './A2UIRenderer';
+import type { A2UIMessage } from './A2UIRenderer';
 import { BubbleContent } from '@/core';
+import { useTranslation } from '@/i18n';
 
 /** HumanVerify 提交数据类型 */
 export interface HumanVerifySubmitData {
@@ -58,14 +61,21 @@ export interface MessageBubbleProps {
   
   // ==================== HumanVerify相关Props ====================
   
-  /** 事件类型（用于特殊消息如 humanVerify、historyCard） */
-  eventType?: 'humanVerify' | 'historyCard';
+  /** 事件类型（用于特殊消息如 humanVerify、historyCard、a2ui） */
+  eventType?: 'humanVerify' | 'historyCard' | 'a2ui';
   /** HumanVerify 相关数据 */
   humanVerifyData?: HumanVerifyData;
   /** HistoryCard 相关数据（历史对话中的审核卡片） */
   historyCardData?: HistoryCardData;
   /** HumanVerify 提交回调 */
   onHumanVerifySubmit?: (data: HumanVerifySubmitData) => void;
+
+  // ==================== A2UI相关Props ====================
+
+  /** A2UI 消息数组（Agent 生成的声明式 UI 描述） */
+  a2uiMessages?: A2UIMessage[];
+  /** A2UI 用户交互回调 */
+  onA2UIAction?: (action: any) => void;
 }
 
 // 样式隔离容器
@@ -270,7 +280,11 @@ export const MessageBubble: React.FC<MessageBubbleProps> = ({
   humanVerifyData,
   historyCardData,
   onHumanVerifySubmit,
+  // A2UI 相关 props
+  a2uiMessages,
+  onA2UIAction,
 }) => {
+  const { t } = useTranslation();
   const [modal, contextHolder] = Modal.useModal();
   
   // 网页搜索抽屉状态
@@ -293,7 +307,7 @@ export const MessageBubble: React.FC<MessageBubbleProps> = ({
     modal.confirm({
       bodyStyle: { maxHeight: '80vh', overflow: 'auto' },
       icon: null,
-      title: '参考资料',
+      title: t('source.title'),
       destroyOnClose: true,
       maskClosable: true,
       closable: true,
@@ -317,7 +331,7 @@ export const MessageBubble: React.FC<MessageBubbleProps> = ({
       ),
       footer: null,
     });
-  }, [modal]);
+  }, [modal, t]);
 
   // 默认的网页搜索点击处理
   const defaultWebSearchClick = useCallback((items: DocReferenceItem[]) => {
@@ -362,6 +376,14 @@ export const MessageBubble: React.FC<MessageBubbleProps> = ({
                 data={historyCardData}
               />
             )}
+
+            {/* A2UI 事件 - Agent 声明式 UI 渲染 */}
+            {eventType === 'a2ui' && a2uiMessages && a2uiMessages.length > 0 && (
+              <A2UISurface
+                messages={a2uiMessages}
+                onAction={onA2UIAction}
+              />
+            )}
             
             {/* 参考资料 */}
             {references && references.length > 0 && status === 'Success' && (

package/src/components/RichMessageBubble.tsx

@@ -12,6 +12,7 @@ import { loadEchartsScript } from '../utils/loadEcharts';
 import { DocReferences, DocReferenceItem } from './DocReferences';
 import { WebSearchPanel } from './WebSearchPanel';
 import { RichBubbleContent } from '../core';
+import { useTranslation } from '../i18n';
 
 export interface RichMessageBubbleProps {
   /** 消息内容 */
@@ -177,6 +178,7 @@ export const RichMessageBubble: React.FC<RichMessageBubbleProps> = ({
   onReferenceClick,
   onWebSearchClick,
 }) => {
+  const { t } = useTranslation();
   const [modal, contextHolder] = Modal.useModal();
   
   // 网页搜索抽屉状态
@@ -199,7 +201,7 @@ export const RichMessageBubble: React.FC<RichMessageBubbleProps> = ({
     modal.confirm({
       bodyStyle: { maxHeight: '80vh', overflow: 'auto' },
       icon: null,
-      title: '参考资料',
+      title: t('source.title'),
       destroyOnClose: true,
       maskClosable: true,
       closable: true,
@@ -223,7 +225,7 @@ export const RichMessageBubble: React.FC<RichMessageBubbleProps> = ({
       ),
       footer: null,
     });
-  }, [modal]);
+  }, [modal, t]);
 
   // 默认的网页搜索点击处理
   const defaultWebSearchClick = useCallback((items: DocReferenceItem[]) => {

package/src/core/RichBubbleContent.tsx

@@ -19,6 +19,7 @@ import { Collapse } from 'antd';
 import { MarkdownView } from '../markdown';
 import { convertTableDataToMarkdown, processStepContent } from '../markdown/utils/dataProcessor';
 import { RichBubbleProvider } from '../context/RichBubble';
+import { useTranslation } from '../i18n';
 
 export interface RichBubbleContentProps {
   /** 消息内容 */
@@ -110,6 +111,7 @@ export const RichBubbleContent: React.FC<RichBubbleContentProps> = ({
   children,
   waitingMessage,
 }) => {
+  const { t } = useTranslation();
   // step消息折叠面板激活的索引
   const [activeKey, setActiveKey] = useState<string | string[]>([]);
 
@@ -150,7 +152,7 @@ export const RichBubbleContent: React.FC<RichBubbleContentProps> = ({
     } else {
       const contentToRender = detail || '';
       if (!contentToRender) {
-        return <StyledStepContent>暂无内容</StyledStepContent>;
+        return <StyledStepContent>{t('rich.emptyContent')}</StyledStepContent>;
       }
 
       return (
@@ -250,7 +252,7 @@ export const RichBubbleContent: React.FC<RichBubbleContentProps> = ({
                     <StyledStatusIcon $success={status === 'Success'}>
                       {status === 'Success' ? '✓' : '⟳'}
                     </StyledStatusIcon>
-                    <StyledStepNumber>步骤{index + 1}:</StyledStepNumber>
+                    <StyledStepNumber>{t('rich.stepLabel', { index: index + 1 })}</StyledStepNumber>
                     <StyledStepText>{itemContent?.title}</StyledStepText>
                   </StyledStepTitleWrapper>
                 ),

package/src/core/SourceContent.tsx

@@ -11,6 +11,7 @@ import styled from 'styled-components';
 import { Image } from 'antd';
 import { SearchOutlined } from '@ant-design/icons';
 import { flatten, uniq } from 'lodash-es';
+import { useTranslation } from '../i18n';
 
 // 参考资料项类型
 export interface SourceItem {
@@ -195,6 +196,7 @@ export const SourceContent: React.FC<SourceContentProps> = ({
   className,
   style,
 }) => {
+  const { t } = useTranslation();
   // 提取唯一图片
   const uniqueImages = useMemo(() => {
     let images;
@@ -244,14 +246,14 @@ export const SourceContent: React.FC<SourceContentProps> = ({
       {webSearchArray.length > 0 && (
         <StyledWebSearchSource onClick={handleWebSearchClick}>
           <SearchOutlined />
-          <div>已搜索到{webSearchArray.length}个网页</div>
+          <div>{t('webSearch.foundPages', { count: webSearchArray.length })}</div>
         </StyledWebSearchSource>
       )}
 
       {/* RAG参考资料 */}
       {ragArray.length > 0 && (
         <StyledAnswerSource>
-          <StyledLabel>回答来源：</StyledLabel>
+          <StyledLabel>{t('source.answerFrom')}</StyledLabel>
           <div style={{ width: 'calc(100% - 70px)' }}>
             {ragArray.map((item, index) => (
               <SourceItemComponent
@@ -268,7 +270,7 @@ export const SourceContent: React.FC<SourceContentProps> = ({
       {/* 图片来源 */}
       {uniqueImages.length > 0 && (
         <StyledAnswerSource>
-          <StyledLabel>图片来源：</StyledLabel>
+          <StyledLabel>{t('source.imageFrom')}</StyledLabel>
           <StyledWrapSpace>
             {uniqueImages.map((image, index) => (
               <StyledImageBox key={index}>

package/src/core/WebSearchContent.tsx

@@ -6,6 +6,7 @@ import React from 'react';
 import styled from 'styled-components';
 import { Drawer, List, Typography } from 'antd';
 import { CloseOutlined } from '@ant-design/icons';
+import { useTranslation } from '../i18n';
 
 const { Title } = Typography;
 
@@ -136,6 +137,7 @@ export const WebSearchContent: React.FC<WebSearchContentProps> = ({
   className,
   style,
 }) => {
+  const { t } = useTranslation();
   // 判断是否移动端
   const isMobile = typeof window !== 'undefined' && window.innerWidth <= 500;
   const panelWidth = isMobile ? '100%' : width;
@@ -174,7 +176,7 @@ export const WebSearchContent: React.FC<WebSearchContentProps> = ({
       <StyledContainer $isMobile={isMobile}>
         <StyledContent>
           <StyledHeader>
-            <Title level={5} style={{ margin: 0 }}>搜索结果</Title>
+            <Title level={5} style={{ margin: 0 }}>{t('webSearch.title')}</Title>
             <StyledCloseButton onClick={handleClose}>
               <CloseOutlined />
             </StyledCloseButton>

package/src/i18n/LocaleContext.tsx

@@ -0,0 +1,70 @@
+/**
+ * Locale Context 与 Provider
+ */
+
+import React, { createContext, useEffect, useMemo } from 'react';
+import zhCN from '../locales/zh-CN';
+import type { DeepPartial, Locale } from '../locales/types';
+import { setGlobalLocale } from './translate';
+import { deepMerge } from './utils';
+
+export interface LocaleContextValue {
+  locale: Locale;
+  localeName: string;
+}
+
+export const LocaleContext = createContext<LocaleContextValue>({
+  locale: zhCN as unknown as Locale,
+  localeName: 'zh-CN',
+});
+
+export interface LocaleProviderProps {
+  /** 完整 locale 对象，默认使用内置 zhCN */
+  locale?: Locale;
+  /** 语言标识，如 'zh-CN' / 'en-US' */
+  localeName?: string;
+  /** 部分覆盖：在选定 locale 基础上 deep merge 自定义文案 */
+  overrides?: DeepPartial<Locale>;
+  children: React.ReactNode;
+}
+
+/**
+ * LocaleProvider
+ *
+ * 用法示例：
+ * ```tsx
+ * import { LocaleProvider, enUS } from '@alicloud/appflow-chat';
+ *
+ * <LocaleProvider locale={enUS} localeName="en-US">
+ *   <App />
+ * </LocaleProvider>
+ * ```
+ */
+export const LocaleProvider: React.FC<LocaleProviderProps> = ({
+  locale,
+  localeName = 'zh-CN',
+  overrides,
+  children,
+}) => {
+  const baseLocale = (locale ?? (zhCN as unknown as Locale)) as Locale;
+
+  const mergedLocale = useMemo<Locale>(() => {
+    if (!overrides) return baseLocale;
+    return deepMerge(
+      baseLocale as unknown as Record<string, unknown>,
+      overrides as Record<string, unknown>
+    ) as unknown as Locale;
+  }, [baseLocale, overrides]);
+
+  // 同步到全局，供非 React 场景（如 ChatService）使用
+  useEffect(() => {
+    setGlobalLocale(mergedLocale, localeName);
+  }, [mergedLocale, localeName]);
+
+  const contextValue = useMemo<LocaleContextValue>(
+    () => ({ locale: mergedLocale, localeName }),
+    [mergedLocale, localeName]
+  );
+
+  return <LocaleContext.Provider value={contextValue}>{children}</LocaleContext.Provider>;
+};

package/src/i18n/index.ts

@@ -0,0 +1,16 @@
+/**
+ * i18n 模块统一导出
+ */
+
+export { LocaleProvider, LocaleContext } from './LocaleContext';
+export type { LocaleProviderProps, LocaleContextValue } from './LocaleContext';
+
+export { useTranslation } from './useTranslation';
+export type { UseTranslationResult } from './useTranslation';
+
+export {
+  translate,
+  setGlobalLocale,
+  getGlobalLocale,
+  getGlobalLocaleName,
+} from './translate';