alibaba/page-agent · warning

Translation key " " not found for language

Error message

Translation key "${key}" not found for language "${this.language}"

What it means

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.

Solutions

1. Add the missing key to the translation dictionary for the affected language (and ideally all locales)
2. Fix the typo in the key passed to t() so it matches an existing TranslationKey
3. If the key is intentionally dynamic, add a typed constant or lookup map so TypeScript verifies it exists
4. Audit with a test that iterates all keys used by the Panel against every locale's dictionary

Example fix

// before
t('panel.toolExecutingMsg') // key missing in de.json

// after: add to the language file
"panel": { "toolExecutingMsg": "Tool wird ausgeführt: {name}" }

// Check the key exists before translating
if (i18n.has(key)) {
  label = i18n.t(key)
} else {
  label = fallbackEnglishText
}

const isTranslationKey = (
  key: string,
  keys: readonly string[]
): key is TranslationKey => keys.includes(key)

// usage: isTranslationKey(dynamicKey, ALL_TRANSLATION_KEYS) ? i18n.t(dynamicKey) : fallback

When it happens

Trigger: 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.

Common situations: 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.

AI-assisted analysis of alibaba/page-agent@d02db1ee7c (2026-08-28). Data as JSON: /api/errors/e949a37af7a7edaf. Report an issue: GitHub.

Appendix: source

Thrown at packages/ui/src/i18n/index.ts:22

	type TranslationParams,
	type TranslationSchema,
	locales,
} from './locales'

export class I18n {
	private language: SupportedLanguage
	private translations: TranslationSchema

	constructor(language: SupportedLanguage = 'en-US') {
		this.language = language in locales ? language : 'en-US'
		this.translations = locales[this.language]
	}

	// 类型安全的翻译方法
	t(key: TranslationKey, params?: TranslationParams): string {
		const value = this.getNestedValue(this.translations, key)
		if (!value) {
			console.warn(`Translation key "${key}" not found for language "${this.language}"`)
			return key
		}

		if (params) {
			return this.interpolate(value, params)
		}
		return value
	}

	private getNestedValue(obj: any, path: string): string | undefined {
		return path.split('.').reduce((current, key) => current?.[key], obj)
	}

	private interpolate(template: string, params: TranslationParams): string {
		return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
			// Use != null to check for both null and undefined, allow empty strings
			return params[key] != null ? params[key].toString() : match
		})

View on GitHub (pinned to d02db1ee7c)