[RFC] paraglide js prototyping outcome

[samuelstroschein]

Outcome

• 80 lines of runtime code
• simple to maintain, adapt to different frameworks, and tiny (600 bytes gzipped)
• feature-rich: typesafe, lazy fetching, SSR

📺 5 min explanation video

Context

i18n libraries are complicated due to a) only send messages to the user that are rendered and b) making lazy loading of messages work with SSR.

The SvelteKit SDK (now renamed to paraglide JS) leveraged complicated AST transforms to achieve a and b, which led to complexity on the library side. Other i18n libraries push complexity to the user scope with namespaces or other manual tricks. Both AST transforms and manual interventions can't be the solution. Namespaces, for example, require coordination between developers, translators, designers, etc. A substantial operating complexity.

Long story short, we re-evaluated our and other i18n approaches and came up with an 80 line code runtime implementation, which seems to solve a and b with unprecedented simplicity.

Architecture

• compiled messages, enabling dynamic imports
• leveraging reactivity to re-render once an import resolves
• bundlers split messages into chunks automatically

1. The messages are compiled to JS

Paraglide is embedded in the build step and compiles messages into JS. Having the messages in JS enables dynamic imports, provides type safety out the box (and also leads performance gains because no runtime interpolation logic is required but that is negalactable).

export default (params: { name: string; count: number }) =>
	`Hello ${params.name}! You have ${params.count} messages.`

2. The lookup function lazy imports messages as required

The breakthrough comes from treating the lookup function m as synchronous function which itself listens to resolved imports. Upon resolved imports, the function triggers a re-render.

// pseudocode
export const m = derived([currentLanguageTag, pendingImports], ([$tag, $pendingPromises]) => {
	return (id: string, params: Record<string, any>): string => {
		// message exists in sync 
		// -> render
		if (messages[id]?.[$tag]) {
			return messages[id][$tag](params)
		}
		// message doesn't exist and hasn't been imported yet
                // -> import the message, re-render once resolved
		else if ($pendingPromises[id] === undefined) {
			importMessage(id, $tag)
		}
	}
})

3. (SSR pre-imports all messages)

The lookup function m is synchronous, if messages have been imported. Thus, SSR works out of the box by importing all messages on the server where size has no impact anyway.

await preImportMessages()

Code

The paraglide-prototyping contains multiple prototypes. The here presented prototype is the sveltekit-function one.

Open questions

1. How to avoid hydration flickering?

See minute 3:10

[samuelstroschein]

@dominikg do you have an idea on how to remove the hydration flickering?

[samuelstroschein]

We know in a server context what messages have been rendered. In theory, we could pass the messages to the client. I don't know how though without a layout file. Ideally, we can state in server.hook.ts that "those messages have been rendered, statically import them on the client"

[samuelstroschein]

CSR routing can be unexpected as messages are rendered after the initial load

Run 1 is simulating slow 3G
Run 2 is running with full speed.

CleanShot.2023-09-19.at.22.22.15.mp4

[samuelstroschein]

@LorisSigrist replied on twitter https://x.com/loris_sigrist/status/1740097689058971964?s=20.

TLDR

• per language splitting is coming
• in the meantime, parglide js is the smallest library

[osdiab]

@samuelstroschein great to hear—I am curious how it will work, is there any discussion somewhere talking about the approach this library would take? Just can't really imagine how the current arrangement would lend to it and the types of API changes it would entail. Thanks!

[LorisSigrist]

The plan is to replace the import * as m from "./paraglide/messages.js" with the language-specific import * as m from "./paraglide/messages/en.js" during build & build translated pages multiple times for each language. We're currently talking with the maintainers of several popular frameworks to make this possible.

[osdiab]

Any updates on whether or not such discussions are making progress? It does worry me a bit to switch to paraglide that this would require cooperation/special sauce from other projects for it to potentially work.

[LorisSigrist]

We're documenting the progress / approaches we're trying in this issue. Subscribe to that for updates
opral/inlang-paraglide-js#88