Making an AI Agent Speak Uyghur: Localization in HexClaw v0.4.0

This started in a conversation with a Uyghur friend a few days ago. He wanted an AI assistant too, but after looking around, could not find a local agent desktop app he could naturally use in Uyghur.

That made me curious: how far does Uyghur support actually extend in local AI-agent desktop apps?

I tried several common apps myself and found much what he described: no Uyghur option, a partial switch that fell back to Chinese or English, or a distorted interface—emoji at the end of the wrong line, reversed version numbers, and incorrectly mirrored buttons.

In the 2026 open-source ecosystem, this should not be an unsolved engineering problem.

i18n is well understood, with mature solutions for Vue, React, and Next. CSS has used the [dir] attribute for almost twenty years; Unicode UAX #9 is a stable bidirectional-text specification; and mainstream browsers widely support logical properties. None of the essential technology is missing.

The issue is priority. Overseas projects usually put English first; Chinese projects usually put Mandarin first. Minority-language users rarely reach the front of the iteration queue.

Internationalization makes a product accessible across markets; localization goes deeper into local users’ language, habits, and culture. Chinese AI-agent desktop apps have English editions. What is missing is a first-class experience for local languages beyond Mandarin.

HexClaw v0.4.0 moved this work up the priority list.

This article covers three things: the words in the UI, direction in CSS, and the language the model actually speaks. Each layer has its own responsibility, and all three are necessary.

Core argument
i18n alone is not language support
A local AI-agent desktop app needs three completed layers for out-of-the-box Uyghur: frontend i18n for translated text, frontend RTL CSS for correct direction, and backend language directives so the model replies in Uyghur. A missing layer breaks the experience.
v0.4.0 implements all three.

30-second version
This release connects more than a language dropdown: 1400+ text keys switch to Uyghur; RTL layout keeps mixed-direction text in order; and the backend system prompt follows the language preference to encourage Uyghur responses.

Start with Uyghur as an engineering problem

Choosing Uyghur first in v0.4.0 was an engineering tradeoff: it exposes the most easily neglected RTL localization debt in one go.

• An Arabic-derived script: letterforms differ completely from Chinese and English, requiring suitable fonts and adjustments to the system fallback chain.
• RTL text direction: writing runs from right to left, requiring the overall layout to mirror.
• The bidi algorithm: mixed Uyghur, Chinese, English, numbers, and emoji are reordered by the browser under Unicode UAX #9; mishandling it produces disorder.
• Numbers and surrounding direction differ: the digits in “2026” remain LTR inside Uyghur text and need the right embedding in an RTL flow.
• Punctuation: the position and form of full stops, commas, and quotation marks differ from Chinese and English.

Tibetan is generally laid out LTR, while traditional Mongolian also involves a vertical writing system. Kazakh written in the Arabic script in Xinjiang faces RTL issues too. This is not a ranking of linguistic difficulty. The engineering choice is that Uyghur has a substantial domestic user base and exposes the core RTL adaptation problems. A thorough Uyghur RTL implementation creates a CSS foundation reusable for Arabic, Persian, Hebrew, Urdu, and other RTL languages.

Layer one: translate all 1400+ text keys

First, the numbers. As of the original article’s cutoff, 2026-05-01, these were the actual line counts of the two files under src/i18n/locales/:

Read both numbers together: 1457 is an approximate locale-key count based on object properties; 1568 is the total line count of ug-CN.ts, including nesting, comments, and blank lines. “1400+ text keys” and “1500+ lines in the ug-CN locale file” are both defensible engineering descriptions.

A qualification comes first: the v0.4.0 Uyghur translation is a usable auto-translated baseline, not a final edition fully reviewed by native speakers. The header of ug-CN.ts says the same: continued native-speaker review is invited through community issues and PRs. Equating completed engineering support with completed translation quality is a common way for release announcements to lose trust.

Why insist on one-to-one key parity?

This deserves its own explanation.

A common shortcut in i18n is silently falling back to the default language when a key is missing. Vue I18n and i18next do this by default, and it seems reasonable.

Inside an RTL interface, however, that fallback becomes one of the most obvious user-facing bugs. A Chinese sentence suddenly appears inside Uyghur, direction changes from RTL to LTR, the line shifts, and a button moves out of place.

The recurring feedback from native Uyghur users was less “inaccurate translation” than “it looks disordered.”

v0.4.0 therefore enforces a rule: CI checks i18n completeness, and a single missing key fails the build. Throughout development, every new PR must update both locales.

