@cogita/plugin-i18n 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 wu9o
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @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.
+
+## Usage
+
+```ts
+import { defineConfig } from '@cogita/core';
+
+export default defineConfig({
+  site: { title: 'My Knowledge Base', lang: 'en-US' },
+  i18n: {
+    locale: 'en-US',
+    fallbackLocale: 'en-US',
+    messages: {
+      'en-US': {
+        'knowledge.home.search': 'Search knowledge',
+      },
+      'zh-CN': {
+        'knowledge.home.search': '搜索知识',
+      },
+    },
+  },
+  theme: '@cogita/theme-knowledge',
+});
+```
+
+Themes and plugins can import `virtual-cogita-i18n-text`:
+
+```ts
+import { t } from 'virtual-cogita-i18n-text';
+
+const label = t('knowledge.home.search', 'Search knowledge');
+```
+
+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.

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import type { CogitaPlugin } from '@cogita/shared';
+import type { CogitaPluginConfig } from '@cogita/shared';
+import type { I18nConfig } from '@cogita/shared';
+
+/** 生成供主题和第三方组件导入的虚拟国际化模块。 */
+export declare function createI18nRuntimeModule(config: ResolvedI18nConfig): string;
+
+export { I18nConfig }
+
+/** 国际化运行时可以消费的文案字典。 */
+export declare type I18nMessages = Readonly<Record<string, Readonly<Record<string, string>>>>;
+
+/** 文案插值变量。 */
+export declare type I18nValues = Readonly<Record<string, string | number>>;
+
+/** 规范化语言标识，兼容 `en_US` 这类常见配置写法。 */
+export declare function normalizeLocale(locale: unknown, fallback?: string): string;
+
+/** 只保留可安全注入浏览器运行时的文案字典。 */
+export declare function normalizeMessages(value: unknown): I18nMessages;
+
+/** 创建站点界面文案国际化插件。 */
+declare function pluginI18n(config: CogitaPluginConfig): CogitaPlugin | null;
+export default pluginI18n;
+export { pluginI18n }
+
+/** 规范化后的国际化配置。 */
+export declare interface ResolvedI18nConfig {
+    enabled: boolean;
+    locale: string;
+    fallbackLocale: string;
+    messages: I18nMessages;
+}
+
+/** 解析国际化配置，默认以英文作为当前语言和回退语言。 */
+export declare function resolveI18nConfig(config?: I18nConfig, siteLocale?: string): ResolvedI18nConfig;
+
+/** 读取一个翻译值，供 Node 侧测试和工具复用相同的回退规则。 */
+export declare function resolveMessage(messages: I18nMessages, locale: string, fallbackLocale: string, key: string, fallback?: string, values?: I18nValues): string;
+
+export { }

package/dist/index.js

@@ -0,0 +1,3 @@
+import { pluginI18n } from "./plugin.js";
+import { createI18nRuntimeModule, normalizeLocale, normalizeMessages, resolveI18nConfig, resolveMessage } from "./utils.js";
+export { createI18nRuntimeModule, pluginI18n as default, normalizeLocale, normalizeMessages, pluginI18n, resolveI18nConfig, resolveMessage };

package/dist/plugin.js

@@ -0,0 +1,26 @@
+import { COGITA_CAPABILITIES, COGITA_VIRTUAL_MODULE_IDS, createCogitaVirtualModule, getCogitaLogger } from "@cogita/shared";
+import { createI18nRuntimeModule, resolveI18nConfig } from "./utils.js";
+function pluginI18n(config) {
+    const logger = getCogitaLogger(config);
+    if (!config.i18n || false === config.i18n.enabled) {
+        logger.info("[I18n Plugin] \u672A\u627E\u5230\u56FD\u9645\u5316\u914D\u7F6E\uFF0C\u8DF3\u8FC7\u754C\u9762\u6587\u6848\u56FD\u9645\u5316");
+        return null;
+    }
+    const finalConfig = resolveI18nConfig(config.i18n, config.site?.lang);
+    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',
+        cogita: {
+            providesCapabilities: [
+                COGITA_CAPABILITIES.UI_I18N
+            ]
+        },
+        addRuntimeModules () {
+            return {
+                [COGITA_VIRTUAL_MODULE_IDS.I18N_TEXT]: createCogitaVirtualModule(createI18nRuntimeModule(finalConfig))
+            };
+        }
+    };
+}
+const src_plugin = pluginI18n;
+export { src_plugin as default, pluginI18n };

