add i18n support by benedikt-bartscher · Pull Request #6796 · reflex-dev/reflex

benedikt-bartscher · 2026-07-17T22:26:12Z

codspeed · 2026-07-17T22:29:36Z

Merging this PR will degrade performance by 6.71%

⚠️

10 benchmarks spent significant time in system calls

System calls cannot be consistently instrumented, so they are not included in the measure, which understates the real cost. Please switch to the Walltime instrument to accurately measure system calls.

Measurement and system calls

test_cli_startup[help]

test_cli_startup[version]

test_cli_startup[run_help]

test_modify_state[disk]

test_cli_startup[deploy_help]

test_python_process_startup

test_set_state[disk]

test_import_cli

test_cli_startup[cloud_help]

test_emit_update

⚠️

Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

❌ 1 regressed benchmark
✅ 147 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	`BASE`	`HEAD`	Efficiency
❌ ⚠️	`test_cli_startup[help]`	803.4 ms	861.3 ms	-6.71%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

_{Comparing benedikt-bartscher:add-i18n (cc80aea) with main (d3f4ab1)}

greptile-apps · 2026-07-17T22:42:22Z

Confidence Score: 4/5

[Medium impact] The PR adds locale-aware behavior to app rendering and extends Reflex plugin and CLI workflows.

The PR still needs the cookie-mode language switcher to update the server before merging.

Findings

Switcher leaves server text unchanged ▶

Summary

Adds optional internationalization through reflex-i18n:

Apps can translate text and format values using a visitor’s locale.
Apps can serve translated pages under locale-based URL paths.
Plugins can set event context and add routes or computed-value dependencies.
The Reflex CLI adds commands for translation catalogs and installed packages.
Hot reload removes dependency links to states that are being reloaded.

No new findings were accepted.

_{Reviews (38) · Last reviewed commit: "Fix first-load locale, regional catalog ..." · Reviewed by Greptile}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6b9a5f5342

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-07-18T11:17:05Z

+  "reflex-base >= 0.9.7.dev0",
+  "reflex >= 0.9.7.dev0",


Remove development pins before publishing reflex-i18n

With the new dispatch-release option, selecting reflex-i18n will create a release and trigger .github/workflows/publish.yml, whose publish job runs scripts/check_min_deps.py --check-dev-pins "$PACKAGE" and explicitly rejects published dependencies containing *.dev pins. Because these two requirements are part of reflex-i18n's published metadata, the publish workflow for any reflex-i18n release will fail at that gate until they are pinned to released versions.

Useful? React with 👍 / 👎.

I'll leave this open for the maintainers

Still for the maintainers, but with the current picture after merging main (c00c5ff): reflex itself carries the same kind of pin (reflex-base >= 0.9.12.dev0), so a dev pin in-tree is the normal state and the publish gate is what forces the bump. reflex-i18n's constraint is genuinely unreleased — it needs register_event_scope_provider, register_implicit_dependency and ExpandRoutesContext, all added by this PR — so no published floor would be truthful, and I'd rather not invent one. It uses none of the API #7268 raised floors for. check_min_deps.py reflex-i18n passes; --check-dev-pins reports the pin as expected.

benedikt-bartscher · 2026-07-29T19:20:18Z

@masenf could you please take a brief look at this from an architectural design and DX perspective? it's totally okay if you have smth completly different in mind

masenf

@benedikt-bartscher thanks for adding this and sorry for the review back-up. i did an initial look and i think the added extension points make sense and the API feels nice.

one potential issue i see affects SEO performance of the SSG static versions of the site -- since the translation depends on state, other languages might not be indexable by crawlers.

cubic-dev-ai

All reported issues were addressed across 55 files

_{Requires human review: Auto-approval blocked because this review re-detected 2 unresolved issues already reported by Cubic.

Re-trigger cubic}

…r/plural conflict check, module-qualified and nested dep tracking, config validation

cubic-dev-ai

All reported issues were addressed across 18 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

…fy registry lifetime

…es the built-ins

masenf

consider b5af4f2

more harmonious interfacing with the var system makes the code easier to maintain

Resolve conflicts in tests/units/istate/test_proxy.py, tests/units/test_state.py and uv.lock. Mark I18nState.is_user_defined with _override_base_method for main's reserved state name validation, and regenerate pyi_hashes.json.