Translation pipeline: start with an auto-translated baseline

One person cannot realistically work through 1400+ keys with a dictionary. v0.4.0 uses these steps:

1. Cross-translation with multiple models: split zh-CN.ts into portions, ask Claude, DeepSeek, and Qwen for Uyghur translations, compare the three outputs, and mark disagreements. This produces the auto-translated baseline.
2. CI completeness checks: fail on keys missing relative to zh-CN; inspect the Arabic-script proportion to catch untranslated Chinese fallback text.
3. Desktop checks: manually switch the main user-path pages to Uyghur and retain screenshots.

Native-speaker review is open to the community. v0.4.0 did not wait for an exhaustive review before release. It shipped an auto-translated edition people could use, then invited continuing improvement through GitHub issues and PRs. One person maintaining six repositories cannot wait for perfect translations. Giving Uyghur users a working starting point and improving through feedback is preferable to keeping it in a drawer.

Glossary decisions

Not every word should be translated. A translated technical term can lose meaning and searchability, making the experience worse. v0.4.0 applies these choices:

The principle is simple: make the app usable in the user’s first language while keeping technical terms searchable.

Layer two: translating words is only the beginning; bidi is the hard part

If you have never adapted a product for RTL, this section may change what you expect from “just add dir=rtl.”

First, a common misconception: “Isn’t RTL just adding dir=rtl to HTML?”

No. dir="rtl" sets only the base text direction.

When a passage mixes Uyghur (strong RTL), Chinese (strong LTR), numbers (weak LTR), and emoji (neutral), the browser uses the Unicode Bidi Algorithm, UAX #9, to dynamically determine the visual direction of each segment.

In many contexts, its default behavior reorders semantic units into the wrong positions.

The classic counterexample

The original HexClaw startup banner reads:

Place it in a Uyghur container and the browser classifies the crab emoji and version as weak-direction material, reordering the passage into something like this:

The emoji moves to the end, and the version number moves with it.

CSS supplies unicode-bidi, with plaintext being the crucial value here. It lets the browser derive direction from the content’s first character rather than forcibly reversing it. It is comparable to HTML’s dir="auto", but can be applied at CSS-selector granularity.

From individual class patches to a global fallback

This evolution was the most useful engineering lesson of the work.

Stage one, the wrong direction: patch classes individually. Each discovered component-level bidi issue received a separate CSS rule:

That approach became unmanageable halfway through.

The problem was that every newly encountered page or component needed another rule. Logs, settings, and IM channels each had their own classes. Any omission left a broken area waiting for a user report.

Stage two, the better direction: a global fallback. One rule covers all content containers:

More than 50 separate CSS rules became one global fallback plus 5–6 special-case overrides. New pages and components no longer require separate RTL adaptation; the CSS foundation handles it.

Mature products and sites rely on this approach too.
The value of mature standards and browser implementations is that they encode this principle: fewer CSS rules can cover more cases.

Logical properties: modern CSS

The second change replaces physical properties with logical properties.

The principle is straightforward: replace padding-left, margin-right, and border-left with their inline-start and inline-end equivalents.

The browser decides whether start and end mean left or right based on the current writing direction, avoiding a duplicate RTL stylesheet.

Elements that must not mirror: a lesson from Uyghur users

A common RTL mistake is assuming every visual element should mirror with the language direction. That is incorrect.

• Layout spacing, borders, and reading progress should follow the language direction.
• Semantic icons, code blocks, URLs, version numbers, and timestamps should retain their original direction or explicitly use LTR.
• Back and forward navigation arrows depend on context; do not mirror them mechanically.

Initially, I applied transform: scaleX(-1) to semantic icons too. After Uyghur users objected, I reverted all of those changes. They explained that these icons normally retain their orientation in RTL usage; mirroring made them unfamiliar.

An engineer’s assumptions alone cannot resolve such details. A feedback loop with native speakers is essential.

How do we enforce “do not mirror” in CSS? Code, commands, and URLs, for example, are explicitly kept LTR:

Otherwise, the bidi algorithm can reorder variable names and comments in a code block inside the Uyghur interface. That is a disaster rather than localization.

Layer three: the UI is Uyghur, but the model still speaks Chinese

This is the layer most easily overlooked, yet especially substantial as engineering work.

Translated UI and completed RTL CSS solve only half the problem.

An LLM does not reply in Uyghur simply because the UI does. Models such as Qwen, DeepSeek, and GLM default toward the languages most likely under their training distributions, usually Chinese or English.