package/dist/utils.js

@@ -0,0 +1,72 @@
+function normalizeLocale(locale, fallback = 'en-US') {
+    if ('string' != typeof locale) return fallback;
+    const normalized = locale.trim().replace(/_/g, '-');
+    return normalized || fallback;
+}
+function normalizeMessages(value) {
+    if (!value || 'object' != typeof value || Array.isArray(value)) return {};
+    const messages = {};
+    for (const [locale, dictionary] of Object.entries(value)){
+        if (!dictionary || 'object' != typeof dictionary || Array.isArray(dictionary)) continue;
+        const normalizedDictionary = Object.fromEntries(Object.entries(dictionary).filter(([, text])=>'string' == typeof text));
+        if (Object.keys(normalizedDictionary).length > 0) messages[normalizeLocale(locale)] = normalizedDictionary;
+    }
+    return messages;
+}
+function resolveI18nConfig(config, siteLocale) {
+    const fallbackLocale = normalizeLocale(config?.fallbackLocale, 'en-US');
+    return {
+        enabled: config?.enabled !== false,
+        locale: normalizeLocale(config?.locale, normalizeLocale(siteLocale, 'en-US')),
+        fallbackLocale,
+        messages: normalizeMessages(config?.messages)
+    };
+}
+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;
+
+function getLocaleCandidates(value) {
+  return value ? [value, value.split('-')[0]] : [];
+}
+
+function getMessage(key, candidates) {
+  for (const candidate of candidates) {
+    const dictionary = messages[candidate];
+    if (dictionary && typeof dictionary[key] === 'string') return dictionary[key];
+  }
+  return undefined;
+}
+
+export function t(key, fallback, values) {
+  const candidates = [...getLocaleCandidates(locale), ...getLocaleCandidates(fallbackLocale)];
+  let text = getMessage(key, candidates) || fallback || key;
+  for (const [name, value] of Object.entries(values || {})) {
+    text = text.split('{{' + name + '}}').join(String(value));
+  }
+  return text;
+}
+
+export const translate = t;
+`;
+}
+function resolveMessage(messages, locale, fallbackLocale, key, fallback = '', values = {}) {
+    const candidates = [
+        ...getLocaleCandidates(locale),
+        ...getLocaleCandidates(fallbackLocale)
+    ];
+    const message = candidates.map((candidate)=>messages[candidate]?.[key]).find((candidate)=>'string' == typeof candidate);
+    let text = message ?? (fallback || key);
+    for (const [name, value] of Object.entries(values))text = text.split(`{{${name}}}`).join(String(value));
+    return text;
+}
+function getLocaleCandidates(locale) {
+    return locale ? [
+        locale,
+        locale.split('-')[0]
+    ] : [];
+}
+export { createI18nRuntimeModule, normalizeLocale, normalizeMessages, resolveI18nConfig, resolveMessage };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@cogita/plugin-i18n",
+  "version": "0.2.0",
+  "description": "为 Cogita 主题提供英文优先的界面文案国际化能力。",
+  "keywords": [
+    "cogita",
+    "plugin",
+    "i18n",
+    "internationalization",
+    "localization",
+    "rspress"
+  ],
+  "author": "wu9o <https://github.com/wu9o>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wu9o/cogita.git",
+    "directory": "plugins/i18n"
+  },
+  "bugs": {
+    "url": "https://github.com/wu9o/cogita/issues"
+  },
+  "homepage": "https://github.com/wu9o/cogita/tree/main/plugins/i18n#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@cogita/shared": "0.13.0"
+  },
+  "devDependencies": {
+    "@rslib/core": "0.11.2",
+    "@rspress/core": "^1.45.1",
+    "rsbuild-plugin-publint": "^0.3.3",
+    "typescript": "^5.0.4"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build -w",
+    "clean": "rm -rf dist",
+    "test": "pnpm build && node --test tests/*.test.mjs"
+  }
+}