zkit-ui 1.0.0

package/src/i18n/I18nProvider.tsx

@@ -0,0 +1,69 @@
+import * as React from 'react';
+import { getDefaultI18nConfig } from '../config';
+import { resolveBuiltinLocale } from './locale';
+import { locales } from './locales';
+import type {
+  I18nContextValue,
+  I18nMessages,
+  I18nMissingKeyPolicy,
+  I18nTranslate,
+  I18nTranslateParams,
+} from './types';
+
+function interpolate(template: string, params?: I18nTranslateParams) {
+  if (!params) return template;
+  return template.replace(/\{(\w+)\}/g, (full, key: string) => {
+    const value = params[key];
+    if (value === undefined || value === null) return full;
+    return String(value);
+  });
+}
+
+function createTranslator(messages: I18nMessages, missingKeyPolicy: I18nMissingKeyPolicy): I18nTranslate {
+  return (key, params) => {
+    const raw = messages[key];
+    if (raw == null) {
+      if (missingKeyPolicy === 'throw') {
+        throw new Error(`[zkit-ui] Missing i18n key: ${key}`);
+      }
+      return key;
+    }
+    return interpolate(raw, params);
+  };
+}
+
+function resolveI18nValue(
+  base: Required<ReturnType<typeof getDefaultI18nConfig>>,
+  override?: {
+    locale?: string;
+    messages?: I18nMessages;
+    missingKeyPolicy?: I18nMissingKeyPolicy;
+  }
+): I18nContextValue {
+  const locale = override?.locale ?? base.locale;
+  // 优先级：override.messages > base.messages > 内置语言包
+  const builtinMessages = locales[resolveBuiltinLocale(locale)] ?? {};
+  const messages = { ...builtinMessages, ...base.messages, ...(override?.messages ?? {}) };
+  const missingKeyPolicy = override?.missingKeyPolicy ?? base.missingKeyPolicy;
+  const t = createTranslator(messages, missingKeyPolicy);
+  return { locale, messages, missingKeyPolicy, t };
+}
+
+export const I18nContext = React.createContext<I18nContextValue>({
+  ...resolveI18nValue(getDefaultI18nConfig()),
+});
+
+export type I18nProviderProps = {
+  locale?: string;
+  messages?: I18nMessages;
+  missingKeyPolicy?: I18nMissingKeyPolicy;
+  children: React.ReactNode;
+};
+
+export function I18nProvider({ locale, messages, missingKeyPolicy, children }: I18nProviderProps) {
+  const value = React.useMemo(() => {
+    const base = getDefaultI18nConfig();
+    return resolveI18nValue(base, { locale, messages, missingKeyPolicy });
+  }, [locale, messages, missingKeyPolicy]);
+  return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>;
+}

package/src/i18n/locale.ts

