akanjs 3.0.0-alpha.81 → 3.0.0-alpha.83

package/client/makePageProto.tsx

@@ -170,12 +170,14 @@ export const makePageProto = <
             }}
           />
         ) as ReactNode;
+
       l.trans = <Returns extends ReactNode>(
         translation: Record<"en" | "ko" | (string & {}), Returns>,
       ): Returns extends string ? string : Returns => {
-        return (translation[lang as "en" | "ko" | (string & {})] ?? "unknown translation") as Returns extends string
-          ? string
-          : Returns;
+        const written = translation[lang as "en" | "ko" | (string & {})];
+        if (written !== undefined) return written as Returns extends string ? string : Returns;
+        const fallback = translation[parseAkanI18nEnv().defaultLocale] ?? Object.values(translation).at(0);
+        return (fallback ?? "") as Returns extends string ? string : Returns;
       };
       return { path, l, lang };
     },

package/client/translator.ts

@@ -1,4 +1,4 @@
-import { pathGetLoose } from "akanjs/common";
+import { interpolateTranslation, parseAkanI18nEnv, pathGetLoose } from "akanjs/common";
 
 export interface Dictionary {
   [key: string]: {
@@ -61,10 +61,19 @@ export class Translator {
     delete getTranslatorState().activePath;
   }
   static translateByLocale(lang: string, key: string, param?: Record<string, string | number>): string {
+    const msg = Translator.#lookup(lang, key) ?? Translator.#lookupDefault(lang, key) ?? key;
+    return interpolateTranslation(msg, param);
+  }
+  static #lookup(lang: string, key: string) {
     const dictionary = getTranslatorState().langDictionaryMap.get(lang);
-    if (!dictionary) return key;
-    const msg = (pathGetLoose(key, dictionary, ".", { t: key }) as { t: string }).t;
-    return param ? msg.replace(/{([^}]+)}/g, (_, key: string) => param[key] as string) : msg;
+    if (!dictionary) return undefined;
+    const node = pathGetLoose(key, dictionary, ".") as { t?: unknown } | null;
+    return typeof node?.t === "string" ? node.t : undefined;
+  }
+
+  static #lookupDefault(lang: string, key: string) {
+    const { defaultLocale } = parseAkanI18nEnv();
+    return defaultLocale === lang ? undefined : Translator.#lookup(defaultLocale, key);
   }
 
   static seed(lang: string, dict: Dictionary | undefined) {

package/common/index.ts

@@ -18,6 +18,7 @@ export { formatNumber } from "./formatNumber";
 export { formatPhone } from "./formatPhone";
 export { getAllPropertyDescriptors } from "./getAllPropertyDescriptors";
 export { type AkanHmrPhase, getAkanHmrPhase, isAkanHmrApplying } from "./hmrPhase";
+export { interpolateTranslation } from "./interpolateTranslation";
 export { isDayjs } from "./isDayjs";
 export { isEmail } from "./isEmail";
 export { isPhoneNumber } from "./isPhoneNumber";

package/common/interpolateTranslation.ts

@@ -0,0 +1,12 @@
+/**
+ * Fills `{name}` placeholders in a translated string.
+ *
+ * A placeholder whose value is absent is left as written: the author's `{name}` reads as a bug in the UI, while
+ * the string "undefined" reads as content, and a partially supplied `data` must not corrupt the rest of the line.
+ */
+export const interpolateTranslation = (message: string, data: Record<string, unknown> | undefined) => {
+  if (!data) return message;
+  return message.replace(/{([^}]+)}/g, (placeholder, name: string) =>
+    data[name] === undefined ? placeholder : String(data[name]),
+  );
+};

package/dictionary/dictionaryRegistry.ts

@@ -1,3 +1,5 @@
+import { parseAkanI18nEnv } from "akanjs/common";
+
 import { ModelDictInfo, ScalarDictInfo, ServiceDictInfo } from "./dictInfo";
 import type { DictModule } from "./locale";
 import type { DictionaryNode, RootDictionary } from "./trans";
