Improve Paraglide docs

[NilsJacobsen]

from https://github.com/inlang/monorepo/issues/1667

Problem

Feedback from @KraXen72: "i am not sure if this is the relevant issue for it, but it took me an hour or two to figure the following things out:

• npx @inlang/paraglide-js@latest init is apparently either supposed to install @inlang/paraglide-js to your project (even though npx does not imply installation usually, or you are supposed to instlal it manually (not mentioned anywhere). i ran the command with the pnpm package manager, pnpm dlx @inlang/paraglide-js@latest init and while it did set up the inlang project sucessfully, it did not add the dependency. also, is @inlang/paraglide-js supposed to be instlled as a devDependency or normal one?
• it took me very long to figure out the import from ./paraglide-js/messages is intentional (it is also wrong) what worked for me was importing form (whatever relative path to src is)/paraglide/messages (not paraglide-js) no where it is mentioned that inlang compilation creates a folder called paraglide in the source folder upon build i think the init script should automatically add an alias (vite or sveltekit alias, idk about other frameworks tho) to src/paraglide as something like $paraglide or @paraglide, and you should mention that this is an implicity created, invisible folder
• in the svelte summit talk, you guys mentioned that there are several translation formats supported, but only json works so far - but i see yaml is being tracked too, so that's good. would be nice to see more formats down the road"

@inlang/martketplace-infrastructure @inlang/paraglide-js

[NilsJacobsen]

I feel like we do need information when things happen under the hood. Maybe we can add collapsable element where we can go into detail without polluting the pages. What do you think?

[LorisSigrist]

A collapsible Element for an FAQ style section would be very convenient.

I'll rewrite the Docs to address the points listed above. (also the init command is supposed to add it as a devDependency, we might have a bug)

[NilsJacobsen]

If you need custom elements ping me or @flornkm we handle that so you should only work on the md file

[flornkm]

A collapsible Element for an FAQ style section would be very convenient.

This was proposed very often. @LorisSigrist how urgent is it to have this element / when do you plan to use it? @NilsJacobsen I can implement the element, that's fine

[LorisSigrist]

I don't need it urgently, I can do an FAQ by just listing out everything. It's more of a nice to have

[KraXen72]

thank you guys <33

[samuelstroschein]

npx @inlang/paraglide-js@latest init

Prompts to run pnpm,npm, yarn install after completion. Seems like @KraXen72 overread this. Question: How can we make this more prominent?

i think the init script should automatically add an alias (vite or sveltekit alias, idk about other frameworks tho) to src/paraglide as something like $paraglide or @paraglide, and you should mention that this is an implicity created, invisible folder

Disagree. It opens a the box of pandora:

• doesn't work in plain JS
• might work for framework A but not framework B
• requires changes to both tsconfig and vite, rollup, turbopack, webpack config

[KraXen72]

understandable. however, atleast a few of the most popular bundlers could offer adding an alias. there are a lot of people using vite nowadays, and it supports asiases. or atleast mention how it all works, with the compiled paraglide directory or just mention in the docs that explain the file structure that you can easily add an alias in your bundler

now that i re-rad the init command in a test repo, it does indeed show that you should run install. but the paraglide-js dependency still gets added to dependencies (when using pnpm), instead of devDependencies - unless thats to be expected

[LorisSigrist]

The worry we have with automatically configuring aliases is that it would be a lot of technical complexity, and it would need to be purpose built for each bundler / framework causing a lot of work.

Expanding the documentation to better inform people about the output directory, and then suggest adding an alias is the way to go.

now that i re-rad the init command in a test repo, it does indeed show that you should run install. but the paraglide-js dependency still gets added to dependencies (when using pnpm), instead of devDependencies - unless thats to be expected

The fix for that is already merged and will be in the next prerelease You can safely move paraglide to devDependencies if you like

[NilsJacobsen]

@KraXen72 if you want you can leave feedback on the update of PR #1715

[KraXen72]

left some feedback. it is a big improvement!

[KraXen72]

very nice. however, i still thing there should be a link to auto-generated, latest API docs in https://inlang.com/m/gerre34r/library-inlang-paraglideJs#runtime

this looks pretty good: https://github.com/blakmatrix/vitepress-jsdoc

also, i found out you can literallly use jsdoc (the api documentation generator) by jsdoc (the github organization), who created jsdoc (the doc comments in js), to generate an api documentation site

https://github.com/jsdoc/jsdoc

another option would be something handrolled that nicely integrates into inlang.com. you can take a look at the dependencies of vitepress-jsdoc, but i think https://www.npmjs.com/package/jsdoc-to-markdown does most of the heavy lifting.

[LorisSigrist]

Agreed, auto-generating the docs would be nicer & more robust. We would need to do the work to integrate the auto-generated docs into the website, and in the meantime doing it manually is better than not having it :)

Definitely a nice-to have for the future!