@cogita/plugin-i18n 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @cogita/plugin-i18n
 
-Lightweight locale-aware UI copy for Cogita themes and third-party components. The plugin injects a message dictionary at build time; it does not translate Markdown content. Content language remains a site-level choice.
+Lightweight locale-aware UI copy for Cogita themes and third-party components. The plugin injects a message dictionary at build time and renders a language switcher when more than one locale is configured. Markdown content remains a site-level choice and should be authored or built as localized content separately.
 
 ## Usage
 
@@ -33,4 +33,10 @@ import { t } from 'virtual-cogita-i18n-text';
 const label = t('knowledge.home.search', 'Search knowledge');
 ```
 
+When two or more message dictionaries are configured, the plugin adds a small global language switcher. The selected locale is stored in the browser and mirrored in the `lang` query parameter so a preview can be shared.
+
+Set `showSwitcher: false` when the host theme already renders a native locale menu, such as an Rspress documentation site. For a site that publishes localized content incrementally, set `contentFallback: true` together with the Rspress `locales` config. Missing localized Markdown routes then reuse the default-language source until a file such as `content/zh-CN/guides/intro.md` is added. Existing localized files always win over the fallback route.
+
 Locale resolution checks the full identifier first (for example, `en-US`), then the language prefix (for example, `en`), and finally `fallbackLocale`. When no message is found, the caller-provided fallback is used, so older sites remain safe when the plugin is not enabled.
+
+The content fallback only keeps locale routes reachable; it does not claim that the fallback page is translated. Article titles, Markdown, and user-provided metadata remain site-level content.

package/dist/index.d.ts

@@ -27,6 +27,7 @@ export { pluginI18n }
 /** 规范化后的国际化配置。 */
 export declare interface ResolvedI18nConfig {
     enabled: boolean;
+    showSwitcher: boolean;
     locale: string;
     fallbackLocale: string;
     messages: I18nMessages;

package/dist/plugin.js

@@ -1,4 +1,8 @@
+import { existsSync } from "node:fs";
+import node_path from "node:path";
+import { fileURLToPath } from "node:url";
 import { COGITA_CAPABILITIES, COGITA_VIRTUAL_MODULE_IDS, createCogitaVirtualModule, getCogitaLogger } from "@cogita/shared";
+import { glob } from "glob";
 import { createI18nRuntimeModule, resolveI18nConfig } from "./utils.js";
 function pluginI18n(config) {
     const logger = getCogitaLogger(config);
@@ -7,6 +11,7 @@ function pluginI18n(config) {
         return null;
     }
     const finalConfig = resolveI18nConfig(config.i18n, config.site?.lang);
+    const pluginDirectory = node_path.dirname(fileURLToPath(import.meta.url));
     logger.info(`[I18n Plugin] \u{4F7F}\u{7528} ${finalConfig.locale} \u{754C}\u{9762}\u{6587}\u{6848}\u{FF0C}\u{56DE}\u{9000}\u{8BED}\u{8A00}\u{4E3A} ${finalConfig.fallbackLocale}`);
     return {
         name: '@cogita/plugin-i18n',
@@ -15,6 +20,37 @@ function pluginI18n(config) {
                 COGITA_CAPABILITIES.UI_I18N
             ]
         },
+        globalUIComponents: finalConfig.showSwitcher ? [
+            node_path.resolve(pluginDirectory, './switcher.js')
+        ] : void 0,
+        async addPages (_rspressConfig, _isProd) {
+            if (!config.i18n?.contentFallback || !config.contentDir || !config.locales?.length) return [];
+            const defaultLocale = config.site?.lang || config.locales[0]?.lang;
+            const localizedLocales = config.locales.map((locale)=>locale.lang).filter((locale)=>locale && locale !== defaultLocale);
+            if (!defaultLocale || 0 === localizedLocales.length) return [];
+            const contentRoot = node_path.resolve(config.root, config.contentDir);
+            const files = await glob('**/*.{md,mdx}', {
+                absolute: true,
+                cwd: contentRoot,
+                ignore: config.locales.map((locale)=>`${locale.lang}/**`),
+                nodir: true
+            });
+            const fallbackPages = [];
+            for (const filePath of files){
+                const relativePath = node_path.relative(contentRoot, filePath);
+                const routePath = relativePath.replace(/\.(md|mdx)$/i, '').replace(/(^|[/\\])index$/i, '$1').split(node_path.sep).join('/');
+                const normalizedRoute = routePath ? `/${routePath}` : '/';
+                for (const locale of localizedLocales){
+                    const localizedFile = node_path.join(contentRoot, locale, relativePath);
+                    if (!existsSync(localizedFile)) fallbackPages.push({
+                        routePath: `/${locale}${'/' === normalizedRoute ? '/' : normalizedRoute}`,
+                        filepath: filePath
+                    });
+                }
+            }
+            if (fallbackPages.length > 0) logger.info(`[I18n Plugin] \u{4E3A} ${fallbackPages.length} \u{4E2A}\u{672A}\u{7FFB}\u{8BD1}\u{5185}\u{5BB9}\u{9875}\u{9762}\u{751F}\u{6210}\u{9ED8}\u{8BA4}\u{8BED}\u{8A00}\u{56DE}\u{9000}\u{8DEF}\u{7531}`);
+            return fallbackPages;
+        },
         addRuntimeModules () {
             return {
                 [COGITA_VIRTUAL_MODULE_IDS.I18N_TEXT]: createCogitaVirtualModule(createI18nRuntimeModule(finalConfig))

package/dist/switcher.js

@@ -0,0 +1,51 @@
+import react, { useState } from "react";
+import { getLocale, setLocale, supportedLocales, t } from "virtual-cogita-i18n-text";
+const localeLabels = {
+    'en-US': 'English',
+    'zh-CN': "\u4E2D\u6587"
+};
+function LanguageSwitcher() {
+    const [currentLocale, setCurrentLocale] = useState(getLocale);
+    if (supportedLocales.length < 2) return null;
+    return /*#__PURE__*/ react.createElement("div", {
+        "aria-label": t('i18n.switcher.label', 'Language'),
+        style: {
+            position: 'fixed',
+            bottom: 16,
+            right: 16,
+            zIndex: 1000,
+            display: 'inline-flex',
+            gap: 2,
+            padding: 3,
+            border: '1px solid var(--cogita-i18n-border, #e4e8f0)',
+            borderRadius: 999,
+            background: 'var(--cogita-i18n-surface, rgba(255, 255, 255, 0.92))',
+            boxShadow: '0 8px 24px rgba(29, 48, 91, 0.08)',
+            backdropFilter: 'blur(12px)'
+        }
+    }, supportedLocales.map((supportedLocale)=>{
+        const active = supportedLocale === currentLocale;
+        return /*#__PURE__*/ react.createElement("button", {
+            key: supportedLocale,
+            type: "button",
+            "aria-pressed": active,
+            onClick: ()=>{
+                setCurrentLocale(supportedLocale);
+                setLocale(supportedLocale);
+            },
+            style: {
+                minHeight: 28,
+                padding: '0 9px',
+                border: 0,
+                borderRadius: 999,
+                background: active ? 'var(--cogita-i18n-accent, #315efb)' : 'transparent',
+                color: active ? '#fff' : 'var(--cogita-i18n-text, #172033)',
+                cursor: 'pointer',
+                font: 'inherit',
+                fontSize: 12,
+                fontWeight: 700
+            }
+        }, localeLabels[supportedLocale] || supportedLocale);
+    }));
+}
+export { LanguageSwitcher as default };

