feat(browserUtils): 添加获取语言国家信息和公共IP的功能

新增 getLocaleInfo 和 getCommonLocaleTable 方法用于获取语言国家信息
改进 getPublicIP 方法增加超时和重试机制
更新相关文档和测试用例

Author: webkubor

docs/guide/api-browser.md

@@ -117,6 +117,42 @@ browserUtils.scrollToTop()
 ```
 :::
 
+## 语言与国家对照（Locale Table）
+- `browserUtils.getLocaleInfo(locale?)` → 返回语言/国家的规范信息
+- `browserUtils.getCommonLocaleTable()` → 常用 Locale 列表（语言/国家英文名）
+
+::: code-group
+```ts [Example]
+import { browserUtils } from 'nex-lib'
+browserUtils.getLocaleInfo('zh-CN')
+browserUtils.getLocaleInfo('en-GB')
+browserUtils.getCommonLocaleTable()
+```
+```json [Output]
+{"code":"zh-CN","language":{"code":"zh","name":"Chinese"},"country":{"code":"CN","name":"China"}}
+{"code":"en-GB","language":{"code":"en","name":"English"},"country":{"code":"GB","name":"United Kingdom"}}
+[
+  {"code":"zh-CN","language":"Chinese","country":"China"},
+  {"code":"en-US","language":"English","country":"United States"},
+  {"code":"ja-JP","language":"Japanese","country":"Japan"},
+  {"code":"ko-KR","language":"Korean","country":"South Korea"}
+]
+```
+:::
+
+## IP 获取（Public IP）
+- `browserUtils.getPublicIP()` → 返回公网 IP 字符串（内置超时与重试）
+
+::: code-group
+```ts [Example]
+import { browserUtils } from 'nex-lib'
+const ip = await browserUtils.getPublicIP()
+```
+```text [Output]
+"203.0.113.42"
+```
+:::
+
 ## 主题（Dark/Light）与监听
 - `browserUtils.isDarkMode()` → `boolean`
 - `browserUtils.getTheme()` → `'dark' | 'light'`

docs/scenarios/react.md

@@ -162,4 +162,55 @@ export default function Theme() {
   return null
 }
 ```
+:::
+
+## 国际化（IP/语言/时区）
+
+::: info I18n Highlights
+- 自动 Locale 与语言/国家英文名
+- 本地时区与 UTC 偏移
+- 一行获取公共 IP（带超时与重试）
+- 示例展示统一 JSON 输出
+:::
+
+::: code-group
+```jsx [JS]
+import { useEffect, useState } from 'react'
+import { browserUtils, TimeUtils } from 'nex-lib'
+export default function I18nInfo() {
+  const [info, setInfo] = useState({ ip: '-', locale: '', language: '', country: '', timezone: '', offsetMin: 0, languages: '' })
+  useEffect(() => {
+    (async () => {
+      // 浏览器首选语言（规范化），以及语言/国家英文名
+      const locale = browserUtils.getPreferredLocale()
+      const li = browserUtils.getLocaleInfo(locale)
+      // 本地时区与与 UTC 的分钟偏移
+      const timezone = TimeUtils.getTimezone()
+      const offsetMin = TimeUtils.getTimezoneOffsetMinutes()
+      const ip = await browserUtils.getPublicIP()
+      setInfo({ ip, locale: li.code, language: li.language.name, country: li.country.name || '', timezone, offsetMin, languages: browserUtils.getLanguage() })
+    })()
+  }, [])
+  return <pre>{JSON.stringify(info, null, 2)}</pre>
+}
+```
+```tsx
+import { useEffect, useState } from 'react'
+import { browserUtils, TimeUtils } from 'nex-lib'
+type Info = { ip: string; locale: string; language: string; country: string; timezone: string; offsetMin: number; languages: string }
+export default function I18nInfo() {
+  const [info, setInfo] = useState<Info>({ ip: '-', locale: '', language: '', country: '', timezone: '', offsetMin: 0, languages: '' })
+  useEffect(() => {
+    (async () => {
+      const locale = browserUtils.getPreferredLocale()
+      const li = browserUtils.getLocaleInfo(locale)
+      const timezone = TimeUtils.getTimezone()
+      const offsetMin = TimeUtils.getTimezoneOffsetMinutes()
+      const ip = await browserUtils.getPublicIP()
+      setInfo({ ip, locale: li.code, language: li.language.name, country: li.country.name || '', timezone, offsetMin, languages: browserUtils.getLanguage() })
+    })()
+  }, [])
+  return <pre>{JSON.stringify(info, null, 2)}</pre>
+}
+```
 :::

