apache / apache/maka

fix(i18n): make built-in tool presentation locale-aware

Open
#3,962 2 comments 0 reactions 1 assignee Claimed by @Colafornia View on GitHub
bug
Dominant language
TypeScript
Stars
5.4k
Forks
502
Avg merge
1d 2h
Merged PRs (30d)
715

Description

## Problem

Maka has a locale authority and typed `UiCatalog` catalogs, but tool presentation does not use the same localization contract.

`MakaTool.displayName?: string` is currently used for two different purposes:

- a tool definition provides a human-readable name;
- the runtime copies that name into tool events and persisted messages.

The UI then prefers the persisted `displayName` before resolving a locale-aware label. This makes a locale-independent runtime field the highest-priority source for user-facing tool copy.

As a result, built-in tools can bypass the active locale. For example, English mode can show `浏览器导航`, while Chinese mode can show the fixed English name `Web search`.

This is a presentation-boundary problem, not only a missing translation entry. Adding individual translations without changing the boundary will allow the same regression whenever a new built-in tool declares a fixed-language `displayName`.

Relevant paths include:

- `packages/runtime/src/tool-runtime.ts`
- `packages/ui/src/tool-activity/display-name.ts`
- `apps/desktop/src/main/browser/browser-tools.ts`
- `apps/desktop/src/main/rive-workflow-tool.ts`
- `packages/runtime/src/explore-agent-tool.ts`
- `packages/runtime/src/web-search-tool.ts`
- `packages/runtime/src/native-web-search-tool.ts`

## Desired outcome

Define and enforce a locale-aware tool presentation boundary:

- Runtime events and persisted messages keep a stable canonical tool ID and locale-independent tool data.
- The presentation layer maps Maka-owned built-in tool IDs to typed `UiCatalog` entries using the active locale.
- Existing session history uses the current locale when it is rendered. Stored events do not need to be rewritten.
- Unknown MCP and custom tool names remain available as raw external identifiers.
- Tool arguments, commands, paths, user content, model output, logs, and protocol values remain unchanged.

Use the existing Maka localization mechanism. Do not introduce a new i18n framework or move all product copy into one global catalog.

The known browser, Rive, Explore, and web-search names should be migrated as the first concrete cases. The same audit should cover every built-in tool definition.

## Acceptance criteria

- The tool presentation API distinguishes stable tool identity from localized display text.
- Every Maka-owned built-in tool shown in Desktop resolves its name through a typed locale catalog.
- English mode does not show Chinese built-in tool names.
- Chinese mode does not show fixed English built-in tool names.
- Changing the locale updates built-in tool names in existing session history.
- Unknown MCP and custom tool names remain unchanged.
- New built-in tool IDs cannot be added without corresponding locale entries.
- Tests cover the presentation resolver for all built-in tool IDs in both supported locales.
- No new localization framework or repository-wide copy migration is introduced.

AI disclosure: OpenAI Codex drafted this issue under maintainer direction.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.