universal-dev-standards 5.14.0 → 5.16.0

package/src/commands/init.js

@@ -23,6 +23,7 @@ import {
 import { displayLanguageToLocale } from '../utils/locale.js';
 import { generateReleaseConfig, RELEASE_MODE_LABELS } from '../utils/release-config.js';
 import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
+import { readInstallYaml } from '../utils/config-manager.js';
 
 /**
  * Init command - initialize standards in current project
@@ -308,7 +309,13 @@ echo "Pre-commit checks passed"
  * Build configuration for non-interactive mode
  */
 function buildNonInteractiveConfig(options, detected, projectPath) {
-  const displayLanguage = options.locale || detectLanguage(null);
+  // Locale resolution order (XSPEC-239 §Req-3):
+  //   CLI --locale > .uds/install.yaml locale: > UDS_LOCALE env > LANG > 'en'
+  // detectLanguage() handles UDS_LOCALE + LANG fallback internally (P1-CLI-3).
+  const installYaml = readInstallYaml(projectPath);
+  const displayLanguage = options.locale
+    || installYaml.locale
+    || detectLanguage(null);
   
   // Determine AI tools
   const detectedAiTools = Object.keys(detected.aiTools).filter(k => detected.aiTools[k]);

package/src/commands/update.js

@@ -30,6 +30,7 @@ import {
   cleanupLegacyCommands
 } from '../utils/skills-installer.js';
 import { displayLanguageToLocale, isLocalizedLocale, detectLocaleFromStandards } from '../utils/locale.js';
+import { readInstallYaml } from '../utils/config-manager.js';
 import {
   getAgentDisplayName,
   getAgentConfig,
@@ -237,17 +238,49 @@ function checkNewStandards(manifest) {
 }
 
 /**
- * Resolve locale from manifest with fallback detection.
- * If manifest has display_language, use it. Otherwise detect from .standards/ files.
+ * Resolve locale for skill / command installation.
+ *
+ * Resolution order (XSPEC-239 §Req-3 / P1-CLI-2 + P1-CLI-3):
+ *   1. CLI `--locale` (passed via `options.locale`)
+ *   2. `.uds/install.yaml` `locale:`
+ *   3. `UDS_LOCALE` env var
+ *   4. manifest `options.display_language` (existing behaviour)
+ *   5. `.standards/` file-based detection (existing behaviour)
+ *   6. `'en'`
+ *
  * @param {Object} manifest - Project manifest
  * @param {string} projectPath - Project root path
+ * @param {Object} [options] - CLI options object (optional, for `--locale`)
  * @returns {string} Locale directory name (e.g., 'zh-TW', 'en')
  */
-function resolveLocale(manifest, projectPath) {
+function resolveLocale(manifest, projectPath, options) {
+  // 1. CLI flag wins
+  const cliLocale = options?.locale && displayLanguageToLocale(options.locale);
+  if (cliLocale && isLocalizedLocale(cliLocale)) return cliLocale;
+  if (cliLocale === 'en') return 'en';
+
+  // 2. .uds/install.yaml
+  const installYaml = readInstallYaml(projectPath);
+  if (installYaml.locale) {
+    const fromYaml = displayLanguageToLocale(installYaml.locale);
+    if (isLocalizedLocale(fromYaml)) return fromYaml;
+    if (fromYaml === 'en') return 'en';
+  }
+
+  // 3. UDS_LOCALE env
+  if (process.env.UDS_LOCALE) {
+    const fromEnv = displayLanguageToLocale(process.env.UDS_LOCALE);
+    if (isLocalizedLocale(fromEnv)) return fromEnv;
+    if (fromEnv === 'en') return 'en';
+  }
+
+  // 4. Manifest
   const fromManifest = displayLanguageToLocale(manifest.options?.display_language);
   if (isLocalizedLocale(fromManifest)) {
     return fromManifest;
   }
+
+  // 5. .standards/ detection → 6. 'en'
   return detectLocaleFromStandards(projectPath) || 'en';
 }
 
@@ -309,13 +342,13 @@ export async function updateCommand(options) {
 
   // Handle --skills option
   if (options.skills) {
-    await updateSkillsOnly(projectPath, manifest);
+    await updateSkillsOnly(projectPath, manifest, options);
     return;
   }
 
   // Handle --commands option
   if (options.commands) {
-    await updateCommandsOnly(projectPath, manifest);
+    await updateCommandsOnly(projectPath, manifest, options);
     return;
   }
 
@@ -892,7 +925,7 @@ export async function updateCommand(options) {
         // Install Skills if user agreed
         if (installSkills.length > 0) {
           const skillSpinner = ora(msg.installingNewSkills || 'Installing Skills...').start();
-          const skillsLocale = resolveLocale(manifest, projectPath);
+          const skillsLocale = resolveLocale(manifest, projectPath, options);
           const skillResult = await installSkillsToMultipleAgents(installSkills, null, projectPath, skillsLocale);
 
           // Update manifest
@@ -933,7 +966,7 @@ export async function updateCommand(options) {
         // Update outdated Skills if user agreed
         if (updateSkills.length > 0) {
           const updateSpinner = ora(msg.updatingSkills || 'Updating Skills...').start();
-          const updateLocale = resolveLocale(manifest, projectPath);
+          const updateLocale = resolveLocale(manifest, projectPath, options);
           const updateResult = await installSkillsToMultipleAgents(updateSkills, null, projectPath, updateLocale);
 
           // Update manifest version
@@ -969,7 +1002,7 @@ export async function updateCommand(options) {
         // Install Commands if user agreed
         if (installCommands.length > 0) {
           const cmdSpinner = ora(msg.installingNewCommands || 'Installing commands...').start();
-          const cmdLocale = resolveLocale(manifest, projectPath);
+          const cmdLocale = resolveLocale(manifest, projectPath, options);
           const cmdResult = await installCommandsToMultipleAgents(installCommands, null, projectPath, cmdLocale);
 
           // Update manifest
@@ -999,7 +1032,7 @@ export async function updateCommand(options) {
         // Update outdated Commands if user agreed
         if (updateCommands.length > 0) {
           const updateCmdSpinner = ora(msg.updatingCommands || 'Updating Commands...').start();
-          const updateCmdLocale = resolveLocale(manifest, projectPath);
+          const updateCmdLocale = resolveLocale(manifest, projectPath, options);
           const updateCmdResult = await installCommandsToMultipleAgents(updateCommands, null, projectPath, updateCmdLocale);
 
           // Update manifest version
@@ -1069,7 +1102,7 @@ export async function updateCommand(options) {
         }
       } else {
         // --yes mode: auto-install/update Skills and Commands (treat -y as confirming all prompts)
-        const skillsLocale = resolveLocale(manifest, projectPath);
+        const skillsLocale = resolveLocale(manifest, projectPath, options);
         let hasChanges = false;
 
         if (missingSkills.length > 0) {
@@ -1551,8 +1584,9 @@ async function syncIntegrationReferences(projectPath, manifest) {
  * Update Skills for all AI agents (--skills option)
  * @param {string} projectPath - Project path
  * @param {Object} manifest - Manifest object
+ * @param {Object} [options] - CLI options (forwarded for locale resolution)
  */
-async function updateSkillsOnly(projectPath, manifest) {
+async function updateSkillsOnly(projectPath, manifest, options) {
   const msg = t().commands.update;
   const repoInfo = getRepositoryInfo();
   const latestVersion = repoInfo.skills.version;
@@ -1621,7 +1655,7 @@ async function updateSkillsOnly(projectPath, manifest) {
 
   const spinner = ora(msg.installingSkills || 'Installing Skills...').start();
 
-  const skillsLocaleForUpdate = resolveLocale(manifest, projectPath);
+  const skillsLocaleForUpdate = resolveLocale(manifest, projectPath, options);
   const result = await installSkillsToMultipleAgents(
     fileBasedInstallations,
     null, // Install all skills
@@ -1665,8 +1699,9 @@ async function updateSkillsOnly(projectPath, manifest) {
  * Update slash commands for all AI agents (--commands option)
  * @param {string} projectPath - Project path
  * @param {Object} manifest - Manifest object
+ * @param {Object} [options] - CLI options (forwarded for locale resolution)
  */
-async function updateCommandsOnly(projectPath, manifest) {
+async function updateCommandsOnly(projectPath, manifest, options) {
   const msg = t().commands.update;
 
   console.log(chalk.cyan(msg.updatingCommandsOnly || 'Updating slash commands for all AI Agents...'));
@@ -1715,7 +1750,7 @@ async function updateCommandsOnly(projectPath, manifest) {
 
   const spinner = ora(msg.installingCommands || 'Installing commands...').start();
 
-  const commandsLocale = resolveLocale(manifest, projectPath);
+  const commandsLocale = resolveLocale(manifest, projectPath, options);
   const result = await installCommandsToMultipleAgents(
     commandsInstallations,
     null, // Install all commands

package/src/i18n/messages.js

@@ -1003,6 +1003,10 @@ export const messages = {
         installingSkills: 'Installing Claude Code Skills...',
         installedSkills: 'Installed {count} Skills to {locations}',
         installedSkillsWithErrors: 'Installed {count} Skills with {errors} errors',
+        // P1-CLI-1: locale fallback summary (printed after install when some
+        // skills lack a localized variant and fell back to English source)
+        localeFallbackTitle: 'Locale fallback: {count} skill(s) fell back to English because no {locale} variant exists:',
+        localeFallbackHint: 'See locales/COVERAGE.md for full coverage status.',
         // Success
         initializedSuccess: '✓ Standards initialized successfully!',
         filesCopied: '{count} files copied to project',
@@ -2264,6 +2268,9 @@ export const messages = {
         installingSkills: '安裝 Claude Code Skills 中...',
         installedSkills: '已安裝 {count} 個 Skills 到 {locations}',
         installedSkillsWithErrors: '已安裝 {count} 個 Skills，有 {errors} 個錯誤',
+        // P1-CLI-1：locale fallback 摘要（安裝結束後顯示，列出沒有對應語系變體而退回英文來源的 skill）
+        localeFallbackTitle: 'Locale fallback：{count} 個 skill 因為沒有 {locale} 變體而退回英文版本：',
+        localeFallbackHint: '完整覆蓋率請參閱 locales/COVERAGE.md。',
         // Success
         initializedSuccess: '✓ 標準初始化成功！',
         filesCopied: '已複製 {count} 個檔案到專案',
@@ -3270,6 +3277,9 @@ export const messages = {
         installingSkills: '正在安装 Claude Code Skills...',
         installedSkills: '已安装 {count} 个 Skills 到 {locations}',
         installedSkillsWithErrors: '已安装 {count} 个 Skills，有 {errors} 个错误',
+        // P1-CLI-1：locale fallback 摘要（安装结束后显示，列出没有对应语种变体而退回英文来源的 skill）
+        localeFallbackTitle: 'Locale fallback：{count} 个 skill 因为没有 {locale} 变体而退回英文版本：',
+        localeFallbackHint: '完整覆盖率请参阅 locales/COVERAGE.md。',
         // Success
         initializedSuccess: '✓ 标准初始化成功！',
         filesCopied: '已复制 {count} 个文件到项目',
@@ -3792,12 +3802,19 @@ export function msg(path) {
 }
 
 /**
- * Detect language from environment or locale setting
+ * Detect language from environment or locale setting.
+ *
+ * Resolution order (XSPEC-239 §Req-3 / P1-CLI-3):
+ *   1. explicit `locale` arg (from CLI `--locale`)
+ *   2. `UDS_LOCALE` env var (UDS-specific override; takes precedence over LANG)
+ *   3. POSIX locale env vars (`LANG` / `LC_ALL` / `LC_MESSAGES`)
+ *   4. `'en'`
+ *
  * @param {string|null} locale - Locale setting from CLI options
- * @returns {string} Detected language code
+ * @returns {string} Detected language code ('zh-tw' | 'zh-cn' | 'en')
  */
 export function detectLanguage(locale) {
-  // If locale is explicitly set, use it
+  // 1. If locale is explicitly set, use it
   if (locale === 'zh-tw') {
     return 'zh-tw';
   }
@@ -3805,7 +3822,17 @@ export function detectLanguage(locale) {
     return 'zh-cn';
   }
 
-  // Check environment variables
+  // 2. UDS-specific env var (P1-CLI-3): preferred over generic POSIX LANG so
+  // adopters can opt into a specific UDS locale in CI without touching LANG.
+  if (process.env.UDS_LOCALE) {
+    const v = process.env.UDS_LOCALE.toLowerCase();
+    if (v === 'zh-tw' || v === 'zh_tw') return 'zh-tw';
+    if (v === 'zh-cn' || v === 'zh_cn') return 'zh-cn';
+    if (v === 'en') return 'en';
+    // Unknown UDS_LOCALE values fall through to LANG detection below
+  }
+
+  // 3. Check POSIX environment variables
   const envLang = process.env.LANG || process.env.LC_ALL || process.env.LC_MESSAGES || '';
   if (envLang.toLowerCase().includes('zh_tw') || envLang.toLowerCase().includes('zh-tw')) {
     return 'zh-tw';
@@ -3814,6 +3841,6 @@ export function detectLanguage(locale) {
     return 'zh-cn';
   }
 
-  // Default to English
+  // 4. Default to English
   return 'en';
 }

package/src/installers/skills-installer.js

@@ -34,6 +34,46 @@ import {
 } from '../config/ai-agent-paths.js';
 import { getRepositoryInfo } from '../utils/registry.js';
 
+/**
+ * Print a single WARN block summarizing skills that fell back to the English
+ * source because no localized variant exists for the requested locale.
+ *
+ * Adopter-facing behaviour (XSPEC-239 §Req-3 / P1-CLI-1):
+ * - One yellow block at the end of install, listing all fallen-back skills.
+ * - Hint pointer to `locales/COVERAGE.md` for the full coverage matrix.
+ *
+ * The `messages` bundle is the same flat command-scope bundle that `installSkills`
+ * receives (e.g. `t().commands.init`). Falls back to English literals if keys
+ * are absent so older translation bundles keep working.
+ *
+ * @param {string[]} fallenBack - Skill names that fell back to English
+ * @param {string} [locale] - Requested locale (e.g. 'zh-TW'); used in the message
+ * @param {Object} [messages] - Command-scope i18n bundle (optional)
+ * @returns {void}
+ */
+export function printLocaleFallbackWarning(fallenBack, locale, messages) {
+  if (!fallenBack || fallenBack.length === 0) return;
+
+  const count = fallenBack.length;
+  const localeLabel = locale || 'requested locale';
+
+  const titleTemplate = messages?.localeFallbackTitle
+    || 'Locale fallback: {count} skill(s) fell back to English because no {locale} variant exists:';
+  const hint = messages?.localeFallbackHint
+    || 'See locales/COVERAGE.md for full coverage status.';
+
+  const title = titleTemplate
+    .replace('{count}', String(count))
+    .replace('{locale}', localeLabel);
+
+  console.log();
+  console.log(chalk.yellow(`⚠ ${title}`));
+  for (const name of fallenBack) {
+    console.log(chalk.yellow(`    - ${name}`));
+  }
+  console.log(chalk.gray(`  ${hint}`));
+}
+
 /**
  * Get all skill files mapping (skill name -> file paths)
  * Used for remote download fallback
@@ -120,6 +160,15 @@ export async function installSkills(skillsConfig, projectPath, messages, results
         .replace('{count}', installResult.totalInstalled)
         .replace('{errors}', installResult.totalErrors));
     }
+
+    // P1-CLI-1: Emit a single locale-fallback WARN after the install loop when
+    // adopters requested a localized variant but some skills only ship in English.
+    // The aggregated list is built in installSkillsToMultipleAgents (deduped).
+    if (Array.isArray(installResult.localeFallbacks) && installResult.localeFallbacks.length > 0) {
+      // `messages` is a flat command-scope bundle (e.g. t().commands.init);
+      // the WARN helper looks for localeFallbackTitle/Hint keys directly on it.
+      printLocaleFallbackWarning(installResult.localeFallbacks, skillsConfig.locale, messages);
+    }
   } else if (skillsConfig.needsInstall && skillsConfig.updateTargets?.length > 0) {
     // Legacy fallback for backward compatibility (remote download)
     await installSkillsLegacy(skillsConfig, projectPath, messages, results);