@palamedes/solid

Use this package when your Solid app wants translated JSX that feels native to Solid: Trans, Plural, Select, and SelectOrdinal, plus a small headless helper layer for locale-aware UI.

Palamedes keeps the runtime model provider-free. Transformed code resolves the active i18n instance through getI18n() from @palamedes/runtime, so your Solid app only needs to register the active client or server instance before translated code runs.

This package is part of the verified Solid story in the example matrix. It shares the same catalog model, runtime semantics, and Vite plugin path as the React integrations while swapping only the JSX adapter layer.

The current adapter targets Solid 2, starting with 2.0.0-rc.3. Solid 1 is no longer part of the supported surface.

Breaking minor release at 1.18.0: @palamedes/solid moved from Solid 1 to Solid 2 while Palamedes packages continued their lockstep 1.x releases. A dependency range such as ^1.17.3 can therefore upgrade a Solid 1 app to a Solid 2 adapter and lose Solid 1 compatibility. If your app must stay on Solid 1, pin @palamedes/solid to the last Solid 1-compatible release, 1.17.3, and keep the matching Solid 1 compiler setup. To use a newer adapter, migrate the app and its compiler/tooling to Solid 2 first, then use @palamedes/solid 1.18.0 or newer.

Install

pnpm add @palamedes/core @palamedes/solid @palamedes/runtime solid-js@^2.0.0-rc.3
pnpm add -D @palamedes/cli @palamedes/config @palamedes/vite-plugin @solidjs/vite-plugin

Example

import { Trans } from "@palamedes/solid/macro";

export function Footer() {
  return (
    <footer>
      <Trans>
        Powered by <strong>Palamedes</strong>
      </Trans>
    </footer>
  );
}

When the Palamedes transform runs, macro imports are rewritten to runtime imports from @palamedes/solid/compiled, which excludes the ICU parser. Rich JSX children are transformed to numeric component slots in the message, for example <0>Palamedes</0>, while the Solid wrapper is passed separately. Direct imports from @palamedes/solid remain the runtime surface for hand-written component patterns. Rich component slots use Solid 2 FlowComponent<{}, Element> functions and receive their nested content through props.children.

Runtime Components

Besides the macro entry point, the package's main entry exports the runtime components Trans, Plural, Select, and SelectOrdinal. These are what macro-transformed JSX renders through, and all of them resolve messages through the active i18n instance. The choice components accept plural categories (zero … other), exact matches written as _0/_1/… (normalized to ICU =N, mirroring the macro transform), and offset; invalid option props and option text with unbalanced braces are rejected with a descriptive error instead of silently misrendering.

offset maps to ICU offset:N and covers "and N others" sentences, where the number shown is smaller than the number counted:

<Plural value={attendees()} offset={1} _0="nobody else" one="# other" other="# others" />

Exact _N keys match the raw value; plural categories select on value - offset, and # renders value - offset. It must be a non-negative safe integer. Select has no numeric operand and takes no offset.

Headless Frontend Helpers

This package also exposes small Solid-native helpers that stay deliberately headless:

• buildLocaleSwitchItems({ locales, currentLocale, labels, testIdPrefix? })
• LocaleSwitchItem<TLocale>

They do not own routing, styling, cookie policy, or server decisions. They only cover the stable frontend primitives that repeat across apps:

• building render-ready locale switch models for links, buttons, or forms

import { buildLocaleSwitchItems } from "@palamedes/solid";

function LocaleToolbar(props: { locale: "en" | "de" }) {
  const items = () =>
    buildLocaleSwitchItems({
      locales: ["en", "de"] as const,
      currentLocale: props.locale,
      labels: { en: "English", de: "Deutsch" },
    });

  return (
    <nav>
      {items().map((item) => (
        <a data-testid={item.testId} href={`/${item.locale}`}>
          {item.label}
        </a>
      ))}
    </nav>
  );
}

Locale links deliberately navigate the document. Components and macros read the plain runtime getter and do not subscribe to in-document locale replacement.

Related Docs

• First working translation in 5 minutes
• Example matrix
• Proof and benchmarks

palamedes is part of the Ferramenta family — Rust-native developer tools that keep the APIs the ecosystem already knows.

Siblings: ferroni · ferriki · ferromark · ferrolex · ferrocat · ferrovia · ferralk · ferrugo.

License

MIT OR Apache-2.0 © 2026 Sebastian Software