Enhance localization of the ai-ide package

[pisv]

What it does

This PR provides localization enhancements for the ai-ide package.

How to test

There are no testing steps as such. This PR is strictly about localization enhacements. Hopefully, it can be verified by reviewing the actual code changes.

Breaking changes

• This PR introduces breaking changes and requires careful review. If yes, the breaking changes section in the changelog has been updated.

Review checklist

• As an author, I have thoroughly tested my changes and carefully followed the review guidelines

Reminder for reviewers

• As a reviewer, I agree to behave in accordance with the review guidelines

[ndoschek]

Thank you @pisv, really appreciate your continued work on the localization enhancements! 🙏

I noticed two things:

1. The descriptions for the tool requests are still missing, e.g., in the following case:
   
   These descriptions appear in the AI chat input suggestions, such as here:
   
2. The messages defined in packages/ai-ide/src/browser/ide-chat-welcome-message-provider.tsx are only partially localized, some html elements are localized, but most are not.
   However, the current approach is a bit cumbersome since each tag needs to be localized individually which makes the code harder to read and maintain. We can of course continue improving this in a follow-up ticket to explore more maintainable solutions as there also other occurrences with the same problem.

[pisv]

@ndoschek Thanks a lot for your thorough reviews, I really appreciate it! 👍

I absolutely concur with your comments. Having said that,

1. As far as I can see, everything regarding tool requests are consistently not localized in Theia, and I guess this is intentional.

   Here's what AI itself thinks about it:

   Should the function descriptions be localized (translated) in an AI application?

   Short answer:
   Generally, no, function descriptions should not be localized (i.e., translated) and should remain in English.

   Why?

   1. Model understanding is optimized for English:
      The OpenAI models, especially for function calling, are primarily trained on and optimized for English JSON Schema and metadata. Function descriptions in English help the model accurately understand the purpose of the function and properly match user intents to function calls.

   2. Consistency and reliability:
      The model expects function definitions—including function names, descriptions, and parameters—to be in English. Localizing descriptions could confuse the model or reduce its ability to correctly parse and use those definitions, resulting in incorrect or missed function calls.

   3. Less user-facing:
      The function descriptions are not typically directly shown to end users; rather, they serve as guidance for the model to understand the functions.

   Since, as you have indicated, the tool descriptions do appear in the AI chat input suggestions in Theia, I think that it could probably be useful to have a separate property for user-facing rather than AI-facing descriptions for tool requests. Those user-facing descriptions would have to be localized. However, I'd suggest to discuss it in a separate issue.

2. Yes, unfortunately, there seems to be no good way to localize text with interspersed HTML elements like in ide-chat-welcome-message-provider.tsx or getting-started-widget.tsx using the current approach. Therefore, I also think that this problem would be worth discussing in a separate issue.

Thank you!

[pisv]

@ndoschek I'd also like to ask your opinion about a pontential follow-up regarding localization of ai-related packages. I've noticed that the ai-claude-code package is mostly unlocalized currently. Given that this package has been created just a while ago, do you think that it would be fine to try to localize it as it stands, or would it be better to postpone its localization until it becomes a bit more mature?

[ndoschek]

Thanks @pisv for the investigation
The tool descriptions are visible to the user but this is also true for variable and agent descriptions, which are handled in the same way and currently have localized descriptions.
Introducing a separate user-facing description field seems a bit overkill and could become hard to maintain imo.

@eneufeld do you have an opinion on this? Thanks in advance!

Ad 2), I'll take care of opening a follow-up.

Regarding the ai-claude-code package, I think it is stable enough to go ahead, thank you for offering! In case of future updates, we should already be aware of that oversight and make sure to include them right away.

[pisv]

The tool descriptions are visible to the user but this is also true for variable and agent descriptions, which are handled in the same way and currently have localized descriptions.

Just to clarify, there is a significant difference between tool descriptions and variable/agent descriptions: tool descriptions are meant for consumption by the language model (AI), while variable/agent descriptions are not, as far as I can tell...

[eneufeld]

Hi @ndoschek , @pisv
I double checked the code:

• Variable descriptions are only user facing.
• Agent descriptions are mainly user facing, but the agent-variable (packages/ai-chat/src/common/chat-agents-variable-contribution.ts) uses the description as part of the variable resolution. So this description can end up in the chat, eg the orchestrator uses that to select the best fitting agent.
• Tool descriptions are mainly llm facing, the only ui place where this is used is in the chat when you get the auto completion. But the LLM is using these descriptions to select the best tool.

My take would be:

• Variable descriptions should be translatable
• Agent descriptions is probably fine, the llm will manage a different language usually
• tool descriptions, don't do it.

The only way, how we might use translations but only if we retrieve them on the fly where they are needed. But one would need to look at the i18n infrastructure.

[pisv]

BTW, there is already a precedent in Theia that uses two separate properties for both localized and unlocalized versions of the same text: Command objects. Commands have label and originalLabel, category and originalCategory.

Probably, something like that could be done for tool descriptions (and may be also agent descriptions) too. But I'd suggest to have a separate issue for that.

[pisv]

As part of this PR, I have pushed 91f71e4 with localization enhancements for the newly added GitHub Agent.

@ndoschek Can you please review?

[ndoschek]

Thanks @eneufeld, I'll create a ticket for the tool descriptions, that we have this documented somewhere.

Besides that, changes LGTM now, thanks for the updates @pisv! 👍