@@ -0,0 +1,108 @@
+import { NativeModules } from 'react-native';
+
+export const DEFAULT_I18N_LOCALE = 'zh-CN';
+
+export const BUILTIN_I18N_LOCALES = ['zh-CN', 'zh-TW', 'ja', 'en-US', 'de'] as const;
+const TRADITIONAL_CHINESE_REGIONS = new Set(['HK', 'MO', 'TW']);
+
+export type BuiltinI18nLocale = (typeof BUILTIN_I18N_LOCALES)[number];
+type NavigatorLike = {
+  language?: string;
+  languages?: readonly string[];
+  userLanguage?: string;
+};
+type NativeSettings = Record<string, unknown>;
+type NativeModulesWithLocale = typeof NativeModules & {
+  I18nManager?: {
+    localeIdentifier?: unknown;
+  };
+  SettingsManager?: {
+    settings?: NativeSettings;
+  };
+};
+
+function getString(value: unknown) {
+  const next = typeof value === 'string' ? value.trim() : '';
+  return next.length > 0 ? next : undefined;
+}
+
+function getStringArray(value: unknown) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    const next = getString(item);
+    return next ? [next] : [];
+  });
+}
+
+function normalizeLocaleParts(locale: string) {
+  const parts = locale
+    .replace(/_/g, '-')
+    .split('-')
+    .map((part) => part.trim())
+    .filter(Boolean);
+
+  if (parts.length === 0) return null;
+
+  return {
+    language: parts[0].toLowerCase(),
+    subtags: parts.slice(1).map((part) => part.toUpperCase()),
+  };
+}
+
+function matchBuiltinLocale(locale?: string | null): BuiltinI18nLocale | undefined {
+  const rawLocale = getString(locale);
+  if (!rawLocale) return undefined;
+
+  const exactLocale = BUILTIN_I18N_LOCALES.find(
+    (supportedLocale) => supportedLocale.toLowerCase() === rawLocale.toLowerCase()
+  );
+  if (exactLocale) return exactLocale;
+
+  const normalized = normalizeLocaleParts(rawLocale);
+  if (!normalized) return undefined;
+
+  if (normalized.language === 'zh') {
+    const usesTraditionalChinese =
+      normalized.subtags.includes('HANT') ||
+      normalized.subtags.some((subtag) => TRADITIONAL_CHINESE_REGIONS.has(subtag));
+    return usesTraditionalChinese ? 'zh-TW' : 'zh-CN';
+  }
+
+  if (normalized.language === 'ja') return 'ja';
+  if (normalized.language === 'en') return 'en-US';
+  if (normalized.language === 'de') return 'de';
+
+  return undefined;
+}
+
+export function resolveBuiltinLocale(locale?: string | null): BuiltinI18nLocale {
+  return matchBuiltinLocale(locale) ?? DEFAULT_I18N_LOCALE;
+}
+
+function getSystemLocaleCandidates() {
+  const nativeModules = (NativeModules ?? {}) as NativeModulesWithLocale;
+  const settings = nativeModules.SettingsManager?.settings;
+  const navigator = (globalThis as { navigator?: NavigatorLike }).navigator;
+
+  return [
+    getString(settings?.AppleLocale),
+    ...getStringArray(settings?.AppleLanguages),
+    getString(nativeModules.I18nManager?.localeIdentifier),
+    ...(navigator?.languages ?? []),
+    getString(navigator?.language),
+    getString(navigator?.userLanguage),
+  ];
+}
+
+export function getSystemLocale() {
+  return getSystemLocaleCandidates().find((candidate) => getString(candidate));
+}
+
+export function resolveSystemBuiltinLocale() {
+  for (const candidate of getSystemLocaleCandidates()) {
+    const locale = matchBuiltinLocale(candidate);
+    if (locale) return locale;
+  }
+
+  return DEFAULT_I18N_LOCALE;
+}

package/src/i18n/locales/de.ts

@@ -0,0 +1,67 @@
+export const de = {
+  // Picker
+  'picker.title': 'Bitte auswählen',
+  'picker.cancel': 'Abbrechen',
+  'picker.confirm': 'Bestätigen',
+  'picker.empty': 'Keine Optionen verfügbar',
+
+  // DatePicker
+  'datePicker.title': 'Datum auswählen',
+  'datePicker.placeholder': 'Datum wählen',
+  'datePicker.year': 'Jahr',
+  'datePicker.month': 'Monat',
+  'datePicker.day': 'Tag',
+
+  // AddressCascader
+  'addressCascader.title': 'Adresse auswählen',
+  'addressCascader.province': 'Provinz',
+  'addressCascader.city': 'Stadt',
+  'addressCascader.district': 'Bezirk',
+  'addressCascader.empty': 'Keine Adressen verfügbar',
+
+  // BetweenTime
+  'betweenTime.title': 'Zeitraum auswählen',
+  'betweenTime.clear': 'Leeren',
+  'betweenTime.startTime': 'Startzeit',
+  'betweenTime.endTime': 'Endzeit',
+  'betweenTime.to': 'bis',
+  'betweenTime.cancel': 'Abbrechen',
+  'betweenTime.confirm': 'Bestätigen',
+  'betweenTime.unit.year': 'Jahr',
+  'betweenTime.unit.month': 'Monat',
+  'betweenTime.unit.day': 'Tag',
+  'betweenTime.unit.hour': 'Std.',
+  'betweenTime.unit.minute': 'Min.',
+  'betweenTime.unit.second': 'Sek.',
+  'betweenTime.quick.today': 'Heute',
+  'betweenTime.quick.thisWeek': 'Diese Woche',
+  'betweenTime.quick.thisMonth': 'Dieser Monat',
+  'betweenTime.quick.thisYear': 'Dieses Jahr',
+  'betweenTime.quick.thisQuarter': 'Dieses Quartal',
+  'betweenTime.quick.recentDays': 'Letzte {n} Tage',
+
+  // ImagePreview
+  'imagePreview.preview': 'Bildvorschau',
+  'imagePreview.close': 'Bildvorschau schließen',
+  'imagePreview.loadFailed': 'Bild konnte nicht geladen werden',
+  'imagePreview.counter': 'Bild {current} von {total}',
+  'imagePreview.image': 'Bild {current} von {total}',
+
+  // ActionDialog
+  'actionDialog.confirm': 'Bestätigen',
+  'actionDialog.cancel': 'Abbrechen',
+  'actionDialog.close': 'Dialog schließen',
+
+  // Loading
+  'loading.loading': 'Wird geladen',
+  'loading.success': 'Fertig',
+  'loading.error': 'Fehlgeschlagen',
+
+  // SliderCaptcha
+  'sliderCaptcha.title': 'Schieber ziehen, um das Puzzle zu lösen',
+  'sliderCaptcha.verifyFailed': 'Verifizierung fehlgeschlagen, bitte erneut versuchen',
+  'sliderCaptcha.verifySuccess': 'Verifiziert',
+
+  // TextInput
+  'textInput.clear': 'Eingabe löschen',
+};