… package Adding reflex-i18n pushes the package count past the workflow_dispatch input limit, so reflex-release sync renders the free-text package field instead of per-package checkboxes.

cubic-dev-ai

6 issues found across 56 files

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/reflex-i18n/src/reflex_i18n/catalog.py">

<violation number="1" location="packages/reflex-i18n/src/reflex_i18n/catalog.py:39">
P2: When a `.po` file lacks a plural or language header, `read_po_catalog` gives Babel no locale, so generated modules use the generic English plural rule. Pass the locale derived from the catalog filename to `read_po`, matching the CLI loader.</violation>
</file>

<file name="packages/reflex-i18n/src/reflex_i18n/nav.py">

<violation number="1" location="packages/reflex-i18n/src/reflex_i18n/nav.py:57">
P2: When `I18nPlugin` uses its default cookie-based mode, this still renders links such as `/de/current-page` even though URL-prefixed routes are not generated, so every switcher link can 404. Require URL routing before creating this component, or make the switcher use the cookie-based `setLocale` behavior when routing is disabled.</violation>
</file>

<file name="packages/reflex-i18n/src/reflex_i18n/runtime.py">

<violation number="1" location="packages/reflex-i18n/src/reflex_i18n/runtime.py:190">
P2: Configured locales containing underscores never negotiate from normal BCP 47 `Accept-Language` tags. Normalize supported locales from `_` to `-` when building both lookup maps, as is already done for the request tag.</violation>
</file>

<file name="packages/reflex-i18n/src/reflex_i18n/_web/i18n.js">

<violation number="1" location="packages/reflex-i18n/src/reflex_i18n/_web/i18n.js:122">
P2: Localized prerendered pages have no route-specific `<html lang>` or `dir` until hydration, reducing accessibility and SEO correctness for crawlers and users. Emit these attributes from the server-rendered document or another SSR-aware route metadata mechanism.</violation>

<violation number="2" location="packages/reflex-i18n/src/reflex_i18n/_web/i18n.js:163">
P2: When an underscore-separated RTL locale is configured, this check marks the document as left-to-right. Split on both supported locale separators, and apply the same normalization in `LocaleRoute`.</violation>

<violation number="3" location="packages/reflex-i18n/src/reflex_i18n/_web/i18n.js:220">
P1: When a configured locale uses an underscore, `getFormatter` passes the tag directly to `Intl`, which throws before formatting any value. Normalize underscores to hyphens before constructing the formatter.</violation>
</file>

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

cubic-dev-ai · 2026-09-21T23:17:17Z