@@ -9,6 +11,12 @@ export interface DictionaryModuleInfo {
   languages: string[];
 }
 
+export interface LocaleGap {
+  locale: string;
+  total: number;
+  missing: string[];
+}
+
 /**
  * Collects every dictionary tree built by `makeTrans` so a server process can read the merged result.
  *
@@ -49,6 +57,25 @@ export class DictionaryRegistry {
     return Object.fromEntries([...DictionaryRegistry.#modules.entries()].map(([key, info]) => [key, { ...info }]));
   }
 
+  /**
+   * Which configured locales the registered dictionaries never wrote, per locale.
+   *
+   * A dictionary declares its own locale tuple — `serviceDictionary(["en", "ko"])` — and a lib ships that tuple to
+   * every app that mounts it, so an app that adds a third locale cannot widen it from the outside. Every key those
+   * modules own then resolves through the default-locale fallback: the screen stays readable and nothing throws,
+   * which is exactly why the gap is invisible without asking.
+   */
+  static getLocaleGaps(locales: string[] = parseAkanI18nEnv().locales): LocaleGap[] {
+    const modules = [...DictionaryRegistry.#modules.entries()];
+    return locales
+      .map((locale) => ({
+        locale,
+        total: modules.length,
+        missing: modules.filter(([, info]) => !info.languages.includes(locale)).map(([refName]) => refName),
+      }))
+      .filter((gap) => gap.missing.length);
+  }
+
   /** Flattened dotted paths of every leaf translation, e.g. `"user.signal.createUser.arg.data"`. */
   static getKeys(root: RootDictionary = DictionaryRegistry.getRoot()): string[] {
     const keys = new Set<string>();

package/dictionary/trans.ts

@@ -1,5 +1,5 @@
 import type { GetStateObject, ObjectAssign, Prettify } from "akanjs/base";
-import { pathGetLoose } from "akanjs/common";
+import { interpolateTranslation, parseAkanI18nEnv, pathGetLoose } from "akanjs/common";
 
 import { DictionaryRegistry } from "./dictionaryRegistry";
 import type { DictModule } from "./locale";
@@ -25,9 +25,7 @@ export const makeDictionary = <Dicts extends Record<string, unknown>[]>(
   return Object.assign(...(dicts as unknown as [object, object])) as Prettify<ObjectAssign<Dicts>>;
 };
 
-const languages = ["en", "ko", "zhChs", "zhCht", "ja"] as const;
-
-type Language = (typeof languages)[number];
+type Language = "en" | "ko" | "zhChs" | "zhCht" | "ja" | (string & {});
 export interface TransMessageOption {
   key?: string;
   duration?: number;
@@ -191,13 +189,22 @@ export const makeTrans = <
       }
     };
   }