package/src/i18n/locales/en-US.ts

@@ -0,0 +1,67 @@
+export const enUS = {
+  // Picker
+  'picker.title': 'Please Select',
+  'picker.cancel': 'Cancel',
+  'picker.confirm': 'Confirm',
+  'picker.empty': 'No options available',
+
+  // DatePicker
+  'datePicker.title': 'Select Date',
+  'datePicker.placeholder': 'Select date',
+  'datePicker.year': 'Year',
+  'datePicker.month': 'Month',
+  'datePicker.day': 'Day',
+
+  // AddressCascader
+  'addressCascader.title': 'Select Address',
+  'addressCascader.province': 'Province',
+  'addressCascader.city': 'City',
+  'addressCascader.district': 'District',
+  'addressCascader.empty': 'No addresses available',
+
+  // BetweenTime
+  'betweenTime.title': 'Select Time Range',
+  'betweenTime.clear': 'Clear',
+  'betweenTime.startTime': 'Start Time',
+  'betweenTime.endTime': 'End Time',
+  'betweenTime.to': 'to',
+  'betweenTime.cancel': 'Cancel',
+  'betweenTime.confirm': 'Confirm',
+  'betweenTime.unit.year': 'Year',
+  'betweenTime.unit.month': 'Month',
+  'betweenTime.unit.day': 'Day',
+  'betweenTime.unit.hour': 'Hour',
+  'betweenTime.unit.minute': 'Min',
+  'betweenTime.unit.second': 'Sec',
+  'betweenTime.quick.today': 'Today',
+  'betweenTime.quick.thisWeek': 'This Week',
+  'betweenTime.quick.thisMonth': 'This Month',
+  'betweenTime.quick.thisYear': 'This Year',
+  'betweenTime.quick.thisQuarter': 'This Quarter',
+  'betweenTime.quick.recentDays': 'Last {n} Days',
+
+  // ImagePreview
+  'imagePreview.preview': 'Image preview',
+  'imagePreview.close': 'Close image preview',
+  'imagePreview.loadFailed': 'Failed to load image',
+  'imagePreview.counter': 'Image {current} of {total}',
+  'imagePreview.image': 'Image {current} of {total}',
+
+  // ActionDialog
+  'actionDialog.confirm': 'Confirm',
+  'actionDialog.cancel': 'Cancel',
+  'actionDialog.close': 'Close dialog',
+
+  // Loading
+  'loading.loading': 'Loading',
+  'loading.success': 'Done',
+  'loading.error': 'Failed',
+
+  // SliderCaptcha
+  'sliderCaptcha.title': 'Drag slider to finish puzzle',
+  'sliderCaptcha.verifyFailed': 'Verification failed',
+  'sliderCaptcha.verifySuccess': 'Verified',
+
+  // TextInput
+  'textInput.clear': 'Clear input',
+};

package/src/i18n/locales/index.ts

@@ -0,0 +1,19 @@
+import { zhCN } from './zh-CN';
+import { zhTW } from './zh-TW';
+import { ja } from './ja';
+import { enUS } from './en-US';
+import { de } from './de';
+import type { I18nMessages } from '../types';
+
+export const locales: Record<string, I18nMessages> = {
+  'zh-CN': zhCN,
+  'zh-TW': zhTW,
+  ja,
+  'en-US': enUS,
+  de,
+  // 别名
+  zh: zhCN,
+  en: enUS,
+};
+
+export { zhCN, zhTW, ja, enUS, de };

package/src/i18n/locales/ja.ts

