@f5xc-salesdemos/pi-utils 19.18.6 → 19.19.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/pi-utils",
-	"version": "19.18.6",
+	"version": "19.19.0",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -38,7 +38,7 @@
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3",
-		"@f5xc-salesdemos/pi-natives": "19.18.6"
+		"@f5xc-salesdemos/pi-natives": "19.19.0"
 	},
 	"engines": {
 		"bun": ">=1.3.7"

package/src/i18n.test.ts

@@ -0,0 +1,155 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { getLocale, initI18n, mapToSupportedLocale, registerLocales, setLocale, t } from "./i18n";
+
+const EN = {
+	greeting: "Hello",
+	"greeting.with.name": "Hello, {name}!",
+	"items.count.one": "{count} item",
+	"items.count.other": "{count} items",
+	"error.notFound": "File not found: {path}",
+};
+
+const JA = {
+	greeting: "こんにちは",
+	"greeting.with.name": "こんにちは、{name}さん！",
+	"items.count.one": "{count}個のアイテム",
+	"items.count.other": "{count}個のアイテム",
+	"error.notFound": "ファイルが見つかりません: {path}",
+};
+
+describe("i18n", () => {
+	beforeEach(() => {
+		registerLocales({ en: EN, ja: JA });
+		setLocale("en");
+	});
+
+	test("t() returns English string by key", () => {
+		expect(t("greeting")).toBe("Hello");
+	});
+
+	test("t() interpolates parameters", () => {
+		expect(t("greeting.with.name", { name: "World" })).toBe("Hello, World!");
+	});
+
+	test("t() falls back to key when key is missing", () => {
+		expect(t("nonexistent.key")).toBe("nonexistent.key");
+	});
+
+	test("t() handles plural: one", () => {
+		expect(t("items.count", { count: 1 })).toBe("1 item");
+	});
+
+	test("t() handles plural: other", () => {
+		expect(t("items.count", { count: 5 })).toBe("5 items");
+	});
+
+	test("setLocale() switches to Japanese", () => {
+		setLocale("ja");
+		expect(t("greeting")).toBe("こんにちは");
+		expect(t("greeting.with.name", { name: "太郎" })).toBe("こんにちは、太郎さん！");
+	});
+
+	test("getLocale() returns current locale", () => {
+		expect(getLocale()).toBe("en");
+		setLocale("ja");
+		expect(getLocale()).toBe("ja");
+	});
+
+	test("falls back to base locale (ja-jp -> ja)", () => {
+		setLocale("ja-jp");
+		expect(t("greeting")).toBe("こんにちは");
+	});
+
+	test("falls back to English for unknown locale", () => {
+		setLocale("xx");
+		expect(t("greeting")).toBe("Hello");
+	});
+
+	test("normalizes locale with underscores", () => {
+		setLocale("ja_JP");
+		expect(getLocale()).toBe("ja");
+		expect(t("greeting")).toBe("こんにちは");
+	});
+
+	test("handles locale with encoding suffix", () => {
+		setLocale("ja_JP.UTF-8");
+		expect(getLocale()).toBe("ja");
+		expect(t("greeting")).toBe("こんにちは");
+	});
+
+	test("interpolation leaves unmatched placeholders", () => {
+		expect(t("error.notFound", { path: "/foo" })).toBe("File not found: /foo");
+		expect(t("greeting.with.name", {})).toBe("Hello, {name}!");
+	});
+
+	test("initI18n() defaults to en when no env vars set", () => {
+		const oldLang = Bun.env.LANG;
+		const oldXcsh = Bun.env.XCSH_LOCALE;
+		delete Bun.env.LANG;
+		delete Bun.env.XCSH_LOCALE;
+		initI18n();
+		expect(getLocale()).toBe("en");
+		if (oldLang) Bun.env.LANG = oldLang;
+		if (oldXcsh) Bun.env.XCSH_LOCALE = oldXcsh;
+	});
+
+	test("initI18n() reads XCSH_LOCALE env var", () => {
+		Bun.env.XCSH_LOCALE = "ja";
+		initI18n();
+		expect(getLocale()).toBe("ja");
+		delete Bun.env.XCSH_LOCALE;
+		setLocale("en");
+	});
+
+	test("initI18n() prefers explicit locale argument", () => {
+		Bun.env.XCSH_LOCALE = "ja";
+		initI18n("en");
+		expect(getLocale()).toBe("en");
+		delete Bun.env.XCSH_LOCALE;
+	});
+});
+
+describe("mapToSupportedLocale", () => {
+	beforeEach(() => {
+		registerLocales({ en: EN, ja: JA, "zh-cn": {}, "zh-tw": {}, "pt-br": {}, fr: {}, de: {} });
+		setLocale("en");
+	});
+
+	test("exact match", () => {
+		expect(mapToSupportedLocale("ja")).toBe("ja");
+		expect(mapToSupportedLocale("en")).toBe("en");
+	});
+
+	test("regional variant maps to base", () => {
+		expect(mapToSupportedLocale("en-US")).toBe("en");
+		expect(mapToSupportedLocale("ja-JP")).toBe("ja");
+		expect(mapToSupportedLocale("fr-FR")).toBe("fr");
+		expect(mapToSupportedLocale("de-DE")).toBe("de");
+	});
+
+	test("regional variant with exact match", () => {
+		expect(mapToSupportedLocale("pt-BR")).toBe("pt-br");
+		expect(mapToSupportedLocale("zh-CN")).toBe("zh-cn");
+		expect(mapToSupportedLocale("zh-TW")).toBe("zh-tw");
+	});
+
+	test("Apple zh-Hans maps to zh-cn", () => {
+		expect(mapToSupportedLocale("zh-Hans")).toBe("zh-cn");
+		expect(mapToSupportedLocale("zh-Hans-CN")).toBe("zh-cn");
+	});
+
+	test("Apple zh-Hant maps to zh-tw", () => {
+		expect(mapToSupportedLocale("zh-Hant")).toBe("zh-tw");
+		expect(mapToSupportedLocale("zh-Hant-TW")).toBe("zh-tw");
+	});
+
+	test("underscore format", () => {
+		expect(mapToSupportedLocale("pt_BR")).toBe("pt-br");
+		expect(mapToSupportedLocale("ja_JP.UTF-8")).toBe("ja");
+	});
+
+	test("unsupported locale returns undefined", () => {
+		expect(mapToSupportedLocale("xx")).toBeUndefined();
+		expect(mapToSupportedLocale("sv-SE")).toBeUndefined();
+	});
+});

package/src/i18n.ts

@@ -0,0 +1,111 @@
+import { $pickenv } from "./env";
+
+type LocaleMap = Record<string, string>;
+type LocaleBundle = Record<string, LocaleMap>;
+
+let currentLocale = "en";
+let bundles: LocaleBundle = {};
+let active: LocaleMap = {};
+
+/**
+ * Register all locale bundles. Call once at startup before any t() calls.
+ * Keys are locale codes ("en", "ja", "zh-cn"), values are flat key→string maps.
+ */
+export function registerLocales(localeBundle: LocaleBundle): void {
+	bundles = localeBundle;
+	active = resolveBundle(currentLocale);
+}
+
+/**
+ * Initialize i18n from environment / config.
+ * Priority: explicit locale arg > XCSH_LOCALE env > PI_LOCALE env > LANG env > "en"
+ */
+export function initI18n(locale?: string): void {
+	const resolved =
+		locale || $pickenv("XCSH_LOCALE", "PI_LOCALE") || parseSystemLocale($pickenv("LANG", "LC_MESSAGES")) || "en";
+	setLocale(resolved);
+}
+
+export function setLocale(locale: string): void {
+	currentLocale = mapToSupportedLocale(locale) ?? normalizeLocale(locale);
+	active = resolveBundle(currentLocale);
+}
+
+export function getLocale(): string {
+	return currentLocale;
+}
+
+/**
+ * Translate a key with optional parameter interpolation.
+ * Falls back to the English string, then to the key itself.
+ *
+ * Usage:
+ *   t("cli.error.patternRequired")
+ *   t("cli.error.fileNotFound", { path: "/foo" })
+ *   t("items.count", { count: 5 })  // uses ".one" / ".other" suffixes
+ */
+export function t(key: string, params?: Record<string, string | number>): string {
+	let template = active[key];
+
+	if (template === undefined && params && typeof params.count === "number") {
+		const pluralSuffix = params.count === 1 ? ".one" : ".other";
+		template = active[key + pluralSuffix];
+		if (template === undefined) {
+			template = bundles.en?.[key + pluralSuffix] ?? bundles.en?.[key];
+		}
+	}
+
+	if (template === undefined) {
+		template = bundles.en?.[key] ?? key;
+	}
+
+	if (!params) return template;
+
+	return template.replace(/\{(\w+)\}/g, (match, name: string) => {
+		const val = params[name];
+		return val !== undefined ? String(val) : match;
+	});
+}
+
+/**
+ * Map an OS locale code (macOS AppleLanguages, Linux LANG) to a supported xcsh locale.
+ * Handles Apple script subtags (zh-Hans, zh-Hant) and regional variants (pt-BR, en-US).
+ * Returns undefined if no supported locale matches.
+ */
+export function mapToSupportedLocale(osLocale: string): string | undefined {
+	const normalized = normalizeLocale(osLocale);
+
+	if (bundles[normalized]) return normalized;
+
+	// Apple uses zh-hans / zh-hant (script subtags) instead of zh-cn / zh-tw
+	if (normalized.startsWith("zh-hans")) return bundles["zh-cn"] ? "zh-cn" : undefined;
+	if (normalized.startsWith("zh-hant")) return bundles["zh-tw"] ? "zh-tw" : undefined;
+
+	// Try with region: pt-br, en-us, etc.
+	const withRegion = normalized.split("-").slice(0, 2).join("-");
+	if (bundles[withRegion]) return withRegion;
+
+	// Fall back to base language: pt-br → pt, en-us → en
+	const base = normalized.split("-")[0];
+	if (bundles[base]) return base;
+
+	return undefined;
+}
+
+function normalizeLocale(raw: string): string {
+	return raw.toLowerCase().replace(/_/g, "-").split(".")[0];
+}
+
+function parseSystemLocale(raw: string | undefined): string | undefined {
+	if (!raw) return undefined;
+	const normalized = normalizeLocale(raw);
+	if (normalized === "c" || normalized === "posix") return "en";
+	return normalized;
+}
+
+function resolveBundle(locale: string): LocaleMap {
+	if (bundles[locale]) return bundles[locale];
+	const base = locale.split("-")[0];
+	if (bundles[base]) return bundles[base];
+	return bundles.en ?? {};
+}

package/src/index.ts

@@ -8,6 +8,7 @@ export * from "./frontmatter";
 export * from "./fs-error";
 export * from "./glob";
 export * from "./hook-fetch";
+export { getLocale, initI18n, mapToSupportedLocale, registerLocales, setLocale, t } from "./i18n";
 export * from "./json";
 export * as logger from "./logger";
 export * from "./mermaid-ascii";