A user switches to Uyghur and asks “How is the weather today?” in Uyghur, only to receive Chinese. That break is worse than a half-translated interface.

The solution: append a language directive to the system prompt

The frontend reads hc-locale from localStorage, the user’s current language preference, and sends it to the backend in the chat metadata field user_locale:

When the backend service constructs the system prompt, it appends a language directive at the end. The implementation is hexclaw/engine/react.go, in localeOutputDirective(locale string) string. Here is the core code with comments removed:

Detail one: why the Uyghur directive is bilingual

Notice the Uyghur case: it contains both Uyghur and Chinese, rather than Uyghur alone.

There is a reason: models differ considerably in Uyghur comprehension and instruction following. Some understand Uyghur instructions; others rely more on the Chinese fallback.

With a Uyghur-only system directive, a model may not understand what it is being asked to do.

The bilingual form is an engineering fallback. Uyghur gives capable models a native-language instruction; Chinese supplies the task even if the model ignores the Uyghur text entirely.

Across several local checks, this was more reliable than a Uyghur-only directive. Uyghur questions more often received Uyghur responses, while an occasional Chinese or English question inside the Uyghur UI could still be answered in that question’s language, rather than enforcing a rigid lock.

Detail two: 🔒 prompt-injection defense

This is the section’s key engineering detail.

Notice the default branch above: an unknown locale returns an empty string and is never inserted into the system prompt. Why?

Because metadata.user_locale originates in the frontend’s hc-locale localStorage value. It is untrusted input. Any user can open browser DevTools and replace it with any string.

An attacker could do this:

If the backend directly interpolated that string with sprintf, a user-controlled locale would become a prompt-injection entrance.

v0.4.0 uses explicit switch cases for valid locales, returning an empty string for unknown values. Adding a language requires a deliberate new case, rather than open-ended variable interpolation.

Principle: never concatenate arbitrary frontend strings into a system prompt; select from explicitly enumerated values.

Test coverage

engine/locale_directive_test.go, 88 lines, covers:

• Basic cases: correct directives for zh-CN / en / ug-CN.
• Alias normalization: treat ug as ug-CN.
• Injected strings: inputs taking the default branch receive an empty directive.
• Placement: append the directive to the end without damaging the original prompt.

At a higher level, the ChatPromptInjection suite contains 11 cases for injection surfaces across the conversation path. Locale is only one attack vector.

An unexpected effect: Chinese transliteration can trigger Uyghur replies

This surprise appeared during testing.

The intended path was simple: Uyghur UI + Uyghur-script input → Uyghur reply. Before the v0.4.0 release, checks revealed something unexpected: input written as Chinese transliteration could also receive a Uyghur reply.

For example, typing “阿达西，一西米然” in the Uyghur UI—a Chinese-character phonetic rendering of a colloquial Uyghur “Hello, friend”—produced a Uyghur answer without switching back to Chinese.

Trying “河蟹AI非常亚克西”—roughly “HexClaw AI is very yaxshi,” where 亚克西 transliterates the Uyghur word for “good”—also produced a Uyghur response, including emoji and a list.

This is an effect of the three layers working together:

1. The system prompt already says the user’s current language is Uyghur.
2. The model can associate common Uyghur expressions with a Uyghur conversation. Chinese transliterations such as 亚克西, 阿达西, and 撒拉姆 also occur on the Chinese internet.
3. With both signals present, the model responds in Uyghur.

The practical result is interesting: even without switching to a Uyghur input method, a user who knows a few Chinese-character transliterations can have a short Uyghur conversation with the AI. For someone trying Uyghur AI without an installed Uyghur keyboard, it is an unexpectedly welcoming behavior.

This effect is evidence that the backend locale-directive layer is doing work. With UI translation alone and no backend directive, Chinese-transliterated input would probably receive Chinese. Such an edge case is a useful check of whether all three layers are connected.

A complete Uyghur conversation across all three layers

Putting those layers together gives this conversation flow:

1. The user switches the UI to Uyghur. Frontend i18n selects ug-CN, switching 1457 locale keys, and changes the <html dir="rtl"> attribute.
2. The CSS adaptation takes effect. [dir='rtl'] selectors match, logical properties mirror automatically, and the global unicode-bidi: plaintext fallback derives mixed-text direction from the content’s first character.
3. The user sends a Uyghur message. The frontend adds user_locale: "ug-CN" to chat metadata sent to the backend.
4. The backend builds the LLM request. localeOutputDirective("ug-CN") returns the bilingual directive appended to the system prompt. Only explicitly valid locales receive directives; unknown locales are ignored.
5. The LLM answers in Uyghur. Its response streams to the frontend, where the RTL CSS applies again during rendering.