@@ -0,0 +1,67 @@
+export const ja = {
+  // Picker
+  'picker.title': '選択',
+  'picker.cancel': 'キャンセル',
+  'picker.confirm': '確認',
+  'picker.empty': '選択できる項目がありません',
+
+  // DatePicker
+  'datePicker.title': '日付を選択',
+  'datePicker.placeholder': '日付を選択',
+  'datePicker.year': '年',
+  'datePicker.month': '月',
+  'datePicker.day': '日',
+
+  // AddressCascader
+  'addressCascader.title': '住所を選択',
+  'addressCascader.province': '都道府県',
+  'addressCascader.city': '市区町村',
+  'addressCascader.district': '町域',
+  'addressCascader.empty': '選択できる住所がありません',
+
+  // BetweenTime
+  'betweenTime.title': '期間を選択',
+  'betweenTime.clear': 'クリア',
+  'betweenTime.startTime': '開始',
+  'betweenTime.endTime': '終了',
+  'betweenTime.to': '〜',
+  'betweenTime.cancel': 'キャンセル',
+  'betweenTime.confirm': '確認',
+  'betweenTime.unit.year': '年',
+  'betweenTime.unit.month': '月',
+  'betweenTime.unit.day': '日',
+  'betweenTime.unit.hour': '時',
+  'betweenTime.unit.minute': '分',
+  'betweenTime.unit.second': '秒',
+  'betweenTime.quick.today': '今日',
+  'betweenTime.quick.thisWeek': '今週',
+  'betweenTime.quick.thisMonth': '今月',
+  'betweenTime.quick.thisYear': '今年',
+  'betweenTime.quick.thisQuarter': '今四半期',
+  'betweenTime.quick.recentDays': '過去{n}日間',
+
+  // ImagePreview
+  'imagePreview.preview': '画像プレビュー',
+  'imagePreview.close': '画像プレビューを閉じる',
+  'imagePreview.loadFailed': '画像の読み込みに失敗しました',
+  'imagePreview.counter': '{total}枚中{current}枚目',
+  'imagePreview.image': '{total}枚中{current}枚目の画像',
+
+  // ActionDialog
+  'actionDialog.confirm': '確認',
+  'actionDialog.cancel': 'キャンセル',
+  'actionDialog.close': 'ダイアログを閉じる',
+
+  // Loading
+  'loading.loading': '読み込み中',
+  'loading.success': '完了',
+  'loading.error': '失敗しました',
+
+  // SliderCaptcha
+  'sliderCaptcha.title': 'スライドで認証',
+  'sliderCaptcha.verifyFailed': '認証失敗',
+  'sliderCaptcha.verifySuccess': '認証成功',
+
+  // TextInput
+  'textInput.clear': '入力をクリア',
+};

package/src/i18n/locales/zh-CN.ts

@@ -0,0 +1,67 @@
+export const zhCN = {
+  // Picker
+  'picker.title': '请选择',
+  'picker.cancel': '取消',
+  'picker.confirm': '确认',
+  'picker.empty': '暂无可选项',
+
+  // DatePicker
+  'datePicker.title': '请选择日期',
+  'datePicker.placeholder': '选择日期',
+  'datePicker.year': '年',
+  'datePicker.month': '月',
+  'datePicker.day': '日',
+
+  // AddressCascader
+  'addressCascader.title': '请选择地址',
+  'addressCascader.province': '省份',
+  'addressCascader.city': '城市',
+  'addressCascader.district': '区县',
+  'addressCascader.empty': '暂无可选地址',
+
+  // BetweenTime
+  'betweenTime.title': '请选择时间',
+  'betweenTime.clear': '清空',
+  'betweenTime.startTime': '开始时间',
+  'betweenTime.endTime': '结束时间',
+  'betweenTime.to': '至',
+  'betweenTime.cancel': '取消',
+  'betweenTime.confirm': '确认',
+  'betweenTime.unit.year': '年',
+  'betweenTime.unit.month': '月',
+  'betweenTime.unit.day': '日',
+  'betweenTime.unit.hour': '时',
+  'betweenTime.unit.minute': '分',
+  'betweenTime.unit.second': '秒',
+  'betweenTime.quick.today': '今天',
+  'betweenTime.quick.thisWeek': '本周',
+  'betweenTime.quick.thisMonth': '本月',
+  'betweenTime.quick.thisYear': '本年',
+  'betweenTime.quick.thisQuarter': '本季度',
+  'betweenTime.quick.recentDays': '最近{n}天',
+
+  // ImagePreview
+  'imagePreview.preview': '图片预览',
+  'imagePreview.close': '关闭图片预览',
+  'imagePreview.loadFailed': '图片加载失败',
+  'imagePreview.counter': '第{current}张，共{total}张',
+  'imagePreview.image': '第{current}张图片，共{total}张',
+
+  // ActionDialog
+  'actionDialog.confirm': '确认',
+  'actionDialog.cancel': '取消',
+  'actionDialog.close': '关闭弹窗',
+
+  // Loading
+  'loading.loading': '正在加载',
+  'loading.success': '已完成',
+  'loading.error': '操作失败',
+
+  // SliderCaptcha
+  'sliderCaptcha.title': '请拖动滑块完成拼图',
+  'sliderCaptcha.verifyFailed': '验证失败，请重试',
+  'sliderCaptcha.verifySuccess': '验证成功',
+
+  // TextInput
+  'textInput.clear': '清空输入',
+};