docs/scenarios/vue.md

@@ -113,4 +113,41 @@ document.documentElement.style.setProperty('--btn-bg', btnBg)
 document.documentElement.style.setProperty('--block-bg', blockBg)
 document.documentElement.style.setProperty('--text', textColor)
 ```
+:::
+
+## 国际化（IP/语言/时区）
+
+::: info I18n Highlights
+- 自动 Locale 与语言/国家英文名
+- 本地时区与 UTC 偏移
+- 一行获取公共 IP（带超时与重试）
+- 示例展示统一 JSON 输出
+:::
+
+::: code-group
+```js [JS]
+import { browserUtils, TimeUtils } from 'nex-lib'
+const locale = browserUtils.getPreferredLocale()
+const li = browserUtils.getLocaleInfo(locale)
+const timezone = TimeUtils.getTimezone()
+const offsetMin = TimeUtils.getTimezoneOffsetMinutes()
+const ip = await browserUtils.getPublicIP()
+const info = { ip, locale: li.code, language: li.language.name, country: li.country.name || '', timezone, offsetMin, languages: browserUtils.getLanguage() }
+// 渲染到页面：<pre id="i18n">...</pre>
+document.querySelector('#i18n').textContent = JSON.stringify(info, null, 2)
+```
+```ts
+import { ref, onMounted } from 'vue'
+import { browserUtils, TimeUtils } from 'nex-lib'
+type Info = { ip: string; locale: string; language: string; country: string; timezone: string; offsetMin: number; languages: string }
+const info = ref<Info>({ ip: '-', locale: '', language: '', country: '', timezone: '', offsetMin: 0, languages: '' })
+onMounted(async () => {
+  const locale = browserUtils.getPreferredLocale()
+  const li = browserUtils.getLocaleInfo(locale)
+  const timezone = TimeUtils.getTimezone()
+  const offsetMin = TimeUtils.getTimezoneOffsetMinutes()
+  const ip = await browserUtils.getPublicIP()
+  info.value = { ip, locale: li.code, language: li.language.name, country: li.country.name || '', timezone, offsetMin, languages: browserUtils.getLanguage() }
+})
+```
 :::

src/browserUtils.ts

@@ -1,3 +1,9 @@
+const LANGUAGE_NAMES: Record<string, string> = {
+    en: 'English', zh: 'Chinese', ja: 'Japanese', ko: 'Korean', de: 'German', fr: 'French', es: 'Spanish', it: 'Italian', pt: 'Portuguese', ru: 'Russian', ar: 'Arabic', hi: 'Hindi', th: 'Thai', vi: 'Vietnamese', id: 'Indonesian', nl: 'Dutch', sv: 'Swedish', pl: 'Polish', tr: 'Turkish', he: 'Hebrew', cs: 'Czech', hu: 'Hungarian', ro: 'Romanian', sk: 'Slovak', uk: 'Ukrainian', el: 'Greek', nb: 'Norwegian', da: 'Danish', fi: 'Finnish'
+};
+const COUNTRY_NAMES: Record<string, string> = {
+    US: 'United States', GB: 'United Kingdom', CN: 'China', TW: 'Taiwan', HK: 'Hong Kong', JP: 'Japan', KR: 'South Korea', DE: 'Germany', FR: 'France', ES: 'Spain', IT: 'Italy', BR: 'Brazil', PT: 'Portugal', RU: 'Russia', SA: 'Saudi Arabia', IN: 'India', TH: 'Thailand', VN: 'Vietnam', ID: 'Indonesia', NL: 'Netherlands', SE: 'Sweden', PL: 'Poland', TR: 'Turkey', IL: 'Israel', CZ: 'Czech Republic', HU: 'Hungary', RO: 'Romania', SK: 'Slovakia', UA: 'Ukraine', GR: 'Greece', NO: 'Norway', DK: 'Denmark', FI: 'Finland', MX: 'Mexico', CA: 'Canada', AU: 'Australia', NZ: 'New Zealand', IE: 'Ireland', SG: 'Singapore'
+};
 const browserUtils = {
 
     isBrowser: () => typeof window !== 'undefined',
@@ -44,8 +50,16 @@ const browserUtils = {
         return window.getSelection().toString();
     },
 
-    async getPublicIP(): Promise<any> {
-        return fetch('https://api.ipify.org?format=json')
+    async getPublicIP(): Promise<string> {
+        try {
+            const r: any = await Http.get('https://api.ipify.org?format=json', { timeoutMs: 3000, retry: 2 });
+            if (r && typeof r.ip === 'string') return r.ip;
+        } catch {}
+        try {
+            const r: any = await Http.get('https://api.myip.com', { timeoutMs: 3000, retry: 2 });
+            if (r && typeof r.ip === 'string') return r.ip;
+        } catch {}
+        return '';
     },
 
     async copyToClipboard(text: string): Promise<boolean> {
@@ -181,8 +195,27 @@ const browserUtils = {
         window.addEventListener('resize', fn);
         fn();
         return () => window.removeEventListener('resize', fn);
+    },
+
+    getLocaleInfo(locale?: string): { code: string; language: { code: string; name: string }; country: { code?: string; name?: string } } {
+        const raw = (locale || (this as any).getPreferredLocale()).replace('_', '-');
+        const parts = raw.split('-');
+        const lang = (parts[0] || '').toLowerCase();
+        const region = parts[1] ? parts[1].toUpperCase() : undefined;
+        const languageName = LANGUAGE_NAMES[lang] || lang;
+        const countryName = region ? (COUNTRY_NAMES[region!] || region) : undefined;
+        return { code: region ? `${lang}-${region}` : lang, language: { code: lang, name: languageName }, country: { code: region, name: countryName } };
+    },
+
+    getCommonLocaleTable(): { code: string; language: string; country: string }[] {
+        const codes = ['zh-CN','zh-TW','zh-HK','en-US','en-GB','ja-JP','ko-KR','de-DE','fr-FR','es-ES','it-IT','pt-BR','pt-PT','ru-RU','ar-SA','hi-IN','th-TH','vi-VN','id-ID','nl-NL','sv-SE','pl-PL','tr-TR','he-IL','cs-CZ','hu-HU','ro-RO','sk-SK','uk-UA','el-GR','nb-NO','da-DK','fi-FI','es-MX','en-CA','en-AU','en-NZ','en-IE','zh-SG'];
+        return codes.map((c) => {
+            const info = (this as any).getLocaleInfo(c);
+            return { code: info.code, language: info.language.name, country: info.country.name || '' };
+        });
     }
 
 }
 
-export default browserUtils
+export default browserUtils
+import Http from './Http'

test/browserUtils.test.ts

@@ -10,6 +10,18 @@ describe('browserUtils', () => {
     expect(typeof browserUtils.getLanguage()).toBe('string');
   });
 
+  it('locale info and table', () => {
+    const zh = browserUtils.getLocaleInfo('zh-CN');
+    const en = browserUtils.getLocaleInfo('en-GB');
+    expect(zh.language.name).toBe('Chinese');
+    expect(zh.country?.name).toBe('China');
+    expect(en.language.name).toBe('English');
+    expect(en.country?.name).toBe('United Kingdom');
+    const table = browserUtils.getCommonLocaleTable();
+    expect(Array.isArray(table)).toBe(true);
+    expect(table.length).toBeGreaterThan(10);
+  });
+
   it('viewport/screen/DPR/mobile flag', () => {
     const vp = browserUtils.getViewportSize();
     const sc = browserUtils.getScreenSize();