Frontend i18n + frontend RTL CSS + backend prompt directives: none can be omitted.
A missing layer breaks the experience at that point. i18n may sound simple, but finishing the first layer still leaves the second and third before Uyghur support is truly complete.

An honest account: what this release has not got right

Engineering notes should describe more than the smooth parts.

Here are v0.4.0’s actual Uyghur validation coverage and known limitations.

Checks reported as passed in the original release

• i18n + RTL contract checks: switching to ug-CN sets root lang="ug" and dir="rtl", and resolves common Uyghur keys.
• Global RTL bidi fallback regression: checks the [dir='rtl'] :is(...) rule so unnamed classes on pages such as logs do not escape coverage.
• Locale-directive checks: cover zh-CN / en / ug-CN and keep malicious locale values out of the system prompt.
• Prompt-injection defense: 11 ChatPromptInjection cases cover injection surfaces across the conversation path.
• Broader package checks: desktop unit tests and backend race checks plus all-package tests passed.

Known remaining issue

Remaining issue: Uyghur letters may appear cramped or joined incorrectly under some macOS font settings.

A few Mac users reported slight crowding between Uyghur characters. Investigation traced this to the macOS fallback chain selecting a font poorly suited to Arabic-script rendering. The original investigation identified this as a system-level font issue without an application-layer root fix. The documented workaround is to install a suitable font such as Tahoma, Noto Naskh Arabic, or Microsoft YaHei, after which rendering returned to normal.

A user who reads “full Uyghur support” and then finds cramped text on their machine can still feel misled. Explaining font-fallback limitations in advance is the more honest approach.

v0.4.0 goes beyond Uyghur

Uyghur localization is one part of this release. v0.4.0 develops both the desktop experience and underlying agent capabilities:

• 🌍 Uyghur support: 1457 i18n keys, a global RTL bidi fallback, and backend locale directives connect three layers, giving Uyghur users a native-language starting point.
• 🧠 Skill self-learning feedback: retain execution traces, create improvement drafts for poor outcomes, and distill stable combinations into meta-Skills, laying the foundation for improvement through use.
• 🤖 Sub-agent delegation: seven strategy modes cover planning, self-checks, multiple approaches, memory enhancement, debate, and related tasks, while reusing ReActEngine and preserving existing tools and streaming.
• 💬 A unified conversation composer: text, images, and video enter through one input, with routing based on model capability, without switching between separate composers.
• 🧩 Structured interactions: buttons / select / approval / card / block let an agent offer clickable and confirmable operations as well as text.
• ⚙️ Runtime governance: feature flags, events, model gateway, skill pipeline, and tool lifecycle share a control system for gradual enablement and quick rollback.

This article develops only Uyghur localization; the other items are listed as release highlights.

Why devote this much space to Uyghur? Because it has long been overlooked in local AI-agent desktop apps. The less often worthwhile engineering work is done, the more useful it is to document the method and mistakes for the next person.

Local AI-agent desktop apps have existed for several years.
It is time for a version Uyghur speakers can open and comfortably use in their first language.

Further reading · Earlier HexClaw articles:

1. HexClaw vs OpenClaw / Hermes — Three paths for local AI agents in 2026
2. Claude Code SOP — Design-driven development, testing feedback loops, and multi-agent collaboration
3. Architecture Deep Dive — One person × Claude Code × five months × six repositories
4. From Lobster to Crab — Product launch and the OpenClaw comparison
5. The Thinking Process — The last mile for Qwen / Gemma / DeepSeek-R1
6. Complete Guide — From zero to a working local AI agent in five minutes
7. Former-Leader Skill — Distill a leader into an AI Skill

References

• HexClaw ecosystem repositories: github.com/hexagon-codes
• Unicode Bidirectional Algorithm: unicode.org/reports/tr9
• MDN · unicode-bidi: developer.mozilla.org/en-US/docs/Web/CSS/unicode-bidi
• MDN · CSS logical properties and values: developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values
• OWASP LLM01 · Prompt Injection: genai.owasp.org/llmrisk/llm01-prompt-injection

Technical sources were checked on 2026-05-01 against official documentation and upstream repositories.

HexClaw
Deploy locally or in the cloud · Control your data · Free and open-source software
Website: hexclaw.net  |  GitHub: hexagon-codes
Weibo: @HexClaw  |  X: @hexclawapp
Email: [email protected]