package/dist/utils.js

@@ -17,6 +17,7 @@ function resolveI18nConfig(config, siteLocale) {
     const fallbackLocale = normalizeLocale(config?.fallbackLocale, 'en-US');
     return {
         enabled: config?.enabled !== false,
+        showSwitcher: config?.showSwitcher !== false,
         locale: normalizeLocale(config?.locale, normalizeLocale(siteLocale, 'en-US')),
         fallbackLocale,
         messages: normalizeMessages(config?.messages)
@@ -25,9 +26,33 @@ function resolveI18nConfig(config, siteLocale) {
 function createI18nRuntimeModule(config) {
     const serializedConfig = JSON.stringify(config);
     return `export const i18nConfig = ${serializedConfig};
-export const locale = i18nConfig.locale;
 export const fallbackLocale = i18nConfig.fallbackLocale;
 export const messages = i18nConfig.messages;
+export const supportedLocales = Object.keys(messages);
+const localeStorageKey = 'cogita-locale';
+
+function normalizeRuntimeLocale(value) {
+  return typeof value === 'string' ? value.trim().replace(/_/g, '-') : '';
+}
+
+function isSupportedLocale(value) {
+  return supportedLocales.includes(value);
+}
+
+export function getLocale() {
+  if (typeof window === 'undefined') return i18nConfig.locale;
+  const queryLocale = normalizeRuntimeLocale(new URLSearchParams(window.location.search).get('lang'));
+  if (isSupportedLocale(queryLocale)) return queryLocale;
+  try {
+    const storedLocale = normalizeRuntimeLocale(window.localStorage.getItem(localeStorageKey));
+    if (isSupportedLocale(storedLocale)) return storedLocale;
+  } catch {
+    // \u{6D4F}\u{89C8}\u{5668}\u{7981}\u{7528}\u{5B58}\u{50A8}\u{65F6}\u{7EE7}\u{7EED}\u{4F7F}\u{7528}\u{6784}\u{5EFA}\u{671F}\u{8BED}\u{8A00}\u{3002}
+  }
+  return i18nConfig.locale;
+}
+
+export const locale = getLocale();
 
 function getLocaleCandidates(value) {
   return value ? [value, value.split('-')[0]] : [];
@@ -42,7 +67,7 @@ function getMessage(key, candidates) {
 }
 
 export function t(key, fallback, values) {
-  const candidates = [...getLocaleCandidates(locale), ...getLocaleCandidates(fallbackLocale)];
+  const candidates = [...getLocaleCandidates(getLocale()), ...getLocaleCandidates(fallbackLocale)];
   let text = getMessage(key, candidates) || fallback || key;
   for (const [name, value] of Object.entries(values || {})) {
     text = text.split('{{' + name + '}}').join(String(value));
@@ -50,6 +75,19 @@ export function t(key, fallback, values) {
   return text;
 }
 
+export function setLocale(nextLocale) {
+  const normalizedLocale = normalizeRuntimeLocale(nextLocale);
+  if (!isSupportedLocale(normalizedLocale) || typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(localeStorageKey, normalizedLocale);
+  } catch {
+    // \u{6D4F}\u{89C8}\u{5668}\u{7981}\u{7528}\u{5B58}\u{50A8}\u{65F6}\u{4ECD}\u{7136}\u{901A}\u{8FC7} URL \u{53C2}\u{6570}\u{5B8C}\u{6210}\u{672C}\u{6B21}\u{5207}\u{6362}\u{3002}
+  }
+  const url = new URL(window.location.href);
+  url.searchParams.set('lang', normalizedLocale);
+  window.location.assign(url.href);
+}
+
 export const translate = t;
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogita/plugin-i18n",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "为 Cogita 主题提供英文优先的界面文案国际化能力。",
   "keywords": [
     "cogita",
@@ -27,6 +27,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./switcher": {
+      "import": "./dist/switcher.js",
+      "default": "./dist/switcher.js"
     }
   },
   "main": "./dist/index.js",
@@ -41,11 +45,17 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "glob": "^11.0.3",
     "@cogita/shared": "0.13.0"
   },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
   "devDependencies": {
     "@rslib/core": "0.11.2",
     "@rspress/core": "^1.45.1",
+    "@types/react": "^19.1.9",
+    "react": "^19.1.1",
     "rsbuild-plugin-publint": "^0.3.3",
     "typescript": "^5.0.4"
   },