+  const lookup = (lang: string, modelName: string, msgKey: string) => {
+    const model = rootDictionary[lang]?.[modelName];
+    if (!model) return undefined;
+    const node = pathGetLoose(msgKey, model, ".") as { t?: unknown } | null;
+    return typeof node?.t === "string" ? node.t : undefined;
+  };
+
+  const lookupDefault = (lang: string, modelName: string, msgKey: string) => {
+    const { defaultLocale } = parseAkanI18nEnv();
+    return defaultLocale === lang ? undefined : lookup(defaultLocale, modelName, msgKey);
+  };
   const translate = (lang: Language, key: _DictKey, data?: TranslationData) => {
-    const [modelName, ...msgKeys] = key.split(".");
+    const [modelName = "", ...msgKeys] = key.split(".");
     const msgKey = msgKeys.join(".");
-    const langDict = rootDictionary[lang] ?? {};
-    const model = langDict[modelName as string] ?? {};
-    const message = pathGetLoose(msgKey as string, model, ".", { t: key }) as { t: string };
-    return message.t;
+    const message = lookup(lang, modelName, msgKey) ?? lookupDefault(lang, modelName, msgKey) ?? (key as string);
+    return interpolateTranslation(message, data);
   };
   const getDictionary = (lang: Language) => {
     return rootDictionary[lang];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.81",
+  "version": "3.0.0-alpha.83",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanServer.ts

@@ -1,7 +1,7 @@
 import type { AkanWebConfig, AkanWebOption } from "akanjs";
 import { type BackendEnv, type BaseEnv, getEnv } from "akanjs/base";
 import { Logger, logSeverity, websocketBinaryFrameContract } from "akanjs/common";
-import { DictionaryLookup } from "akanjs/dictionary";
+import { DictionaryLookup, DictionaryRegistry } from "akanjs/dictionary";
 import type {
   Adaptor,
   AdaptorCls,
@@ -611,6 +611,24 @@ export class AkanServer {
     );
   }
 
+  /**
+   * Names, once at boot, every configured locale the dictionaries never wrote.
+   *
+   * A dictionary declares its own locale tuple and a lib ships that tuple to every app that mounts it, so an app
+   * that configures a third locale cannot widen it from the outside — the framework's own `base.*` keys included.
+   * Those keys then resolve through the default-locale fallback, which is a readable screen and therefore a
+   * silent one: the only other symptom is text that never turned into the new language.
+   */
+  #reportLocaleCoverage() {
+    for (const { locale, missing, total } of DictionaryRegistry.getLocaleGaps()) {
+      const listed = missing.slice(0, 10).join(", ");
+      const rest = missing.length > 10 ? `, and ${missing.length - 10} more` : "";
+      this.logger.warn(
+        `Locale "${locale}" is configured but ${missing.length}/${total} dictionaries do not declare it, so their keys fall back to the default locale: ${listed}${rest}`,
+      );
+    }
+  }
+
   #createBuiltinRoutes(): HttpRoutes {
     const { appName } = getEnv();
     const openapiRoutes: HttpRoutes = this.openapi
