Support Vue with the same DX than React

[JSteunou]

I'm starting to work with Vue, coming from the React world, and I really want to keep using lingui because I think it is the best frontend solution for handling i18n issues.

Lingui + Vue + Vite works with the basics, as a JS project, so atm you do not have some features like :

• id generation
• Components
• handling html tags in your sentences with placeholders / children components.
• ...

In fact every goodies that make Lingui having a very good DX.

I want to make this happen, but I need the help of Vue & Lingui masters here.

• For the JS/TS/setup part I though about using macros, which should be split in order to not import the React universe.
• For the template part I though about relying on the vue-extractor + AST reading for the extraction part, and a set of Vue components using render function for the rendering part.

Who's on board?

[SpiderDan98]

Here are hopefully some good links:

• Vue support #1017
• RFC: Split macro to vanilla js + react #1361

[timofei-iatsenko]

I'm not very familiar with Vue, so i could not help on the best solution in that ecosystem.

You already can use just t and msg macros, and it will give auto-id generation, ICU expanding and so on.

To replicate JSX macro in Vue templates you need to somehow hook into the Vue compiler, and as far as i understand it's not something very popular and doable. So the easiest way would be just pass strings created using macro from setup script to template.

[timofei-iatsenko]

Show me the input code. This not a related to macro, it's related to how Vue compiler transforms the code. It tries to push t variable from macro (which is virtual) to the template function, you can clearly see it here:

 19 |       return bar;
  20 |     }, get t() {
> 21 |       return t;
     |       ^^^^^^^^^
  22 |     }, get i18n() {
  23 |       return i18n;

And then babel-macro plugin attempt to parse this and fail because there are no handlers in lingui-macro for such cases.

[JSteunou]

You are right. After digging I had the same feeling. Here is what looks like the code after vue compiler / before macro in dev mode.

• ❎ extract (known, because of template)
• ❎ dev mode HMR
• 〽️ build pass but component render is broken, empty view

    _createElementVNode(
      "h2",
      null,
      _toDisplayString($setup.t`inside a t macro`),
      1
      /* TEXT */
    ),
    _hoisted_3
  ]);

Vue links every template global variable to $setup var.

This one also fails (in HMR)

• ✔️ extract is ok
• ❎ dev mode HMR (same error with macro)
• ✔️ build & preview works

    _createElementVNode(
      "h2",
      null,
      _toDisplayString($setup.i18n.t("inside a t core i18n")),
      1
      /* TEXT */
    ),
    _hoisted_3
  ]);

This one goes well

• ✔️ extract is ok
• ✔️ dev mode HMR works
• ✔️ build & preview works

    _createElementVNode(
      "h2",
      null,
      _toDisplayString($setup.i18n._("inside a _ core i18n")),
      1
      /* TEXT */
    ),
    _hoisted_3
  ]);

Update: list all cases

[JSteunou]

During a build, vue wraps those setup var with _unref which make the macro fails

in

        _createElementVNode("h2", null, _toDisplayString(_unref(t)`inside a t macro`), 1),

out

_createElementVNode("h2", null, _toDisplayString(i18n._(
      /*i18n*/
      {
        id: "J/hVSQ",
        values: {
          0: _unref(t)
        }
      })`inside a t macro`), 1),

[timofei-iatsenko]

And because macro used in template is referenced not directly from import, but passed thru $setup var it's hardly possibly to find it using static analysis and expand the macro. The vue compiler produces the bindings metadata during compilation (i playd with a compiler a bit while helped to implement vue extractor), but i didn't find a way how to hook into compiler in vite-vue and tight all parts together.

[JSteunou]

Yup‚ so far I see there is no choice to play with vue compiler. Doable in vue extractor‚ to go from a Trans component to an i18n._ call with id generation and maybe as vite plugin before babel macro

[JSteunou]

Following the discussion above, we now are sure, as of today, using vue@3 + vite + lingui & extractor & vite plugin, it is possible to:

• use any lingui feature inside SFC setup part (macro or core)
• use lingui core features inside SFC template part (but call to i18n.t break the HMR in dev mode)

The goal would be to improve the DX inside the template part and for that I think it is doable to plug into the lingui extractor for vue between the vue parser and the vue compiler in order to update the template AST.

Going from

<template>
  <Trans>Hi, I am a <b>statement</b> withing my {{ name }} template</Trans>
</template>

to

<template>
  {{ i18n._({id: "XXXX", message: "Hi, I am a <0>statement</0> withing my {name} template", comments: "", context: ""}) }}
</template>

I still need to found in vue how the descriptor can be updated if and when the AST is changed

Next step would be to reuse part of that logic to transform the template via vite to produce a real Trans component code with slots for children.

[JSteunou]

Using nodeTransforms from the compilerOptions I was able to write a quick PoC that use the AST & update it to transform a <Trans> into a {{ i18n._ }} and make the extractor fully extract sentences with markup & interpolation in it.

I'm looking for the part in lingui that generate the id @thekip do you know if and where it is exported by any chance?

[andrii-bodnar]

@JSteunou please check the @lingui/message-utils package

[JSteunou]

I again, I'm back at it after several months :)

I now can extract and use lingui inside vue template section using fake Trans component processed during vue pre-compilation, but I cannot get the exact same experience than native lingui.

The issue is around id generation: my code transform <Trans>some message</Trans> into i18n._(...) code with message descriptor, but if I provide an id it is considered as explicit id, and if I don't, the message is the id. Either case I cannot get lingui handle the message id under the hood as it does with macro.

Any idea to achieve this?

[JSteunou]

I might generated the id the wrong way, now I can get it right.

@thekip or @andrii-bodnar can you confirm than when passing an id to i18n._ call, during extration, if lingui generate the same id in core it is considered as the internal id and not a custom message id?

