@nuxtjs/i18n package with support for nuxt2, nuxt-bridge and nuxt3

[kazupon]

I have come up with the following development step for @nuxtjs/i18n to migrate seamlessly to nuxt3 and would like to discuss if it is feasible.

Summary

• Step 1: Backward compatibility for nuxt2
• Step 2: Backward and forward compatibility for nuxt-bridge
• Step 3: Deal with for nuxt3

Step 1

This step only implements loading the existing version of @nuxtjs/i18n in a single order.

We can use installModule in @nuxt/kit to achieve this.
This is all you need to do to make it work as a nuxt2 module and keep backward compatibility.
In other words, this new @nuxtjs/i18n is just a wrapper nuxt module.

Step 2

This step implements a bridge for nuxt3 to work in the nuxt-bridge environment.

The nuxt bridge is an environment that works Vue 2 runtime and backports the Composition API of nuxt 3.
We will implement in this step the following:

• Loading the existing versions of @nuxtjs/i18n.
• Installing vue-i18n-bridge and implementing (tweaking of existing @nuxt/i18n) with it.
• Implementation of Composition API using @nuxt/composition-api (@vue/composition-api) and vue-i18n-bridge Composition API.

The nuxt-bridge provides a runtime that is almost identical to nuxt2.
Backward compatibility is maintained by loading existing versions of @nuxtjs/i18n.

vue-i18n-bridge has the Composition API backported from vue-i18n-next.
We can install vue-i18n-bridge, and then can use @nuxt/composition-api backported from nuxt3 to implement the Composition API working with nuxt3.

If there are any other backports from nuxt3 for nuxt-bridge, they will be implemented as well.

Step 3

In this step, we will implement it to work in the nuxt3 environment.

• Installation of vue-i18n-next and implementation (tweaking) using it
• Implementation for nuxt3

Since the Composition API and other birding for nuxt3 have been implemented in Step2, there is almost no need to deal with it.
We only need to implement it to work with nuxt3.

PoC examples

My PoC example repo is here:
https://github.com/kazupon/nuxt-i18n-next

It is not possible to run it using vite because of the following issue
https://github.com/nuxt/framework/issues/1461

Disclaimer: About new features

There are some exciting features, such as Nitro engine, that will not be discussed in this proposal.

[rchl]

When you say Strategy 1, 2, 3, do you mean that those are alternatives and we have to pick one or those are more like Step 1, 2, 3?

From reading your description those seem more like steps.

We can use installModule in @nuxt/kit to achieve this.

I guess you have familiarity with that code already but as for me, I haven't played with nuxt/kit and I'm not sure how this really works. And there is no documentation for it either.

What does installModule really do? Install a package by adding it to package.json at runtime? That would be a bit weird...
Are we instead able to use the nuxt/kit directly, without creating a wrapper package?

[kazupon]

When you say Strategy 1, 2, 3, do you mean that those are alternatives and we have to pick one or those are more like Step 1, 2, 3?

From reading your description those seem more like steps.

I'm really sorry, my terrible proposal. 🙇
You are right, step is correct, not strategy.
I've updated the proposal.

What does installModule really do? Install a package by adding it to package.json at runtime? That would be a bit weird...

@nuxt/kit docs are not ready, but you can read these codes.
the following installModule function code permalink:
https://github.com/nuxt/framework/blob/bdbfa3698790e9dc655954ab5f985790ca408075/packages/kit/src/module/install.ts#L9-L64

