diff --git a/.github/workflows/dispatch_release.yml b/.github/workflows/dispatch_release.yml index e11adc81957..30b7caf79ea 100644 --- a/.github/workflows/dispatch_release.yml +++ b/.github/workflows/dispatch_release.yml @@ -147,6 +147,10 @@ on: description: "reflex-hosting-cli" type: boolean default: false + reflex_i18n: + description: "reflex-i18n" + type: boolean + default: false reflex_otel: description: "reflex-otel" type: boolean @@ -209,6 +213,7 @@ jobs: ${{ inputs.reflex_components_sonner && 'reflex-components-sonner' || '' }} ${{ inputs.reflex_docgen && 'reflex-docgen' || '' }} ${{ inputs.reflex_hosting_cli && 'reflex-hosting-cli' || '' }} + ${{ inputs.reflex_i18n && 'reflex-i18n' || '' }} ${{ inputs.reflex_otel && 'reflex-otel' || '' }} ${{ inputs.reflex_release && 'reflex-release' || '' }} ${{ inputs.reflex_workflow && 'reflex-workflow' || '' }} diff --git a/docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/learn.py b/docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/learn.py index c887d20d65c..ba1d012c1bf 100644 --- a/docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/learn.py +++ b/docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/learn.py @@ -127,6 +127,7 @@ def get_sidebar_items_backend(): database, enterprise, events, + i18n, state, state_structure, utility_methods, @@ -183,6 +184,12 @@ def get_sidebar_items_backend(): client_storage.overview, ], ), + create_item( + "Internationalization", + children=[ + i18n.overview, + ], + ), create_item( "Database", children=[ diff --git a/docs/i18n/overview.md b/docs/i18n/overview.md new file mode 100644 index 00000000000..7b5f944852e --- /dev/null +++ b/docs/i18n/overview.md @@ -0,0 +1,499 @@ +```python exec +import reflex as rx +``` + +# Internationalization (i18n) + +Reflex supports translating your app into multiple languages through the +[`reflex-i18n`](https://pypi.org/project/reflex-i18n/) package. It covers the +two kinds of text in an app: + +- **Static content** — literal strings in your components (labels, buttons, + headings), translated on the client with `rx.t(...)`. +- **Dynamic content** — strings produced by your state (messages, formatted + values), translated on the server with `gettext`. + +Only the visitor's active language is ever sent to the browser, so adding more +locales does not bloat what each user downloads. + +## Installation + +```bash +pip install reflex-i18n +``` + +Then enable it by adding the `I18nPlugin` to your `rxconfig.py`, listing the +locales you support: + +```python +import reflex as rx +from reflex_i18n import I18nPlugin + +config = rx.Config( + app_name="myapp", + plugins=[ + I18nPlugin(locales=["en", "de", "fr"], default_locale="en"), + ], +) +``` + +`default_locale` is the language your source strings are written in. Translations +live in `.po` files under `locales/` (configurable with `catalog_dir=`). + +## Static content with `rx.t` + +Wrap literal component strings in `rx.t`. The text you pass is the message in +your default locale; at runtime it is looked up in the active locale's catalog, +falling back to the original text when a translation is missing. + +```python +def index(): + return rx.vstack( + rx.heading(rx.t("Welcome")), + rx.button(rx.t("Sign in")), + ) +``` + +### Interpolating values + +Use `{name}` placeholders and pass the values as keyword arguments. Values may +be plain data **or state vars** — they interpolate on the client, so they stay +reactive: + +```python +class State(rx.State): + name: str = "Ada" + + +def greeting(): + return rx.text(rx.t("Hello, {name}!", name=State.name)) +``` + +### Plurals + +Pass a `plural` form and a `count`. The correct form is chosen using the active +locale's plural rules, and `count` is also available as the `{count}` +placeholder: + +```python +class CartState(rx.State): + items: int = 1 + + +def cart_label(): + return rx.text(rx.t("{count} item", plural="{count} items", count=CartState.items)) +``` + +A message is either singular or plural: gettext keys catalog entries by their +msgid, so using the same text both with and without `plural` raises an error. +Give one of them a `context` (below) if you need both. + +### Disambiguating with context + +When the same source text needs different translations in different places, +give it a `context`: + +```python +rx.t("Open", context="verb") # "to open something" +rx.t("Open", context="status") # "currently open" +``` + +## Dynamic content with `gettext` + +For text generated in your state, import `gettext` (conventionally aliased `_`) +and call it wherever you build the string. It translates into the current +visitor's locale. + +The best place is a **computed var**: it re-runs and re-sends the translated +string automatically when the locale changes. + +```python +from reflex_i18n import gettext as _ + + +class DashboardState(rx.State): + unread: int = 0 + + @rx.var + def status(self) -> str: + return _("You have {n} new messages").format(n=self.unread) +``` + +You can also translate at the moment you produce a one-off message, such as in +an event handler: + +```python +from reflex_i18n import gettext as _, ngettext + + +class OrderState(rx.State): + message: str = "" + + @rx.event + def checkout(self): + self.message = _("Order confirmed") + + @rx.event + def summarize(self, n: int): + self.message = ngettext("{n} order", "{n} orders", n).format(n=n) +``` + +`ngettext(singular, plural, n)` handles plurals and `pgettext(context, message)` +handles context, mirroring `rx.t`. + +Note: translate at render time (in a computed var) or at the moment you emit a +message. A translated string stored in a plain var earlier will not +re-translate on its own when the locale changes. + +### Text defined at import time + +A module-level constant or an enum label is created before any visitor has a +locale, so translating it right there would freeze it in the default language. +Mark it with `N_` (short for `gettext_noop`) instead: it returns the text +unchanged, but `reflex i18n extract` adds it to the catalogs. Translate the +value where it is shown, with `rx.t` in a component or `gettext` in state: + +```python +from reflex_i18n import N_, gettext as _ + +EMPTY_CART = N_("Your cart is empty") + + +def cart_hint(): + return rx.text(rx.t(EMPTY_CART)) + + +class CartState(rx.State): + hint: str = "" + + @rx.event + def clear(self): + self.hint = _(EMPTY_CART) +``` + +### Outside an event + +Event handlers and computed vars translate into their visitor's locale +automatically. Code that runs without a visitor (a background job, a scheduled +report, a message sent to someone else) has no locale until you set one with +`rx.i18n.use_locale`. `gettext` and the `format_*` helpers below follow it: + +```python +import datetime + +from reflex_i18n import format_date, gettext as _, use_locale + + +def monthly_report_title(user_locale: str, month: datetime.date) -> str: + with use_locale(user_locale): + return _("Report for {month}").format(month=format_date(month)) +``` + +`use_locale` raises a `ValueError` for a locale the plugin does not list. +`rx.i18n.get_locale()` returns the locale in effect, or `None` outside any. + +## Translated data + +Some text is data rather than part of your app: a product name or a +description entered once per language, stored for example as a +`{locale: text}` dict. `rx.i18n.pick` shows it in the visitor's language: + +```python +class ProductState(rx.State): + description: dict[str, str] = {"en": "Sparkling water", "de": "Mineralwasser"} + + +def product_card(): + return rx.text( + rx.i18n.pick(ProductState.description), + lang=rx.i18n.pick_locale(ProductState.description), + ) +``` + +When there is no text in the visitor's locale, the server and the browser fall +back in the same order: a text in the same language (`de-AT` takes `de`), the +default locale, the `fallback_locale`, the other configured locales, and +finally any text there is. `rx.i18n.pick_locale` returns the language actually +shown, e.g. for the element's `lang`. The browser re-picks instantly when the +locale changes. + +On the server, `pick_translation(texts)` picks for the current visitor (or for +the locale `use_locale` set), and `fallback_chain(locale)` returns the order +itself, each locale followed by its own language (`de-AT`, `de`) and spelled +the way `normalize_locale` spells stored keys. Trying the keys in that order, +e.g. in an SQL `COALESCE`, picks what `pick_translation` picks as long as the +keys are normalized languages without a region; a key like `de-CH` is found +only where the chain names it. `normalize_locale` spells a language +tag the way the plugin does, which keeps stored keys consistent. + +## Formatting numbers and dates + +Numbers, currencies, percentages and dates are formatted differently per locale +(`1,234.5` vs `1.234,5`, `7/18/2026` vs `18.07.2026`). There are two ways to +format, mirroring static vs dynamic content. + +**In components (client-side).** `rx.i18n.number` / `currency` / `percent` / +`date` / `time` / `datetime` format a value in the browser using `Intl`, and +reformat instantly when the locale changes: + +```python +import datetime + + +class PriceState(rx.State): + quantity: float = 3.5 + total: float = 41.9 + tax_rate: float = 0.19 + created: datetime.datetime = datetime.datetime.now(datetime.timezone.utc) + + +def price_row(): + return rx.hstack( + rx.text(rx.i18n.number(PriceState.quantity, max_fraction_digits=2)), + rx.text(rx.i18n.currency(PriceState.total, "EUR")), + rx.text(rx.i18n.percent(PriceState.tax_rate, max_fraction_digits=1)), + rx.text(rx.i18n.date(PriceState.created, length="long")), + ) +``` + +Curated options — `min_fraction_digits`, `max_fraction_digits`, `grouping`, +`compact`, and `length` (`"short"`/`"medium"`/`"long"`/`"full"`) — cover the +common cases; pass `options={...}` for raw +[`Intl`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) +options. A `None` value (or a date that does not parse) renders as empty text. + +**In state (server-side).** Use the `format_*` helpers, e.g. when building a +translated string. Like `gettext`, a computed var using one reformats when the +locale changes: + +```python +from reflex_i18n import gettext as _, format_currency + + +class CartState(rx.State): + total: float = 0.0 + + @rx.var + def summary(self) -> str: + return _("Total: {amount}").format(amount=format_currency(self.total, "EUR")) +``` + +`rx.i18n.locale` exposes the active locale as a var, e.g. to drive +`rx.moment(PriceState.created, locale=rx.i18n.locale)`. + +Languages and weekdays have names in every locale too. `rx.i18n.language_name` +names a language tag (`"pt-BR"` shows as "Portugiesisch (Brasilien)" to a German +visitor) and `rx.i18n.weekday` names a weekday, counted from 0 for Monday like +`datetime.date.weekday()`, with `length="long"`, `"short"` or `"narrow"`. Their +server-side counterparts are `format_language` and `format_weekday`. + +Two caveats: + +- **Naive datetimes client-side** are shown in the visitor's local time zone (a + datetime with no offset has no absolute meaning). For a fixed zone, use a + timezone-aware datetime, pass `options={"timeZone": "..."}`, or format + server-side with `format_datetime`. (Plain dates and times are unambiguous and + render correctly.) +- Python's `f"{value:,}"` formatting on a numeric var stays `en-US` by design; + use `rx.i18n.number` for locale-aware output. + +## Detecting and switching the locale + +On a visitor's first load, the locale is negotiated from their browser's +`Accept-Language`, falling back to `fallback_locale`, which is `default_locale` +unless you set it. Once they pick a language it is remembered in a cookie. + +The source language is not always the best guess for a visitor whose browser +asks for none of your locales. An app written in German that also ships English +can send everyone else to English: + +```python +I18nPlugin(locales=["de", "en"], default_locale="de", fallback_locale="en") +``` + +Switch languages with `rx.i18n.set_locale`, which updates both static and +dynamic content: + +```python +def language_switcher(): + return rx.hstack( + rx.button("English", on_click=rx.i18n.set_locale("en")), + rx.button("Deutsch", on_click=rx.i18n.set_locale("de")), + ) +``` + +Static (`rx.t`) content updates instantly; dynamic (state) content updates on +the next server round-trip. + +Once a page has loaded, the browser follows the locale the server holds for it. +A backend handler can therefore pick the language itself, e.g. the one stored in +a user's profile after they log in: + +```python +class AuthState(rx.State): + @rx.event + async def on_login(self): + user = await load_user(self.router.session.client_token) + return rx.i18n.set_locale(user.language) +``` + +`rx.i18n.language_switcher()` is a prebuilt switcher with one `` per locale, +labelled with each language's own name ("English", "Deutsch"). +Here it switches static and dynamic content just like `set_locale`, and becomes +a set of real crawlable links once URL routing is on (below). + +Locales are BCP 47 language tags written with hyphens (`en`, `pt-BR`, +`zh-Hant`) — they double as URL segments and `Intl` tags, so the underscore +spelling is rejected. + +## URL-based locales & SEO + +The cookie-based default keeps every language on the same URL. That's ideal for +apps (dashboards, authenticated tools), but bad for **SEO**: search engines see +only the default language, because the locale lives in a cookie/state rather +than the URL. + +For public sites, opt into **URL-based locales** by giving the plugin a routing +strategy: + +```python +from reflex_i18n import I18nPlugin, PathPrefixRouting + +config = rx.Config( + app_name="mysite", + deploy_url="https://mysite.com", # used for absolute hreflang hrefs + plugins=[ + I18nPlugin( + locales=["en", "de", "fr"], + default_locale="en", + routing=PathPrefixRouting(), # /de/..., /fr/... + ) + ], +) +``` + +You write each page **once**; the plugin fans it out into a concrete route per +locale. With the default `PathPrefixRouting(default_at_root=True)`: + +- `/pricing` serves the default locale, `/de/pricing` and `/fr/pricing` the + others (use `default_at_root=False` to prefix every locale). +- Each route is prerendered and carries reciprocal + `` (plus `x-default` and `canonical`) in + its ``, so all languages are discoverable and indexable. +- The locale comes from the **URL**, not a cookie — so each language URL renders + its own content for crawlers. + +Here the switcher's links become real per-locale URLs (crawlers follow them +instead of a cookie swap); you can also build your own with +`rx.i18n.locale_url`: + +```python +rx.i18n.language_switcher() # prebuilt links +rx.link("Deutsch", href=rx.i18n.locale_url("de", "/pricing")) +``` + +Notes: + +- Page `title`/`meta` translated with `rx.t` still resolve in the default + locale (the document head is outside the per-route locale provider); prefer + per-route titles if that matters. +- `default_at_root=True` (the default) is recommended for SEO: the default + locale keeps clean canonical URLs (`/pricing`). With `default_at_root=False` + every locale is prefixed; visiting an unprefixed path redirects to its + default-locale address (`/pricing` → `/en/pricing`), and its canonical link + points there. +- App routes must not start with a configured locale (e.g. a `/de/...` page of + your own while `de` is configured): those URLs are reserved for the generated + locale routes, and compilation fails with a clear error. +- Each locale route prerenders that language's content, `hreflang`, + `canonical` and ``/`dir`. Unprefixed pages of the default locale + keep the app-wide `rx.App(html_lang=...)`, so set it to your `default_locale`. + +## Translation catalogs + +Translations are standard gettext `.po` files, one per locale, under `locales/`: + +```text +locales/ + en.po + de.po + fr.po +``` + +A catalog entry pairs the source text (`msgid`) with its translation +(`msgstr`): + +```po +msgid "Welcome" +msgstr "Willkommen" + +msgid "{count} item" +msgid_plural "{count} items" +msgstr[0] "{count} Artikel" +msgstr[1] "{count} Artikel" +``` + +You don't write these by hand — the CLI generates and maintains them. + +## The `reflex i18n` CLI + +Once the plugin is configured, three commands manage your catalogs: + +```bash +# Scan the app for rx.t and gettext calls and update every locale's .po file +# (new messages added, translations preserved, removed ones marked obsolete). +reflex i18n extract + +# Create a fresh catalog for a new locale. +reflex i18n init es + +# Fail (non-zero exit) if any non-default locale has untranslated or fuzzy +# messages (the default locale holds the source msgids). Useful as a CI check. +reflex i18n check +``` + +A typical workflow: run `reflex i18n extract` after adding or changing strings, +fill in the `msgstr` values in each locale's `.po` file, and add +`reflex i18n check` to CI to catch missing translations. + +## Translating a library + +A package that other apps install marks its text the same way: `rx.t` in +components, `gettext` in state, `N_` for constants. It does not need the apps +using it to translate. Without an `I18nPlugin`, `rx.t` renders the source text +and the `rx.i18n` formatters format in English, as the server-side `format_*` +helpers do outside any locale. + +A package can ship its translations too: one `.po` file per locale in a +`locales/` directory inside the package (make sure its distribution includes +them). Manage them from the package's repository, no app needed: + +```bash +reflex i18n init de --package my_lib # create my_lib/locales/de.po +reflex i18n extract --package my_lib # update the catalogs after changing text +reflex i18n check --package my_lib # fail on untranslated messages (CI) +``` + +Extraction finds `gettext`-family calls, `N_` markers and `rx.t` calls with +literal text. Text computed at runtime is invisible to it, so mark it with `N_` +where it is defined. + +An app uses a package's translations by listing the package: + +```python +I18nPlugin(locales=["de", "en"], default_locale="de", catalog_packages=["my_lib"]) +``` + +Its catalogs then translate the package's messages in the browser and on the +server, and `reflex i18n extract` leaves those messages out of the app's own +catalogs. + +## How it works + +- `rx.t` compiles to a client-side lookup. At build time Reflex generates one + small JavaScript catalog per locale, and the browser loads **only the active + language** on demand. +- `gettext` runs on the server against the locale resolved for the current + client, so no translation data for other languages is sent to the browser. +- Missing translations always fall back to the source text, so an incomplete + catalog degrades gracefully rather than showing blank strings. diff --git a/examples/ruff.toml b/examples/ruff.toml index 41393b91a35..8c33feb588b 100644 --- a/examples/ruff.toml +++ b/examples/ruff.toml @@ -32,6 +32,7 @@ reflex_components_react_player.msg = "Examples import Reflex only as `import ref reflex_components_recharts.msg = "Examples import Reflex only as `import reflex as rx`." reflex_components_sonner.msg = "Examples import Reflex only as `import reflex as rx`." reflex_docgen.msg = "Examples import Reflex only as `import reflex as rx`." +reflex_i18n.msg = "Examples import Reflex only as `import reflex as rx`." reflex_otel.msg = "Examples import Reflex only as `import reflex as rx`." reflex_release.msg = "Examples import Reflex only as `import reflex as rx`." reflex_site_shared.msg = "Examples import Reflex only as `import reflex as rx`." diff --git a/news/6796.bugfix.md b/news/6796.bugfix.md new file mode 100644 index 00000000000..e35bad428dd --- /dev/null +++ b/news/6796.bugfix.md @@ -0,0 +1 @@ +Hot reload no longer crashes in `_mark_dirty_computed_vars` when a computed var defined in the reloaded module depends on a state outside it: the dependency edges that surviving state kept for the reloaded computed var are now purged instead of being left to dangle. diff --git a/news/6796.feature.md b/news/6796.feature.md new file mode 100644 index 00000000000..6d38d9a5a2f --- /dev/null +++ b/news/6796.feature.md @@ -0,0 +1 @@ +Added internationalization support through the new `reflex-i18n` package, exposed under `rx.i18n`: translate static component content with `rx.t` and dynamic state content server-side with `rx.i18n.gettext`/`ngettext`/`pgettext`, and configure locales with `rx.i18n.I18nPlugin` in `rx.Config(plugins=[...])`. With `reflex-i18n` installed, `reflex i18n` manages the translation catalogs. diff --git a/packages/reflex-base/news/6796.feature.md b/packages/reflex-base/news/6796.feature.md new file mode 100644 index 00000000000..53c5b675b98 --- /dev/null +++ b/packages/reflex-base/news/6796.feature.md @@ -0,0 +1 @@ +Added three extension points (used by `reflex-i18n`, available to any package): `register_event_scope_provider` wraps each event's handler execution and delta resolution in an ambient context that is re-derived after the handler runs (e.g. the active locale), which plain middleware cannot do; `register_implicit_dependency` marks functions whose use inside a computed var getter implies a dependency on a var the getter never reads directly (e.g. a gettext helper reading the active locale from a contextvar); and a plugin's `expand_routes` hook (`reflex_base.plugins.ExpandRoutesContext`) can register extra pages derived from the app's own, e.g. one route per locale. The first two are no-ops with negligible cost when nothing is registered. diff --git a/packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py b/packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py index 8af90e5b769..e891c96a9f0 100644 --- a/packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py +++ b/packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py @@ -32,6 +32,7 @@ from reflex_base.event.context import EventContext from reflex_base.event.processor.event_processor import EventProcessor, EventQueueEntry from reflex_base.event.processor.future import EventFuture +from reflex_base.event.processor.scope import event_scope from reflex_base.registry import RegisteredEventHandler from reflex_base.utils.form import form_data_as_dict, transform_form_data from reflex_base.utils.format import format_event_handler @@ -492,7 +493,10 @@ async def chain_updates( if root_state is not None: # Emit deltas first, so any frontend events are processed with the - # latest state. The clean deliberately runs after resolution: the + # latest state. Enter the event scope again here (after the handler + # ran): a provider may derive its context from state the handler just + # changed (e.g. the locale), and computed vars are recomputed during + # delta resolution. The clean deliberately runs after resolution: the # SharedState fan-out captures its dirty vars at clean time, and # resolving the delta is what re-marks linked vars through the patch # machinery, so cleaning earlier would fan out a stale set (see @@ -508,13 +512,16 @@ async def chain_updates( # of being cleaned, and the next flush sends it. concurrent = bool(ctx.inline_tasks) seen = _written_snapshot(root_state) if concurrent else {} - delta = await root_state._get_resolved_delta() - while concurrent and _written_since( - seen, written := _written_snapshot(root_state) - ): - seen = written - for name, late in (await root_state._get_resolved_delta()).items(): - delta[name] = {**delta.get(name, {}), **late} + # A provider suppressing a resolution error leaves nothing to send. + delta = {} + async with event_scope(root_state): + delta = await root_state._get_resolved_delta() + while concurrent and _written_since( + seen, written := _written_snapshot(root_state) + ): + seen = written + for name, late in (await root_state._get_resolved_delta()).items(): + delta[name] = {**delta.get(name, {}), **late} finally: root_state._clean() if delta: @@ -959,23 +966,30 @@ async def _execute_event( # the plain try/finally spares the context manager's overhead. ctx.set_locked_root(root_state) try: - if needs_to_rehydrate: - await self._rehydrate(root_state) - - # Process non-background events while holding the lock. + # Enter any per-event ambient context (e.g. i18n locale) around + # handler execution. A no-op unless a feature registered a scope + # provider, so apps without one pay effectively nothing. + async with event_scope(root_state): + if needs_to_rehydrate: + await self._rehydrate(root_state) + + # Process non-background events while holding the lock. + if not registered_handler.handler.is_background: + try: + return await process_event( + handler=registered_handler.handler, + payload=event.payload, + state=substate, + root_state=root_state, + ) + except (Exception, asyncio.CancelledError): + await _flush_failed_handler( + root_state, registered_handler.handler.fn.__qualname__ + ) + raise if not registered_handler.handler.is_background: - try: - return await process_event( - handler=registered_handler.handler, - payload=event.payload, - state=substate, - root_state=root_state, - ) - except (Exception, asyncio.CancelledError): - await _flush_failed_handler( - root_state, registered_handler.handler.fn.__qualname__ - ) - raise + # The scope suppressed the handler's exception. + return None finally: await ctx.release_lock() # Otherwise drop the state lock and start processing the background task @@ -987,6 +1001,8 @@ async def _execute_event( # background task's own state changes are emitted (and cleaned) by its # `async with self` context exits, which re-acquire the lock. proxy = StateProxy(substate) + # The scope releases the root state once entered, so it pins no tree. + scope = event_scope(root_state) # Leave the tree loaded under the lock to the proxy, which replaces it on # `async with self`. A manager like redis loads a fresh tree for every # lock, so these locals would pin an extra copy for the whole task. @@ -994,12 +1010,13 @@ async def _execute_event( handler_error: BaseException | None = None result = None try: - result = await process_event( - handler=registered_handler.handler, - state=proxy, - payload=event.payload, - root_state=None, - ) + async with scope: + result = await process_event( + handler=registered_handler.handler, + state=proxy, + payload=event.payload, + root_state=None, + ) except BaseException as ex: handler_error = ex raise diff --git a/packages/reflex-base/src/reflex_base/event/processor/scope.py b/packages/reflex-base/src/reflex_base/event/processor/scope.py new file mode 100644 index 00000000000..ced810772d0 --- /dev/null +++ b/packages/reflex-base/src/reflex_base/event/processor/scope.py @@ -0,0 +1,95 @@ +"""Per-event ambient context providers (e.g. i18n locale). + +A provider yields a context manager entered around both handler execution and +delta resolution; it is called fresh at each phase, so state a handler changed +is re-read. Middleware can't do this (separate pre/post calls). No registered +providers means a ``nullcontext`` fast path. +""" + +from __future__ import annotations + +import contextlib +from collections.abc import Awaitable, Callable +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from types import TracebackType + + from reflex.state import BaseState + +# A provider takes the root state and returns (async) a synchronous context +# manager to enter for the current event phase. +EventScopeProvider = Callable[ + ["BaseState"], Awaitable[contextlib.AbstractContextManager[None]] +] + +_providers: list[EventScopeProvider] = [] + + +def register_event_scope_provider(provider: EventScopeProvider) -> None: + """Register a per-event ambient-context provider. + + Args: + provider: Async callable from root state to a context manager. + """ + _providers.append(provider) + + +def has_event_scope_providers() -> bool: + """Whether any event-scope providers are registered. + + Returns: + True if at least one provider is registered. + """ + return bool(_providers) + + +class _EventScope: + """Async context manager entering every registered provider's scope.""" + + __slots__ = ("_root_state", "_stack") + + def __init__(self, root_state: BaseState): + self._root_state = root_state + self._stack = contextlib.ExitStack() + + async def __aenter__(self) -> None: + # Drop the reference so a background task's scope does not pin the tree + # its proxy replaces on `async with self`. + root_state = self._root_state + del self._root_state + # ``async with`` only calls ``__aexit__`` if ``__aenter__`` returns, so + # a provider raising mid-loop would otherwise leak the contexts already + # entered (e.g. an earlier provider's contextvar token). + try: + for provider in _providers: + self._stack.enter_context(await provider(root_state)) + except BaseException: + self._stack.close() + raise + + async def __aexit__( + self, + exc_type: type[BaseException] | None, + exc_value: BaseException | None, + traceback: TracebackType | None, + ) -> bool | None: + # Forwarded so a provider's context manager can observe (and suppress) + # an exception raised by the handler or by delta resolution. + return self._stack.__exit__(exc_type, exc_value, traceback) + + +def event_scope( + root_state: BaseState, +) -> contextlib.AbstractAsyncContextManager[None]: + """Ambient-context scope for processing an event. + + Args: + root_state: The client's root state instance. + + Returns: + A scope entering every provider, or a no-op when none are registered. + """ + if not _providers: + return contextlib.nullcontext() + return _EventScope(root_state) diff --git a/packages/reflex-base/src/reflex_base/plugins/__init__.py b/packages/reflex-base/src/reflex_base/plugins/__init__.py index c82a36d559f..cdde8beea42 100644 --- a/packages/reflex-base/src/reflex_base/plugins/__init__.py +++ b/packages/reflex-base/src/reflex_base/plugins/__init__.py @@ -18,6 +18,7 @@ from ._screenshot import ScreenshotPlugin as _ScreenshotPlugin from .base import ( CommonContext, + ExpandRoutesContext, Plugin, PostBuildContext, PostCompileContext, @@ -45,6 +46,7 @@ "CompilerHooks", "ComponentAndChildren", "EmbedPlugin", + "ExpandRoutesContext", "PageContext", "PageDefinition", "Plugin", @@ -78,6 +80,7 @@ "_screenshot": [("ScreenshotPlugin", "_ScreenshotPlugin")], "base": [ "CommonContext", + "ExpandRoutesContext", "Plugin", "PostBuildContext", "PostCompileContext", diff --git a/packages/reflex-base/src/reflex_base/plugins/base.py b/packages/reflex-base/src/reflex_base/plugins/base.py index 3f52afe48ee..dbb542e3f83 100644 --- a/packages/reflex-base/src/reflex_base/plugins/base.py +++ b/packages/reflex-base/src/reflex_base/plugins/base.py @@ -106,6 +106,12 @@ class RegisterRouteContext(CommonContext): has_app_page: Callable[[str], bool] +class ExpandRoutesContext(RegisterRouteContext): + """Context for ``expand_routes``: adds the app's registered ``pages``.""" + + pages: Sequence["UnevaluatedPage"] + + class PostCompileContext(CommonContext): """Context for post-compile hooks.""" @@ -194,6 +200,16 @@ def register_route(self, **context: Unpack[RegisterRouteContext]) -> None: context: The route registration context. """ + def expand_routes(self, **context: Unpack[ExpandRoutesContext]) -> None: + """Contribute pages derived from the app's already-registered pages. + + Runs after ``register_route`` with the same staged ``add_page``; the + context adds ``pages`` (the app's registered pages) to fan out from. + + Args: + context: The route-expansion context. + """ + def pre_compile(self, **context: Unpack[PreCompileContext]) -> None: """Called before the compilation of the plugin. diff --git a/packages/reflex-base/src/reflex_base/utils/lazy_loader.py b/packages/reflex-base/src/reflex_base/utils/lazy_loader.py index b3ec6164c88..5874d27e35d 100644 --- a/packages/reflex-base/src/reflex_base/utils/lazy_loader.py +++ b/packages/reflex-base/src/reflex_base/utils/lazy_loader.py @@ -20,7 +20,7 @@ import importlib import os import sys -from collections.abc import Mapping, Sequence +from collections.abc import Iterable, Mapping, Sequence SubmodAttrsType = Mapping[str, Sequence[str | tuple[str, str]]] @@ -139,10 +139,7 @@ def attach( for attr in attrs } - __all__ = sorted([ - *(submodules | alias_to_module_and_attr.keys()), - *(extra_mappings or []), - ]) + __all__ = exported_names(submodules, submod_attrs, extra_mappings) def __getattr__(name: str): # noqa: N807 if name in extra_mappings: @@ -190,6 +187,27 @@ def __dir__(): # noqa: N807 return __getattr__, __dir__, list(__all__) +def exported_names( + submodules: Iterable[str] | None, + submod_attrs: SubmodAttrsType | None, + extra_mappings: Iterable[str] | None, +) -> list[str]: + """Get the names ``attach`` lists in a package's ``__all__``. + + Args: + submodules: The submodules to attach. + submod_attrs: Dictionary of submodule -> list of attributes / functions. + extra_mappings: The names of the additional mappings. + + Returns: + The sorted names. + """ + aliases = { + comp_alias(attr) for attrs in (submod_attrs or {}).values() for attr in attrs + } + return sorted([*(set(submodules or ()) | aliases), *(extra_mappings or ())]) + + def comp_name(comp: str | tuple[str, str]) -> str: """Get the component name from the mapping value. diff --git a/packages/reflex-base/src/reflex_base/utils/log.py b/packages/reflex-base/src/reflex_base/utils/log.py index 101e5345ab0..2e460f846e0 100644 --- a/packages/reflex-base/src/reflex_base/utils/log.py +++ b/packages/reflex-base/src/reflex_base/utils/log.py @@ -63,6 +63,7 @@ "reflex_components_lucide", "reflex_components_plotly", "reflex_components_react_player", + "reflex_i18n", "reflex_otel", "reflex_build_sdk", "reflex_workflow", diff --git a/packages/reflex-base/src/reflex_base/utils/pyi_generator.py b/packages/reflex-base/src/reflex_base/utils/pyi_generator.py index 06280c42e84..8bf43365fbb 100644 --- a/packages/reflex-base/src/reflex_base/utils/pyi_generator.py +++ b/packages/reflex-base/src/reflex_base/utils/pyi_generator.py @@ -27,6 +27,7 @@ from reflex_base.components.component import DEFAULT_TRIGGERS_AND_DESC, Component from reflex_base.environment import interpret_boolean_env +from reflex_base.utils.lazy_loader import exported_names from reflex_base.vars.base import Var @@ -1603,7 +1604,9 @@ def _get_init_lazy_imports(mod: ModuleType, new_tree: ast.AST): + "\n" ) text += ast.unparse(new_tree) + "\n\n" - text += f"__all__ = {getattr(mod, '__all__', [])!r}\n" + # From the mappings rather than the runtime __all__, which can leave out the + # names of an optional package the stub build environment does not have. + text += f"__all__ = {exported_names(sub_mods, sub_mod_attrs, extra_mappings)!r}\n" return text diff --git a/packages/reflex-base/src/reflex_base/vars/dep_tracking.py b/packages/reflex-base/src/reflex_base/vars/dep_tracking.py index 733b5274820..ac24220de70 100644 --- a/packages/reflex-base/src/reflex_base/vars/dep_tracking.py +++ b/packages/reflex-base/src/reflex_base/vars/dep_tracking.py @@ -9,6 +9,7 @@ import importlib import inspect import sys +from collections.abc import Callable, Iterable from types import CellType, CodeType, FunctionType, MemberDescriptorType, ModuleType from typing import TYPE_CHECKING, Any, ClassVar, cast @@ -22,6 +23,26 @@ CellEmpty = object() +# Functions whose mere use inside a computed var getter implies a dependency on +# a var, even though the getter never reads that var directly (e.g. a gettext +# helper that reads the active locale from a contextvar). Maps the function to a +# provider returning the implied dependency Var, or None when inactive. +_implicit_dependency_providers: dict[object, Callable[[], Var | None]] = {} + + +def register_implicit_dependency( + funcs: Iterable[object], provider: Callable[[], Var | None] +) -> None: + """Register functions that imply a computed-var dependency when referenced. + + Args: + funcs: The functions to detect (matched by object identity). + provider: Returns the implied dependency Var, or None when the + dependency is not currently applicable. + """ + for func in funcs: + _implicit_dependency_providers[func] = provider + def get_cell_value(cell: CellType) -> Any: """Get the value of a cell object. @@ -118,6 +139,14 @@ class DependencyTracker: _get_var_value_positions: dis.Positions | None = dataclasses.field(default=None) _last_import_name: str | None = dataclasses.field(default=None) + # A module loaded by the previous instruction, so `pkg.mod.helper` can be + # resolved attribute by attribute (a code object has no globals of its own). + _attr_base: ModuleType | None = dataclasses.field(default=None) + # Globals and closure of the enclosing function when ``func`` is a nested + # code object (comprehension, lambda), which carries neither itself. + _globals: dict[str, Any] | None = dataclasses.field(default=None) + _closure: dict[str, Any] | None = dataclasses.field(default=None) + INVALID_NAMES: ClassVar[list[str]] = ["parent_state", "substates", "get_substate"] def __post_init__(self): @@ -198,6 +227,10 @@ def load_attr_or_method(self, instruction: dis.Instruction) -> None: if not self.top_of_stack: return target_obj = self.get_tracked_local(self.top_of_stack) + if isinstance(target_obj, ModuleType): + # `mod.helper` on an inline-imported module. + self._load_module_attr(target_obj, instruction.argval) + return try: target_state = assert_base_state(target_obj, local_name=self.top_of_stack) except VarValueError: @@ -230,6 +263,39 @@ def load_attr_or_method(self, instruction: dis.Instruction) -> None: instruction.argval ) + def _load_module_attr(self, module: ModuleType, name: str) -> None: + """Resolve an attribute of a module; detect helpers, follow submodules. + + Args: + module: The module on top of the stack. + name: The attribute being loaded. + """ + obj = getattr(module, name, None) + self._add_implicit_dependency(obj) + self._attr_base = obj if isinstance(obj, ModuleType) else None + + def _add_implicit_dependency(self, obj: object) -> None: + """Record an implied dependency if ``obj`` is a registered function. + + Args: + obj: The object a load instruction resolved to (may be anything). + """ + if not _implicit_dependency_providers: + return + try: + provider = _implicit_dependency_providers.get(obj) + except TypeError: + return # unhashable objects can't be registered functions + if provider is None: + return + dep_var = provider() + if dep_var is None: + return + var_data = dep_var._get_all_var_data() + if var_data is None or not var_data.state: + return + self.dependencies.setdefault(var_data.state, set()).add(var_data.field_name) + def _get_globals(self) -> dict[str, Any]: """Get the globals of the function. @@ -237,7 +303,7 @@ def _get_globals(self) -> dict[str, Any]: The var names and values in the globals of the function. """ if isinstance(self.func, CodeType): - return {} + return self._globals or {} return self.func.__globals__ # pyright: ignore[reportAttributeAccessIssue] def _get_closure(self) -> dict[str, Any]: @@ -247,7 +313,7 @@ def _get_closure(self) -> dict[str, Any]: The var names and values in the closure of the function. """ if isinstance(self.func, CodeType): - return {} + return self._closure or {} return { var_name: get_cell_value(cell) for var_name, cell in zip( @@ -415,6 +481,8 @@ def _populate_dependencies(self) -> None: define comprehensions or nested functions that may reference "self". """ for instruction in dis.get_instructions(self.func): + # Only the instruction right after a module load continues its chain. + attr_base, self._attr_base = self._attr_base, None if self.scan_status == ScanStatus.GETTING_STATE: self.handle_getting_state(instruction) elif self.scan_status == ScanStatus.GETTING_STATE_POST_AWAIT: @@ -432,29 +500,43 @@ def _populate_dependencies(self) -> None: ) and instruction.argval in self.tracked_locals ): + # A tracked local may be an inline-imported function that + # implies a dependency (e.g. a gettext helper). + self._add_implicit_dependency(self.tracked_locals[instruction.argval]) # bytecode loaded the class instance to the top of stack, next load instruction # is referencing an attribute on self self.top_of_stack = instruction.argval self.scan_status = ScanStatus.GETTING_ATTR - elif ( - instruction.opname - in ( - "LOAD_FAST_LOAD_FAST", - "LOAD_FAST_BORROW_LOAD_FAST_BORROW", - "STORE_FAST_LOAD_FAST", - ) - and instruction.argval[-1] in self.tracked_locals + elif instruction.opname in ( + "LOAD_FAST_LOAD_FAST", + "LOAD_FAST_BORROW_LOAD_FAST_BORROW", + "STORE_FAST_LOAD_FAST", ): - # Double LOAD_FAST family instructions load multiple values onto the stack, - # the last value in the argval list is the top of the stack. - self.top_of_stack = instruction.argval[-1] - self.scan_status = ScanStatus.GETTING_ATTR + # Every loaded name (the first one is a store, not a load, in + # STORE_FAST_LOAD_FAST) may be an inline-imported function + # that implies a dependency, same as the single-load case. + loaded_from = 1 if instruction.opname == "STORE_FAST_LOAD_FAST" else 0 + for name in instruction.argval[loaded_from:]: + if name in self.tracked_locals: + self._add_implicit_dependency(self.tracked_locals[name]) + if instruction.argval[-1] in self.tracked_locals: + # Double LOAD_FAST family instructions load multiple values onto the stack, + # the last value in the argval list is the top of the stack. + self.top_of_stack = instruction.argval[-1] + self.scan_status = ScanStatus.GETTING_ATTR elif self.scan_status == ScanStatus.GETTING_ATTR and instruction.opname in ( "LOAD_ATTR", "LOAD_METHOD", ): self.load_attr_or_method(instruction) self.top_of_stack = None + elif attr_base is not None and instruction.opname in ( + "LOAD_ATTR", + "LOAD_METHOD", + ): + # `pkg.mod.helper(...)`: walk the attribute chain off a module + # so a module-qualified helper reference is detected too. + self._load_module_attr(attr_base, instruction.argval) elif instruction.opname == "LOAD_CONST" and isinstance( instruction.argval, CodeType ): @@ -465,8 +547,28 @@ def _populate_dependencies(self) -> None: func=instruction.argval, state_cls=self.state_cls, tracked_locals=self.tracked_locals, + _globals=self._get_globals(), + _closure=self._get_closure(), ) ) + elif ( + instruction.opname == "LOAD_GLOBAL" + and self.scan_status == ScanStatus.SCANNING + ): + # A referenced global may be a function that implies a + # dependency (e.g. a gettext helper reading the active locale), + # or a module such a helper is then loaded from. + obj = self._get_globals().get(instruction.argval) + self._add_implicit_dependency(obj) + self._attr_base = obj if isinstance(obj, ModuleType) else None + elif ( + instruction.opname == "LOAD_DEREF" + and self.scan_status == ScanStatus.SCANNING + ): + # Same as above for a closure-captured reference. + obj = self._get_closure().get(instruction.argval) + self._add_implicit_dependency(obj) + self._attr_base = obj if isinstance(obj, ModuleType) else None elif instruction.opname == "IMPORT_NAME": if instruction.argval is None: continue diff --git a/packages/reflex-i18n/README.md b/packages/reflex-i18n/README.md new file mode 100644 index 00000000000..d22ae2c9dc2 --- /dev/null +++ b/packages/reflex-i18n/README.md @@ -0,0 +1,42 @@ +# reflex-i18n + +Internationalization (i18n) for [Reflex](https://reflex.dev) apps. + +- `rx.t(...)` — translate static component strings, resolved client-side from + per-locale catalogs (only the active locale is shipped to the client). +- `gettext` / `ngettext` / `pgettext` — translate dynamic (state) content + server-side; translated computed vars retranslate automatically on a locale + switch. +- `I18nPlugin` — configure locales and wire compilation. + +```python +import reflex as rx +from reflex_i18n import I18nPlugin, t, gettext as _ + + +class State(rx.State): + @rx.var + def greeting(self) -> str: + return _("Hello") + + +def index(): + return rx.text(t("Welcome")) + + +app = rx.App() +app.add_page(index) +``` + +```python +# rxconfig.py +import reflex as rx +from reflex_i18n import I18nPlugin + +config = rx.Config( + app_name="myapp", + plugins=[I18nPlugin(locales=["en", "de"], default_locale="en")], +) +``` + +Translations live in `locales/{locale}.po`. diff --git a/packages/reflex-i18n/news/6796.feature.md b/packages/reflex-i18n/news/6796.feature.md new file mode 100644 index 00000000000..aacf9241801 --- /dev/null +++ b/packages/reflex-i18n/news/6796.feature.md @@ -0,0 +1 @@ +New `reflex-i18n` package providing internationalization for Reflex apps: `rx.t` for translating static component text, server-side `gettext`/`ngettext`/`pgettext` for dynamic state content, an `I18nPlugin`/`I18nConfig` to configure available locales, an `I18nState` whose active locale is backed by a cookie, a `reflex i18n` CLI that extracts messages into the per-locale `.po` catalogs and reports untranslated ones, and `catalog_packages` so a library can ship its own catalogs. diff --git a/packages/reflex-i18n/pyproject.toml b/packages/reflex-i18n/pyproject.toml new file mode 100644 index 00000000000..5bbdcfa9449 --- /dev/null +++ b/packages/reflex-i18n/pyproject.toml @@ -0,0 +1,38 @@ +[project] +name = "reflex-i18n" +dynamic = ["version"] +description = "Internationalization (i18n) for Reflex apps." +license.text = "Apache-2.0" +readme = "README.md" +authors = [{ name = "Reflex", email = "maintainers@reflex.dev" }] +maintainers = [{ name = "Reflex", email = "maintainers@reflex.dev" }] +requires-python = ">=3.11" +classifiers = [ + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", + "Programming Language :: Python :: 3.15", +] +dependencies = [ + # TODO: Bump to the released versions before publishing. + "reflex-base >= 0.10.2.dev0", + "reflex >= 0.10.2.dev0", + "babel >= 2.14.0,<3.0", +] + +[tool.hatch.version] +source = "uv-dynamic-versioning" + +[tool.uv-dynamic-versioning] +pattern-prefix = "reflex-i18n-" +fallback-version = "0.0.0dev0" +bump = true + +[tool.hatch.build] +artifacts = ["_web/**"] + +[build-system] +requires = ["hatchling", "uv-dynamic-versioning"] +build-backend = "hatchling.build" diff --git a/packages/reflex-i18n/src/reflex_i18n/__init__.py b/packages/reflex-i18n/src/reflex_i18n/__init__.py new file mode 100644 index 00000000000..8149521f76e --- /dev/null +++ b/packages/reflex-i18n/src/reflex_i18n/__init__.py @@ -0,0 +1,139 @@ +"""Internationalization (i18n) for Reflex apps. + +Static (component) content is translated with :func:`t`; dynamic (state) +content is translated server-side with :func:`gettext` / :func:`ngettext` / +:func:`pgettext`. Configure locales with :class:`I18nPlugin` in +``rx.Config(plugins=[...])``. +""" + +from typing import TYPE_CHECKING, Any + +from .config import ( + LOCALE_COOKIE_NAME, + I18nConfig, + normalize_locale, + source_locale, + validate_locale, +) + +# date/datetime/time use the alias form and are omitted from __all__ so +# `from reflex_i18n import *` cannot shadow the stdlib names; they remain +# available as rx.i18n.date / .time / .datetime (prefer attribute access). +from .format import currency, language_name, number, percent, weekday +from .format import date as date +from .format import datetime as datetime +from .format import time as time +from .nav import language_switcher, locale_url +from .plugin import I18nPlugin +from .routing import PathPrefixRouting +from .runtime import ( + fallback_chain, + format_currency, + format_date, + format_datetime, + format_decimal, + format_language, + format_number, + format_percent, + format_time, + format_weekday, + get_locale, + gettext, + gettext_noop, + match_locale, + ngettext, + pgettext, + pick_translation, + pick_translation_locale, + use_locale, +) +from .vars import pick, pick_locale, t + +if TYPE_CHECKING: + from reflex_base.vars.sequence import StringVar + + from .state import I18nState, set_locale + + # The active locale as a client-side var; resolved lazily (see below). + locale: StringVar + +# The conventional gettext shorthands: ``_`` translates, ``N_`` only marks. +_ = gettext +N_ = gettext_noop + +# "date", "datetime" and "time" are intentionally omitted (see the import +# above): reachable as rx.i18n.date/.time/.datetime but excluded from +# `import *` so they cannot shadow the stdlib names. "locale" is omitted for a +# different reason: `import *` resolves every exported name, and that one +# depends on whether an I18nPlugin is configured by the time it is built. +__all__ = [ + "LOCALE_COOKIE_NAME", + "I18nConfig", + "I18nPlugin", + "I18nState", + "PathPrefixRouting", + "currency", + "fallback_chain", + "format_currency", + "format_date", + "format_datetime", + "format_decimal", + "format_language", + "format_number", + "format_percent", + "format_time", + "format_weekday", + "get_locale", + "gettext", + "gettext_noop", + "language_name", + "language_switcher", + "locale_url", + "match_locale", + "ngettext", + "normalize_locale", + "number", + "percent", + "pgettext", + "pick", + "pick_locale", + "pick_translation", + "pick_translation_locale", + "set_locale", + "source_locale", + "t", + "use_locale", + "validate_locale", + "weekday", +] + +# Importing ``.state`` registers ``I18nState`` as a substate (a global side +# effect). Defer it so merely importing this package (e.g. the reflex CLI +# loading the ``reflex i18n`` command) does not attach i18n state to apps +# that never use i18n; opting in via ``I18nPlugin`` or accessing these names +# does. +_LAZY_STATE_ATTRS = frozenset({"I18nState", "set_locale"}) + + +def __getattr__(name: str) -> Any: + """Lazily resolve state-registering attributes. + + Args: + name: The attribute name. + + Returns: + The resolved attribute. + + Raises: + AttributeError: If the attribute is not part of the public API. + """ + if name in _LAZY_STATE_ATTRS: + from . import state + + return getattr(state, name) + if name == "locale": + from .format import locale_var + + return locale_var() + msg = f"module {__name__!r} has no attribute {name!r}" + raise AttributeError(msg) diff --git a/packages/reflex-i18n/src/reflex_i18n/_web/i18n.js b/packages/reflex-i18n/src/reflex_i18n/_web/i18n.js new file mode 100644 index 00000000000..940ecbb621c --- /dev/null +++ b/packages/reflex-i18n/src/reflex_i18n/_web/i18n.js @@ -0,0 +1,592 @@ +import { + createContext, + createElement, + Fragment, + useCallback, + useContext, + useEffect, + useRef, + useState, +} from "react"; +import { useHref, useLocation, useNavigate } from "react-router"; + +import { + cookieName, + defaultAtRoot, + defaultLocale, + defaultPlural, + deployUrl, + fallbackLocale, + loaders, + locales, + urlRouting, +} from "$/i18n/index.js"; + +// gettext msgctxt separator; catalog keys are "context\u0004msgid". +const CONTEXT_SEPARATOR = "\u0004"; + +// Language subtags written right-to-left. +const RTL_LANGUAGES = new Set([ + "ar", + "arc", + "ckb", + "dv", + "fa", + "he", + "ks", + "ps", + "sd", + "ug", + "ur", + "yi", +]); + +// Set /dir for a locale. Tags are case-insensitive (RFC 5646). +const applyDocumentLocale = (locale) => { + const root = document.documentElement; + root.lang = locale; + const language = locale.split("-")[0].toLowerCase(); + root.dir = RTL_LANGUAGES.has(language) ? "rtl" : "ltr"; +}; + +const stripContext = (key) => { + const index = key.indexOf(CONTEXT_SEPARATOR); + return index === -1 ? key : key.slice(index + 1); +}; + +const interpolate = (message, params) => + message.replace(/\{(\w+)\}/g, (match, name) => + params && name in params ? String(params[name]) : match, + ); + +const readCookie = (name) => { + const match = document.cookie + .split("; ") + .find((row) => row.startsWith(name + "=")); + return match ? decodeURIComponent(match.split("=")[1]) : undefined; +}; + +const writeCookie = (name, value) => { + const secure = location.protocol === "https:" ? "; secure" : ""; + document.cookie = `${name}=${encodeURIComponent(value)}; path=/; max-age=31536000; samesite=lax${secure}`; +}; + +// The supported locale that best serves a list of requested ones: for each +// requested tag in turn, the supported locale with the same tag, else the first +// one with the same primary language ("de-AT" -> "de"). Tags compare +// case-insensitively (RFC 5646). Mirrors reflex_i18n.runtime.match_locale. +export const matchLocale = (requested, supported) => { + const byTag = new Map(); + const byLanguage = new Map(); + for (const locale of supported) { + const tag = locale.toLowerCase(); + byTag.set(tag, locale); + const language = tag.split("-")[0]; + if (!byLanguage.has(language)) { + byLanguage.set(language, locale); + } + } + for (const tag of requested) { + const lower = tag.toLowerCase(); + const match = byTag.get(lower) ?? byLanguage.get(lower.split("-")[0]); + if (match !== undefined) { + return match; + } + } + return undefined; +}; + +// The locales to try, in order, for content wanted in a locale (the default +// locale if none), each followed by its own language. Mirrors +// reflex_i18n.runtime.fallback_chain. +export const fallbackChain = (locale) => { + const chain = new Map(); + for (const candidate of [ + locale || defaultLocale, + defaultLocale, + fallbackLocale, + ...locales, + ]) { + for (const tag of [candidate, candidate.split("-")[0]]) { + if (!chain.has(tag.toLowerCase())) { + chain.set(tag.toLowerCase(), tag); + } + } + } + return [...chain.values()]; +}; + +// The locale whose text to show from a {locale: text} mapping, "" if it has +// no text. Mirrors reflex_i18n.runtime.pick_translation_locale. +export const pickTranslationLocale = (translations, locale) => { + const available = Object.keys(translations ?? {}).filter( + (key) => String(translations[key] ?? "").trim() !== "", + ); + return matchLocale(fallbackChain(locale), available) ?? available[0] ?? ""; +}; + +const initialLocale = () => { + const fromCookie = readCookie(cookieName); + if (fromCookie && locales.includes(fromCookie)) { + return fromCookie; + } + return ( + matchLocale(navigator.languages ?? [navigator.language], locales) ?? + fallbackLocale + ); +}; + +export const I18nContext = createContext({ + locale: defaultLocale, + catalog: undefined, + setLocale: () => {}, +}); + +// The mounted provider's setter, so a Reflex event (run_script) can switch +// the locale without threading context through the calling component. +let _switchLocale = null; + +export function switchLocale(locale, options) { + if (_switchLocale) { + _switchLocale(locale, options); + } +} + +// Publish a setter as the one `switchLocale` (a Reflex event) drives, without +// clobbering another provider's on unmount. +const usePublishedSetter = (setLocale) => { + useEffect(() => { + _switchLocale = setLocale; + return () => { + if (_switchLocale === setLocale) { + _switchLocale = null; + } + }; + }, [setLocale]); +}; + +// Switch locale by navigating to the current page's address in the target +// locale, keeping the query string and fragment. +const useLocaleNavigate = () => { + const { pathname, search, hash } = useLocation(); + const navigate = useNavigate(); + return useCallback( + (nextLocale, options) => + navigate( + localizePath(delocalizePath(pathname), nextLocale) + search + hash, + options, + ), + [pathname, search, hash, navigate], + ); +}; + +export function I18nProvider({ children, onLocaleChange, serverLocale }) { + const { pathname } = useLocation(); + const navigateLocale = useLocaleNavigate(); + // The compiled event binding (cookie mode only) may change identity between + // renders; reading it through a ref keeps setLocale stable. + const onLocaleChangeRef = useRef(onLocaleChange); + onLocaleChangeRef.current = onLocaleChange; + // Cookie mode starts from the default locale so the server/first render is + // deterministic and never touches document/navigator; the cookie- and + // browser-based locale is resolved client-side in the effect below. + const [cookieLocale, setCookieLocale] = useState(defaultLocale); + // With URL routing the path is authoritative (mirroring the server), so + // the cookie and browser preferences never override what the URL names. + const locale = urlRouting + ? (pathLocale(pathname) ?? defaultLocale) + : cookieLocale; + const [catalog, setCatalog] = useState(undefined); + + useEffect(() => { + if (!urlRouting) { + setCookieLocale(initialLocale()); + } + }, []); + + // Once hydrated, the server's locale wins: it is the one server-side + // translations use, and it follows a locale a backend handler chose (e.g. the + // one saved in a user's profile). + useEffect(() => { + if (!urlRouting && serverLocale && locales.includes(serverLocale)) { + setCookieLocale(serverLocale); + } + }, [serverLocale]); + + useEffect(() => { + let cancelled = false; + loaders[locale]() + .then((module_) => { + if (!cancelled) { + setCatalog(module_); + } + }) + .catch((error) => { + // A failed chunk load (e.g. a stale hashed chunk after a redeploy) + // falls back to the source msgids rather than keeping the previous + // locale's catalog. Surface it instead of an unhandled rejection. + if (!cancelled) { + setCatalog(undefined); + } + console.error( + `Failed to load i18n catalog for locale "${locale}".`, + error, + ); + }); + // With URL routing the routing wrap (on every page) owns /dir. + if (!urlRouting) { + applyDocumentLocale(locale); + } + return () => { + cancelled = true; + }; + }, [locale]); + + const setLocale = useCallback( + (nextLocale, { notifyServer = true } = {}) => { + if (!locales.includes(nextLocale)) { + console.error( + `Invalid locale "${nextLocale}". Supported locales: ${locales.join(", ")}.`, + ); + return; + } + if (urlRouting) { + // The URL owns the locale in this mode: switch by navigating to the + // localized address (the cookie is not consulted). + navigateLocale(nextLocale); + return; + } + // The cookie is the source of truth for a chosen locale; only an + // explicit choice writes it, so browser-preference changes keep + // applying for users who never picked a language. + writeCookie(cookieName, nextLocale); + setCookieLocale(nextLocale); + // Keep the server's locale (server-side translations) in step. A caller + // that already sends I18nState.set_locale itself opts out. + if (notifyServer) { + onLocaleChangeRef.current?.(nextLocale); + } + }, + [navigateLocale], + ); + + usePublishedSetter(setLocale); + + return createElement( + I18nContext.Provider, + { value: { locale, catalog, setLocale } }, + children, + ); +} + +// Cached Intl formatter instances, keyed by locale + serialized options, so a +// list of many formatted values reuses one formatter per (locale, options). +const _numberFormatters = new Map(); +const _dateFormatters = new Map(); +const _languageNames = new Map(); + +// In normal use the key set is small (locales x compile-time option sets), but +// runtime-varying options (a Var in `options=`) could grow it, so cap the cache +// and evict the oldest entry (Map preserves insertion order). +const FORMATTER_CACHE_LIMIT = 100; + +const getFormatter = (cache, Ctor, locale, options) => { + 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); + } + cache.set(key, formatter); + } + return formatter; +}; + +// Turn a value into a Date, normalizing Python's str(date/datetime/time): +// trim microseconds to milliseconds; parse a date-only value as local midnight +// (not UTC, which would shift the day in negative offsets); anchor a bare time +// to the epoch date so Intl can format it (new Date("14:30:00") is invalid). +const toDate = (value) => { + if (value instanceof Date) return value; + if (typeof value === "number") return new Date(value); + const s = String(value).replace(/(\.\d{3})\d+/, "$1"); + if (/^\d{4}-\d{2}-\d{2}$/.test(s)) return new Date(`${s}T00:00:00`); + if (/^\d{2}:\d{2}/.test(s)) return new Date(`1970-01-01T${s}`); + return new Date(s.replace(" ", "T")); +}; + +const LANGUAGE_NAMES = { type: "language", languageDisplay: "standard" }; + +// A language's name in another language ("Portugiesisch (Brasilien)"), or the +// tag itself for one Intl cannot name. +const languageName = (tag, inLocale) => { + try { + return ( + getFormatter( + _languageNames, + Intl.DisplayNames, + inLocale, + LANGUAGE_NAMES, + ).of(tag) ?? tag + ); + } catch { + return tag; + } +}; + +export function useFormat() { + const { locale } = useContext(I18nContext); + // A missing value (or a date that does not parse) formats as empty text, + // rather than as 0 or a thrown RangeError. + const formatNumber = useCallback( + (value, options) => + value == null + ? "" + : getFormatter( + _numberFormatters, + Intl.NumberFormat, + locale, + options, + ).format(value), + [locale], + ); + const formatDate = useCallback( + (value, options) => { + const date = value == null ? undefined : toDate(value); + return date === undefined || Number.isNaN(date.getTime()) + ? "" + : getFormatter( + _dateFormatters, + Intl.DateTimeFormat, + locale, + options, + ).format(date); + }, + [locale], + ); + const formatLanguage = useCallback( + (tag) => languageName(tag, locale), + [locale], + ); + return [formatNumber, formatDate, formatLanguage]; +} + +export function useLocale() { + return useContext(I18nContext).locale; +} + +// [pick, pickLocale] for {locale: text} mappings, defaulting to the active +// locale (for a missing or empty one, as on the server); both return "" when +// the mapping has no text. +export function usePick() { + const { locale: active } = useContext(I18nContext); + const pickLocale = useCallback( + (translations, locale) => + pickTranslationLocale(translations, locale || active), + [active], + ); + const pick = useCallback( + (translations, locale) => { + const key = pickLocale(translations, locale); + return key === "" ? "" : translations[key]; + }, + [pickLocale], + ); + return [pick, pickLocale]; +} + +export function useTranslation() { + const { catalog } = useContext(I18nContext); + + const t_ = useCallback( + (key, params) => { + const message = catalog?.messages.get(key) ?? stripContext(key); + return interpolate(message, params); + }, + [catalog], + ); + + const tp_ = useCallback( + (key, pluralMessage, count, params) => { + const entry = catalog?.messages.get(key); + // Uncataloged messages fall back to the two source strings, picked by + // the DEFAULT locale's plural rule (they are written in that language). + const message = Array.isArray(entry) + ? (entry[catalog.plural(count)] ?? entry[entry.length - 1]) + : defaultPlural(count) === 0 + ? stripContext(key) + : pluralMessage; + return interpolate(message, params); + }, + [catalog], + ); + + return [t_, tp_]; +} + +// URL-based locale routing, opt-in via I18nPlugin(routing=...). + +// The URL-routing locale setter: validate, then navigate to the current page in +// that locale. Independent of the I18nProvider, which an app that uses neither +// rx.t nor a formatting var never pulls in. +const useUrlLocaleSetter = (navigateLocale) => + useCallback( + (nextLocale) => { + if (!locales.includes(nextLocale)) { + console.error( + `Invalid locale "${nextLocale}". Supported locales: ${locales.join(", ")}.`, + ); + return; + } + navigateLocale(nextLocale); + }, + [navigateLocale], + ); + +// Provide a fixed locale + statically-imported catalog to a route's subtree. +// The catalog is a static import (bundled with the route chunk), so the right +// language is present synchronously during prerender. +export function LocaleRoute({ locale, catalog, children }) { + const setLocale = useUrlLocaleSetter(useLocaleNavigate()); + return createElement( + I18nContext.Provider, + { value: { locale, catalog, setLocale } }, + children, + ); +} + +// Path-prefix helpers (mirror reflex_i18n.routing.PathPrefixRouting). + +// The configured locale a path segment names, matched case-insensitively as +// React Router matches paths, in the configured spelling. +const localesBySegment = new Map( + locales.map((locale) => [locale.toLowerCase(), locale]), +); +const segmentLocale = (segment) => localesBySegment.get(segment.toLowerCase()); + +const pathLocale = (pathname) => + segmentLocale(pathname.replace(/^\/+/, "").split("/")[0]); + +// One leading slash: "//host" is a protocol-relative URL off the site. +const sitePath = (path) => "/" + path.replace(/^\/+/, ""); + +const delocalizePath = (pathname) => { + const [head, ...rest] = pathname.replace(/^\/+/, "").split("/"); + return sitePath( + segmentLocale(head) === undefined ? pathname : rest.join("/"), + ); +}; + +const localizePath = (base, locale) => { + if (locale === defaultLocale && defaultAtRoot) { + return base; + } + return base === "/" ? "/" + locale : "/" + locale + base; +}; + +const absoluteUrl = (path) => { + const base = (deployUrl || "").replace(/\/$/, ""); + return base ? base + path : path; +}; + +// React Router paths (useLocation, navigate) are relative to the router +// basename (Reflex's `frontend_path`); raw / hrefs are not, so they +// need the basename prepended. useHref("/") is the basename with a trailing "/". +const useBasename = () => useHref("/").replace(/\/$/, ""); + +// Emit reciprocal + canonical for the current +// route. Rendered as an app-wrap so it applies to every page; React hoists the +// links into and they prerender into the static HTML. +export function HreflangLinks({ children }) { + const { pathname } = useLocation(); + const basename = useBasename(); + const navigateLocale = useLocaleNavigate(); + // This wrap is on every page with URL routing, unlike the provider and + // LocaleRoute (absent from the default locale's unprefixed pages), so it + // publishes the setter rx.i18n.set_locale drives and keeps /dir + // in step with the URL, including on the way back to an unprefixed page. + usePublishedSetter(useUrlLocaleSetter(navigateLocale)); + useEffect( + () => applyDocumentLocale(pathLocale(pathname) ?? defaultLocale), + [pathname], + ); + // When every locale is prefixed (defaultAtRoot off), an unprefixed URL has + // no locale of its own; send it to its default-locale address. + useEffect(() => { + if (!defaultAtRoot && pathLocale(pathname) === undefined) { + navigateLocale(defaultLocale, { replace: true }); + } + }, [pathname, navigateLocale]); + const base = delocalizePath(pathname); + const href = (locale) => absoluteUrl(basename + localizePath(base, locale)); + const links = locales.map((locale) => + createElement("link", { + key: locale, + rel: "alternate", + hrefLang: locale, + href: href(locale), + }), + ); + links.push( + createElement("link", { + key: "x-default", + rel: "alternate", + hrefLang: "x-default", + href: href(defaultLocale), + }), + createElement("link", { + key: "canonical", + rel: "canonical", + // The localized URL for the page's own locale: identical to pathname + // except for an unprefixed page when every locale is prefixed, whose + // canonical is its default-locale address. + href: href(pathLocale(pathname) ?? defaultLocale), + }), + ); + // This is an app-wrap: render the links AND pass the app content through. + return createElement(Fragment, null, ...links, children); +} + +// A language switcher: one per locale, labelled with the language's own name. With URL routing these are real +// links to the current page in each locale, so crawlers follow them and the +// URL stays the source of truth; without it there is only one URL per page, so +// they set the locale through the provider (and cookie) instead. +export function LanguageSwitcher(props) { + const { pathname, search, hash } = useLocation(); + const basename = useBasename(); + const { locale: active, setLocale } = useContext(I18nContext); + const base = delocalizePath(pathname); + // Keep the query string and fragment: switching language must not drop the + // filters or the anchor the visitor is on. The clean canonical URL for each + // locale is emitted by HreflangLinks, so crawlers still see one per page. + const rest = search + hash; + return createElement( + "nav", + props, + ...locales.map((locale) => + createElement( + "a", + { + key: locale, + href: + basename + + (urlRouting ? localizePath(base, locale) : sitePath(pathname)) + + rest, + hrefLang: locale, + // Each language is named in itself, so a visitor finds their own + // whatever the page's language is. + lang: locale, + "aria-current": locale === active ? "true" : undefined, + onClick: urlRouting + ? undefined + : (event) => { + event.preventDefault(); + setLocale(locale); + }, + }, + languageName(locale, locale), + ), + ), + ); +} diff --git a/packages/reflex-i18n/src/reflex_i18n/catalog.py b/packages/reflex-i18n/src/reflex_i18n/catalog.py new file mode 100644 index 00000000000..0565837ba11 --- /dev/null +++ b/packages/reflex-i18n/src/reflex_i18n/catalog.py @@ -0,0 +1,272 @@ +"""Compile ``.po`` catalogs into the per-locale JS modules served to clients.""" + +from __future__ import annotations + +import gettext +import json +import logging +import re +from collections.abc import Sequence +from pathlib import Path +from typing import TYPE_CHECKING + +from .config import LOCALE_COOKIE_NAME, I18nConfig, get_active_catalog_dirs +from .registry import MessageKey, format_message_list + +if TYPE_CHECKING: + from babel.messages.catalog import Catalog, Message + +logger = logging.getLogger(__name__) + +_FALLBACK_PLURAL_EXPR = "n != 1" + +# What gettext accepts but JS reads differently: "/" divides integers only in +# gettext, and a leading zero ("010") is a syntax error in a JS module. +_JS_DIVERGENT_PLURAL_RE = re.compile(r"/|\b0\d") + +_GENERATED_HEADER = "// Generated by Reflex. Do not edit.\n" + + +def _is_portable_plural_expr(expr: str) -> bool: + """Whether gettext and the client's JS evaluate a plural rule alike. + + Args: + expr: The C plural expression from a catalog header. + + Returns: + True if gettext parses the rule and JS reads it the same way. + """ + try: + # gettext admits only n, integers, parentheses and C operators, so a + # rule it parses cannot inject code into the client's JS. + gettext.c2py(expr) + except ValueError: + return False + return _JS_DIVERGENT_PLURAL_RE.search(expr) is None + + +def read_po_catalog(path: Path, locale: str | None = None) -> Catalog: + """Parse a ``.po`` catalog file. + + A plural rule gettext cannot parse, or JS would evaluate differently, is + replaced by the generic one, so the server and the client pick forms by + the same rule. + + Args: + path: The path of the ``.po`` file. + locale: The catalog's locale, supplying CLDR plural rules for a file + whose header declares none. + + Returns: + The parsed catalog. + """ + from babel.messages.pofile import read_po + + with path.open("r", encoding="utf-8") as po_file: + try: + catalog = read_po(po_file, locale=locale and locale.replace("-", "_")) + except ValueError: + # A tag Babel has no CLDR data for; the catalog's own header (or + # the generic rule) decides the plural forms. read_po builds the + # Catalog before reading, so nothing was consumed. + catalog = read_po(po_file) + expr = catalog.plural_expr + if not _is_portable_plural_expr(expr): + logger.warning( + f"Ignoring unsupported Plural-Forms expression {expr!r} in {path}; " + f"falling back to {_FALLBACK_PLURAL_EXPR!r}." + ) + catalog.mime_headers = [ + ("Plural-Forms", f"nplurals=2; plural={_FALLBACK_PLURAL_EXPR};") + ] + return catalog + + +def is_translated(message: Message) -> bool: + """Whether a catalog entry carries a usable translation. + + Args: + message: The catalog entry. + + Returns: + False for a fuzzy (stale) entry or one with an empty (plural) form. + """ + if message.fuzzy: + return False + strings = message.string + if isinstance(strings, str): + return bool(strings) + return bool(strings) and all(strings) + + +def load_catalog(locale: str) -> Catalog | None: + """Read a locale's catalogs: the app's, completed by its catalog packages'. + + The app's translation of a message wins; a package's fills in where the app + has none (or only a fuzzy or partial one). + + Args: + locale: The locale whose catalogs to read. + + Returns: + The merged catalog, or None if no catalog directory has the locale. + """ + merged: Catalog | None = None + for catalog_dir in get_active_catalog_dirs(): + path = catalog_dir / f"{locale}.po" + if not path.exists(): + continue + catalog = read_po_catalog(path, locale) + if merged is None: + merged = catalog + continue + for message in catalog: + if not message.id or not is_translated(message): + continue + current = merged.get(message.id, message.context) + if current is not None: + if is_translated(current): + continue + # Assigning onto an existing entry would keep its empty string. + merged.delete(message.id, message.context) + merged[message.id] = message + return merged + + +def compile_catalog_module( + catalog: Catalog | None, + used_messages: Sequence[MessageKey], + locale: str, + *, + is_default_locale: bool, +) -> str: + """Render the JS catalog module for one locale (used messages only). + + Args: + catalog: The catalog from :func:`read_po_catalog`, whose plural rule + is embedded as is, or None if the locale has none. + used_messages: All messages collected from ``rx.t`` calls. + locale: The locale being compiled, for warnings. + is_default_locale: If True, missing translations are not warned about. + + Returns: + The JS module source code. + """ + entries: list[str] = [] + missing: list[MessageKey] = [] + for key in used_messages: + translation = _lookup_translation(catalog, key) + if translation is None: + missing.append(key) + continue + entries.append(f" [{json.dumps(key.catalog_key)}, {json.dumps(translation)}],") + if missing and not is_default_locale: + logger.warning( + f"{len(missing)} translation(s) missing for locale {locale!r} " + f"(falling back to the default locale):\n{format_message_list(missing)}" + ) + messages_body = "\n".join(entries) + plural = catalog.plural_expr if catalog is not None else _FALLBACK_PLURAL_EXPR + # A Map, not an object literal: a message named like a prototype member + # ("constructor", "__proto__") must miss rather than resolve to one. + return ( + f"{_GENERATED_HEADER}" + f"export const plural = (n) => Number({plural});\n" + f"export const messages = new Map([\n{messages_body}\n]);\n" + ) + + +def _lookup_translation( + catalog: Catalog | None, key: MessageKey +) -> str | list[str] | None: + """Find the translation for a message in a catalog. + + Args: + catalog: The parsed catalog, or None. + key: The message to look up. + + Returns: + The translated string, a list of plural forms, or None if the message + is untranslated (including partially translated plurals). + """ + if catalog is None: + return None + message = catalog.get(key.msgid, key.context) + # A fuzzy entry carries a stale translation; fall back to the source text + # (the server side already excludes fuzzy via write_mo). + if message is None or not is_translated(message): + return None + strings = message.string + if key.plural is None: + return strings if isinstance(strings, str) else None + if isinstance(strings, str): + return [strings] + return list(strings) if strings else None + + +def default_plural_expr_js(catalog: Catalog | None, locale: str) -> str: + """The default locale's plural expression for the client-side fallback. + + Args: + catalog: The default locale's catalog from :func:`read_po_catalog`, + if one exists. + locale: The default locale. + + Returns: + A validated JS plural expression over the variable ``n``. + """ + if catalog is None: + from babel.messages.catalog import Catalog as BabelCatalog + + try: + # Babel's built-in CLDR plural table for the locale. + catalog = BabelCatalog(locale=locale.replace("-", "_")) + except ValueError: + return _FALLBACK_PLURAL_EXPR + return catalog.plural_expr + + +def compile_index_module( + config: I18nConfig, + *, + url_routing: bool = False, + default_at_root: bool = True, + deploy_url: str = "", + default_plural_expr: str = _FALLBACK_PLURAL_EXPR, +) -> str: + """Render the JS module describing the app's locales and catalog loaders. + + The static ``import()`` map lets the bundler code-split one chunk per + locale, so clients only ever download the active language. + + Args: + config: The app's i18n configuration. + url_routing: Whether URL-based locale routing is enabled (so the client + knows the locale comes from the URL, not the cookie). + default_at_root: Whether URL routing serves the default locale at the + unprefixed path (used by the hreflang helper). + deploy_url: Absolute site URL for building absolute hreflang hrefs, or + empty to emit relative hrefs. + default_plural_expr: The default locale's plural expression, used + client-side to pick between the two source strings of a plural + message that has no catalog entry. + + Returns: + The JS module source code. + """ + loaders = "\n".join( + f" {json.dumps(locale)}: () => import({json.dumps(f'$/i18n/{locale}.js')})," + for locale in config.locales + ) + return ( + f"{_GENERATED_HEADER}" + f"export const locales = {json.dumps(list(config.locales))};\n" + f"export const defaultLocale = {json.dumps(config.default_locale)};\n" + f"export const fallbackLocale = {json.dumps(config.fallback_locale)};\n" + f"export const cookieName = {json.dumps(LOCALE_COOKIE_NAME)};\n" + f"export const urlRouting = {json.dumps(url_routing)};\n" + f"export const defaultAtRoot = {json.dumps(default_at_root)};\n" + f"export const deployUrl = {json.dumps(deploy_url)};\n" + f"export const defaultPlural = (n) => Number({default_plural_expr});\n" + f"export const loaders = {{\n{loaders}\n}};\n" + ) diff --git a/packages/reflex-i18n/src/reflex_i18n/cli.py b/packages/reflex-i18n/src/reflex_i18n/cli.py new file mode 100644 index 00000000000..272418d0048 --- /dev/null +++ b/packages/reflex-i18n/src/reflex_i18n/cli.py @@ -0,0 +1,586 @@ +"""The ``reflex i18n`` command group: extract, init, and check catalogs. + +Registered lazily as ``reflex i18n`` by ``reflex.reflex`` when this package is +installed. +""" + +from __future__ import annotations + +import ast +import dataclasses +import logging +import os +import sys +from collections.abc import Collection, Iterator, Sequence +from pathlib import Path +from typing import IO, TYPE_CHECKING + +import click +from reflex_base.config import get_config +from reflex_base.plugins.base import get_plugin +from reflex_base.utils import log + +from .config import PACKAGE_CATALOG_DIR, find_package_dir, validate_locale +from .plugin import I18nPlugin +from .registry import MessageKey, collected_messages + +if TYPE_CHECKING: + from babel.messages.catalog import Catalog + from babel.messages.extract import _ExtractionResult, _PyOptions + +logger = logging.getLogger(__name__) + +# An rx.t call as Babel extraction methods report one: line, keyword, messages, +# comments. +_TCall = tuple[int, str, tuple[str, ...], list[str]] + +# Call names extracted for server-side (dynamic) translation, and the markers +# for text translated later. Matched syntactically by Babel, so the +# conventional ``gettext as _`` and ``gettext_noop as N_`` aliases work. +_GETTEXT_KEYWORDS = { + "_": None, + "N_": None, + "gettext": None, + "gettext_noop": None, + "ngettext": (1, 2), + "pgettext": ((1, "c"), 2), +} + +# Babel keyword specs for the literal rx.t calls _extract_python reports, under +# names no real call has. The context variant passes the context first, as +# pgettext does. +_T_KEYWORD = "rx.t" +_T_CONTEXT_KEYWORD = "rx.t(context)" +_KEYWORDS = { + **_GETTEXT_KEYWORDS, + _T_KEYWORD: {1: (1,), 2: (1, 2)}, + _T_CONTEXT_KEYWORD: {2: ((1, "c"), 2), 3: ((1, "c"), 2, 3)}, +} + +# The attribute paths rx.t is reachable under from each module that exposes it. +_T_PATHS = { + "reflex": ("t", "i18n.t"), + "reflex.i18n": ("t",), + "reflex_i18n": ("t", "vars.t"), + "reflex_i18n.vars": ("t",), +} + +_POT_FILENAME = "messages.pot" + +_PACKAGE_OPTION = click.option( + "--package", + default=None, + help=( + "Manage the catalogs an installed package ships in its " + f"{PACKAGE_CATALOG_DIR}/ directory instead of the app's." + ), +) + + +@dataclasses.dataclass +class LocaleStats: + """Per-locale translation completeness, for reporting and ``check``.""" + + locale: str + missing: int = 0 + fuzzy: int = 0 + obsolete: int = 0 + + @property + def incomplete(self) -> bool: + """Whether the locale has untranslated or fuzzy messages. + + Returns: + True if any message is missing or fuzzy. + """ + return bool(self.missing or self.fuzzy) + + +def _resolve_plugin() -> I18nPlugin: + """Find the active I18nPlugin in the loaded config. + + Returns: + The configured plugin. + + Raises: + click.ClickException: If no I18nPlugin is configured. + """ + plugin = get_plugin(I18nPlugin) + if plugin is None: + msg = ( + "No I18nPlugin configured. Add I18nPlugin(locales=[...]) to " + "rx.Config(plugins=[...]) in rxconfig.py." + ) + raise click.ClickException(msg) + return plugin + + +def _extract_template() -> tuple[I18nPlugin, Catalog, Path]: + """Dry-compile the app and extract every message into a template catalog. + + Returns: + The plugin, the extracted template, and the catalog directory. + """ + from reflex.utils import prerequisites + + prerequisites.get_compiled_app(dry_run=True, use_rich=False) + plugin = _resolve_plugin() + template = extract_catalog( + _app_source_dir(), + collected_messages(), + [_package_dir(package) for package in plugin.catalog_packages], + ) + return plugin, template, Path.cwd() / plugin.catalog_dir + + +def _package_dir(package: str) -> Path: + """Locate an installed package for the CLI. + + Args: + package: The importable package name. + + Returns: + The package directory. + + Raises: + click.ClickException: If the package is not installed. + """ + try: + return find_package_dir(package) + except ValueError as exc: + raise click.ClickException(str(exc)) from exc + + +def _dotted_name(node: ast.expr) -> str | None: + """The dotted name a call target spells, e.g. ``rx.i18n.t``. + + Args: + node: The call's ``func`` expression. + + Returns: + The dotted name, or None if it is not a plain (attribute) name. + """ + parts: list[str] = [] + while isinstance(node, ast.Attribute): + parts.append(node.attr) + node = node.value + if not isinstance(node, ast.Name): + return None + parts.append(node.id) + return ".".join(reversed(parts)) + + +def _t_call_names(tree: ast.Module) -> set[str]: + """The dotted names rx.t is reachable under in a module, from its imports. + + Args: + tree: The parsed module. + + Returns: + The names a call to rx.t is spelled as, e.g. ``{"rx.t", "rx.i18n.t"}``. + """ + names: set[str] = set() + for node in ast.walk(tree): + if isinstance(node, ast.Import): + for alias in node.names: + # `import a.b as x` binds the submodule; `import a.b` binds `a`. + module = alias.name if alias.asname else alias.name.split(".")[0] + bound = alias.asname or module + names.update(f"{bound}.{path}" for path in _T_PATHS.get(module, ())) + elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module: + for alias in node.names: + bound = alias.asname or alias.name + if alias.name == "t" and node.module in _T_PATHS: + names.add(bound) + else: + paths = _T_PATHS.get(f"{node.module}.{alias.name}", ()) + names.update(f"{bound}.{path}" for path in paths) + return names + + +def _string_literal(node: ast.expr) -> str | None: + """The value of a string literal. + + Args: + node: The expression. + + Returns: + The string, or None if the expression is not a string literal. + """ + if isinstance(node, ast.Constant) and isinstance(node.value, str): + return node.value + return None + + +def _t_calls(tree: ast.Module) -> Iterator[_TCall]: + """Find the rx.t calls whose message, plural and context are literals. + + Args: + tree: The parsed module. + + Yields: + Babel extraction results, in source order. + """ + names = _t_call_names(tree) + if not names: + return + calls = sorted( + ( + node + for node in ast.walk(tree) + if isinstance(node, ast.Call) and _dotted_name(node.func) in names + ), + key=lambda call: (call.lineno, call.col_offset), + ) + for call in calls: + message = _string_literal(call.args[0]) if call.args else None + if message is None: + continue + options = { + keyword.arg: _string_literal(keyword.value) + for keyword in call.keywords + if keyword.arg in ("plural", "context") + } + if None in options.values(): + # A computed plural or context cannot be extracted reliably. + continue + plural = options.get("plural") + forms = (message,) if plural is None else (message, plural) + if context := options.get("context"): + yield call.lineno, _T_CONTEXT_KEYWORD, (context, *forms), [] + else: + yield call.lineno, _T_KEYWORD, forms, [] + + +def _extract_python( + fileobj: IO[bytes], + keywords: Collection[str], + comment_tags: Collection[str], + options: _PyOptions, +) -> Iterator[_ExtractionResult | _TCall]: + """Babel extraction method: gettext-family calls plus literal rx.t calls. + + Args: + fileobj: The source file. + keywords: The gettext-family call names to extract. + comment_tags: Comment tags to collect as translator comments. + options: Babel extraction options. + + Yields: + Babel extraction results. + """ + from babel.messages.extract import extract_python + + # Babel hands a method the keyword names only; the specs apply afterwards. + yield from extract_python(fileobj, dict.fromkeys(keywords), comment_tags, options) + fileobj.seek(0) + try: + tree = ast.parse(fileobj.read()) + except (SyntaxError, ValueError): + # Babel tokenizes what it can; a module Python cannot parse has no + # rx.t calls to add. + return + yield from _t_calls(tree) + + +def scan_sources(source_dir: Path) -> Catalog: + """Extract the messages marked in a source tree: gettext, N_ and rx.t calls. + + Args: + source_dir: The directory to scan. Source locations are recorded + relative to the working directory, the project root. + + Returns: + A catalog holding every message found (untranslated template). + """ + from babel.messages.catalog import Catalog + from babel.messages.extract import extract_from_dir + + catalog = Catalog() + try: + location_root = Path(os.path.relpath(source_dir)) + except ValueError: + # On Windows a directory on another drive than the project (a temp + # dir, an installed package) has no relative path. + location_root = source_dir + for filename, lineno, message, _comments, context in extract_from_dir( + source_dir, + method_map=[("**.py", f"{__name__}:{_extract_python.__name__}")], + keywords=_KEYWORDS, + ): + catalog.add( + message, + locations=[((location_root / filename).as_posix(), lineno)], + context=context, + ) + return catalog + + +def extract_catalog( + app_dir: Path, + used_messages: tuple[MessageKey, ...], + package_dirs: Sequence[Path] = (), +) -> Catalog: + """Build the app's message template from its sources and its rx.t registry. + + Args: + app_dir: The app source directory to scan. + used_messages: Static ``rx.t`` messages from the compile registry, + including computed ones the source scan cannot see. + package_dirs: Catalog packages' directories; the messages they mark + are translated by the packages' own catalogs, not the app's. + + Returns: + A catalog holding every message the app translates (untranslated + template). + """ + catalog = scan_sources(app_dir) + for key in used_messages: + catalog.add(key.msgid, context=key.context) + for package_dir in package_dirs: + for message in scan_sources(package_dir): + if message.id: + catalog.delete(message.id, message.context) + return catalog + + +def _read_or_new_catalog(po_path: Path, locale: str) -> Catalog: + """Read an existing ``.po`` file or create an empty catalog for a locale. + + Args: + po_path: The path of the ``.po`` file. + locale: The locale identifier. + + Returns: + The loaded or newly created catalog. + """ + from babel.messages.catalog import Catalog + from babel.messages.pofile import read_po + + # Babel parses only the underscore form of a hyphenated tag (pt-BR). + babel_locale = locale.replace("-", "_") + if po_path.exists(): + with po_path.open("rb") as f: + return read_po(f, locale=babel_locale) + return Catalog(locale=babel_locale) + + +def _write_catalog(catalog: Catalog, path: Path) -> None: + """Write a catalog to a ``.po``/``.pot`` file. + + Args: + catalog: The catalog to write. + path: The destination path. + """ + from babel.messages.pofile import write_po + + path.parent.mkdir(parents=True, exist_ok=True) + with path.open("wb") as f: + write_po(f, catalog, omit_header=False) + + +def merge_into_locale(template: Catalog, po_path: Path, locale: str) -> LocaleStats: + """Merge the template into a locale catalog, preserving translations. + + Args: + template: The freshly extracted message template. + po_path: The locale's ``.po`` file path. + locale: The locale identifier. + + Returns: + Stats describing the merged catalog. + """ + catalog = _read_or_new_catalog(po_path, locale) + catalog.update(template) + _write_catalog(catalog, po_path) + return _catalog_stats(catalog, locale) + + +def _catalog_stats(catalog: Catalog, locale: str) -> LocaleStats: + """Count untranslated, fuzzy, and obsolete messages in a catalog. + + Args: + catalog: The catalog to inspect. + locale: The locale identifier. + + Returns: + The computed stats. + """ + stats = LocaleStats(locale=locale, obsolete=len(catalog.obsolete)) + for message in catalog: + if not message.id: # the header entry + continue + if "fuzzy" in message.flags: + stats.fuzzy += 1 + elif not message.string or ( + isinstance(message.string, (list, tuple)) and not all(message.string) + ): + stats.missing += 1 + return stats + + +def _report(stats: LocaleStats, *, is_source: bool = False) -> None: + """Print a one-line summary for a locale. + + Args: + stats: The locale stats to report. + is_source: Whether this is the default locale, whose catalog holds the + source text and is expected to have empty ``msgstr`` entries. + """ + detail = f"{stats.missing} missing, {stats.fuzzy} fuzzy, {stats.obsolete} obsolete" + if is_source: + logger.info(f" {stats.locale}: source catalog ({stats.obsolete} obsolete)") + elif stats.incomplete: + logger.warning(f" {stats.locale}: {detail}") + else: + logger.log( + log.SUCCESS, f" {stats.locale}: complete ({stats.obsolete} obsolete)" + ) + + +def _app_source_dir() -> Path: + """The app's Python source directory. + + Resolved from the imported app module (the dry compile imported it), so + ``app_module_import`` and src layouts scan the real package; falls back to + ``/`` when the module cannot be found. + + Returns: + The directory scanned for gettext calls. + """ + config = get_config() + top_module = sys.modules.get(config.module.partition(".")[0]) + pkg_paths = getattr(top_module, "__path__", None) + if pkg_paths: + return Path(next(iter(pkg_paths))) + module_file = getattr(top_module, "__file__", None) + if module_file: + return Path(module_file).parent + return Path.cwd() / config.app_name + + +def _managed_catalogs( + package: str | None, +) -> tuple[Catalog, Path, tuple[str, ...], str | None]: + """The catalogs a command manages: the app's, or a package's own. + + Args: + package: The package whose catalogs to manage, or None for the app's. + + Returns: + The message template, the catalog directory, the locales it holds + catalogs for, and the source locale (the app's default; a package has + no source catalog). + + Raises: + click.ClickException: If a package catalog is not named after a locale. + """ + if package is None: + plugin, template, catalog_dir = _extract_template() + return template, catalog_dir, tuple(plugin.locales), plugin.default_locale + package_dir = _package_dir(package) + catalog_dir = package_dir / PACKAGE_CATALOG_DIR + locales = tuple(sorted(path.stem for path in catalog_dir.glob("*.po"))) + for locale in locales: + try: + validate_locale(locale) + except ValueError as exc: + raise click.ClickException(str(exc)) from exc + return scan_sources(package_dir), catalog_dir, locales, None + + +@click.group() +def i18n_cli(): + """Manage translation catalogs for the app.""" + + +@i18n_cli.command(name="extract") +@_PACKAGE_OPTION +def extract_command(package: str | None): + """Extract messages and update every locale's ``.po`` catalog. + + Args: + package: The package whose catalogs to update, or None for the app's. + """ + template, catalog_dir, locales, source_locale = _managed_catalogs(package) + + _write_catalog(template, catalog_dir / _POT_FILENAME) + logger.info(f"Extracted {len(template)} messages.") + if not locales: + logger.info( + f"No catalogs yet: create one with `reflex i18n init " + f"--package {package}`." + ) + return + for locale in locales: + _report( + merge_into_locale(template, catalog_dir / f"{locale}.po", locale), + is_source=locale == source_locale, + ) + logger.log(log.SUCCESS, "Catalogs updated.") + + +@i18n_cli.command(name="init") +@click.argument("locale") +@_PACKAGE_OPTION +def init_command(locale: str, package: str | None): + """Create a new ``.po`` catalog for LOCALE. + + Args: + locale: The locale to initialize (e.g. ``de``). + package: The package to create the catalog in, or None for the app. + + Raises: + ClickException: If the locale is not a language tag, or the catalog + already exists. + """ + try: + validate_locale(locale) + except ValueError as exc: + raise click.ClickException(str(exc)) from exc + template, catalog_dir, locales, _ = _managed_catalogs(package) + po_path = catalog_dir / f"{locale}.po" + if po_path.exists(): + msg = f"Catalog already exists: {po_path}. Use `reflex i18n extract`." + raise click.ClickException(msg) + + stats = merge_into_locale(template, po_path, locale) + logger.log( + log.SUCCESS, f"Created {po_path} with {stats.missing} messages to translate." + ) + if package is None and locale not in locales: + logger.info( + f"Add {locale!r} to I18nPlugin(locales=[...]) in rxconfig.py to ship it." + ) + + +@i18n_cli.command(name="check") +@_PACKAGE_OPTION +def check_command(package: str | None): + """Fail if any non-default locale has untranslated or fuzzy messages. + + Args: + package: The package whose catalogs to check, or None for the app's. + + Raises: + ClickException: If a catalog is incomplete, or the package ships none. + """ + template, catalog_dir, locales, source_locale = _managed_catalogs(package) + if not locales: + msg = f"{package!r} ships no catalogs in {catalog_dir}." + raise click.ClickException(msg) + + incomplete = False + for locale in locales: + if locale == source_locale: + continue + catalog = _read_or_new_catalog(catalog_dir / f"{locale}.po", locale) + catalog.update(template) + stats = _catalog_stats(catalog, locale) + _report(stats) + incomplete = incomplete or stats.incomplete + + if incomplete: + msg = "Some locales have untranslated or fuzzy messages." + raise click.ClickException(msg) + logger.log(log.SUCCESS, "All locales are complete.") diff --git a/packages/reflex-i18n/src/reflex_i18n/component.py b/packages/reflex-i18n/src/reflex_i18n/component.py new file mode 100644 index 00000000000..5078b4e4acc --- /dev/null +++ b/packages/reflex-i18n/src/reflex_i18n/component.py @@ -0,0 +1,119 @@ +"""The client components backing i18n (provider, per-route locale, hreflang).""" + +from __future__ import annotations + +import functools +from typing import Any + +from reflex_base.components.component import Component +from reflex_base.constants import CompileVars +from reflex_base.event import EventHandler, passthrough_event_spec +from reflex_base.plugins.base import get_plugin +from reflex_base.vars.base import LiteralVar, Var +from reflex_base.vars.number import ternary_operation + +# Outside the ErrorBoundary (55) so error fallback UI can translate too. +_PROVIDER_PRIORITY = 58 + + +class I18nProvider(Component): + """Provides the active locale and message catalog via React context. + + Implemented in the static web template ``utils/i18n.js``; pulled into the + app shell automatically (via ``VarData.app_wraps``) whenever ``rx.t`` is + used. + """ + + library = "$/utils/i18n" + + tag = "I18nProvider" + + # Fires with the locale a user picks through the provider (cookie mode only). + on_locale_change: EventHandler[passthrough_event_spec(str)] + + # The locale the server resolved for this client, empty until the page has + # hydrated (cookie mode only). The provider switches to it, so static text + # follows whatever the server translates in. + server_locale: Var[str] + + +@functools.cache +def _provider() -> I18nProvider: + """The provider app wrap shared by every feature that needs it. + + In cookie mode it reports a client-side switch to ``I18nState`` so the + server's locale follows, and follows a locale the server chose itself; the + URL owns the locale otherwise. + + Returns: + The provider for the configured plugin. + """ + # Inline: the plugin module imports this one, and the state module + # registers I18nState on import. + from .plugin import I18nPlugin + + plugin = get_plugin(I18nPlugin) + if plugin is None or plugin.routing is not None: + return I18nProvider.create() + + from reflex.state import State + + from .state import I18nState + + return I18nProvider.create( + on_locale_change=I18nState.set_locale, + # The compiled initial state carries a placeholder until hydration. + server_locale=ternary_operation( + State.vars[CompileVars.IS_HYDRATED], I18nState.locale, LiteralVar.create("") + ), + ) + + +class LocaleRoute(Component): + """Wraps a per-locale route with a fixed locale + static catalog. + + The static catalog import makes the language available synchronously during + prerender (unlike the provider's default dynamic import). + """ + + library = "$/utils/i18n" + + tag = "LocaleRoute" + + # The locale this route renders in. + locale: Var[str] + + # The statically-imported catalog module for ``locale``. + catalog: Var[Any] + + +class HreflangLinks(Component): + """App-wrap emitting ``hreflang`` alternates + canonical for the route. + + Reads the current path and its config from ``$/i18n/index.js`` (no props). + When every locale is prefixed, it also redirects an unprefixed URL to its + default-locale address. + """ + + library = "$/utils/i18n" + + tag = "HreflangLinks" + + +class LanguageSwitcher(Component): + """A language switcher: one ```` per locale (crawlable with URL routing).""" + + library = "$/utils/i18n" + + tag = "LanguageSwitcher" + + @staticmethod + def _get_app_wrap_components() -> dict[tuple[int, str], Component]: + """Pull in the provider so the switcher can read and set the locale. + + Returns: + The provider app wrap. + """ + # A page may use the switcher without any rx.t or rx.i18n formatting + # var, neither of which would then drag the provider in. + return {(_PROVIDER_PRIORITY, "I18nProvider"): _provider()} diff --git a/packages/reflex-i18n/src/reflex_i18n/config.py b/packages/reflex-i18n/src/reflex_i18n/config.py new file mode 100644 index 00000000000..4bbec047f26 --- /dev/null +++ b/packages/reflex-i18n/src/reflex_i18n/config.py @@ -0,0 +1,301 @@ +"""App-level i18n configuration.""" + +from __future__ import annotations + +import dataclasses +import importlib.util +import re +from collections.abc import Sequence +from pathlib import Path + +# Cookie persisting the user's chosen locale; read by both the client +# runtime and the server-side locale resolution. +LOCALE_COOKIE_NAME = "reflex_locale" + +# The locale an app without an I18nPlugin renders and formats in, server-side +# and client-side alike. +UNCONFIGURED_LOCALE = "en" + +# The directory inside a package holding the catalogs it ships. +PACKAGE_CATALOG_DIR = "locales" + +# A BCP 47-shaped tag: alphabetic language, optional alphanumeric subtags. +# Locales double as URL path segments, JS catalog identifiers and `Intl` / +# `Accept-Language` tags, all of which are hyphen-separated, so the underscore +# spelling is rejected rather than normalized in each of those places. Babel's +# underscore form is derived internally where it is needed. +_LOCALE_RE = re.compile(r"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$") + + +def validate_locale(locale: str) -> None: + """Check that a locale is a usable language tag. + + Args: + locale: The locale to check. + + Raises: + ValueError: If the locale is not a hyphen-separated language tag. + """ + if not _LOCALE_RE.fullmatch(locale): + msg = ( + f"Invalid locale {locale!r}: expected a hyphen-separated language " + "tag such as 'en', 'pt-BR' or 'zh-Hant'." + ) + raise ValueError(msg) + + +@dataclasses.dataclass(frozen=True) +class I18nConfig: + """Internationalization configuration held by :class:`I18nPlugin`.""" + + # Locales the app supports, e.g. ("en", "de"). Order is preserved for + # Accept-Language negotiation ties. + locales: tuple[str, ...] + + # The locale the source-text msgids are written in. + default_locale: str = "en" + + # Directory (relative to the app root) containing {locale}.po catalogs. + catalog_dir: str = "locales" + + # The locale for a visitor whose browser asks for none of the configured + # ones (Accept-Language negotiation); the default locale unless set. + fallback_locale: str = "en" + + # Installed packages whose own catalogs (/locales/{locale}.po) + # translate their messages; the app's catalogs take precedence. + catalog_packages: tuple[str, ...] = () + + def __init__( + self, + locales: Sequence[str], + default_locale: str = "en", + catalog_dir: str = "locales", + fallback_locale: str | None = None, + catalog_packages: Sequence[str] = (), + ): + """Initialize and validate the i18n configuration. + + Args: + locales: Locales the app supports, e.g. ``["en", "de"]``. + default_locale: The locale the source-text msgids are written in. + catalog_dir: Directory (relative to the app root) containing + ``{locale}.po`` catalogs. + fallback_locale: The locale for a visitor whose browser asks for + none of the configured ones. Defaults to ``default_locale``. + catalog_packages: Installed packages whose own catalogs + (``/locales/{locale}.po``) translate their messages. + + Raises: + ValueError: If no locales are given, a locale is repeated in any + case, a locale is not a language tag, or the default or fallback + locale is not among them. + """ + locales_tuple = tuple(locales) + if not locales_tuple: + msg = "I18nConfig.locales must contain at least one locale." + raise ValueError(msg) + if len({locale.lower() for locale in locales_tuple}) != len(locales_tuple): + # Tags are case-insensitive, like the router and catalog lookups, so + # "en" and "EN" would claim one route and catalog module twice. + msg = ( + "I18nConfig.locales must not repeat a locale (tags are " + f"case-insensitive): {locales_tuple!r}." + ) + raise ValueError(msg) + for locale in locales_tuple: + validate_locale(locale) + if fallback_locale is None: + fallback_locale = default_locale + for name, locale in ( + ("default_locale", default_locale), + ("fallback_locale", fallback_locale), + ): + if locale not in locales_tuple: + msg = ( + f"I18nConfig.{name} {locale!r} must be one of the " + f"configured locales {locales_tuple!r}." + ) + raise ValueError(msg) + object.__setattr__(self, "locales", locales_tuple) + object.__setattr__(self, "default_locale", default_locale) + object.__setattr__(self, "catalog_dir", catalog_dir) + object.__setattr__(self, "fallback_locale", fallback_locale) + object.__setattr__(self, "catalog_packages", tuple(catalog_packages)) + + +def find_package_dir(package: str) -> Path: + """Locate an installed package's directory, importing only its parents. + + Args: + package: The importable package name, e.g. ``"my_lib"`` or + ``"my_lib.ui"``. + + Returns: + The absolute package directory. + + Raises: + ValueError: If no package of that name is installed. + """ + msg = f"Cannot find the package {package!r}: it is not installed." + try: + # A dotted name imports its parent, which raises if that is missing. + spec = importlib.util.find_spec(package) + except ModuleNotFoundError as exc: + raise ValueError(msg) from exc + if spec is None or not spec.submodule_search_locations: + raise ValueError(msg) + return Path(next(iter(spec.submodule_search_locations))).resolve() + + +_active_config: I18nConfig | None = None + +# Absolute catalog directories, captured when the app is constructed (cwd is +# the app root then): the app's first, then each catalog package's. Used at +# compile and request time so catalog loading does not depend on the process +# cwd, which is not guaranteed to be the app root later. +_active_catalog_dirs: tuple[Path, ...] = () + + +def set_active_i18n_config(config: I18nConfig | None) -> None: + """Set the i18n configuration of the running app. + + Called by ``rx.App`` so server-side translation helpers can resolve + locales without a reference to the app instance. Must be called while the + current working directory is the app root (it is during app construction). + + Args: + config: The configuration to activate, or None to deactivate. + """ + # Inline to avoid a circular import; runtime imports from this module. + from .runtime import clear_translations_cache + + global _active_config, _active_catalog_dirs + catalog_dirs = ( + ( + (Path.cwd() / config.catalog_dir).resolve(), + *( + find_package_dir(package) / PACKAGE_CATALOG_DIR + for package in config.catalog_packages + ), + ) + if config is not None + else () + ) + _active_config = config + _active_catalog_dirs = catalog_dirs + # Drop translators built from the previous catalog dir (or from catalogs + # edited before a dev hot reload re-activated the config). + clear_translations_cache() + + +def get_active_i18n_config() -> I18nConfig | None: + """Get the i18n configuration of the running app. + + Returns: + The active configuration, or None if the app has no i18n config. + """ + return _active_config + + +def _subtag_case(subtag: str) -> str: + """The conventional case of a non-initial subtag (RFC 5646 section 2.1.1). + + Args: + subtag: A subtag after the language, e.g. ``"hant"`` or ``"br"``. + + Returns: + Title case for a script, upper case for a region, else lower case. + """ + if len(subtag) == 4 and subtag.isalpha(): + return subtag.title() + if (len(subtag) == 2 and subtag.isalpha()) or ( + len(subtag) == 3 and subtag.isdigit() + ): + return subtag.upper() + return subtag.lower() + + +def normalize_locale(locale: str) -> str: + """Spell a language tag canonically. + + A tag naming a configured locale (tags are case-insensitive) takes the + configured spelling; any other tag its conventional case. + + Args: + locale: The tag to normalize, e.g. ``"PT-br"``. + + Returns: + The canonical spelling, e.g. ``"pt-BR"``. + + Raises: + ValueError: If the locale is not a hyphen-separated language tag. + """ + validate_locale(locale) + return spell_locale(locale) + + +def spell_locale(locale: str) -> str: + """Spell a language tag canonically, like :func:`normalize_locale`, unvalidated. + + Args: + locale: The tag to spell. + + Returns: + The configured spelling, else the conventional case. + """ + lowered = locale.lower() + if _active_config is not None: + for configured in _active_config.locales: + if configured.lower() == lowered: + return configured + language, *subtags = lowered.split("-") + cased = [language] + # From a singleton on (an extension such as "u-ca-gregory" or private use + # "x-..."), subtags are not scripts or regions and stay lowercase. + in_extension = False + for subtag in subtags: + in_extension = in_extension or len(subtag) == 1 + cased.append(subtag if in_extension else _subtag_case(subtag)) + return "-".join(cased) + + +def source_locale() -> str: + """The language the app's source text is written in. + + Returns: + The configured default locale, or ``UNCONFIGURED_LOCALE`` without an + I18nPlugin. + """ + if _active_config is None: + return UNCONFIGURED_LOCALE + return _active_config.default_locale + + +def check_configured_locale(locale: str) -> None: + """Check that a locale is one of the running app's configured locales. + + Args: + locale: The locale to check. + + Raises: + ValueError: If i18n is configured and the locale is not among its + locales. + """ + config = _active_config + if config is not None and locale not in config.locales: + msg = ( + f"Locale {locale!r} is not configured. Configured locales: " + f"{list(config.locales)}." + ) + raise ValueError(msg) + + +def get_active_catalog_dirs() -> tuple[Path, ...]: + """Get the absolute catalog directories of the running app, by precedence. + + Returns: + The app's catalog directory, then each catalog package's; empty if i18n + is not configured. + """ + return _active_catalog_dirs diff --git a/packages/reflex-i18n/src/reflex_i18n/format.py b/packages/reflex-i18n/src/reflex_i18n/format.py new file mode 100644 index 00000000000..18c029e3c87 --- /dev/null +++ b/packages/reflex-i18n/src/reflex_i18n/format.py @@ -0,0 +1,460 @@ +"""Client-side, locale-aware number and date formatting vars. + +``rx.i18n.number`` / ``rx.i18n.currency`` / ``rx.i18n.date`` (and friends) +format a value in the active locale using the browser's ``Intl`` API, +reactively reformatting when the locale changes. To format inside state +(server-side), use the ``format_*`` helpers in :mod:`reflex_i18n.runtime`. +""" + +from __future__ import annotations + +import functools +from collections.abc import Mapping +from typing import TYPE_CHECKING, Any + +from reflex_base.utils.imports import ImportVar +from reflex_base.vars.base import LiteralVar, Var, VarData +from reflex_base.vars.function import FunctionStringVar, FunctionVar, ReflexCallable +from reflex_base.vars.sequence import StringVar + +from .component import _PROVIDER_PRIORITY, _provider +from .config import UNCONFIGURED_LOCALE, get_active_i18n_config +from .runtime import WeekdayLength + +if TYPE_CHECKING: + # Aliased so the `date`/`time`/`datetime` functions below don't shadow it. + import datetime as _datetime + + +@functools.cache +def _format_var_data() -> VarData: + """VarData injecting the ``useFormat`` hook and the provider. + + Returns: + The shared VarData for number/date formatting vars. + """ + return VarData( + imports={"$/utils/i18n": [ImportVar(tag="useFormat")]}, + hooks={"const [ fmtNumber, fmtDate, fmtLanguage ] = useFormat()": None}, + app_wraps=((_PROVIDER_PRIORITY, _provider()),), + ) + + +@functools.cache +def _locale_var_data() -> VarData: + """VarData injecting the ``useLocale`` hook and the provider. + + Returns: + The shared VarData for the active-locale var. + """ + return VarData( + imports={"$/utils/i18n": [ImportVar(tag="useLocale")]}, + hooks={"const i18nLocale = useLocale()": None}, + app_wraps=((_PROVIDER_PRIORITY, _provider()),), + ) + + +# ``useFormat`` destructures to ``[fmtNumber, fmtDate]``; each takes the value +# to format and an ``Intl`` options object, and returns the formatted string. +_Formatter = ReflexCallable[[Any, Mapping[str, Any]], str] + + +@functools.cache +def _fmt_number() -> FunctionVar[_Formatter]: + """The client-side number formatter for the active locale. + + Returns: + The ``fmtNumber`` hook function as a callable Var. + """ + return FunctionStringVar.create( + "fmtNumber", _var_type=_Formatter, _var_data=_format_var_data() + ) + + +@functools.cache +def _fmt_date() -> FunctionVar[_Formatter]: + """The client-side date formatter for the active locale. + + Returns: + The ``fmtDate`` hook function as a callable Var. + """ + return FunctionStringVar.create( + "fmtDate", _var_type=_Formatter, _var_data=_format_var_data() + ) + + +@functools.cache +def _fmt_language() -> FunctionVar[ReflexCallable[[str], str]]: + """The client-side language namer for the active locale. + + Returns: + The ``fmtLanguage`` hook function as a callable Var. + """ + return FunctionStringVar.create( + "fmtLanguage", + _var_type=ReflexCallable[[str], str], + _var_data=_format_var_data(), + ) + + +# Without an I18nPlugin there is no client runtime: format inline in the +# locale the server formats in then. The date normalization mirrors the +# runtime's ``toDate``. +_SOURCE_FMT_NUMBER: FunctionVar[_Formatter] = FunctionStringVar.create( + '((value, options) => value == null ? "" : ' + f'new Intl.NumberFormat("{UNCONFIGURED_LOCALE}", options).format(value))', + _var_type=_Formatter, +) +_SOURCE_FMT_DATE: FunctionVar[_Formatter] = FunctionStringVar.create( + "((value, options) => { " + 'if (value == null) return ""; ' + 'const s = String(value).replace(/(\\.\\d{3})\\d+/, "$1"); ' + "const date = value instanceof Date ? value " + ': typeof value === "number" ? new Date(value) ' + ': /^\\d{4}-\\d{2}-\\d{2}$/.test(s) ? new Date(s + "T00:00:00") ' + ': /^\\d{2}:\\d{2}/.test(s) ? new Date("1970-01-01T" + s) ' + ': new Date(s.replace(" ", "T")); ' + 'return Number.isNaN(date.getTime()) ? "" : ' + f'new Intl.DateTimeFormat("{UNCONFIGURED_LOCALE}", options).format(date); }})', + _var_type=_Formatter, +) + + +_SOURCE_FMT_LANGUAGE: FunctionVar[ReflexCallable[[str], str]] = ( + FunctionStringVar.create( + "((tag) => { try { " + f'return new Intl.DisplayNames(["{UNCONFIGURED_LOCALE}"], ' + '{ type: "language", languageDisplay: "standard" }).of(tag) ?? tag; ' + "} catch { return tag; } })", + _var_type=ReflexCallable[[str], str], + ) +) + + +def _number_formatter() -> FunctionVar[_Formatter]: + """The number formatter for the app: the runtime's, else an inline one. + + Returns: + The formatter as a callable Var. + """ + return _SOURCE_FMT_NUMBER if get_active_i18n_config() is None else _fmt_number() + + +def _date_formatter() -> FunctionVar[_Formatter]: + """The date formatter for the app: the runtime's, else an inline one. + + Returns: + The formatter as a callable Var. + """ + return _SOURCE_FMT_DATE if get_active_i18n_config() is None else _fmt_date() + + +def _number_options( + *, + style: str | None = None, + currency: str | None = None, + min_fraction_digits: int | None = None, + max_fraction_digits: int | None = None, + grouping: bool | None = None, + compact: bool = False, + options: dict[str, Any] | None = None, +) -> Var[Mapping[str, Any]]: + """Build the ``Intl.NumberFormat`` options object from curated kwargs. + + Args: + style: The Intl number style (``decimal``/``currency``/``percent``). + currency: The ISO 4217 currency code (for ``style="currency"``). + min_fraction_digits: Minimum fraction digits. + max_fraction_digits: Maximum fraction digits. + grouping: Whether to show the grouping (thousands) separator. + compact: Whether to use compact notation (e.g. ``1.2M``). + options: Raw ``Intl.NumberFormat`` options, merged last. + + Returns: + The Intl options object as a Var. + """ + opts: dict[str, Any] = {} + if style is not None: + opts["style"] = style + if currency is not None: + opts["currency"] = currency + if min_fraction_digits is not None: + opts["minimumFractionDigits"] = min_fraction_digits + if max_fraction_digits is not None: + opts["maximumFractionDigits"] = max_fraction_digits + if grouping is not None: + opts["useGrouping"] = grouping + if compact: + opts["notation"] = "compact" + if options: + opts.update(options) + return LiteralVar.create(opts) + + +def number( + value: Var[Any] | int | float, + *, + min_fraction_digits: int | None = None, + max_fraction_digits: int | None = None, + grouping: bool | None = None, + compact: bool = False, + options: dict[str, Any] | None = None, +) -> StringVar: + """Format a number in the active locale. + + Args: + value: The number to format. + min_fraction_digits: Minimum fraction digits. + max_fraction_digits: Maximum fraction digits. + grouping: Whether to show the grouping separator. + compact: Whether to use compact notation (e.g. ``1.2M``). + options: Raw ``Intl.NumberFormat`` options, merged last. + + Returns: + A StringVar resolving to the localized number. + """ + opts = _number_options( + min_fraction_digits=min_fraction_digits, + max_fraction_digits=max_fraction_digits, + grouping=grouping, + compact=compact, + options=options, + ) + return _number_formatter().call(value, opts).to(str) + + +def currency( + value: Var[Any] | int | float, + currency: str, + *, + min_fraction_digits: int | None = None, + max_fraction_digits: int | None = None, + grouping: bool | None = None, + compact: bool = False, + options: dict[str, Any] | None = None, +) -> StringVar: + """Format a currency amount in the active locale. + + Args: + value: The amount to format. + currency: The ISO 4217 currency code (e.g. ``"EUR"``). + min_fraction_digits: Minimum fraction digits. + max_fraction_digits: Maximum fraction digits. + grouping: Whether to show the grouping separator. + compact: Whether to use compact notation. + options: Raw ``Intl.NumberFormat`` options, merged last. + + Returns: + A StringVar resolving to the localized currency amount. + """ + opts = _number_options( + style="currency", + currency=currency, + min_fraction_digits=min_fraction_digits, + max_fraction_digits=max_fraction_digits, + grouping=grouping, + compact=compact, + options=options, + ) + return _number_formatter().call(value, opts).to(str) + + +def percent( + value: Var[Any] | int | float, + *, + min_fraction_digits: int | None = None, + max_fraction_digits: int | None = None, + grouping: bool | None = None, + options: dict[str, Any] | None = None, +) -> StringVar: + """Format a ratio as a percentage in the active locale (``0.15`` -> ``15%``). + + Args: + value: The ratio to format (``1`` == 100%). + min_fraction_digits: Minimum fraction digits. + max_fraction_digits: Maximum fraction digits. + grouping: Whether to show the grouping separator. + options: Raw ``Intl.NumberFormat`` options, merged last. + + Returns: + A StringVar resolving to the localized percentage. + """ + opts = _number_options( + style="percent", + min_fraction_digits=min_fraction_digits, + max_fraction_digits=max_fraction_digits, + grouping=grouping, + options=options, + ) + return _number_formatter().call(value, opts).to(str) + + +# ``Intl.DateTimeFormat`` throws when ``dateStyle``/``timeStyle`` are combined +# with any of these per-component options, so the curated ``length`` gives way +# when the escape hatch spells the format out field by field. +_DATE_COMPONENT_OPTIONS = frozenset({ + "weekday", + "era", + "year", + "month", + "day", + "dayPeriod", + "hour", + "minute", + "second", + "fractionalSecondDigits", + "timeZoneName", +}) + + +def _date_options( + *, + date_style: str | None = None, + time_style: str | None = None, + options: dict[str, Any] | None = None, +) -> Var[Mapping[str, Any]]: + """Build the ``Intl.DateTimeFormat`` options object from curated kwargs. + + Args: + date_style: The Intl ``dateStyle`` (``short``/``medium``/``long``/``full``). + time_style: The Intl ``timeStyle``. + options: Raw ``Intl.DateTimeFormat`` options, merged last. + + Returns: + The Intl options object as a Var. + """ + opts: dict[str, Any] = {} + if not (options and _DATE_COMPONENT_OPTIONS.intersection(options)): + if date_style is not None: + opts["dateStyle"] = date_style + if time_style is not None: + opts["timeStyle"] = time_style + if options: + opts.update(options) + return LiteralVar.create(opts) + + +def date( + value: Var[Any] | _datetime.date | str, + *, + length: str = "medium", + options: dict[str, Any] | None = None, +) -> StringVar: + """Format a date in the active locale. + + Args: + value: The date to format (a Var or ISO string). + length: The date length (``short``/``medium``/``long``/``full``). + options: Raw ``Intl.DateTimeFormat`` options, merged last. + + Returns: + A StringVar resolving to the localized date. + """ + return ( + _date_formatter() + .call(value, _date_options(date_style=length, options=options)) + .to(str) + ) + + +def time( + value: Var[Any] | _datetime.time | str, + *, + length: str = "medium", + options: dict[str, Any] | None = None, +) -> StringVar: + """Format a time in the active locale. + + Args: + value: The time to format (a Var or ISO string). + length: The time length (``short``/``medium``/``long``/``full``). + options: Raw ``Intl.DateTimeFormat`` options, merged last. + + Returns: + A StringVar resolving to the localized time. + """ + return ( + _date_formatter() + .call(value, _date_options(time_style=length, options=options)) + .to(str) + ) + + +def datetime( + value: Var[Any] | _datetime.datetime | str, + *, + length: str = "medium", + options: dict[str, Any] | None = None, +) -> StringVar: + """Format a date and time in the active locale. + + Args: + value: The datetime to format (a Var or ISO string). + length: The length (``short``/``medium``/``long``/``full``). + options: Raw ``Intl.DateTimeFormat`` options, merged last. + + Returns: + A StringVar resolving to the localized date and time. + """ + opts = _date_options(date_style=length, time_style=length, options=options) + return _date_formatter().call(value, opts).to(str) + + +@functools.cache +def _locale_var() -> StringVar: + """Build the active-locale var (cached singleton). + + Returns: + A StringVar resolving to the active locale code. + """ + return Var(_js_expr="i18nLocale", _var_data=_locale_var_data()).to(str) + + +def locale_var() -> StringVar: + """The active locale as a client-side var (``rx.i18n.locale``). + + Returns: + The runtime's active locale, or the fixed locale an app without an + I18nPlugin formats in. + """ + if get_active_i18n_config() is None: + return LiteralVar.create(UNCONFIGURED_LOCALE).to(str) + return _locale_var() + + +def language_name(locale: Var[str] | str) -> StringVar: + """Name a language in the active locale, e.g. ``Englisch`` for ``en``. + + Args: + locale: The language tag to name. + + Returns: + A StringVar resolving to the language's name, or the tag itself for a + language the browser does not know. + """ + namer = ( + _fmt_language() + if get_active_i18n_config() is not None + else _SOURCE_FMT_LANGUAGE + ) + return namer.call(locale).to(str) + + +def weekday(day: Var[int] | int, *, length: WeekdayLength = "long") -> StringVar: + """Name a weekday in the active locale, e.g. ``Montag``. + + Args: + day: The weekday, 0 for Monday as ``datetime.date.weekday()`` counts. + length: ``long``, ``short`` or ``narrow``. + + Returns: + A StringVar resolving to the weekday's name. + """ + day_var = LiteralVar.create(day) + # 2024-01-01 was a Monday. + reference = Var( + _js_expr=f"new Date(2024, 0, 1 + {day_var!s})", + _var_data=day_var._get_all_var_data(), + ) + options = _date_options(options={"weekday": length}) + return _date_formatter().call(reference, options).to(str) diff --git a/packages/reflex-i18n/src/reflex_i18n/nav.py b/packages/reflex-i18n/src/reflex_i18n/nav.py new file mode 100644 index 00000000000..9ae039b15dd --- /dev/null +++ b/packages/reflex-i18n/src/reflex_i18n/nav.py @@ -0,0 +1,60 @@ +"""Navigation helpers for URL-based locale routing (``rx.i18n.*``).""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +from .component import LanguageSwitcher + +if TYPE_CHECKING: + from reflex_base.components.component import Component + + +def _base_path(route: str) -> str: + """Normalize a route to a base URL path. + + Args: + route: A route key (``"index"``, ``"pricing"``) or path (``"/pricing"``). + + Returns: + The URL path (``"/"`` for the index, else ``"/"``). + """ + if route in ("", "/", "index"): + return "/" + return route if route.startswith("/") else f"/{route}" + + +def locale_url(locale: str, route: str) -> str: + """The URL path for a route in a given locale (for custom links). + + Like any Reflex route, the path is relative to ``frontend_path``, which + ``rx.link`` and ``rx.redirect`` prepend. + + Args: + locale: The target locale. + route: The base route (``"/pricing"`` or ``"pricing"``). + + Returns: + The localized URL path (unchanged if URL routing is off). + """ + from reflex_base.plugins.base import get_plugin + + from .plugin import I18nPlugin + + path = _base_path(route) + plugin = get_plugin(I18nPlugin) + if plugin is None or plugin.routing is None: + return path + return plugin.routing.localize(path, locale, plugin.default_locale) + + +def language_switcher(**props: Any) -> Component: + """A crawlable language switcher: one ```` link per locale. + + Args: + props: Props forwarded to the switcher's ``