valaxy 0.28.0-beta.6 → 0.28.0-beta.7

package/client/composables/locale.ts

@@ -1,12 +1,12 @@
 import type { Ref } from 'vue'
+import type { TaxonomyNamespace } from '../../shared/utils/i18n'
 import { isClient, useStorage } from '@vueuse/core'
 import dayjs from 'dayjs'
-import { computed } from 'vue'
 
+import { computed, watch } from 'vue'
 // not optimize deps all locales
 import { useI18n } from 'vue-i18n'
-import { tObject } from '../../shared/utils/i18n'
-import { LOCALE_PREFIX } from '../utils'
+import { isLocaleKey, resolveTaxonomyLocaleKey, stripLocalePrefix, tObject } from '../../shared/utils/i18n'
 import 'dayjs/locale/en'
 import 'dayjs/locale/zh-cn'
 
@@ -63,13 +63,16 @@ export function useLocale() {
 export function useLocaleTitle(fm: Ref<{
   title?: string | Record<string, string>
 } | null>) {
-  const { locale } = useI18n()
+  const { t, locale } = useI18n()
   return computed(() => {
     if (!fm.value)
       return ''
 
     const lang = locale.value
-    return tObject(fm.value.title || '', lang) || ''
+    const title = tObject(fm.value.title || '', lang) || ''
+    if (typeof title === 'string' && isLocaleKey(title))
+      return t(stripLocalePrefix(title))
+    return title
   })
 }
 
@@ -79,16 +82,19 @@ export function useLocaleTitle(fm: Ref<{
  * 会从 locales/ 目录中获取对应的翻译
  */
 export function useValaxyI18n() {
-  const { t, locale } = useI18n()
+  const { t, te, locale } = useI18n()
+  const termCache = new Map<string, string>()
+
+  // Clear cache on locale switches so each composable instance stays bounded.
+  watch(locale, () => termCache.clear())
 
   /**
    * translate `$locale:key`
    * @param key
    */
   const $t = (key: string) => {
-    if (key.startsWith(LOCALE_PREFIX)) {
-      return t(key.slice(LOCALE_PREFIX.length))
-    }
+    if (isLocaleKey(key))
+      return t(stripLocalePrefix(key))
     return key
   }
 
@@ -104,6 +110,47 @@ export function useValaxyI18n() {
     return tObject(data || '', locale.value)
   }
 
+  /**
+   * @en
+   * Translate a taxonomy term.
+   *
+   * Resolution order:
+   * 1. `$locale:` prefix → strip and translate via `t()`
+   * 2. Locale key `{namespace}.{key}` exists → translate via `t()`
+   * 3. Fallback → return the original key as-is
+   *
+   * The result is cached by `locale + namespace + key` to avoid repeated
+   * `te()` / `t()` lookups in tag clouds and category trees.
+   *
+   * @zh
+   * 翻译 taxonomy 术语。
+   *
+   * 解析顺序：
+   * 1. `$locale:` 前缀 → 去掉前缀后通过 `t()` 翻译
+   * 2. locale 中存在 `{namespace}.{key}` → 通过 `t()` 翻译
+   * 3. 兜底 → 原样返回
+   *
+   * 结果会按 `locale + namespace + key` 做轻量缓存，
+   * 避免标签云和分类树中重复执行 `te()` / `t()`。
+   */
+  const $tTerm = (namespace: TaxonomyNamespace, key: string) => {
+    const cacheKey = `${locale.value}:${namespace}:${key}`
+    const cached = termCache.get(cacheKey)
+    if (cached !== undefined)
+      return cached
+
+    const { localeKey, isExplicitLocaleKey } = resolveTaxonomyLocaleKey(namespace, key)
+    const result = isExplicitLocaleKey || te(localeKey)
+      ? `${t(localeKey)}`
+      : key
+
+    termCache.set(cacheKey, result)
+    return result
+  }
+
+  const $tTag = (key: string) => $tTerm('tag', key)
+  const $tCategory = (key: string) => $tTerm('category', key)
+
   return {
     locale,
     /**
@@ -111,5 +158,17 @@ export function useValaxyI18n() {
      */
     $t,
     $tO,
+    /**
+     * translate taxonomy term (auto-lookup `{namespace}.{key}` in locale files)
+     */
+    $tTerm,
+    /**
+     * translate tag name (auto-lookup `tag.{key}` in locale files)
+     */
+    $tTag,
+    /**
+     * translate category name (auto-lookup `category.{key}` in locale files)
+     */
+    $tCategory,
   }
 }

package/client/composables/post/index.ts

@@ -6,15 +6,18 @@ import { orderByMeta, useSiteConfig } from 'valaxy'
 import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { useRouterStore } from '../../stores'
-import { tObject } from '../../utils'
+import { isLocaleKey, stripLocalePrefix, tObject } from '../../utils'
 
 export * from './usePagination'
 export * from './usePrevNext'
 
 export function usePostTitle(post: ComputedRef<Post>) {
-  const { locale } = useI18n()
+  const { t, locale } = useI18n()
   return computed(() => {
-    return tObject(post.value.title || '', locale.value)
+    const title = tObject(post.value.title || '', locale.value)
+    if (typeof title === 'string' && isLocaleKey(title))
+      return t(stripLocalePrefix(title))
+    return title
   })
 }
 

package/dist/node/cli/index.mjs

@@ -1,7 +1,7 @@
 import 'node:process';
 import 'yargs';
 import 'yargs/helpers';
-export { c as cli, I as registerDevCommand, W as run, Z as startValaxyDev } from '../../shared/valaxy.BVsZMcdc.mjs';
+export { c as cli, I as registerDevCommand, W as run, Z as startValaxyDev } from '../../shared/valaxy.DAkHYbg0.mjs';
 import 'node:os';
 import 'node:path';
 import 'consola';

package/dist/node/index.d.mts

@@ -694,6 +694,30 @@ interface ValaxyExtendConfig {
              */
             maxDuration?: number;
         };
+        /**
+         * @en Taxonomy i18n validation during `valaxy dev` / `valaxy build`.
+         * Checks whether translated `tag.*` / `category.*` keys are consistently
+         * defined across configured languages.
+         *
+         * @zh `valaxy dev` / `valaxy build` 期间的 taxonomy i18n 校验。
+         * 用于检查 `tag.*` / `category.*` 翻译 key 是否在已配置语言中保持一致。
+         */
+        taxonomyI18n?: {
+            /**
+             * @en Validation level for taxonomy i18n checks.
+             * - `'off'`: disable checks
+             * - `'warn'`: print warnings and continue
+             * - `'error'`: fail validation after reporting all issues
+             *
+             * @zh taxonomy i18n 校验级别。
+             * - `'off'`：关闭检查
+             * - `'warn'`：输出 warning 并继续流程
+             * - `'error'`：输出所有问题后以错误结束
+             *
+             * @default 'warn'
+             */
+            level?: 'off' | 'warn' | 'error';
+        };
     };
     /**
      * @experimental

package/dist/node/index.mjs

@@ -1,4 +1,4 @@
-export { A as ALL_ROUTE, E as EXCERPT_SEPARATOR, G as GLOBAL_STATE, P as PATHNAME_PROTOCOL_RE, V as ViteValaxyPlugins, b as build, c as cli, a as createServer, d as createValaxyPlugin, e as customElements, f as defaultSiteConfig, g as defaultValaxyConfig, h as defaultViteConfig, i as defineAddon, j as defineConfig, k as defineSiteConfig, l as defineTheme, m as defineValaxyAddon, n as defineValaxyConfig, o as defineValaxyTheme, p as encryptContent, q as generateClientRedirects, r as getGitTimestamp, s as getIndexHtml, t as getServerInfoText, u as isExternal, v as isInstalledGlobally, w as isKatexEnabled, x as isKatexPluginNeeded, y as isMathJaxEnabled, z as isPath, B as loadConfigFromFile, C as mergeValaxyConfig, D as mergeViteConfigs, F as postProcessForSSG, H as processValaxyOptions, I as registerDevCommand, J as resolveAddonsConfig, K as resolveImportPath, L as resolveImportUrl, M as resolveOptions, N as resolveSiteConfig, O as resolveSiteConfigFromRoot, Q as resolveThemeConfigFromRoot, R as resolveThemeValaxyConfig, S as resolveUserThemeConfig, T as resolveValaxyConfig, U as resolveValaxyConfigFromRoot, W as run, X as ssgBuild, Y as ssgBuildLegacy, Z as startValaxyDev, _ as toAtFS, $ as transformObject, a0 as version } from '../shared/valaxy.BVsZMcdc.mjs';
+export { A as ALL_ROUTE, E as EXCERPT_SEPARATOR, G as GLOBAL_STATE, P as PATHNAME_PROTOCOL_RE, V as ViteValaxyPlugins, b as build, c as cli, a as createServer, d as createValaxyPlugin, e as customElements, f as defaultSiteConfig, g as defaultValaxyConfig, h as defaultViteConfig, i as defineAddon, j as defineConfig, k as defineSiteConfig, l as defineTheme, m as defineValaxyAddon, n as defineValaxyConfig, o as defineValaxyTheme, p as encryptContent, q as generateClientRedirects, r as getGitTimestamp, s as getIndexHtml, t as getServerInfoText, u as isExternal, v as isInstalledGlobally, w as isKatexEnabled, x as isKatexPluginNeeded, y as isMathJaxEnabled, z as isPath, B as loadConfigFromFile, C as mergeValaxyConfig, D as mergeViteConfigs, F as postProcessForSSG, H as processValaxyOptions, I as registerDevCommand, J as resolveAddonsConfig, K as resolveImportPath, L as resolveImportUrl, M as resolveOptions, N as resolveSiteConfig, O as resolveSiteConfigFromRoot, Q as resolveThemeConfigFromRoot, R as resolveThemeValaxyConfig, S as resolveUserThemeConfig, T as resolveValaxyConfig, U as resolveValaxyConfigFromRoot, W as run, X as ssgBuild, Y as ssgBuildLegacy, Z as startValaxyDev, _ as toAtFS, $ as transformObject, a0 as version } from '../shared/valaxy.DAkHYbg0.mjs';
 import 'node:path';
 import 'fs-extra';
 import 'consola/utils';

package/dist/shared/{valaxy.BVsZMcdc.mjs → valaxy.DAkHYbg0.mjs}

@@ -854,6 +854,9 @@ const defaultValaxyConfig = {
     foucGuard: {
       enabled: true,
       maxDuration: 5e3
+    },
+    taxonomyI18n: {
+      level: "warn"
     }
   },
   deploy: {},
@@ -985,6 +988,30 @@ function tObject(data, lang) {
   }
   return data;
 }
+function isLocaleKey(value) {
+  return value.startsWith(LOCALE_PREFIX);
+}
+function stripLocalePrefix(value) {
+  return isLocaleKey(value) ? value.slice(LOCALE_PREFIX.length) : value;
+}
+function getLocaleMessageValue(messages, key) {
+  return key.split(".").reduce((result, part) => result?.[part], messages);
+}
+function hasLocaleMessage(messages, key) {
+  return getLocaleMessageValue(messages, key) !== void 0;
+}
+function resolveTaxonomyLocaleKey(namespace, rawValue) {
+  if (isLocaleKey(rawValue)) {
+    return {
+      localeKey: stripLocalePrefix(rawValue),
+      isExplicitLocaleKey: true
+    };
+  }
+  return {
+    localeKey: `${namespace}.${rawValue}`,
+    isExplicitLocaleKey: false
+  };
+}
 
 const indexRE = /(^|.*\/)index.md(.*)$/i;
 function linkPlugin(md, externalAttrs, base) {
@@ -1692,7 +1719,7 @@ async function setupMarkdownPlugins(md, options, base = "/") {
   return md;
 }
 
-const version = "0.28.0-beta.6";
+const version = "0.28.0-beta.7";
 
 const GLOBAL_STATE = {
   valaxyApp: void 0,
@@ -2482,9 +2509,8 @@ function loadLocalesYml(localesPath, force = false) {
   return locales;
 }
 function nodeT(key, lang) {
-  if (key.startsWith(LOCALE_PREFIX)) {
-    key = key.slice(LOCALE_PREFIX.length);
-  }
+  if (isLocaleKey(key))
+    key = stripLocalePrefix(key);
   const data = NODE_I18N.locales[lang] || {};
   const keys = key.split(".");
   let result = data;
@@ -2529,7 +2555,7 @@ function getSiteUrl(options) {
 }
 
 function resolveText(value, lang) {
-  if (typeof value === "string" && value.startsWith(LOCALE_PREFIX))
+  if (typeof value === "string" && isLocaleKey(value))
     return nodeT(value, lang);
   return tObject(value, lang);
 }
@@ -5650,6 +5676,162 @@ const content = {
   loadAllContent: loadAllContent
 };
 
+function getConfiguredLanguages(options) {
+  const configured = options.config.siteConfig.languages?.length ? options.config.siteConfig.languages : [options.config.siteConfig.lang || "en"];
+  return [...new Set(configured.filter(Boolean))];
+}
+function normalizeToStringArray(value) {
+  if (typeof value === "string")
+    return value.trim() ? [value] : [];
+  if (Array.isArray(value)) {
+    return value.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean);
+  }
+  return [];
+}
+async function collectPageFiles(options) {
+  const userPages = await scanPageFiles(options.userRoot, ["**/*.md"]);
+  const userPageFiles = userPages.map((file) => resolve(options.userRoot, "pages", file));
+  const contentDir = resolve(options.tempDir, "content", "pages");
+  if (!await fs.pathExists(contentDir))
+    return userPageFiles;
+  const contentPages = await fg(["**/*.md"], {
+    cwd: contentDir,
+    ignore: ["**/node_modules"]
+  });
+  return [.../* @__PURE__ */ new Set([
+    ...userPageFiles,
+    ...contentPages.map((file) => resolve(contentDir, file))
+  ])];
+}
+async function loadMergedLocaleMessages(options) {
+  const languages = getConfiguredLanguages(options);
+  const messages = Object.fromEntries(languages.map((lang) => [lang, {}]));
+  for (const root of options.roots) {
+    for (const lang of languages) {
+      const localeFiles = [
+        resolve(root, "locales", `${lang}.yml`),
+        resolve(root, "locales", `${lang}.yaml`)
+      ];
+      for (const localeFile of localeFiles) {
+        if (!await fs.pathExists(localeFile))
+          continue;
+        const content = await fs.readFile(localeFile, "utf-8");
+        if (!content.trim())
+          continue;
+        const data = yaml.load(content);
+        messages[lang] = replaceArrMerge(data || {}, messages[lang]);
+      }
+    }
+  }
+  return messages;
+}
+async function collectTaxonomyUsages(options) {
+  const files = await collectPageFiles(options);
+  const posts = await readPostFiles(files);
+  const usageMap = /* @__PURE__ */ new Map();
+  const addUsage = (namespace, rawValue, file) => {
+    const key = `${namespace}:${rawValue}`;
+    if (!usageMap.has(key)) {
+      usageMap.set(key, {
+        namespace,
+        rawValue,
+        files: /* @__PURE__ */ new Set()
+      });
+    }
+    usageMap.get(key).files.add(file);
+  };
+  for (const post of posts) {
+    const file = relative(options.userRoot, post.filePath);
+    for (const tag of normalizeToStringArray(post.data.tags))
+      addUsage("tag", tag, file);
+    for (const category of normalizeToStringArray(post.data.categories))
+      addUsage("category", category, file);
+  }
+  return Array.from(usageMap.values(), (item) => ({
+    namespace: item.namespace,
+    rawValue: item.rawValue,
+    files: [...item.files].sort()
+  })).sort((a, b) => `${a.namespace}:${a.rawValue}`.localeCompare(`${b.namespace}:${b.rawValue}`));
+}
+function findTaxonomyI18nIssues(usages, messages, languages) {
+  const issues = [];
+  for (const usage of usages) {
+    const { namespace, rawValue, files } = usage;
+    const { localeKey, isExplicitLocaleKey } = resolveTaxonomyLocaleKey(namespace, rawValue);
+    const presentLanguages = languages.filter((lang) => hasLocaleMessage(messages[lang], localeKey));
+    const missingLanguages = languages.filter((lang) => !hasLocaleMessage(messages[lang], localeKey));
+    if (isExplicitLocaleKey) {
+      if (missingLanguages.length) {
+        issues.push({
+          type: "explicit-locale-key-missing",
+          namespace,
+          rawValue,
+          localeKey,
+          presentLanguages,
+          missingLanguages,
+          files
+        });
+      }
+      continue;
+    }
+    if (presentLanguages.length === 0 || presentLanguages.length === languages.length)
+      continue;
+    issues.push({
+      type: "partial-locale-coverage",
+      namespace,
+      rawValue,
+      localeKey,
+      presentLanguages,
+      missingLanguages,
+      files
+    });
+  }
+  return issues;
+}
+function formatFiles(files) {
+  const preview = files.slice(0, 3).map((file) => colors.dim(file)).join(", ");
+  if (files.length <= 3)
+    return preview;
+  return `${preview}${colors.dim(` and ${files.length - 3} more`)}`;
+}
+function logTaxonomyI18nIssues(issues, level) {
+  if (!issues.length)
+    return;
+  const log = level === "error" ? consola.error : consola.warn;
+  const count = level === "error" ? colors.red(String(issues.length)) : colors.yellow(String(issues.length));
+  log(`Detected ${count} taxonomy i18n issue(s).`);
+  for (const issue of issues) {
+    const where = formatFiles(issue.files);
+    if (issue.type === "explicit-locale-key-missing") {
+      log(
+        `[taxonomy-i18n] ${colors.cyan(issue.rawValue)} is an explicit locale key but ${colors.red(`missing in: ${issue.missingLanguages.join(", ")}`)}. Files: ${where}`
+      );
+      continue;
+    }
+    log(
+      `[taxonomy-i18n] ${colors.cyan(issue.rawValue)} resolves to ${colors.cyan(issue.localeKey)} in ${colors.green(issue.presentLanguages.join(", "))}, but is ${colors.red(`missing in: ${issue.missingLanguages.join(", ")}`)}. Files: ${where}`
+    );
+  }
+}
+function resolveTaxonomyI18nValidationLevel(options) {
+  return options.config.build.taxonomyI18n?.level || "warn";
+}
+async function validateTaxonomyI18n(options) {
+  const level = resolveTaxonomyI18nValidationLevel(options);
+  if (level === "off")
+    return [];
+  const languages = getConfiguredLanguages(options);
+  const [messages, usages] = await Promise.all([
+    loadMergedLocaleMessages(options),
+    collectTaxonomyUsages(options)
+  ]);
+  const issues = findTaxonomyI18nIssues(usages, messages, languages);
+  logTaxonomyI18nIssues(issues, level);
+  if (level === "error" && issues.length)
+    throw new Error(`Taxonomy i18n validation failed with ${issues.length} issue(s).`);
+  return issues;
+}
+
 function getServerInfoText(msg) {
   return `${valaxyPrefix} ${colors.gray(msg)}`;
 }
@@ -5790,6 +5972,7 @@ async function execBuild({ ssg, ssgEngine, root, output, log }) {
   );
   await callHookWithLog("config:init", valaxyApp);
   await callHookWithLog("build:before", valaxyApp);
+  await validateTaxonomyI18n(options);
   consola.box("\u{1F320} Start building...");
   try {
     if (ssg) {
@@ -6075,6 +6258,7 @@ async function startValaxyDev({
     await valaxyApp.hooks.callHook("content:before-load");
     await loadAllContent(loaders, ctx);
     await valaxyApp.hooks.callHook("content:loaded");
+    await validateTaxonomyI18n(resolvedOptions);
     for (const loader of loaders) {
       if (loader.devPollInterval) {
         const poll = async () => {
@@ -6082,6 +6266,7 @@ async function startValaxyDev({
             await valaxyApp.hooks.callHook("content:before-load");
             await loadAllContent([loader], ctx);
             await valaxyApp.hooks.callHook("content:loaded");
+            await validateTaxonomyI18n(resolvedOptions);
           } catch (error) {
             consola.error("[content-loader] Error while polling:", error);
           } finally {
@@ -6092,6 +6277,8 @@ async function startValaxyDev({
         setTimeout(poll, loader.devPollInterval);
       }
     }
+  } else {
+    await validateTaxonomyI18n(resolvedOptions);
   }
   const viteConfig = mergeConfig({
     // initial vite config

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "valaxy",
   "type": "module",
-  "version": "0.28.0-beta.6",
+  "version": "0.28.0-beta.7",
   "description": "📄 Vite & Vue powered static blog generator.",
   "author": {
     "email": "me@yunyoujun.cn",
@@ -95,7 +95,7 @@
     "jiti": "^2.6.1",
     "js-base64": "^3.7.8",
     "js-yaml": "^4.1.1",
-    "katex": "^0.16.38",
+    "katex": "^0.16.40",
     "lru-cache": "^11.2.7",
     "markdown-it": "^14.1.1",
     "markdown-it-anchor": "^9.2.0",
@@ -110,7 +110,7 @@
     "medium-zoom": "^1.1.0",
     "mermaid": "^11.13.0",
     "minisearch": "^7.2.0",
-    "mlly": "^1.8.1",
+    "mlly": "^1.8.2",
     "nprogress": "^0.2.0",
     "open": "10.1.0",
     "ora": "^9.3.0",
@@ -129,19 +129,19 @@
     "unplugin-vue-components": "28.0.0",
     "unplugin-vue-markdown": "^30.0.0",
     "vanilla-lazyload": "^19.1.3",
-    "vite": "^8.0.0",
+    "vite": "^8.0.1",
     "vite-dev-rpc": "^1.1.0",
     "vite-plugin-vue-devtools": "^8.1.0",
-    "vite-plugin-vue-layouts-next": "^2.0.1",
+    "vite-plugin-vue-layouts-next": "^2.1.0",
     "vite-ssg": "^28.3.0",
     "vite-ssg-sitemap": "^0.10.0",
     "vitepress-plugin-group-icons": "^1.7.1",
     "vue": "3.5.22",
     "vue-i18n": "^11.3.0",
-    "vue-router": "^5.0.3",
+    "vue-router": "^5.0.4",
     "yargs": "^18.0.0",
-    "@valaxyjs/devtools": "0.28.0-beta.6",
-    "@valaxyjs/utils": "0.28.0-beta.6"
+    "@valaxyjs/utils": "0.28.0-beta.7",
+    "@valaxyjs/devtools": "0.28.0-beta.7"
   },
   "devDependencies": {
     "@mdit-vue/plugin-component": "^3.0.2",

package/shared/node/i18n.ts

@@ -1,6 +1,6 @@
 import fs from 'fs-extra'
 import yaml from 'js-yaml'
-import { LOCALE_PREFIX } from '../constants'
+import { isLocaleKey, stripLocalePrefix } from '../utils/i18n'
 
 export const NODE_I18N: {
   locales: Record<string, any>
@@ -64,9 +64,9 @@ export function loadLocalesYml(localesPath: string, force = false): Record<strin
  * ```
  */
 export function nodeT(key: string, lang: string): string {
-  if (key.startsWith(LOCALE_PREFIX)) {
-    key = key.slice(LOCALE_PREFIX.length)
-  }
+  if (isLocaleKey(key))
+    key = stripLocalePrefix(key)
+
   const data = NODE_I18N.locales[lang] || {}
   const keys = key.split('.')
   let result: any = data

package/shared/utils/i18n.ts

@@ -1,3 +1,7 @@
+import { LOCALE_PREFIX } from '../constants'
+
+export type TaxonomyNamespace = 'tag' | 'category'
+
 /**
  * translate object
  *
@@ -15,3 +19,54 @@ export function tObject<T = string>(data: string | Record<string, T>, lang: stri
   }
   return data
 }
+
+/**
+ * Whether the value is an explicit locale key like `$locale:tag.notes`.
+ */
+export function isLocaleKey(value: string): boolean {
+  return value.startsWith(LOCALE_PREFIX)
+}
+
+/**
+ * Strip `$locale:` prefix when present.
+ */
+export function stripLocalePrefix(value: string): string {
+  return isLocaleKey(value) ? value.slice(LOCALE_PREFIX.length) : value
+}
+
+/**
+ * Resolve a nested locale message value by dot-separated key.
+ */
+export function getLocaleMessageValue(messages: Record<string, any> | undefined, key: string): any {
+  return key.split('.').reduce<any>((result, part) => result?.[part], messages)
+}
+
+/**
+ * Whether a locale message exists for the given key.
+ */
+export function hasLocaleMessage(messages: Record<string, any> | undefined, key: string): boolean {
+  return getLocaleMessageValue(messages, key) !== undefined
+}
+
+/**
+ * Resolve the effective locale key for a taxonomy term.
+ *
+ * - `$locale:tag.notes` -> `tag.notes` (explicit locale key)
+ * - `notes` in `tag` namespace -> `tag.notes`
+ */
+export function resolveTaxonomyLocaleKey(namespace: TaxonomyNamespace, rawValue: string): {
+  localeKey: string
+  isExplicitLocaleKey: boolean
+} {
+  if (isLocaleKey(rawValue)) {
+    return {
+      localeKey: stripLocalePrefix(rawValue),
+      isExplicitLocaleKey: true,
+    }
+  }
+
+  return {
+    localeKey: `${namespace}.${rawValue}`,
+    isExplicitLocaleKey: false,
+  }
+}