agent-desk-ng/docs/knowledge-localization.md

Knowledge retrieval localization and derived data

Locale and request lifetime

The dashboard debug-search, debug-answer, and index-build handlers pass their HTTP request context into RAG. i18nx.WithLocale adds the locale already selected by i18nx.Locale without dropping cancellation, deadlines, or parent values. i18nx.LocaleFromContext falls back to the configured DefaultLocale for existing callers and background jobs.

This does not change application-wide locale detection. In particular, ResolveRequestLocale continues to use the configured default rather than trusting request language headers. Callers with an explicitly selected locale can carry it through the context helper.

Built-in debug-answer system/user prompts, no-answer and model-error fallbacks, answer-status names, and context wrappers use the English, Russian, and Chinese catalogs. Configured custom prompts, model output, user questions, document bodies, and FAQ source answers are not translated or rewritten. Cancellation is not converted into a completed fallback answer.

FAQ labels and existing index data

FAQ question, similar-question, and answer labels are application-owned. The source strings are separate inputs and are preserved without trimming or substring replacement. New FAQ index content uses the configured default locale, not whichever request locale an administrator supplies. This keeps index generation consistent for a deployment.

For live retrieval only, the stored FAQ chunk is compared byte-for-byte with a complete serialization of the current authoritative FAQ record:

• The exact frozen pre-localization Chinese format is recognized.
• The generated format in each currently supported locale is recognized.
• Only a complete match permits rendering the application-owned labels in the selected context locale. This also safely handles newlines or literal 问题：, 相似问：, and 回答： strings inside source content, because they are never parsed as separators.
• If the source has since changed, the chunk was edited manually, the stored format is unknown, or no exact match exists, the stored text remains unchanged. Document chunks never enter this FAQ conversion path.

Locale changes and reads do not update stored chunks, vectors, hashes, FAQ records, or historical retrieval logs. Previous answers and hit snippets are historical evidence and remain as recorded. Newly generated logs record the localized content actually used for that new request; they do not relabel old answers after the fact.

Unverifiable legacy or stale chunks may therefore still show old generated wording. Rebuilding the affected index from its current source through the existing authorized indexing action is the deliberate way to regenerate that derived data. A rebuild can change embeddings, scores, and retrieval behavior and should be validated against representative queries before a production rollout. This change contains no migration, automatic rebuild, or production data write.

Failure responses

Immediate debug/index failures use stable localized summaries instead of exposing SQL, provider, or network diagnostics. Known catalog-backed application errors without arbitrary diagnostic arguments retain their message and code even when wrapped by a provider error. Unrecognized errors, raw code errors, and errors containing interpolation arguments are replaced with a generic localized operation error. Stored operational details are not returned by this boundary.

Focused validation

Run the isolated tests without external model or vector service credentials:

go test -tags dev ./internal/pkg/i18nx ./internal/ai/rag ./internal/handlers/dashboard

Coverage includes locale fallback and isolation; request cancellation/deadlines; localized no-hit, model-error, empty-model and successful generation branches; byte-for-byte source preservation; exact legacy matching and stale-content preservation; localized context wrappers; and safe error responses in all three locales. The model-generation tests inject a local function and the cancellation tests return before database or provider access.

API labels, index failures, and FAQ spreadsheets

Knowledge-base, document, FAQ, directory, and retrieval-history DTO builders accept an optional locale; omitted locales use the configured default for compatibility. Dashboard handlers supply their selected locale explicitly. Stable type/status/index codes remain unchanged. The UI maps those codes with shared catalog helpers rather than trusting legacy display-name strings. Unknown values use a localized unknown label.

Document and FAQ DTOs return a safe localized indexing-failure summary, not the stored provider or SQL diagnostic. The UI applies the same safe summary when connected to an older server. This change does not rewrite stored operational diagnostics or add a public raw-error endpoint.

FAQ spreadsheet templates and export headers use the selected locale. Import accepts Russian headings and both legacy Chinese and English aliases. Export preserves stored question, answer, similar-question, and note values; import preserves authored question, answer, note, and individual nonempty similar-question text, including surrounding whitespace. Newlines remain the spreadsheet format's delimiter between similar questions. Missing optional columns no longer copy the question column accidentally. No sample-data initializer or table-reset command is needed or run.

Additional isolated checks:

go test -tags dev ./internal/builders ./internal/services -run 'TestKnowledgeBuilders|TestKnowledgeFAQExcel|TestImportKnowledgeFAQs|TestDeleteKnowledgeBase|TestBuildKnowledgeBaseModel' -count=1
node --test web/lib/knowledge-i18n.test.mjs

These are logic and contract checks, not production or browser acceptance. Before rollout, validate the real KB list, content dialog, spreadsheet import/export, debug search/answer, and history in Russian and English at desktop and narrow widths. Use isolated fixtures and do not run the destructive sample-data initializer.