I18n support proposition

[agsoto]

Hello! This is the draft we talked about on #82. Key considerations I had for the changes:

• Keeping components code under packages to be reusable
• Maintaining configuration consistent with both site and Astro config files
• Trying to make sure the update won't introduce any breaking changes
• Providing a ready to use component approach for multilingual websites that appears only if there's i18n configuration

Caveats:

• Files under [lang] could be provided ready to use or just documented examples of how to use the features
• There are more file changes than I expected but many of them are just function calls
• There are still some chores and to-dos such as moving a few functions logic, unify lang property on markdown files, using translation functions or change components imports if those are merged
• Excuses in advance if there's any error on Zh translations! Those were created with online tools

I understand you're busy right now but I would like to know your thoughts on the approach when you have the time.
Thank you! 😃

[vercel]

@agsoto is attempting to deploy a commit to the cworld Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
astro-theme-pure	Ready	Preview, Comment	Dec 21, 2025 5:10pm

[cworld1]

22:22:37.146
 14:22:37 [ERROR] [build] Failed to call getStaticPaths for /en/[...slug]
22:22:37.287
 [GetStaticPathsRequired] `getStaticPaths()` function is required for dynamic routes. Make sure that you `export` a `getStaticPaths` function from your dynamic route.
22:22:37.287
   Hint:
22:22:37.288
     See https://docs.astro.build/en/guides/routing/#dynamic-routes for more information on dynamic routes.
22:22:37.288
     
22:22:37.288
     	If you meant for this route to be server-rendered, set `export const prerender = false;` in the page.
22:22:37.288
   Error reference:
22:22:37.288
     https://docs.astro.build/en/reference/errors/get-static-paths-required/
22:22:37.288
   Location:
22:22:37.289
     /en/[...slug]:0:0
22:22:37.289
   Stack trace:
