feat(desktop): add 15-language i18n with hybrid JSON+TS architecture by iaendi · Pull Request #69819 · NousResearch/hermes-agent

iaendi · 2026-07-23T03:56:20Z

Summary

Clean i18n-only PR split from #38846 per alt-glitch's re-triage request.

35 files changed, Desktop-i18n-only scope.

Architecture

JSON catalogs (src/locales/*.json) — canonical translation source, translator-friendly
sync-locales.py — bridge script: validates keys, generates TypeScript defineLocale() calls
Generated TS files (src/i18n/*.ts) — full type annotations, defineLocale() with English fallback
i18n store — i18n.tsx, use-locale-sync.ts for runtime locale switching

Languages (15)

en, zh-CN, zh-Hant, ja, ko, de, es, fr, pt-BR, ar, hi, th, vi, it, ru

Key design decisions

JSON files are the source of truth; sync-locales.py generates TS (no manual TS edits needed)
Partial translations gracefully fall back to English via defineLocale()
No changes to upstream i18n infrastructure (define-locale.ts, types.ts, context.tsx remain as-is)
~~522 files (old PR) → 35 files (this PR), Desktop-i18n-only

Verification

TypeScript: 0 i18n type errors
Locale key parity: all 15 locales validated against en.json (active keys)
No core agent/gateway/CLI/platform/CI changes

Closes #38846

Clean split from NousResearch#38846 — Desktop-i18n-only files: - 15 locale JSON catalogs (ar, de, en, es, fr, hi, it, ja, ko, pt-BR, ru, th, vi, zh-CN, zh-Hant) - sync-locales.py bridge: JSON source → TypeScript defineLocale() - Generated TS locale files with full type annotations - i18n store (i18n.tsx, use-locale-sync.ts) - Locale key parity test Architecture: - JSON files in src/locales/ are the canonical translation source - sync-locales.py validates keys against en.json and generates src/i18n/*.ts - defineLocale() merges partial translations with English fallback - 249 en.json active keys, 122 keys per locale (remaining fall back to en) Supersedes: NousResearch#38846 (522 files → 35 files, i18n-only)

alt-glitch · 2026-07-23T04:46:26Z

This was generated by AI during triage.

Related: #38846 was the closed oversized predecessor; #38183 remains an open Desktop i18n architecture. This clean 15-language split is an alternative implementation and needs maintainer direction, not duplicate closure.

timoncool · 2026-07-23T23:33:14Z

@iaendi — heads-up on a Russian overlap, so we don't land a regression by accident.

This PR's apps/desktop/src/i18n/ru.ts covers 122 of 2303 catalog keys (~5%); everything else falls back to English. #66833 is a complete Russian Desktop locale — 2303/2303 at its reviewed base — with a native technical editorial pass and correct 11–14 plural handling contributed by @DrMaks22, 37 behaviour tests, and typecheck + eslint green.

Both PRs add the same file, so whichever lands second will conflict on it — and if this one lands first, the shipped Russian drops from complete to ~5%.

Suggestion that keeps this PR's breadth and the RU depth:

drop ru from this PR (or source its contents from feat(i18n): add Russian (ru) desktop locale #66833), and let the complete Russian land via feat(i18n): add Russian (ru) desktop locale #66833.

Happy to do the mechanical part either way — I can open a patch against this branch that swaps in the complete ru.ts, whichever you prefer. cc @DrMaks22

DrMaks22 · 2026-07-26T21:46:49Z

Russian consolidation update: the complete, current-main RU Desktop candidate is now #72250.

It is the rebased continuation of #66833 with original contributor authorship preserved, exact 2526/2526 current catalog coverage, native technical editorial review, correct Russian plural handling, behavior tests, full Desktop typecheck/lint/build, and the complete UI/Electron suites green.

To avoid a Russian coverage regression, the cleanest path remains either:

drop ru from this multi-language foundation PR and let feat(i18n): add complete Russian desktop locale #72250 provide the Russian locale; or
source the Russian catalog from feat(i18n): add complete Russian desktop locale #72250 rather than the partial 122-key file in this branch.

That keeps this PR's multi-language architecture work independent while preserving the reviewed Russian depth.

teknium1

Thanks for narrowing the earlier i18n work to a Desktop-only change. The additional locales are still absent from current main, but this branch needs substantial adaptation before it can be evaluated as a merge candidate.

Problems

apps/desktop/src/locales/locales.test.ts:61 requires complete key parity, but the PR’s own en.json has 250 keys while de.json has 126. That contradicts the documented partial-catalog fallback model and makes the test fail.
apps/desktop/scripts/sync-locales.py:226-228 records every missing key as an error, then exits nonzero at :310; partial catalogs therefore cannot sync successfully despite the fallback message at :227.
apps/desktop/src/store/i18n.tsx:23-92 creates localStorage-backed locale state alongside current main’s config-backed I18nProvider in apps/desktop/src/i18n/context.tsx:95-191. The current provider persists display.language, updates runtime translations, applies RTL, and rolls back failed saves.
The Russian overlap remains unresolved: this PR adds src/i18n/ru.ts, while the discussion identifies #72250 as the complete current-main Russian candidate.

Suggested changes

Port locale registration and catalogs onto the existing apps/desktop/src/i18n/ provider; do not introduce the parallel store.
Make partial-catalog fallback non-fatal and test that behavior, or provide full catalogs.
Drop ru or consolidate it with #72250 before salvage.

Automated hermes-sweeper review.

teknium1 · 2026-07-30T07:27:26Z

+      const missingKeys = englishKeys.filter(k => !localeKeys.includes(k))
+
+      // Only fail on missing keys, not extra self-reference keys
+      expect(missingKeys, `${locale}: missing keys`).toEqual([])


This asserts full catalog parity, but the PR's en.json has 250 keys and de.json has 126. It will fail for the intentionally partial catalogs and conflicts with the stated English-fallback model. Please test fallback behavior instead, or require complete translations.

teknium1 · 2026-07-30T07:27:26Z

+
+        if missing:
+            print(f'  ⚠️  {locale["json"]}: {len(missing)} keys missing (will fallback to en)')
+            issues += len(missing)


Counting missing keys as errors makes every partial locale fail at the sys.exit(1) on line 310, despite the fallback claim immediately above. Missing override keys must be non-fatal if partial defineLocale() catalogs are supported.

teknium1 · 2026-07-30T07:27:27Z

+  'ru': 'Русский',
+  'pt-BR': 'Português (Brasil)',
+}
+


Current main already owns locale persistence in src/i18n/context.tsx through display.language, including runtime synchronization, RTL handling, and rollback on failed saves. Do not add a separate localStorage locale authority; port the new locales through that provider.

… parallel store P1: sync-locales.py — missing keys are now informational (fallback to en), exit 0 on partial catalogs instead of exit 1 P2: locales.test.ts — accept partial catalogs as valid; extra-key check remains but missing keys are expected P3: Remove store/i18n.tsx, store/use-locale-sync.ts, store/i18n.test.ts — dead code not imported by any consumer; all store files correctly use @/i18n (upstream I18nProvider) P4: Drop Russian locale (ru.json, ru.ts, KNOWN_LOCALES entry) — NousResearch#72250 is the complete Russian candidate; removing to avoid 5% coverage regression on merge

iaendi

Thanks for the thorough review @teknium1. All four issues have been addressed in 0deeefe:

P1 — sync-locales.py partial-catalog fallback: Missing keys are now informational only (ℹ️ instead of ⚠️), and the script exits 0 on partial catalogs. The existing fallback-to-English message path is preserved — defining fewer keys than en.json is expected and no longer treated as a validation error.

P2 — locales.test.ts partial-catalog test: The test now validates that non-English catalogs are subsets of the English catalog (no keys that en.json does not define), rather than requiring full key parity. Missing keys are expected and fall back to English at runtime.

P3 — Parallel i18n store removed: store/i18n.tsx, store/use-locale-sync.ts, and store/i18n.test.ts have been deleted. They were dead code — no consumer imported from them. All store files that need i18n correctly import from @/i18n (the upstream I18nProvider in apps/desktop/src/i18n/context.tsx).

P4 — Russian locale dropped: ru.json, ru.ts, and all Russian entries in sync-locales.py have been removed. The complete Russian candidate lives in #72250 and should land independently to avoid the ~5% coverage regression.

The branch now has 14 locales and is ready for re-evaluation.

iaendi · 2026-08-03T05:46:16Z

@timoncool thanks for catching this. I have dropped ru from this PR — ru.json, ru.ts, and all Russian config entries have been removed. The complete Russian locale should land via #72250 (the rebased continuation of #66833 with full 2526/2526 catalog coverage).

This PR now carries 14 languages; Russian is intentionally left to the dedicated candidate.

iaendi · 2026-08-03T05:46:21Z

@DrMaks22 agreed — the cleanest path is to drop ru from this multi-language foundation PR and let #72250 provide the complete Russian locale. Done in 0deeefe: Russian has been removed from this PR. Good luck with #72250.

iaendi mentioned this pull request Jul 23, 2026

feat(desktop): add 15-language i18n — hybrid JSON+TypeScript system #38846

Closed

teknium1 reviewed Jul 30, 2026

View reviewed changes

teknium1 added sweeper:risk-compatibility Sweeper risk: may break existing users, config, migrations, defaults, or upgrades sweeper:blast-moderate Sweeper blast radius: moderate — a subsystem or single platform labels Jul 30, 2026

iaendi commented Aug 3, 2026

View reviewed changes

auto: sync with upstream main [skip ci]

10b7c3a

iaendi requested a review from a team August 3, 2026 05:52

alt-glitch added the blocked Waiting on external dependency or decision label Aug 3, 2026

andrexibiza mentioned this pull request Aug 6, 2026

[COMPLETE] Large-file decomposition: 20/20 done #78647

Closed

Navigation Menu

Uh oh!

feat(desktop): add 15-language i18n with hybrid JSON+TS architecture - #69819

feat(desktop): add 15-language i18n with hybrid JSON+TS architecture#69819
iaendi wants to merge 3 commits into
NousResearch:mainfrom
iaendi:feat/i18n-desktop-clean

iaendi commented Jul 23, 2026

Uh oh!

alt-glitch commented Jul 23, 2026

Uh oh!

timoncool commented Jul 23, 2026

Uh oh!

DrMaks22 commented Jul 26, 2026

Uh oh!

teknium1 left a comment

Uh oh!

teknium1 Jul 30, 2026

Uh oh!

teknium1 Jul 30, 2026

Uh oh!

teknium1 Jul 30, 2026

Uh oh!

iaendi left a comment

Uh oh!

iaendi commented Aug 3, 2026

Uh oh!

iaendi commented Aug 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

iaendi commented Jul 23, 2026

Summary

Architecture

Languages (15)

Key design decisions

Verification

Uh oh!

alt-glitch commented Jul 23, 2026

Uh oh!

timoncool commented Jul 23, 2026

Uh oh!

DrMaks22 commented Jul 26, 2026

Uh oh!

teknium1 left a comment

Choose a reason for hiding this comment

Problems

Suggested changes

Uh oh!

teknium1 Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

teknium1 Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

teknium1 Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

iaendi left a comment

Choose a reason for hiding this comment

Uh oh!

iaendi commented Aug 3, 2026

Uh oh!

iaendi commented Aug 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants