feat: add SolidJS support

[Azq2]

Description

Basic SolidJS integration ported from @lingui/react
All tests passed.

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Examples update

Checklist

• I have read the CONTRIBUTING and CODE_OF_CONDUCT docs
• I have added tests that prove my fix is effective or that my feature works
• I have added the necessary documentation (if appropriate)

Testing

My package for testing: https://github.com/Azq2/js-lingui-solid

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
js-lingui	✅ Ready (Inspect)	Visit Preview	Nov 30, 2024 11:12am

[github-actions]

size-limit report 📦

Path	Size
./packages/core/dist/index.mjs	3.09 KB (0%)
./packages/detect-locale/dist/index.mjs	723 B (0%)
./packages/react/dist/index.mjs	1.65 KB (0%)
./packages/remote-loader/dist/index.mjs	7.26 KB (0%)

[timofei-iatsenko]

Thanks for contribution, that looks interesting. Could you highlight what the key difference between react and solidjs integration?

[Azq2]

Key differences:

• Different reactivity model.
• VDOM vs real HTML nodes.

---

1. Different useLingui() API
   React:

   const { _, i18n } = useLingui();
   
   useEffect(() => {
       console.log(i18n.locale)
   }, [i18n])
   
   return (
       <div>
   	    {_(msg`lang:`)} {i18n.locale}
       </div>
   );

   SolidJS:

   // i18n - reactive signal
   // defaultComponent - reactive signal
   // _ - wrapper around i18n()._(...) for reactivity
   
   const { _, i18n } = useLingui();
   
   createEffect(() => {
       console.log(i18n().locale)
   })
   
   return (
       <div>
   	    {_(msg`lang:`)} {i18n().locale}
       </div>
   );

   In all other respects, the lingui API is fully compatible between React and SolidJS.

2. In SolidJS we work with real DOM nodes instead of VDOM nodes. But it's not a problem, formatElements work okay.

3. I use vite instead of unbuild, beacuse unbuild can't solidjs code with JSX.
   And I don't know how to fix that. Maybe it is impossible.

4. Different test API: render(<JSX>) vs render(() => <JSX>)

---

All tests are ported from React, except:

• "should create two children with different keys" - SolidJS don't have key= analog.
• "should render nested elements with asChild pattern" - impossible with SolidJS.
• "should render class component as simple prop" - in SolidJS all components are functional.

This is not ported to SolidJS:

• RSC server - I don't know analog in SolidJS

P.S. SolidJS and React code are still similar

diff -Naur packages/react packages/solid | colordiff

[timofei-iatsenko]