@@ -658,6 +676,7 @@ export class AkanServer {
       : {};
 
     mcpRouter?.report();
+    this.#reportLocaleCoverage();
 
     const devtoolsRoutes = new DevtoolsRouter({
       di: this.#di,

package/types/client/translator.d.ts

@@ -7,6 +7,7 @@ export interface AllDictionary {
     [key: string]: Dictionary;
 }
 export declare class Translator {
+    #private;
     constructor(dictionary: Record<string, Record<string, Record<string, unknown>>>);
     hasDictionary(lang: string): boolean;
     static setActiveLocale(lang: string | undefined): void;

package/types/common/index.d.ts

@@ -9,6 +9,7 @@ export { formatNumber } from "./formatNumber.d.ts";
 export { formatPhone } from "./formatPhone.d.ts";
 export { getAllPropertyDescriptors } from "./getAllPropertyDescriptors.d.ts";
 export { type AkanHmrPhase, getAkanHmrPhase, isAkanHmrApplying } from "./hmrPhase.d.ts";
+export { interpolateTranslation } from "./interpolateTranslation.d.ts";
 export { isDayjs } from "./isDayjs.d.ts";
 export { isEmail } from "./isEmail.d.ts";
 export { isPhoneNumber } from "./isPhoneNumber.d.ts";

package/types/common/interpolateTranslation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Fills `{name}` placeholders in a translated string.
+ *
+ * A placeholder whose value is absent is left as written: the author's `{name}` reads as a bug in the UI, while
+ * the string "undefined" reads as content, and a partially supplied `data` must not corrupt the rest of the line.
+ */
+export declare const interpolateTranslation: (message: string, data: Record<string, unknown> | undefined) => string;

package/types/dictionary/dictionary.d.ts

@@ -4,10 +4,10 @@ export declare const dictionary: {
     agentTurn: import("./locale.d.ts").DictModule<import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc`, never>;
     agent: import("./locale.d.ts").DictModule<import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, "agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed">;
 };
-export declare const Err: import("./trans.d.ts").ErrConstructor<"base.error.gatewayTimeout" | "base.error.serverUnavailable" | "base.error.serverUnreachable" | "base.error.unexpectedResponse" | "agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed">, translate: (lang: "en" | "ko" | "zhChs" | "zhCht" | "ja", key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "ok" | "agent" | "connecting" | "new" | "success" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "cameraPromptHeader" | "cameraPromptPhoto" | "cameraPromptPicture" | "cameraPromptCancel" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, data?: import("./trans.d.ts").TranslationData) => string, msg: {
+export declare const Err: import("./trans.d.ts").ErrConstructor<"base.error.gatewayTimeout" | "base.error.serverUnavailable" | "base.error.serverUnreachable" | "base.error.unexpectedResponse" | "agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed">, translate: (lang: "en" | "ko" | (string & {}) | "zhChs" | "zhCht" | "ja", key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "ok" | "agent" | "connecting" | "new" | "success" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "cameraPromptHeader" | "cameraPromptPhoto" | "cameraPromptPicture" | "cameraPromptCancel" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, data?: import("./trans.d.ts").TranslationData) => string, msg: {
     info: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "ok" | "agent" | "connecting" | "new" | "success" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "cameraPromptHeader" | "cameraPromptPhoto" | "cameraPromptPicture" | "cameraPromptCancel" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
     success: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "ok" | "agent" | "connecting" | "new" | "success" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "cameraPromptHeader" | "cameraPromptPhoto" | "cameraPromptPicture" | "cameraPromptCancel" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
     error: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "ok" | "agent" | "connecting" | "new" | "success" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "cameraPromptHeader" | "cameraPromptPhoto" | "cameraPromptPicture" | "cameraPromptCancel" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
     warning: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "ok" | "agent" | "connecting" | "new" | "success" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "cameraPromptHeader" | "cameraPromptPhoto" | "cameraPromptPicture" | "cameraPromptCancel" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
     loading: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "ok" | "agent" | "connecting" | "new" | "success" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "cameraPromptHeader" | "cameraPromptPhoto" | "cameraPromptPicture" | "cameraPromptCancel" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
-}, getDictionary: (lang: "en" | "ko" | "zhChs" | "zhCht" | "ja") => object, getAllDictionary: () => import("./trans.d.ts").RootDictionary, __Dict_Key__: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "ok" | "agent" | "connecting" | "new" | "success" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "cameraPromptHeader" | "cameraPromptPhoto" | "cameraPromptPicture" | "cameraPromptCancel" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, __Error_Key__: "base.error.gatewayTimeout" | "base.error.serverUnavailable" | "base.error.serverUnreachable" | "base.error.unexpectedResponse" | "agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed";
+}, getDictionary: (lang: "en" | "ko" | (string & {}) | "zhChs" | "zhCht" | "ja") => object, getAllDictionary: () => import("./trans.d.ts").RootDictionary, __Dict_Key__: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "ok" | "agent" | "connecting" | "new" | "success" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "cameraPromptHeader" | "cameraPromptPhoto" | "cameraPromptPicture" | "cameraPromptCancel" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, __Error_Key__: "base.error.gatewayTimeout" | "base.error.serverUnavailable" | "base.error.serverUnreachable" | "base.error.unexpectedResponse" | "agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed";

package/types/dictionary/dictionaryRegistry.d.ts

@@ -5,6 +5,11 @@ export interface DictionaryModuleInfo {
     kind: DictionaryModuleKind;
     languages: string[];
 }
+export interface LocaleGap {
+    locale: string;
+    total: number;
+    missing: string[];
+}
 /**
  * Collects every dictionary tree built by `makeTrans` so a server process can read the merged result.
  *
@@ -19,6 +24,15 @@ export declare class DictionaryRegistry {
     static getRoot(): RootDictionary;
     static getLanguages(): string[];
     static getModules(): Record<string, DictionaryModuleInfo>;
+    /**
+     * Which configured locales the registered dictionaries never wrote, per locale.
+     *
+     * A dictionary declares its own locale tuple — `serviceDictionary(["en", "ko"])` — and a lib ships that tuple to
+     * every app that mounts it, so an app that adds a third locale cannot widen it from the outside. Every key those
+     * modules own then resolves through the default-locale fallback: the screen stays readable and nothing throws,
+     * which is exactly why the gap is invisible without asking.
+     */
+    static getLocaleGaps(locales?: string[]): LocaleGap[];
     /** Flattened dotted paths of every leaf translation, e.g. `"user.signal.createUser.arg.data"`. */
     static getKeys(root?: RootDictionary): string[];
     /** Test-only reset; the registry is module-level global state. */

package/types/dictionary/trans.d.ts

@@ -17,8 +17,7 @@ export type TransMessage<Locale extends Record<string, unknown>> = {
     [K in keyof Locale]-?: `${K & string}${Locale[K] extends Record<string, unknown> ? `.${keyof Locale[K] extends string ? keyof Locale[K] : never}` : ""}`;
 }[keyof Locale];
 export declare const makeDictionary: <Dicts extends Record<string, unknown>[]>(...dicts: Dicts) => Prettify<ObjectAssign<Dicts>>;
-declare const languages: readonly ["en", "ko", "zhChs", "zhCht", "ja"];
-type Language = (typeof languages)[number];
+type Language = "en" | "ko" | "zhChs" | "zhCht" | "ja" | (string & {});
 export interface TransMessageOption {
     key?: string;
     duration?: number;

package/ui/System/SelectLanguage.tsx

@@ -12,15 +12,36 @@ const languageNames = {
   ko: "한국어",
   zhChs: "简体中文",
   zhCht: "繁體中文",
+  ja: "日本語",
+} as const;
+
+const nameOf = (locale: string) => languageNames[locale as keyof typeof languageNames] ?? locale;
+
+const warned = new Set<string>();
+
+const warnDropped = (dropped: string[], locales: string[]) => {
+  if (process.env.AKAN_PUBLIC_ENV !== "local") return;
+  const unseen = dropped.filter((locale) => !warned.has(locale));
+  if (!unseen.length) return;
+  for (const locale of unseen) warned.add(locale);
+  console.warn(
+    `<SelectLanguage> dropped ${unseen.join(", ")}: not in AKAN_PUBLIC_LOCALES (${locales.join(",")}). Add the locale to the app i18n config, or drop it from the \`languages\` prop.`,
+  );
 };
 
 export interface SelectLanguageProps {
   className?: string;
   languages?: string[];
 }
-export const SelectLanguage = ({ className, languages = parseAkanI18nEnv().locales }: SelectLanguageProps) => {
+export const SelectLanguage = ({ className, languages }: SelectLanguageProps) => {
   const { lang } = usePage();
-  const offered = languages.filter((lang) => !!languageNames[lang as keyof typeof languageNames]);
+  const { locales } = parseAkanI18nEnv();
+  const requested = languages ?? locales;
+  const offered = requested.filter((locale) => locales.includes(locale));
+  warnDropped(
+    requested.filter((locale) => !locales.includes(locale)),
+    locales,
+  );
   const setLanguage = st
     .tool("setLanguage")
     .desc("Show the site in another language.")
@@ -32,18 +53,18 @@ export const SelectLanguage = ({ className, languages = parseAkanI18nEnv().local
     <Dropdown
       className={className}
       buttonClassName="mx-2 my-auto h-8 min-h-0 border-none px-3 font-medium text-xs md:mx-4"
-      value={languageNames[lang as keyof typeof languageNames]}
-      content={offered.map((lang) => (
-        <li key={lang}>
+      value={nameOf(lang)}
+      content={offered.map((locale) => (
+        <li key={locale}>
           <button
             type="button"
             className={buttonRecipe({ variant: "ghost", size: "sm" }, "w-full justify-start")}
             onClick={() => {
-              void setLanguage(lang);
+              void setLanguage(locale);
             }}
             {...agentAttrs(setLanguage)}
           >
-            {languageNames[lang as keyof typeof languageNames]}
+            {nameOf(locale)}
           </button>
         </li>
       ))}