if the second params string, In other words, if it is a module name defined in dependencies of packages.json, it will be loading it dynamically.`

The nuxt module loaded with installModule is instantiated with ModuleContainer (createModuleContainer) which is compatible with nuxt2.

About ModuleContainer, you can see the this link:
https://github.com/nuxt/framework/blob/bdbfa3698790e9dc655954ab5f985790ca408075/packages/kit/src/module/container.ts#L9

This means that an existing nuxt module will work by using installModule.

After that, that install will be called to run the nuxt module.

@pi0
I'm sorry for the mention. if I have misunderstood you, please feel free to comment. 🙏

Are we instead able to use the nuxt/kit directly, without creating a wrapper package?

Yes! we can use it directly at @nuxtjs/i18n.

My proposal is not to create a new wrapper module, to develop for nuxt3 in @nuxtjs/i18n or nuxt-community/i18n-module repo.
sorry, for my poor proposal explanation.

[divine]

Hello guys,

I'm actually a bit scared to use i18n with @nuxt/kit wrapper as it could break anything at any time for any nuxt 2 projects using it.

As @rchl pointed out there is no documentation and looks like everything is too fresh and not ready for production usage, yikes.

I can understand with the time someone would be asking for composition API for nuxt 2 but it's too risky to use that until everything becomes stable which will take some time.

Maybe we just release a new version completely written for Nuxt 3 and after that do those steps in reverse:

Step 1: Deal with for nuxt3 (by releasing a new alpha version v2)
Step 2: Backward and forward compatibility for nuxt-bridge
Step 3: Backward compatibility for nuxt2 (alpha and not ready for production and not touching v1 at all?)

Thanks!

[rchl]

As long as someone wants to spend time on experimenting, we could try both approaches simultaneously.

That is, both try to convert the code to use @nuxt/kit and also try to just make the module work directly in Nuxt 3. As for the latter, does that require that we use @nuxt/kit anyway? Is it: a) needed b) recommended c) not needed?

As for the @nuxt/kit approach, I'm skeptical due to lack of documentation and potentially it not supporting some of the functionality needed currently (the module uses various hooks and it's not very clear if/how would those work in Nuxt 3).

[kazupon]

That is, both try to convert the code to use @nuxt/kit and also try to just make the module work directly in Nuxt 3. As for the latter, does that require that we use @nuxt/kit anyway? Is it: a) needed b) recommended c) not needed?

For the latter, We need to use the @nuxt/kit, because Nuxt 3 works on Vue 3 runtime environment. @nuxtjs/i18n currently version is made by Vue 2.

As for the @nuxt/kit approach, I'm skeptical due to lack of documentation and potentially it not supporting some of the functionality needed currently (the module uses various hooks and it's not very clear if/how would those work in Nuxt 3).

Currently, as you said, @nuxt/kit docs are not enough, but we can read the @nuxt/kit codes here:
https://github.com/nuxt/framework/tree/main/packages/kit

And also, We can refer to the code in nuxt3.
nuxt3 features such as routing, auto importing of components, and meta in nuxt3 are implemented in the nuxt module using @nuxt/kit.

The docs are not insufficient, but they can compensate for the development of the nuxt module using @nuxt/kit

BTW, I am going ahead and developing a new @nuxtjs/i18n to verify if my proposal is feasible.
Repo is here:

• legacy @nuxtjs/i18n that is extended for nuxt bridge: https://github.com/kazupon/i18n-module
• new @nuxtjs/i18n: https://github.com/kazupon/nuxt-i18n-next

[kazupon]

Hi, there!

I've been prototyping @nuxt/i18n for nuxt bridge / nuxt3 while now.
As a result, I was able to get i18n routing working with these environments.

we can check is here:
https://github.com/kazupon/nuxt-i18n-next/tree/nuxt-bridge-and-nuxt3-working

I would also share the video demo of the nuxt bridge and nuxt3 below:

simple i18n routing is working on nuxt bridge:

nuxti18n_on_nuxt_bridge.mov

simple i18n routing is working on nuxt3:

nuxti18n-on-nuxt3.mov

I found the following in this prototyping:

• It works with nuxt bridge and nuxt3 from porting the logic of @nuxt/i18n existing version
• By porting the logic of the @nuxt/i18n existing version as Composition API, we can manage the development code of nuxt bridge and Nuxt3 almost as one source.

I had previously suggested Step 2 and Step 3, which is a step-by-step process. In this prototyping, I have developed at the same time both of these steps.

So, we can develop @nuxt/i18n for nuxt bridge & nuxt3 at the same time.

Step 1 can be easily supported with installModule API that I have described before.

[kazupon]

If you have any questions about this, please feel free to comment. 😃
I believe that we will be able to develop at the same time, so I would like to develop.

The goal of this development is to first focus on supporting compatibility with the existing @nuxtjs/i18n.

I would like to develop without considering adding new features until we have a new module firstly.
But it would be possible to add new features if there are any along the way.

I have a request about this new module development.
I can make with development in this repository, but if possible, I would like to develop in a new repo.
Because, with an existing repo, it's hard to triage issues when we will release the alpha/beta release version,
and by being isolated from the existing development environment, we will be easy to develop in the new repo.

@nuxtjs/i18n is a module created by the Nuxt community. so I would like to create a new repo like i18n-next on the nuxt-community organization.

[rchl]

i18n-next doesn't sound good as Next is a react framework so that would be confusing. There is even already a module called i18next.

As for creating another i18n module in the Nuxt Community organization then I'm personally not sure about that either. It has potential to create fragmentation and, again, confusion. Wouldn't it make sense instead to develop that prototype separately and merge things in when ready?

@pi0 @danielroe - maybe you have a different take on it then feel free to chime in.

[kazupon]

I have a request about this new module development.
I can make with development in this repository, but if possible, I would like to develop in a new repo.

Sorry for my lack of explanation. 🙇

For the quote my comment, I will eventually integrate the integration into the source repo.
I agree that we will keep going separate repository is confusing to the community.
I was thinking of that integration at the time when we will have released the public (major) version.

[kazupon]

Hi, there! 😃

I have set up a new development environment in this repository for Nuxt Bridge / Nuxt3.
You can see the environment in the next branch.
By developing on a separate branch from the main branch, I believe that module releases can be smoothed out by easily switching branches.

If you have any questions about this environment, feel free to comment. 😃

[terion-name]

Does this branch already support router integration?

[rchl]

@terion-name As far as I can tell by looking at the code, nothing really is supported yet. It's just an initial project scaffolding.

@kazupon

By developing on a separate branch from the main branch, I believe that module releases can be smoothed out by easily switching branches.

Yes, good idea.

If you have any questions about this environment, feel free to comment.

Nothing serious but I see some things that I haven't seen before.

• Why include the yarn binary in the repo? I'm sure there are theoretical benefits to using very specific versions of the tools but is it really worth it? Binaries in repos are feel wrong to me.
• You've decided to use mocha for testing rather than jest like this module was doing. Why?
• Would it make more sense for nuxt-kit to be a peer dependency rather than dependency?

[kazupon]

• Why include the yarn binary in the repo? I'm sure there are theoretical benefits to using very specific versions of the tools but is it really worth it? Binaries in repos are feel wrong to me.

Yeah, I don't really want to include binary (generated js code) either... However, if you will try yarn migration step by step, you'll see that yarn actually recommends including binary...

I prefer pnpm as the package manager uses less disk, installs faster, and is compatible with npm, but nuxt bridge / nuxt 3 is not supported completely at this time 😢

For this reason, I’ve chosen yarn, which is also used in the nuxt framework project.

• You've decided to use mocha for testing rather than jest like this module was doing. Why?

I’ve chosen mocha as the reason because it is faster to run tests than jest and it works well with tests using ES Modules.

jest is a testing framework that includes test runner, mock, and snapshot. This is why it is very useful out of the box.
However, as the number of tests increases, the test execution time is slow. Especially, when there are snapshot tests, it's slow.
Also jest lags behind in supporting ES Modules, so it is difficult to test es modules first in nuxt bridge / nuxt 3 and vite.

On the other hand, mocha is test runner, and we will be using other libraries such as chai and sinon.
There are no limitations on ES Modules in these libraries.

As for snapshot, you can implement snapshot helper by yourself by using the plugin in the case of chai.
For reference, here is a helper that I implemented snapshot myself with using chai 😃
https://github.com/intlify/cli/blob/main/test/helper.ts

For timely information, vite team members are preparing an alternative test library with support for ES modules.
https://twitter.com/antfu7/status/1467179992245481472

When it is released, it will be worth a try. 😉

• Would it make more sense for nuxt-kit to be a peer dependency rather than dependency?

I don't know if it should be peer dependencies or not.
I think we should consider it after the nuxt kit (nuxt3) is officially released.

[rchl]

Yeah, I don't really want to include binary (generated js code) either... However, if you will try yarn migration step by step, you'll see that yarn actually recommends including binary...

I suppose that's the way go if you want to use yarn 2 now.
I've been sticking with yarn 1 for now since that's the latest stable version.

I prefer pnpm as the package manager uses less disk

I would prefer not to switch to something else as most of the Nuxt ecosystem uses Yarn. And at work I'm using npm so that's enough package managers. :)

I’ve chosen mocha as the reason because it is faster to run tests than jest and it works well with tests using ES Modules.

OK. I don't mind too much I guess. Though the bottleneck with the @nuxt/i18n tests wasn't the runner itself but the fact that it had to compile dozens of fixtures.

Thanks for all very clear answers. :)

[rchl]

One more thing. The 80 chars limit for prettier seems a bit restrictive. I would either remove the limit and leave to the discretion of the developer or at least set it to 120.

[psycongaroo]

Hi!
Any news about nuxt bridge support?

[kazupon]

Sorry for the lack of updates to nuxt/i18n for a while now.
I’m working on the i18n routing core i18n routing library at my GitHub organization.
When I prototyped nuxt/i18n for nuxt 3, I noticed that it could be used not only as the Nuxt module but also as Vue plugin if it is more generalized.
With this background, I focus on the core library so that it can be built-in into nuxt/i18n.

That library will be supported nuxt bridge.

[fellz]

Hi, is there any way to use i18n module for nuxt3 now ? I tried to add https://github.com/nuxt-community/i18n-module/tree/next like yarn add https://github.com/nuxt-community/i18n-module#next which gives an error. Can't add "@nuxt/i18n-monorepo": invalid package version undefined (yarn 1.22.17). @kazupon

[nivv]

Any news on this? I'm on a nuxt 2 project using nuxt-bridge and vite.

I've been using below for developing. Running nuxi dev works fine, routing and all.

"dependencies": {
    "@nuxtjs/i18n": "npm:@nuxtjs/i18n-edge"
}

When building/preparing for production I get the below error:

↳ yarn build
yarn run v1.22.17
$ nuxi build
Nuxt CLI v3.0.0-27439932.78761c2                                                                                                                                                09:28:21

 FATAL  Cannot find module '/Users/albin/code/project.se/node_modules/vue-i18n-bridge/dist/vue-i18n-bridge-runtime.esm-bundler.js'

If I check the node_modules folder for vue-i18n-bridge-runtime.esm-bundler.js it is indeed missing. Any ideas? As stated before, running development works fine.

I tried to install vue-i18-bridge separately and then the vue-i18n-bridge-runtime.esm-bundler.js is present.

@kazupon

[GMartigny]

I don't know how you manage to make it worked when it clearly say that it doesn't support bridge. Do you have any pointers ?

[jozefvodicka]

Use version 7.X for Nuxt Bridge. Latest version 8.x as @GMartigny is pointing out, dropped support for Nuxt Bridge.

[kazupon]

Since the beginning of March, I have not been able to work much on OSS development these days due to family matter reasons. I will settle down soon 🙇‍♂️

[szulcus]

@kazupon Any updates? What should I do now if I use Nuxt2 + Nuxt Bridge and want to access reactive variables $i18n, localePath etc?

[neversaynever88]

@kazupon Any updates? What should I do now if I use Nuxt2 + Nuxt Bridge

[jozefvodicka]

Use version 7.X for Nuxt Bridge. Latest version 8.x as @GMartigny is pointing out, dropped support for Nuxt Bridge.