package/src/i18n/locales/zh-TW.ts

@@ -0,0 +1,67 @@
+export const zhTW = {
+  // Picker
+  'picker.title': '請選擇',
+  'picker.cancel': '取消',
+  'picker.confirm': '確認',
+  'picker.empty': '暫無可選項',
+
+  // DatePicker
+  'datePicker.title': '請選擇日期',
+  'datePicker.placeholder': '選擇日期',
+  'datePicker.year': '年',
+  'datePicker.month': '月',
+  'datePicker.day': '日',
+
+  // AddressCascader
+  'addressCascader.title': '請選擇地址',
+  'addressCascader.province': '省份',
+  'addressCascader.city': '城市',
+  'addressCascader.district': '區縣',
+  'addressCascader.empty': '暫無可選地址',
+
+  // BetweenTime
+  'betweenTime.title': '請選擇時間',
+  'betweenTime.clear': '清空',
+  'betweenTime.startTime': '開始時間',
+  'betweenTime.endTime': '結束時間',
+  'betweenTime.to': '至',
+  'betweenTime.cancel': '取消',
+  'betweenTime.confirm': '確認',
+  'betweenTime.unit.year': '年',
+  'betweenTime.unit.month': '月',
+  'betweenTime.unit.day': '日',
+  'betweenTime.unit.hour': '時',
+  'betweenTime.unit.minute': '分',
+  'betweenTime.unit.second': '秒',
+  'betweenTime.quick.today': '今天',
+  'betweenTime.quick.thisWeek': '本週',
+  'betweenTime.quick.thisMonth': '本月',
+  'betweenTime.quick.thisYear': '本年',
+  'betweenTime.quick.thisQuarter': '本季度',
+  'betweenTime.quick.recentDays': '最近{n}天',
+
+  // ImagePreview
+  'imagePreview.preview': '圖片預覽',
+  'imagePreview.close': '關閉圖片預覽',
+  'imagePreview.loadFailed': '圖片載入失敗',
+  'imagePreview.counter': '第{current}張，共{total}張',
+  'imagePreview.image': '第{current}張圖片，共{total}張',
+
+  // ActionDialog
+  'actionDialog.confirm': '確認',
+  'actionDialog.cancel': '取消',
+  'actionDialog.close': '關閉彈窗',
+
+  // Loading
+  'loading.loading': '正在載入',
+  'loading.success': '已完成',
+  'loading.error': '操作失敗',
+
+  // SliderCaptcha
+  'sliderCaptcha.title': '請拖動滑塊完成拼圖',
+  'sliderCaptcha.verifyFailed': '驗證失敗，請重試',
+  'sliderCaptcha.verifySuccess': '驗證成功',
+
+  // TextInput
+  'textInput.clear': '清空輸入',
+};

package/src/i18n/types.ts

@@ -0,0 +1,21 @@
+// I18nMessages 使用扁平字典，便于：
+// - 接入现有业务多语言系统（通常也是 key-value）
+// - 做静态分析/漏 key 校验（后续可扩展）
+export type I18nMessages = Record<string, string>;
+
+// missingKeyPolicy:
+// - key：找不到 key 时回显 key（避免线上崩溃）
+// - throw：找不到 key 时抛错（更适合开发/测试的 fail-fast）
+export type I18nMissingKeyPolicy = 'key' | 'throw';
+
+export type I18nTranslateParams = Record<string, string | number>;
+
+export type I18nTranslate = (key: string, params?: I18nTranslateParams) => string;
+
+export type I18nContextValue = {
+  // locale 目前主要用于透传；未来可扩展数字/日期格式化等能力
+  locale: string;
+  messages: I18nMessages;
+  missingKeyPolicy: I18nMissingKeyPolicy;
+  t: I18nTranslate;
+};

package/src/i18n/useI18n.ts

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import { I18nContext } from './I18nProvider';
+
+export function useI18n() {
+  return React.useContext(I18nContext);
+}
+