feat: add support for working with locale

packages/docs/src/routes/docs/advanced/i18n/index.mdx

@@ -0,0 +1,61 @@
+---
+title: Internationalization
+contributors:
+  - mhevery
+---
+
+# 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](https://github.com/mhevery/qwik-i18n)
+- [qwik-speak](https://github.com/robisim74/qwik-speak)

packages/docs/src/routes/docs/menu.md

@@ -39,6 +39,7 @@
 - [QRL](advanced/qrl/index.mdx)
 - [Qwikloader](advanced/qwikloader/index.mdx)
 - [Custom Build Directory](advanced/custom-build-dir/index.mdx)
+- [Internationalization](advanced/i18n/index.mdx)
 
 ## Community
 

packages/qwik-city/buildtime/vite/dev-server.ts

@@ -54,6 +54,7 @@ export function ssrDevMiddleware(ctx: BuildContext, server: ViteDevServer) {
   return async (req: Connect.IncomingMessage, res: ServerResponse, next: Connect.NextFunction) => {
     try {
       const url = new URL(req.originalUrl!, `http://${req.headers.host}`);
+      const requestHeaders: Record<string, string> = req.headers as any;
 
       if (skipRequest(url.pathname) || isVitePing(url.pathname, req.headers)) {
         next();
@@ -102,7 +103,7 @@ export function ssrDevMiddleware(ctx: BuildContext, server: ViteDevServer) {
 
           if (userResponse.type === 'pagedata') {
             // dev server endpoint handler
-            await pageHandler(requestCtx, userResponse, noopDevRender);
+            await pageHandler('dev', requestCtx, userResponse, noopDevRender);
             return;
           }
 
@@ -114,7 +115,12 @@ export function ssrDevMiddleware(ctx: BuildContext, server: ViteDevServer) {
 
           // qwik city vite plugin should handle dev ssr rendering
           // but add the qwik city user context to the response object
-          const envData = getQwikCityEnvData(userResponse);
+          const envData = getQwikCityEnvData(
+            requestHeaders,
+            userResponse,
+            requestCtx.locale,
+            'dev'
+          );
           if (ctx.isDevServerClientOnly) {
             // because we stringify this content for the client only
             // dev server, there's some potential stringify issues

packages/qwik-city/middleware/cloudflare-pages/index.ts

@@ -31,6 +31,7 @@ export function createQwikCity(opts: QwikCityCloudflarePagesOptions) {
       }
 
       const requestCtx: QwikCityRequestContext<Response> = {
+        locale: undefined,
         url,
         request,
         response: (status, headers, body) => {
@@ -74,7 +75,7 @@ export function createQwikCity(opts: QwikCityCloudflarePagesOptions) {
       };
 
       // send request to qwik city request handler
-      const handledResponse = await requestHandler<Response>(requestCtx, opts);
+      const handledResponse = await requestHandler<Response>('server', requestCtx, opts);
       if (handledResponse) {
         return handledResponse;
       }

packages/qwik-city/middleware/netlify-edge/index.ts

@@ -22,6 +22,7 @@ export function createQwikCity(opts: QwikCityNetlifyOptions) {
     }
     try {
       const requestCtx: QwikCityRequestContext<Response> = {
+        locale: undefined,
         url: new URL(request.url),
         request,
         response: (status, headers, body) => {
@@ -58,7 +59,7 @@ export function createQwikCity(opts: QwikCityNetlifyOptions) {
       };
 
       // send request to qwik city request handler
-      const handledResponse = await requestHandler<Response>(requestCtx, opts);
+      const handledResponse = await requestHandler<Response>('server', requestCtx, opts);
       if (handledResponse) {
         return handledResponse;
       }

packages/qwik-city/middleware/node/http.ts

@@ -61,6 +61,7 @@ export function fromNodeHttp(url: URL, req: IncomingMessage, res: ServerResponse
       ssr: true,
       node: process.versions.node,
     },
+    locale: undefined,
   };
 
   return requestCtx;

packages/qwik-city/middleware/node/index.ts

@@ -23,7 +23,7 @@ export function createQwikCity(opts: QwikCityNodeRequestOptions) {
     try {
       const requestCtx = fromNodeHttp(getUrl(req), req, res);
       try {
-        const rsp = await requestHandler(requestCtx, opts);
+        const rsp = await requestHandler('server', requestCtx, opts);
         if (!rsp) {
           next();
         }

packages/qwik-city/middleware/request-handler/page-handler.ts

@@ -6,12 +6,17 @@ import type {
   RenderResult,
   RenderToStringResult,
 } from '@builder.io/qwik/server';
-import type { ClientPageData, QwikCityEnvData } from '../../runtime/src/library/types';
+import type {
+  ClientPageData,
+  QwikCityEnvData,
+  QwikCityMode,
+} from '../../runtime/src/library/types';
 import { getErrorHtml } from './error-handler';
 import { HttpStatus } from './http-status-codes';
 import type { QwikCityRequestContext, UserResponseContext } from './types';
 
 export function pageHandler<T = any>(
+  mode: QwikCityMode,
   requestCtx: QwikCityRequestContext,
   userResponse: UserResponseContext,
   render: Render,
@@ -21,6 +26,8 @@ export function pageHandler<T = any>(
   const { status, headers } = userResponse;
   const { response } = requestCtx;
   const isPageData = userResponse.type === 'pagedata';
+  const requestHeaders: Record<string, string> = {};
+  requestCtx.request.headers.forEach((value, key) => (requestHeaders[key] = value));
 
   if (isPageData) {
     // page data should always be json
@@ -35,7 +42,7 @@ export function pageHandler<T = any>(
     try {
       const result = await render({
         stream: isPageData ? noopStream : stream,
-        envData: getQwikCityEnvData(userResponse),
+        envData: getQwikCityEnvData(requestHeaders, userResponse, requestCtx.locale, mode),
         ...opts,
       });
 
@@ -132,14 +139,24 @@ function getPrefetchBundleNames(result: RenderResult, routeBundleNames: string[]
   return bundleNames;
 }
 
-export function getQwikCityEnvData(userResponse: UserResponseContext): {
+export function getQwikCityEnvData(
+  requestHeaders: Record<string, string>,
+  userResponse: UserResponseContext,
+  locale: string | undefined,
+  mode: QwikCityMode
+): {
   url: string;
+  requestHeaders: Record<string, string>;
+  locale: string | undefined;
   qwikcity: QwikCityEnvData;
 } {
   const { url, params, pendingBody, resolvedBody, status } = userResponse;
   return {
     url: url.href,
+    requestHeaders: requestHeaders,
+    locale: locale,
     qwikcity: {
+      mode: mode,
       params: { ...params },
       response: {
         body: pendingBody || resolvedBody,

packages/qwik-city/middleware/request-handler/request-handler.ts

@@ -1,15 +1,17 @@
 import { loadRoute } from '../../runtime/src/library/routing';
-import { loadUserResponse, updateRequestCtx } from './user-response';
-import type { QwikCityRequestContext, QwikCityHandlerOptions } from './types';
-import { errorHandler, ErrorResponse, errorResponse } from './error-handler';
+import type { QwikCityMode } from '../../runtime/src/library/types';
 import { endpointHandler } from './endpoint-handler';
+import { errorHandler, ErrorResponse, errorResponse } from './error-handler';
 import { pageHandler } from './page-handler';
 import { RedirectResponse, redirectResponse } from './redirect-handler';
+import type { QwikCityHandlerOptions, QwikCityRequestContext } from './types';
+import { loadUserResponse, updateRequestCtx } from './user-response';
 
 /**
  * @alpha
  */
 export async function requestHandler<T = any>(
+  mode: QwikCityMode,
   requestCtx: QwikCityRequestContext,
   opts: QwikCityHandlerOptions
 ): Promise<T | null> {
@@ -43,6 +45,7 @@ export async function requestHandler<T = any>(
       }
 
       const pageResult = await pageHandler(
+        mode,
         requestCtx,
         userResponse,
         render,

packages/qwik-city/middleware/request-handler/test-utils.ts

@@ -38,7 +38,7 @@ export function mockRequestContext(opts?: {
     });
   };
 
-  return { url, request, response, responseData, platform: { testing: true } };
+  return { url, request, response, responseData, platform: { testing: true }, locale: undefined };
 }
 
 export interface TestQwikCityRequestContext extends QwikCityRequestContext {
@@ -47,6 +47,7 @@ export interface TestQwikCityRequestContext extends QwikCityRequestContext {
     headers: Headers;
     body: any;
   };
+  locale: string | undefined;
 }
 
 export async function wait() {

packages/qwik-city/middleware/request-handler/types.ts

@@ -12,6 +12,7 @@ export interface QwikCityRequestContext<T = any> {
   response: ResponseHandler<T>;
   url: URL;
   platform: Record<string, any>;
+  locale: string | undefined;
 }
 
 export interface QwikCityDevRequestContext extends QwikCityRequestContext {

packages/qwik-city/middleware/request-handler/user-response.ts

@@ -132,6 +132,12 @@ export async function loadUserResponse(
           get headers() {
             return userResponse.headers;
           },
+          get locale() {
+            return requestCtx.locale;
+          },
+          set locale(locale) {
+            requestCtx.locale = locale;
+          },
           redirect,
           error,
         };

packages/qwik-city/runtime/src/api.md

@@ -73,6 +73,8 @@ export interface DocumentHeadProps<T = unknown> extends RouteLocation {
     data: T;
     // (undocumented)
     head: ResolvedDocumentHead;
+    // (undocumented)
+    withLocale: <T>(fn: () => T) => T;
 }
 
 // @alpha (undocumented)
@@ -233,6 +235,7 @@ export interface ResponseContext {
     // Warning: (ae-forgotten-export) The symbol "ErrorResponse" needs to be exported by the entry point index.d.ts
     readonly error: (status: number) => ErrorResponse;
     readonly headers: Headers;
+    locale: string | undefined;
     // Warning: (ae-forgotten-export) The symbol "RedirectResponse" needs to be exported by the entry point index.d.ts
     readonly redirect: (url: string, status?: number) => RedirectResponse;
     status: number;

packages/qwik-city/runtime/src/library/head.ts

@@ -1,3 +1,4 @@
+import { withLocale } from '@builder.io/qwik';
 import type {
   ContentModule,
   RouteLocation,
@@ -11,20 +12,25 @@ import type {
 export const resolveHead = (
   endpoint: EndpointResponse | ClientPageData | undefined | null,
   routeLocation: RouteLocation,
-  contentModules: ContentModule[]
+  contentModules: ContentModule[],
+  locale: string
 ) => {
   const head = createDocumentHead();
   const headProps: DocumentHeadProps = {
     data: endpoint ? endpoint.body : null,
     head,
+    withLocale: (fn) => withLocale(locale, fn),
     ...routeLocation,
   };
 
   for (let i = contentModules.length - 1; i >= 0; i--) {
     const contentModuleHead = contentModules[i] && contentModules[i].head;
     if (contentModuleHead) {
       if (typeof contentModuleHead === 'function') {
-        resolveDocumentHead(head, contentModuleHead(headProps));
+        resolveDocumentHead(
+          head,
+          withLocale(locale, () => contentModuleHead(headProps))
+        );
       } else if (typeof contentModuleHead === 'object') {
         resolveDocumentHead(head, contentModuleHead);
       }

packages/qwik-city/runtime/src/library/qwik-city-component.tsx

@@ -5,6 +5,7 @@ import {
   Slot,
   useContextProvider,
   useEnvData,
+  getLocale,
   useStore,
   useWatch$,
 } from '@builder.io/qwik';
@@ -93,8 +94,9 @@ export const QwikCity = component$<QwikCityProps>(() => {
   useContextProvider(RouteNavigateContext, routeNavigate);
 
   useWatch$(async ({ track }) => {
+    const locale = getLocale('');
     const { routes, menus, cacheModules } = await import('@qwik-city-plan');
-    const path = track(routeNavigate, 'path');
+    const path = track(() => routeNavigate.path);
     const url = new URL(path, routeLocation.href);
     const pathname = url.pathname;
 
@@ -121,7 +123,7 @@ export const QwikCity = component$<QwikCityProps>(() => {
       contentInternal.contents = noSerialize(contentModules);
 
       const clientPageData = await endpointResponse;
-      const resolvedHead = resolveHead(clientPageData, routeLocation, contentModules);
+      const resolvedHead = resolveHead(clientPageData, routeLocation, contentModules, locale);
 
       // Update document head
       documentHead.links = resolvedHead.links;

packages/qwik-city/runtime/src/library/types.ts

@@ -132,6 +132,7 @@ export interface DocumentStyle {
 export interface DocumentHeadProps<T = unknown> extends RouteLocation {
   data: T;
   head: ResolvedDocumentHead;
+  withLocale: <T>(fn: () => T) => T;
 }
 
 /**
@@ -247,6 +248,13 @@ export interface ResponseContext {
    */
   status: number;
 
+  /**
+   * Which locale the content is in.
+   *
+   * The locale value can be retrieved from selected methods using `getLocale()`:
+   */
+  locale: string | undefined;
+
   /**
    * HTTP response headers.
    *
@@ -346,10 +354,13 @@ export interface StaticGenerate {
 export interface QwikCityRenderDocument extends Document {}
 
 export interface QwikCityEnvData {
+  mode: QwikCityMode;
   params: RouteParams;
   response: EndpointResponse;
 }
 
+export type QwikCityMode = 'dev' | 'static' | 'server';
+
 export type GetEndpointData<T> = T extends RequestHandler<infer U> ? U : T;
 
 export interface SimpleURL {