+  const key = locale + " " + JSON.stringify(options ?? {});
+  let formatter = cache.get(key);
+  if (formatter === undefined) {
+    formatter = new Ctor(locale, options);


P1: When a configured locale uses an underscore, getFormatter passes the tag directly to Intl, which throws before formatting any value. Normalize underscores to hyphens before constructing the formatter.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/reflex-i18n/src/reflex_i18n/_web/i18n.js, line 220: <comment>When a configured locale uses an underscore, `getFormatter` passes the tag directly to `Intl`, which throws before formatting any value. Normalize underscores to hyphens before constructing the formatter.</comment> <file context> @@ -0,0 +1,410 @@ + const key = locale + " " + JSON.stringify(options ?? {}); + let formatter = cache.get(key); + if (formatter === undefined) { + formatter = new Ctor(locale, options); + if (cache.size >= FORMATTER_CACHE_LIMIT) { + cache.delete(cache.keys().next().value); </file context>

Suggested change

formatter = new Ctor(locale, options);

formatter = new Ctor(locale.replace(/_/g, "-"), options);

Fixed at the root in 9ec44ec: I18nConfig now rejects underscore locales outright instead of normalizing them at each use site. Locales double as URL segments, Intl tags and Accept-Language matches, all hyphen-separated, so the underscore spelling has no consistent meaning here.

…outesContext

…view findings

cubic-dev-ai

All reported issues were addressed across 26 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

… in the docs example

FarhanAliRaza

I exercised the translation example in Chrome with cookie and URL routing, compared client and server translations, and ran a production export and the focused tests. I also reran catalog initialization and loading with language-only and regional locale tags.

See the inline comments.

FarhanAliRaza · 2026-09-25T15:11:17Z

+            ? undefined
+            : (event) => {
+                event.preventDefault();
+                setLocale(locale);


[P2] Synchronize the backend locale from the cookie-mode switcher

With default cookie routing, this calls only the provider’s client setter; it never dispatches I18nState.set_locale. In the live en/de example, clicking de changes rx.t("Hello") to Hallo, but a computed var returning gettext("Welcome") stays Welcome, even after another backend event. The same var becomes Willkommen when using rx.i18n.set_locale("de"). Please make the cookie-mode switcher update both the client and server locale so dynamic translations follow the selected language.

FarhanAliRaza · 2026-09-25T15:11:17Z

+            return read_po(f, locale=locale)
+    return Catalog(locale=locale)


[P2] Convert accepted locale tags before passing them to Babel

I18nConfig accepts hyphenated tags such as pt-BR and zh-Hant, but both calls pass them verbatim to Babel, which expects underscore-separated locale identifiers. uv run reflex i18n init pt-BR fails here with ValueError: expected only letters, got 'pt-br'; reading an existing catalog fails the same way, while de succeeds. Normalize the locale for both Babel calls (as the runtime catalog loader already does), while retaining the configured tag in filenames and URLs.

# Conflicts: # .github/workflows/dispatch_release.yml # packages/reflex-base/src/reflex_base/vars/dep_tracking.py # tests/units/test_state.py

Upstream now deletes the dispatch-time state tree locals before a background handler runs (reflex-dev#7447), while this branch enters the event scope around that handler with the same root state. The background scope is now created before the locals are deleted, and _EventScope drops its root state reference once entered, so a registered provider (e.g. the i18n locale) no longer pins the tree; test_scope.py covers the release. reflex-i18n takes upstream's workspace-wide Python 3.11 floor and the 3.11-3.15 classifiers. uv.lock is upstream's, relocked with uv 0.12.5 (the CI version) to add reflex-i18n and babel; pyi_hashes.json is regenerated.

greptile-apps · 2026-10-20T21:15:19Z

+            : (event) => {
+                event.preventDefault();
+                setLocale(locale);


Switcher leaves server text unchanged

In cookie mode, LanguageSwitcher only writes the browser cookie and changes React state. It never sends I18nState.set_locale, so server translations keep using the old locale_cookie, even on later ordinary events. Browser cookies are read back during navigation or connection setup, not on each event.

Send the server locale change too, as the Python set_locale helper does.

Knowledge Base Used: State management and event processing

Build the hydrate snapshot in a locale scope entered after browser storage is applied, convert hyphenated tags for Babel in the catalog CLI, and raise the reflex and reflex-base floors to the dev release that has the APIs reflex-i18n imports.

greptile-apps Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread packages/reflex-base/src/reflex_base/event/processor/scope.py Outdated

Comment thread packages/reflex-i18n/src/reflex_i18n/runtime.py

Comment thread packages/reflex-i18n/src/reflex_i18n/_web/i18n.js

greptile-apps Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread packages/reflex-i18n/src/reflex_i18n/_web/i18n.js Outdated

greptile-apps Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread reflex/__init__.py

benedikt-bartscher marked this pull request as ready for review July 18, 2026 11:09

benedikt-bartscher requested review from a team and Alek99 as code owners July 18, 2026 11:09

benedikt-bartscher changed the title ~~first i18n wip~~ add basic i18n support Jul 18, 2026

chatgpt-codex-connector Bot reviewed Jul 18, 2026

View reviewed changes

greptile-apps Bot reviewed Jul 18, 2026

View reviewed changes

Comment thread reflex/reflex.py Outdated

benedikt-bartscher changed the title ~~add basic i18n support~~ add i18n support Jul 18, 2026

masenf reviewed Jul 30, 2026

View reviewed changes

benedikt-bartscher force-pushed the add-i18n branch from e68fb65 to 3e540c0 Compare July 30, 2026 23:20

benedikt-bartscher added 15 commits July 31, 2026 01:24

first i18n wip

1314ba5

ruffing

375a544

format js

8925b6d

dry and fix ci

b11f2ac

fix aenter

55aa426

some state import fixes and docstr cleanup

8f65f43

fixes

d2b37ea

some typing fixes

5d51480

minor docstring stuff

26012b6

add changelog and some DRYness

3ba79df

sde effect struggle

72cce65

add explicit console error

2e969e5

add support for numbers, dates, currencies etc

e40bd73

add memo test

6e1f271

greptile

3a77ed9

fix versions

7e0a384

benedikt-bartscher marked this pull request as ready for review September 4, 2026 12:26

cubic-dev-ai Bot reviewed Sep 4, 2026

View reviewed changes

address cubic review: basename-aware i18n URLs, Map catalogs, singula…

3376a91

…r/plural conflict check, module-qualified and nested dep tracking, config validation

cubic-dev-ai Bot reviewed Sep 4, 2026

View reviewed changes

Comment thread packages/reflex-i18n/src/reflex_i18n/config.py Outdated

Comment thread packages/reflex-i18n/src/reflex_i18n/registry.py

Comment thread packages/reflex-i18n/src/reflex_i18n/registry.py

benedikt-bartscher and others added 7 commits September 4, 2026 16:22

i18n: fullmatch locale validation, treat empty context as none, clari…

5613788

…fy registry lifetime

Merge branch 'main' into add-i18n

cfe98b2

Merge remote-tracking branch 'upstream/main' into add-i18n

73858ed

Merge branch 'main' into add-i18n

b74611d

Merge remote-tracking branch 'upstream/main' into add-i18n

9a75a4c

perf: defer the reflex.cli entry point scan until a command name miss…

3639600

…es the built-ins

Merge branch 'main' into add-i18n

748cdd3

masenf reviewed Sep 17, 2026

View reviewed changes

benedikt-bartscher added 2 commits September 22, 2026 00:50

Merge branch 'main' into add-i18n

696c6ee

Resolve conflicts in tests/units/istate/test_proxy.py, tests/units/test_state.py and uv.lock. Mark I18nState.is_user_defined with _override_base_method for main's reserved state name validation, and regenerate pyi_hashes.json.

chore: regenerate dispatch_release workflow for the added reflex-i18n…

3b84af4

… package Adding reflex-i18n pushes the package count past the workflow_dispatch input limit, so reflex-release sync renders the free-text package field instead of per-package checkboxes.

cubic-dev-ai Bot reviewed Sep 21, 2026

View reviewed changes

benedikt-bartscher added 2 commits September 23, 2026 19:26

reflex-base: forward exc_info from the event scope and export ExpandR…

3d5f676

…outesContext

i18n: give the client hooks real FunctionVars and address the open re…

9ec44ec

…view findings

greptile-apps Bot reviewed Sep 23, 2026

View reviewed changes

Comment thread packages/reflex-i18n/src/reflex_i18n/_web/i18n.js Outdated

cubic-dev-ai Bot reviewed Sep 23, 2026

View reviewed changes

Comment thread docs/i18n/overview.md Outdated

benedikt-bartscher and others added 3 commits September 23, 2026 19:46

i18n: keep query and fragment in switcher links, and use timezone.utc…

8c96e15

… in the docs example

Merge upstream main (84bb6ab) into add-i18n

c00c5ff

Merge branch 'main' into add-i18n

89f2ce7

FarhanAliRaza requested changes Sep 25, 2026

View reviewed changes

Merge remote-tracking branch 'upstream/main' into add-i18n

2ad8c81

# Conflicts: # .github/workflows/dispatch_release.yml # packages/reflex-base/src/reflex_base/vars/dep_tracking.py # tests/units/test_state.py

masenf added the documentation Improvements or additions to documentation label Oct 6, 2026

benedikt-bartscher marked this pull request as draft October 8, 2026 20:15

greptile-apps Bot reviewed Oct 20, 2026

View reviewed changes

	formatter = new Ctor(locale, options);
	formatter = new Ctor(locale.replace(/_/g, "-"), options);

		return read_po(f, locale=locale)
		return Catalog(locale=locale)

Conversation

benedikt-bartscher commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will degrade performance by 6.71%

Performance Changes

Uh oh!

greptile-apps Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 4/5

Findings

Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

benedikt-bartscher Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

benedikt-bartscher Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

benedikt-bartscher commented Jul 29, 2026

Uh oh!

masenf left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

masenf left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai Bot Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

benedikt-bartscher Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benedikt-bartscher commented Jul 17, 2026 •

edited

Loading

codspeed Bot commented Jul 17, 2026 •

edited

Loading

greptile-apps Bot commented Jul 17, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading