{"record":{"id":"e949a37af7a7edaf","repo":"alibaba/page-agent","slug":"translation-key-key-not-found-for-language","errorCode":null,"errorMessage":"Translation key \"${key}\" not found for language \"${this.language}\"","messagePattern":"Translation key \"(.+?)\" not found for language \"(.+?)\"","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/ui/src/i18n/index.ts","lineNumber":22,"sourceCode":"\ttype TranslationParams,\n\ttype TranslationSchema,\n\tlocales,\n} from './locales'\n\nexport class I18n {\n\tprivate language: SupportedLanguage\n\tprivate translations: TranslationSchema\n\n\tconstructor(language: SupportedLanguage = 'en-US') {\n\t\tthis.language = language in locales ? language : 'en-US'\n\t\tthis.translations = locales[this.language]\n\t}\n\n\t// 类型安全的翻译方法\n\tt(key: TranslationKey, params?: TranslationParams): string {\n\t\tconst value = this.getNestedValue(this.translations, key)\n\t\tif (!value) {\n\t\t\tconsole.warn(`Translation key \"${key}\" not found for language \"${this.language}\"`)\n\t\t\treturn key\n\t\t}\n\n\t\tif (params) {\n\t\t\treturn this.interpolate(value, params)\n\t\t}\n\t\treturn value\n\t}\n\n\tprivate getNestedValue(obj: any, path: string): string | undefined {\n\t\treturn path.split('.').reduce((current, key) => current?.[key], obj)\n\t}\n\n\tprivate interpolate(template: string, params: TranslationParams): string {\n\t\treturn template.replace(/\\{\\{(\\w+)\\}\\}/g, (match, key) => {\n\t\t\t// Use != null to check for both null and undefined, allow empty strings\n\t\t\treturn params[key] != null ? params[key].toString() : match\n\t\t})","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/alibaba/page-agent/blob/d02db1ee7c41f5315beda88bab2fe935c580f662/packages/ui/src/i18n/index.ts#L4-L40","documentation":"The I18n `t()` method failed to resolve a translation key for the currently selected language, so it logs a warning and returns the raw key string. This happens when the key is missing from the loaded translation dictionary, misspelled, or not yet added for that language.","triggerScenarios":"Calling `i18n.t('some.key')` (directly or via Panel internals like status-change handlers, activity updates, askUser, reset, or tool-executing text) with a key that does not exist in the translations object for `this.language`, e.g. adding a new UI string but not adding it to every locale file, or passing a dynamic/runtime-built key string that isn't a valid TranslationKey.","commonSituations":"Adding a new UI string to the Panel but forgetting to add it to one locale; switching to a language with an incomplete dictionary; renaming a key in code but not in translation files; passing interpolated/dynamic keys that bypass the TranslationKey type.","solutions":["Add the missing key to the translation dictionary for the affected language (and ideally all locales)","Fix the typo in the key passed to t() so it matches an existing TranslationKey","If the key is intentionally dynamic, add a typed constant or lookup map so TypeScript verifies it exists","Audit with a test that iterates all keys used by the Panel against every locale's dictionary"],"exampleFix":"// before\nt('panel.toolExecutingMsg') // key missing in de.json\n\n// after: add to the language file\n\"panel\": { \"toolExecutingMsg\": \"Tool wird ausgeführt: {name}\" }","handlingStrategy":"type-guard","validationCode":"// Check the key exists before translating\nif (i18n.has(key)) {\n  label = i18n.t(key)\n} else {\n  label = fallbackEnglishText\n}","typeGuard":"const isTranslationKey = (\n  key: string,\n  keys: readonly string[]\n): key is TranslationKey => keys.includes(key)\n\n// usage: isTranslationKey(dynamicKey, ALL_TRANSLATION_KEYS) ? i18n.t(dynamicKey) : fallback","tryCatchPattern":null,"preventionTips":["Always add new keys to every locale file in the same commit","Never build translation keys from uncontrolled runtime strings; use a typed union (TranslationKey)","Add a unit test that diffs the key sets of all locale files so incomplete locales fail CI"],"tags":["i18n","translation-key","localization","missing-key"],"backgroundTag":"missing-translation-key","analyzedSha":"d02db1ee7c41f5315beda88bab2fe935c580f662","analyzedAt":"2026-08-28T19:39:48.634Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}