[timofei-iatsenko]

if hash generated from message using @lingui/message-utils is the same as provided ID - it's considered "internal"

[JSteunou]

After several months away from this project I'm back and I have a thing working for vue template. It is not complete, it is a start with the <Trans> component and support for interpolation and html tag in it. Other components like Plural should be easy to add now.

How I did it: I wrote an extractor based on the actual lingui vue extractor but with a nodeTransforms for the SFC compilerTemplate part and another transformer for the same SFC template compilerOptions for the vite vue plugin (but can easily be used anywhere I think). Both transformers have a lot of code in common obviously.

How it works ?

• during the extraction it transforms all the <Trans>...</Trans> it can find (reading the AST) into i18n._() call
• during the build it transforms all the <Trans>...</Trans> it can find (still reading the AST) into <Trans id="" message="" values=""></Trans> with template slots as children when needed instead of the original message. Kudos to Ugzuzg ideas
• during the runtime the Trans component uses the id, message, values from the props and then format the result with the slots in a render function using a formater inspired by the one from lingui react

What still need to be done?

• publishing it obviously: @thekip or any lingui maintainer I need your guidance here 😅
• adding Plural, Select, formater, ... support
• use transform to update the import so we can have 2 Trans component, one acting like a macro, the other the real one (as of today I cheat a little, only one component, all props are optional)
• documentation
• tests

[JSteunou]

Sure thing. I'm currently integrating it in our monorepo first, kind of alpha testing it, then I will invite you both on a separate copy.

[JSteunou]

Done. I will keep it private until it reaches an acceptable state, then I will switch it to public and / or you could add it into lingui project.

To be honest I will be using it at my job so every issue I'll find I'll fix it, but I'm not sure to be able to maintain it on my own fully. So I think it would be better to integrate it into lingui project.

[JSteunou]

Some news from the battlefield:

• I added up a helper vt that does the same thing (but not yet all the things) that t macro does. So translation in template tag attributes works
• I found a better way to handle inner tags (and inner of inner of inner ...) that gives supa powa to <Trans> and allow unlimited inner tags and components depth
• I added some usage & explanation doc in the README

The big part that still need to be done is unit testing (yes I'm lazy I dev all the thing through example & demo case)

[andrii-bodnar]

Hi @JSteunou,

Thanks a lot for your work! I just checked out the repository and was amazed at the progress you've made.

I think it's a great addition to the Lingui project and I'm happy to help you with the release process.

I wonder what the next steps might be to make it happen. Probably we can include it as a separate package in the current repository, and also move the demo project to the examples folder.

I think we should create a separate article in the documentation that covers all aspects of working with Vue. Details about the technical implementation can be left in the README of the package.

From my perspective, the plan might look like this:

• finish the implementation of the <Trans> component
• finish the "support messages as prop during extraction" (maybe not completely, but at least the most critical parts)
• add tests
• prettify the package and the demo project, match the style of the other packages
• add documentation
• release

Also, I noticed some code duplication from the @lingui/extractor-vue package. What would be the best way to handle this? It would be great to avoid having two similar extractors.

What do you think about this?

[JSteunou]

Thank you :)

Totally agree with your plan.

• The component is 80% complete, the other features can be added one by one later to make it 100% similar to the React one
• regarding the prop you might talk about the vt helper I added. It works very well today with some differences with the t helper from lingui macro / react. No i18n instance can by given in parameter, no context, and all variables are extracted / replaced by index (0, 1, ...), because I choose the shortest path and make vt run as is in runtime, without transformation, thanks to generateMessageId available for browsers. Also no complexes forms, not inside <Trans> inner tag. Very simple support but I think it covers 90% of use cases.
• tests are currently in progress and will be added by the end of the week

About @lingui/extractor-vue I think it should be deprecated as the new one superseed it.

Then about the integration I'm wondering if it should be as it is now or if module naming and folders should be rethink. Do you think one package is ok, or should it be split in multiple packages (extractor, vue, ...)

Maybe we should also start to think about and anticipate a split / renaming of @lingui/macro to have react-macro, vue-macro, etc.

[jrd]

What’s the current status? Do you have an example?

[andrii-bodnar]

No updates on this one, unfortunately. The furthest anyone has got is #1925. It's still a draft and needs more work before it can land, mainly Plural/Select support and making vt behave like the t macro. It's also the closest thing to an example right now. We'd really appreciate help from someone with Vue experience to pick it up.

[yves-riot]

Hi @andrii-bodnar 👋
We forked the project and added support for Vue in this branch.
It's running in production for 3 weeks now in 2 large SPAs without any issues and the workflow is the same as React (we also tried to plug it into a Nuxt app succesfully).
Is that ok if I open a PR?

[andrii-bodnar]

Hi @yves-riot, thank you, that looks really promising! 🤩

It's great to hear it's already running in production. Yes, please go ahead and open a PR, it'll be easier to discuss the details there.

[jrd]

@yves-riot @andrii-bodnar I integrated the fork (parts of it) in my current django-vue boilerplate. It’s working great. My team use the Option API rather than the Compose API of vue3, but it’s working nontheless.

You can find my repo in the lingui branch here : https://gitlab.com/systracorp/hq/boilerplates/django-vue-boilerplate/-/tree/lingui?ref_type=heads

So I hope @yves-riot starts a pull request to integrate it. Even if not rebased to tip of master/main, this could allow discussion there.

[yves-riot]

PR created #2732!

[andrii-bodnar]

Vue support is now available in v6.11.0 with the new @lingui/vue package. Thanks @yves-riot for the PR!

More details in the blog post, and the Vue tutorial shows how to get started.