Thanks for details explanation, from the PR file listing (i haven't dug into this properly yet) it looks like many code duplication with React, is there something that could be extracted and reused? Maintaining few copies in the long run isn't a very pleasant experience.

[Azq2]

Thanks for details explanation, from the PR file listing (i haven't dug into this properly yet) it looks like many code duplication with React, is there something that could be extracted and reused? Maintaining few copies in the long run isn't a very pleasant experience.

I'm not sure. The reactive model and data types are dramatically different. It just looks similar, but the details are completely different.

[Azq2]

Done at this moment:

• @lingui/solid
• @lingui/solid tests
• support for @lingui/solid in @lingui/babel-plugin-lingui-macro
• support for @lingui/solid in @lingui/babel-plugin-extract-messages

What else is needed for merging PR? Documentation? Examples? CI?

[Azq2]

Also, macro plugin don't work with @lingui/solid/macro without this lines in config:

  runtimeConfigModule: {
    Trans: ["@lingui/solid", "Trans"],
    useLingui: ["@lingui/solid", "useLingui"],
  }

I think that it would be ideal to automatically determine the required package.
@lingui/<something>/macro -> @lingui/<something>

[Azq2]

Another question.
In React, we have state. The state is simple variables. And this works:

Hello {name}
// Hello {name}

But in SolidJS, we use signals. They are always function calls.

Hello {name()}
// Hello {0}

It's okay? Or can I change the logic of macros?

Better variant for SolidJS:

Hello {name()}
// Hello {name}

But... breaking change for other integrations. Of course, is not critical, working SolidJS integration is still cool even without named macros for signals.

[timofei-iatsenko]

I'm not sure. The reactive model and data types are dramatically different. It just looks similar, but the details are completely different.

I understand that inside these two frameworks are different. But some implementation details of a library are very similar. And because of the code duplication this will increase a maintenance burden for the maintainers.

So i'm really want to avoid this at any cost. Take for example the format function. Is there any difference from the react version? If it's almost the same, we can move it to some shared package and reuse between both.

The same is for other parts.

Note regarding macro. There is also a SWC version of it, is there any configurations where solid can be used with a SWC? if yes, then SWC version should also be updated.

Better variant for SolidJS:

Hello {name()}
// Hello {name}
But... breaking change for other integrations. Of course, is not critical, working SolidJS integration is still cool even without named macros for signals.

There is a PR for labeled placeholders, it might help in this case:

Hello {{name: name()}}

[Azq2]

https://gist.github.com/Azq2/fb6a5485242746a6e62318f1b959b728

• macro/index.d.ts - different data types
• macro/__typetests__/index.test-d.tsx - 90% is the same, but: different imports & API, data types and state vs signal() problem
• src/format.ts - same part is only parser
• src/I18nProvider.tsx - same only comments
• src/TransNoContext.tsx - same logic and flow, but heavy difference
• src/Trans.tsx - different data types
• src/format.test.tsx - 90% is the same, but: different imports & API, data types
• src/I18nProvider.test.tsx - 90% is the same, but: different imports & API, data types and state vs signal()
• src/Trans.test.tsx - 90% is the same, but: different imports & API, data types and state vs signal()

---

• The most similar part is tests and macro. This is theoretically (but hard) portable by shimming types and API.

  type LinguiNode = JSX.Element;
  // vs
  type LinguiNode = ReactNode;

• The framework neutral part is only parser in format.ts.

[Azq2]

Another way - I can develop solidjs integration by myself, unofficially, in a separate package/organization.

But with official support in:

• lingui babel extract plugin
• lingui babel macro plugin
• lingui vite plugin

This is required for normal work.

[Bubz43]

For what its worth, I've been using import { Trans } from @lingui/react/macro in a solidjs project, with the runtimeConfigModule in the lingui.config.ts set to a solidjs component similar to the one in this PR and everything works fine without further changes than that. Maybe something like @lingui/jsx/macro could be a thing and requires that the config has the runtimeConfigModule setup.

[Azq2]

I've been using import { Trans } from @lingui/react/macro in a solidjs project

@Bubz43 Can you show an example? I'll be surprised if this works with TS.

[Bubz43]

Apologies, I should have specified that by default the component's props don't work with TS autocomplete/typechecking (though the JSDoc comments still work) but it also doesn't have any errors for the common use case of <Trans>foo</Trans> (as I'm pretty sure it narrows them to any as the react module isn't installed).

To get actual TS support you can override @lingui/react/macro by adding a .d.ts file in the project (ideally the more complete one from this pr)

declare module "@lingui/react/macro" {
	import type { ParentComponent } from "solid-js";
	/**
	 * Trans is the basic macro for static messages,
	 * messages with variables, but also for messages with inline markup
	 *
	 * @example
	 * ```
	 * <Trans>Hello {username}. Read the <a href="/docs">docs</a>.</Trans>
	 * ```
	 * @example
	 * ```
	 * <Trans id="custom.id">Hello {username}.</Trans>
	 * ```
	 */
	export const Trans: ParentComponent<{
		id?: string;
		comment?: string;
		context?: string;
	}>;
}

I'm not suggesting this is reasonable for the average end user to do, just wanted to share in case it sparks an idea for an easier way forward that lowers the surface area for maintenance and/or for supporting solid-js from an external package.

[Azq2]

I have production ready variant in my package https://github.com/Azq2/js-lingui-solid

But the current version is very difficult to maintain, since I had to create fork of the packages:
@lingui-solid/vite-plugin
@lingui-solid/babel-plugin-lingui-macro
@lingui-solid/babel-plugin-extract-messages

The reason for the fork is only to add support for @lingui-solid/solid next to @lingui/react. Only few lines changed...
It would be cool if this could be done with official packages using a config.

Then I can adequately support the SolidJS version in my own separate package.
Because I no longer believe that it is possible to include this in the official LinguiJS.

[melavas]

For what its worth, I've been using import { Trans } from @lingui/react/macro in a solidjs project, with the runtimeConfigModule in the lingui.config.ts set to a solidjs component similar to the one in this PR and everything works fine without further changes than that. Maybe something like @lingui/jsx/macro could be a thing and requires that the config has the runtimeConfigModule setup.

@Bubz43 would you please 🙏 share a gist with this component you're mentioning here? And also the specific configuration for runtimeConfigModule you're using to set it up?

That would be super helpful for me, as I really like Lingui and I'm also trying to use it with Solid, it seems the best alternative out there but this is a real blocker for me.

Also, I don't want to use a fork of this library, so I'd prefer to just copy a macro implementation if somebody already implemented it. I'm just looking for the simplest solution to this.

Thanks!

[timofei-iatsenko]

@Azq2 The main reason this PR is on hold is that I believe the existing Lingui code could be refactored to reduce duplication. However, to propose meaningful changes, I need to fully understand the context of this task and review everything thoroughly.

The main concern here is the increased maintenance surface if this package is added. Also, I don’t have experience with SolidJS and honestly don’t want to take on that maintenance burden.

A separate package seems like a good approach. From my side, I’m fully committed to making the necessary changes in macro and lingui/react to minimize code duplication between your package and lingui/react.

If you have any ideas or additional configurations that could help reduce duplication, I’m open to implementing them.

[timofei-iatsenko]

@Azq2 here is list (not complete) of changes need to be done to lingui to reduce duplication with your package:

• add configuration for macro to allow Trans from diffrent packages. (for consistency not only react but core macro also should be configurable)
• make macro paths configurable in vite plugin
• make trans / core components configurable in extractor plugin
• format.tsx refactored to be framework agnostic and extracted somehow to separate package to be reused

Also looking for a way to reuse typings (props, and so on) between react / other jsx libs, but it seems the hassle is not worth the effort.