Internationalization

Internationalization is a complex problem. Qwik does not solve the internationalization problem directly instead it only provides low-level APIs to allow other libraries to solve it.

Runtime vs compile time translation

At a high level there are two ways in which the translation problem can be solved:

• Runtime: load a translation map and look up the translations at runtime.
• Compile time: Have a compile step inline the translations into the output string.

Both of the above approaches have trade-offs that one should take into consideration.

The advantages of runtime approaches are:

• Simplicity. Does not require an additional build step.

Disadvantages of the runtime approach are:

• Each string is present in triplicate:
  1. Once as the original string in the code.
  2. Once as a key in a translation map.
  3. Once as a translated value in the translation map.
• The tools don't know how to break up the translation map, for this reason, the whole translation map must be loaded eagerly on application startup. This is a problem because it undoes the effort Qwik put into breaking up and lazy load your codebase. In addition because translation maps are not broken up, the browser will download unnecessary translations. For example, translations for static components that will never re-render on the client.
• There is a runtime cost to translation lookups.

The advantages of compile-time approaches are:

• Qwik's lazy loading of code now extends to the lazy loading of translation strings. (No unnecessary translation text is loaded)
• No runtime translation map means strings are not in triplicate.

Disadvantages of compile time approaches are:

• Extra build step.
• Changing languages requires a page reload.

Recommendation

With the above in mind, Qwik recommends that you use a tool that best fits your constraints. To help you make a decision there are three different considerations: Browser, Server, and Development.

Browser

Qwik's goal is to deliver the best possible user experience. It achieves this by deferring the loading of code to later so that the initial startup performance is not overwhelmed. Because the runtime approach requires eager loading of all translations, we don't recommend this approach. We think that the compile-time approach is best for the browser.

Server

The server does not have the constraint of lazy loading. For this reason, the server can use either the runtime or compiled approach. The disadvantage of compile time approach on the server is that we need to have a separate deployment for each translation. This complicates the deployment process as well as puts greater demand on number of servers. For this reason, we think the runtime approach is preferable on the server.

Development

During development, fewer build steps will result in a faster turnaround. For this reason, runtime translation should result in a simpler development workflow.

Our Recommendation

Our recommendation is to use a tool that would provide a runtime approach on the server, and runtime or compile time on the client depending on whether we are in development or production. This way it is possible to prove the best user experience and development experience, and use the least server resources.

Internationalization libraries

• $localize
• qwik-speak