22:22:37.289
     at validateDynamicRouteModule (file:///vercel/path0/node_modules/astro/dist/core/routing/validation.js:19:11)
22:22:37.289
     at getPathsForRoute (file:///vercel/path0/node_modules/astro/dist/core/build/generate.js:213:31)
22:22:37.289
     at async generatePages (file:///vercel/path0/node_modules/astro/dist/core/build/generate.js:99:7)
22:22:37.289
     at async AstroBuilder.build (file:///vercel/path0/node_modules/astro/dist/core/build/index.js:157:5)
22:22:37.289
     at async build (file:///vercel/path0/node_modules/astro/dist/core/build/index.js:45:3)
22:22:37.289
     at async runCommand (file:///vercel/path0/node_modules/astro/dist/cli/index.js:151:7)
22:22:37.325
 error: script "build" exited with code 1
22:22:37.329
 Error: Command "bun run build" exited with 1

[agsoto]

I tried to replicate the error on my machine changing configuration such as the Astro routing with prefixDefaultLocale: true and disabling redirections but still no similar error appears. Do you get the error on the home?

[cworld1]

I've never tried prefixDefaultLocale before. OK, the deployment looks good, with some warnings:

09:44:54   └─ /archives/index.html09:44:54 [WARN] `Astro.request.headers` was used when rendering the route `src/pages/archives/index.astro'`. `Astro.request.headers` is not available on prerendered pages. If you need access to request headers, make sure that the page is server-rendered using `export const prerender = false;` or by setting `output` to `"server"` in your Astro config to make all your pages server-rendered by default.

Can you making sure your code can work well with static mode? I mean, build it, and make a server like python http to test it

[cworld1]

Seems something not work well? I checked the deployment, something mixed the zh and es language, and seems cannot render content when the language is not the default ones. If you want the authentication of deployment, you can visit https://astro-theme-pure-n7se13krf-cworld.vercel.app/ and send me the request (you know, Vercel is good for personal usage, but has some limitations for collaboration on free account)

[agsoto]

I've never tried prefixDefaultLocale before. OK, the deployment looks good, with some warnings:

09:44:54   └─ /archives/index.html09:44:54 [WARN] `Astro.request.headers` was used when rendering the route `src/pages/archives/index.astro'`. `Astro.request.headers` is not available on prerendered pages. If you need access to request headers, make sure that the page is server-rendered using `export const prerender = false;` or by setting `output` to `"server"` in your Astro config to make all your pages server-rendered by default.

Can you making sure your code can work well with static mode? I mean, build it, and make a server like python http to test it

Sure, I'll do it in a new github repo just for dev-test purposes.

Seems something not work well? I checked the deployment, something mixed the zh and es language, and seems cannot render content when the language is not the default ones. If you want the authentication of deployment, you can visit https://astro-theme-pure-n7se13krf-cworld.vercel.app/ and send me the request (you know, Vercel is good for personal usage, but has some limitations for collaboration on free account)

Yep, I saw that it seems that the rendering order of nested components wouldn't compute the locale in the intended order, I pushed few more commits on that.

Regarding the content not rendering content other than default, I assume you're talking about getting 404 error page when you enter pages other than blog and there's a decision to make that I mentioned before. I can think of three approaches:

Option A

Duplicate the same pages structure under [lang]. Right now it's set only for the blog page and the home.
Pro: Internationalization would be ready to use and who doesn't want it, could just delete [lang] folder.
Con: Basically duplication of the pages in the repo.

Option B

Keep only pages under [lang].
Pro: Internationalization ready to use and no duplication.
Con: For those who don't want / need it and want to keep clean monolingual structure would have to create their own pages.

Option C

We leave only the backbones of internationalization along with helper functions, ready to use components and no [lang] pages by default.
Pro: Better for those who won't include internationalization.
Con: For those who want internationalization would have to create their own pages under [lang]

In summary: It's deciding how much of the feature would be usable out of the box.

Until this point only archive, tags and sitemap is remaining to be ready for review, I'll keep working on those later.

Sorry for the long reply I think it's important to discuss it, I will try the vercel request, thanks!

[agsoto]

Alright, there might be more options fixing the bug that was happening on npm run build, refactor on 6411929 provide routes for static output. Maybe there's chance for other options, but those would just automate the pages / folder structures duplication as variants of option A.

Edit: Warning on build is still present :S I'll have to find a solution replacing Astro.currentDefault

[cworld1]

Your code is starting to get bigger, which makes me confused about how you implement your features, that affects me to give you some indirect help that might be useful. It is better to read the official documentation carefully (I feel like I would get something new every time I read it), and the official example project starlight

[agsoto]

Hello! You were right to be suspicious, I realized some functions were re-implementations of Astro's i18n helpers. Looking at the docs and code of Starlight helped me a lot, thanks.
That explained just a bit of the PR size, there are other considerations:

• It was much more lines and effort than I thought, as you know there was many issues with static output
• First version was partial and in mutated considerably with also experimental features and some were dropped, that's why it was still as draft
• Many lines are from the JSON localization files and pages (those under /[lang] are almost identical)

Now I can offer a much more polished version:

• Using the most of i18n built in features
• Loading translation strings using collections and strings customization just as Starlight does
• Ensuring static output working (You can see it deployed on this test GH page)
• As a nice consequence of using functions to localize the links, those also create URLs considering trailingSlash and base path config

Is still remaining the work mentioned before regarding tags, archives and sitemap and the decision given the options in the previous comment. But for now it's ready to be reviewed. Let me know your thougths.

[cworld1]

Considering Starlight is a more complex and complete system, you might want to simplify things a bit. I'll might be very busy lately, but I'll try to review the code and consider merging as much as possible when I have some time😊

[cworld1]

A small warn when build:

04:38:30 [WARN] [glob-loader] The base directory "/vercel/path0/src/content/i18n/" does not exist.

[agsoto]

Indeed the Starlight project has a bunch of stuff, including the usage i18next. As you'll see the more complex thing on the PR is the translation strings part, which uses Astro's collections just like Starlight, the rest is mainly for the language switch and routing.
I'll continue then fixing the missing folder warning (this exists because them users can replace / extend translations putting the corresponding json files under /src/content/i18n/[lang or locale]).
Later I'll work on the remaining blog related parts such as tags and archives, trying to leave the big decisions at the end.

[cworld1]

plz consider rebase (if it is very hard for rebase, merge is also allowed) main branch with new coming commits. This will help us better accept your pr without a lot of conflicts. tk you again😉

[cworld1]

if you've done that work, you can tell me here. I will take the time to make better small changes

[agsoto]

I rebased a few times, last was until version 4.1, it seems those remaining conflicts are happening because a later update. These are busy dates for me but as soon as I rebase again I'll leave a message too

[agsoto]

@cworld1 Apparently there weren't many confusing conflicts, I rebased again with builds working fine. After the decision about including i18n ready pages in the template and your code review, maybe just doc updates would be left.

[cworld1]

Well, after spent so much time on making a lot of changes that don't matter, I decide to spent a whole version on your pr, and plan to release a pre-release version that can prevent bugs. You can continue to rebase all your work, and then I'll transfer your work in v4-1-3-beta branch. And again, thank you for your contribution!

[agsoto]

Hi @cworld1 Happy new year! I've just rebased again. Although changes are few, those are becoming more confusing to rebase and more bug prone. I see there's a few astro.config.ts conflicts but those changes were made after v4.1.2, I think it would be a good idea to merge ASAP and rebase the later changes from your side.

[cworld1]

If it is hard for you to use rebase, you can directly use git merge instead. And sorry I'll be busy in next a few days, for preparing exam :(

[agsoto]

@cworld1 I'm wondering if the changes are going to be merged next, as they supposed to be on v4.1.3? Otherwise I see no point on rebasing endlessly and we should rather drop and close the PR

[cworld1]

Sorry for that. I really like this feature in fact, but you know I haven't been able to find time recently, and some basic maintenance work still needs me to finish. In fact, v4.1.3 only makes basic maintenance and doesn't add any new substantial features.

[cworld1]

If you have patience, you can choose to close this PR first. And in the future, when I have time or interest, I will leave a message here inviting you to open a new collaboration. How about this?

[agsoto]

Let's keep this open then. I hope when you can dedicate some effort to this you will tag me here again, expecting I'll also provide help if needed for the merge ✌️