Update docs & sample app

README.md

@@ -200,10 +200,10 @@ Translates a path, an URL or an array of paths. The translating string can be in
 Validate `language[-script][-region]`
 
 - `extractFromUrl(route: URL)`
-Extract lang from url
+Extract prefix from url
 
 - `extractFromDomain(route: URL, domains: SpeakLocale[] | RewriteRouteOption[])`
-Extract lang from domain
+Extract lang/prefix from domain
 
 ### Testing
 - `QwikSpeakMockProvider` component provides the Speak context to test enviroments

docs/quick-start.md

@@ -107,6 +107,11 @@ _src/routes/plugin.ts_
 import type { RequestHandler } from '@builder.io/qwik-city';
 import { config } from '../speak-config';
 
+/**
+ * This middleware function must only contain the logic to set the locale,
+ * because it is invoked on every request to the server.
+ * Avoid redirecting or throwing errors here, and prefer layouts or pages
+ */
 export const onRequest: RequestHandler = ({ request, locale }) => {
   const acceptLanguage = request.headers?.get('accept-language');
 

docs/tutorial-routing-rewrite.md

@@ -88,29 +88,49 @@ Update `plugin.ts` in the root of the `src/routes` directory:
 _src/routes/plugin.ts_
 ```typescript
 import type { RequestHandler } from "@builder.io/qwik-city";
-import { extractFromUrl, validateLocale } from 'qwik-speak';
+import { extractFromUrl, setSpeakContext, validateLocale } from 'qwik-speak';
 
 import { config } from '../speak-config';
 
-export const onRequest: RequestHandler = ({ locale, error, url }) => {
+/**
+ * This middleware function must only contain the logic to set the locale,
+ * because it is invoked on every request to the server.
+ * Avoid redirecting or throwing errors here, and prefer layouts or pages
+ */
+export const onRequest: RequestHandler = ({ locale, url }) => {
   let lang: string | undefined = undefined;
 
   const prefix = extractFromUrl(url);
 
   if (prefix && validateLocale(prefix)) {
     // Check supported locales
     lang = config.supportedLocales.find(value => value.lang === prefix)?.lang;
-    // 404 error page
-    if (!lang) throw error(404, 'Page not found');
   } else {
     lang = config.defaultLocale.lang;
   }
 
+  // Set Speak context (optional: set the configuration on the server)
+  setSpeakContext(config);
+
   // Set Qwik locale
   locale(lang);
 };
 ```
 
+If you want to handle errors or redirects due to the locale, use layouts or pages. For example you could add in `src/routes/layout.ts`:
+```typescript
+export const onRequest: RequestHandler = ({ locale, error, redirect }) => {
+  // E.g. 404 error page
+  if (!locale()) throw error(404, 'Page not found for requested locale');
+
+  // E.g. Redirect
+  // if (!locale()) {
+  //   const getPath = localizePath();
+  //   throw redirect(302, getPath('/page', 'en-US')); // Let the server know the language to use
+  // }
+};
+```
+
 ## Usage
 Add `index.tsx` with some translation, providing optional default values for each translation: `key@@[default value]`:
 
@@ -401,26 +421,27 @@ Since the `de` language does not have a default domain, but we have associated a
 Update `plugin.ts` to get the language from the domain:
 ```typescript
 import type { RequestHandler } from '@builder.io/qwik-city';
-import { extractFromDomain, extractFromUrl, validateLocale } from 'qwik-speak';
+import { extractFromDomain, extractFromUrl, setSpeakContext, validateLocale } from 'qwik-speak';
 
 import { config } from '../speak-config';
 import { rewriteRoutes } from '../speak-routes';
 
-export const onRequest: RequestHandler = ({ locale, error, url }) => {
+export const onRequest: RequestHandler = ({ locale, url }) => {
   let lang: string | undefined = undefined;
 
   const prefix = extractFromUrl(url);
 
   if (prefix && validateLocale(prefix)) {
     // Check supported locales
     lang = config.supportedLocales.find(value => value.lang === prefix)?.lang;
-    // 404 error page
-    if (!lang) throw error(404, 'Page not found');
   } else {
     // Extract from domain
     lang = extractFromDomain(url, rewriteRoutes) || config.defaultLocale.lang;
   }
 
+  // Set Speak context (optional: set the configuration on the server)
+  setSpeakContext(config);
+
   // Set Qwik locale
   locale(lang);
 };

docs/tutorial-routing.md

@@ -24,27 +24,47 @@ Now let's handle it. Update `plugin.ts` in the root of the `src/routes` director
 _src/routes/plugin.ts_
 ```typescript
 import type { RequestHandler } from '@builder.io/qwik-city';
-import { validateLocale } from 'qwik-speak';
+import { setSpeakContext, validateLocale } from 'qwik-speak';
 
 import { config } from '../speak-config';
 
-export const onRequest: RequestHandler = ({ params, locale, error }) => {
+/**
+ * This middleware function must only contain the logic to set the locale,
+ * because it is invoked on every request to the server.
+ * Avoid redirecting or throwing errors here, and prefer layouts or pages
+ */
+export const onRequest: RequestHandler = ({ params, locale }) => {
   let lang: string | undefined = undefined;
 
   if (params.lang && validateLocale(params.lang)) {
     // Check supported locales
     lang = config.supportedLocales.find(value => value.lang === params.lang)?.lang;
-    // 404 error page
-    if (!lang) throw error(404, 'Page not found');
   } else {
     lang = config.defaultLocale.lang;
   }
 
+  // Set Speak context (optional: set the configuration on the server)
+  setSpeakContext(config);
+
   // Set Qwik locale
   locale(lang);
 };
 ```
 
+If you want to handle errors or redirects due to the locale, use layouts or pages. For example you could add in `src/routes/layout.ts`:
+```typescript
+export const onRequest: RequestHandler = ({ locale, error, redirect }) => {
+  // E.g. 404 error page
+  if (!locale()) throw error(404, 'Page not found for requested locale');
+
+  // E.g. Redirect
+  // if (!locale()) {
+  //   const getPath = localizePath();
+  //   throw redirect(302, getPath('/page', 'en-US')); // Let the server know the language to use
+  // }
+};
+```
+
 ## Usage
 Add `index.tsx` with some translation, providing optional default values for each translation: `key@@[default value]`:
 
@@ -271,23 +291,24 @@ Since the `de` language does not have a default domain, but we have associated a
 Update `plugin.ts` to get the language from the domain:
 ```typescript
 import type { RequestHandler } from '@builder.io/qwik-city';
-import { extractFromDomain, validateLocale } from 'qwik-speak';
+import { extractFromDomain, setSpeakContext, validateLocale } from 'qwik-speak';
 
 import { config } from '../speak-config';
 
-export const onRequest: RequestHandler = ({ params, locale, error, url }) => {
+export const onRequest: RequestHandler = ({ params, locale, url }) => {
   let lang: string | undefined = undefined;
 
   if (params.lang && validateLocale(params.lang)) {
     // Check supported locales
     lang = config.supportedLocales.find(value => value.lang === params.lang)?.lang;
-    // 404 error page
-    if (!lang) throw error(404, 'Page not found');
    } else {
     // Extract from domain
     lang = extractFromDomain(url, config.supportedLocales) || config.defaultLocale.lang;
   }
 
+  // Set Speak context (optional: set the configuration on the server)
+  setSpeakContext(config);
+
   // Set Qwik locale
   locale(lang);
 };

src/routes/layout.tsx

@@ -1,6 +1,9 @@
 import { component$, Slot } from '@builder.io/qwik';
+import type { RequestHandler } from '@builder.io/qwik-city';
 
 import { Header } from '../components/header/header';
+// import { localizePath } from '../../packages/qwik-speak/src/routing';
+// import { config } from '../speak-config';
 
 export default component$(() => {
   return (
@@ -10,3 +13,14 @@ export default component$(() => {
     </main>
   );
 });
+
+export const onRequest: RequestHandler = ({ locale, error }) => {
+  // E.g. 404 error page
+  if (!locale()) throw error(404, 'Page not found for requested locale');
+
+  // E.g. Redirect
+  // if (!locale()) {
+  //   const getPath = localizePath();
+  //   throw redirect(302, getPath('/page', 'en-US')); // Let the server know the language to use
+  // }
+};

src/routes/plugin.ts

@@ -1,21 +1,27 @@
 import type { RequestHandler } from '@builder.io/qwik-city';
-import { validateLocale } from 'qwik-speak';
+import { setSpeakContext, validateLocale } from 'qwik-speak';
 
 import { config } from '../speak-config';
 //import { rewriteRoutes } from '../speak-routes';
 
-export const onRequest: RequestHandler = ({ params, locale, error }) => {
+/**
+ * This middleware function must only contain the logic to set the locale,
+ * because it is invoked on every request to the server.
+ * Avoid redirecting or throwing errors here, and prefer layouts or pages
+ */
+export const onRequest: RequestHandler = ({ params, locale }) => {
   let lang: string | undefined = undefined;
 
   if (params.lang && validateLocale(params.lang)) {
     // Check supported locales
     lang = config.supportedLocales.find(value => value.lang === params.lang)?.lang;
-    // 404 error page
-    if (!lang) throw error(404, 'Page not found');
   } else {
     lang = config.defaultLocale.lang;
   }
 
+  // Set Speak context (optional: set the configuration on the server)
+  setSpeakContext(config);
+
   // Set Qwik locale
   locale(lang);
 };
@@ -24,20 +30,21 @@ export const onRequest: RequestHandler = ({ params, locale, error }) => {
  * Uncomment this lines to use url rewriting to translate paths.
  * Remove [..lang] from folders structure
  */
-// export const onRequest: RequestHandler = ({ locale, error, url }) => {
+// export const onRequest: RequestHandler = ({ locale, url }) => {
 //   let lang: string | undefined = undefined;
 
 //   const prefix = extractFromUrl(url);
 
 //   if (prefix && validateLocale(prefix)) {
 //     // Check supported locales
 //     lang = config.supportedLocales.find(value => value.lang === prefix)?.lang;
-//     // 404 error page
-//     if (!lang) throw error(404, 'Page not found');
 //   } else {
 //     lang = config.defaultLocale.lang;
 //   }
 
+//   // Set Speak context (optional: set the configuration on the server)
+//   setSpeakContext(config);
+
 //   // Set Qwik locale
 //   locale(lang);
 // };