feat: support multi-language kirby sites

johannschopplich · johannschopplich · commit c012bf41e07f · 2022-07-22T10:16:36.000+02:00
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -86,6 +86,7 @@ function sidebarGuide(): DefaultTheme.SidebarGroup[] {
       collapsible: true,
       items: [
         { text: 'Token-Based Authentication', link: '/guide/token-authentication' },
+        { text: 'Multi-Language Sites', link: '/guide/multi-language-sites' },
       ],
     },
     {
diff --git a/docs/api/kql.md b/docs/api/kql.md
@@ -9,7 +9,7 @@ Query responses are cached by default.
 ```ts
 function $kql<T extends KirbyQueryResponse = KirbyQueryResponse>(
   query: KirbyQueryRequest,
-  options: KqlOptions = {},
+  opts: KqlOptions = {},
 ): Promise<T>
 
 interface KqlOptions {
@@ -19,6 +19,14 @@ interface KqlOptions {
    * @default true
    */
   cache?: boolean
+  /**
+   * Language code to fetch data for in multilang Kirby setups
+   */
+  language?: string
+  /**
+   * Custom headers to send with the request
+   */
+  headers?: HeadersInit
 }
 ```
 
diff --git a/docs/api/public-kql.md b/docs/api/public-kql.md
@@ -15,7 +15,15 @@ function $publicKql<T extends KirbyQueryResponse = KirbyQueryResponse>(
 ): Promise<T>
 
 // `FetchOptions` imported from `ohmyfetch`
-type PublicKqlOptions = Omit<FetchOptions, 'baseURL' | 'body' | 'params' | 'parseResponse' | 'responseType' | 'response'>
+type PublicKqlOptions = Omit<
+  FetchOptions,
+  'baseURL' | 'body' | 'params' | 'parseResponse' | 'responseType' | 'response'
+> & {
+  /**
+   * Language code to fetch data for in multilang Kirby setups
+   */
+  language?: string
+}
 ```
 
 ## Example
diff --git a/docs/api/use-kql.md b/docs/api/use-kql.md
@@ -12,7 +12,7 @@ function useKql<
   ReqT extends KirbyQueryRequest = KirbyQueryRequest,
 >(query: Ref<ReqT> | ReqT, opts?: UseKqlOptions<ResT>): AsyncData<ResT, true | Error>
 
-export type UseKqlOptions<T> = Omit<
+type UseKqlOptions<T> = Omit<
   UseFetchOptions<T>,
   | 'baseURL'
   | 'params'
@@ -22,7 +22,12 @@ export type UseKqlOptions<T> = Omit<
   | 'response'
   | 'transform'
   | keyof Omit<globalThis.RequestInit, 'headers'>
->
+> & {
+  /**
+   * Language code to fetch data for in multilang Kirby setups
+   */
+  language?: string
+}
 ```
 
 `useKql` infers all of Nuxt's [`useAsyncData` options](https://v3.nuxtjs.org/api/composables/use-async-data#params).
diff --git a/docs/api/use-public-kql.md b/docs/api/use-public-kql.md
@@ -16,7 +16,7 @@ function usePublicKql<
   ReqT extends KirbyQueryRequest = KirbyQueryRequest,
 >(query: Ref<ReqT> | ReqT, opts?: UseKqlOptions<ResT>): AsyncData<ResT, true | Error>
 
-export type UseKqlOptions<T> = Omit<
+type UseKqlOptions<T> = Omit<
   UseFetchOptions<T>,
   | 'baseURL'
   | 'params'
@@ -26,7 +26,12 @@ export type UseKqlOptions<T> = Omit<
   | 'response'
   | 'transform'
   | keyof Omit<globalThis.RequestInit, 'headers'>
->
+> & {
+  /**
+   * Language code to fetch data for in multilang Kirby setups
+   */
+  language?: string
+}
 ```
 
 `usePublicKql` infers all of Nuxt's [`useAsyncData` options](https://v3.nuxtjs.org/api/composables/use-async-data#params).
diff --git a/docs/guide/multi-language-sites.md b/docs/guide/multi-language-sites.md
@@ -0,0 +1,55 @@
+# Multi-Language Sites
+
+`nuxt-kql` comes with built-in support for multi-language Kirby sites. For this to work, you will have to use the [kirby-headless-starter](https://github.com/johannschopplich/kirby-headless-starter), which provides a custom KQL endpoint to retrieve translated content.
+
+To fetch language-specific content from your Kirby instance, pass a `language` option with your query request for every language but the primary one.
+
+Take the following example to fetch data from the about page, where `en` is the default language, `de` the secondary one. The `en` slug is called `about`, the `de` slug `ueber-uns`.
+
+```ts
+// Since `en` is the default language, the `language` option isn't needed
+const { data } = await useKql({
+  query: 'kirby.page("home")'
+})
+
+// For the `de` slug to be found, add the `language` option
+const { data } = await useKql(
+  {
+    query: 'kirby.page("ueber-uns")'
+  },
+  {
+    language: 'de'
+  }
+)
+```
+
+## Dynamic Routes
+
+You will probably use some kind of dynamic routes in your Nuxt application. To make your life easier fetching translated content, you can create a `useLocaleSlug` composable to extract both a page's `slug` and its language code:
+
+```ts
+// `/composables/language.ts`
+
+// Extract language code and slug from path
+export function useLocaleSlug(path: string) {
+  const segments = path.split('/').filter(i => i !== '')
+
+  return {
+    language: segments[0],
+    slug: segments.slice(1).join('/'),
+  }
+}
+```
+
+Now you can simplify your templates. For example in `/pages/[...id].vue`:
+
+```vue
+<script setup lang="ts">
+const route = useRoute()
+const { language, slug } = useLocaleSlug(route.path)
+
+const { data } = await useKql({
+  query: `kirby.page("${slug}")`
+}, { language })
+</script>
+```
diff --git a/src/runtime/composables/$kql.ts b/src/runtime/composables/$kql.ts
@@ -1,4 +1,5 @@
 import { hash } from 'ohash'
+import { headersToObject } from '../utils'
 import type { KirbyQueryRequest, KirbyQueryResponse } from '#nuxt-kql'
 import { useNuxtApp } from '#imports'
 import { apiRoute } from '#build/nuxt-kql/options'
@@ -10,15 +11,29 @@ export interface KqlOptions {
    * @default true
    */
   cache?: boolean
+  /**
+   * Language code to fetch data for in multilang Kirby setups
+   */
+  language?: string
+  /**
+   * Custom headers to send with the request
+   */
+  headers?: HeadersInit
 }
 
 export function $kql<T extends KirbyQueryResponse = KirbyQueryResponse>(
   query: KirbyQueryRequest,
-  options: KqlOptions = {},
+  opts: KqlOptions = {},
 ): Promise<T> {
-  const body = { query }
+  const body = {
+    query,
+    headers: {
+      ...headersToObject(opts.headers),
+      ...(opts.language ? { 'X-Language': opts.language } : {}),
+    },
+  }
 
-  if (options.cache === false) {
+  if (opts.cache === false) {
     return $fetch<T>(apiRoute, {
       method: 'POST',
       body,
diff --git a/src/runtime/composables/$publicKql.ts b/src/runtime/composables/$publicKql.ts
@@ -4,7 +4,15 @@ import { getAuthHeaders, headersToObject } from '../utils'
 import type { KirbyQueryRequest, KirbyQueryResponse } from '#nuxt-kql'
 import { useRuntimeConfig } from '#imports'
 
-export type PublicKqlOptions = Omit<FetchOptions, 'baseURL' | 'body' | 'params' | 'parseResponse' | 'responseType' | 'response'>
+export type PublicKqlOptions = Omit<
+  FetchOptions,
+  'baseURL' | 'body' | 'params' | 'parseResponse' | 'responseType' | 'response'
+> & {
+  /**
+   * Language code to fetch data for in multilang Kirby setups
+   */
+  language?: string
+}
 
 export function $publicKql<T extends KirbyQueryResponse = KirbyQueryResponse>(
   query: KirbyQueryRequest,
@@ -23,6 +31,7 @@ export function $publicKql<T extends KirbyQueryResponse = KirbyQueryResponse>(
     headers: {
       ...headersToObject(opts.headers),
       ...getAuthHeaders(kql as ModuleOptions),
+      ...(opts.language ? { 'X-Language': opts.language } : {}),
     },
   })
 }
diff --git a/src/runtime/composables/useKql.ts b/src/runtime/composables/useKql.ts
@@ -3,6 +3,7 @@ import { hash } from 'ohash'
 import type { Ref } from 'vue'
 import type { NitroFetchRequest } from 'nitropack'
 import type { AsyncData, UseFetchOptions } from 'nuxt/app'
+import { headersToObject } from '../utils'
 import type { KirbyQueryRequest, KirbyQueryResponse } from '#nuxt-kql'
 import { useFetch } from '#imports'
 import { apiRoute } from '#build/nuxt-kql/options'
@@ -17,7 +18,12 @@ export type UseKqlOptions<T> = Omit<
   | 'response'
   | 'transform'
   | keyof Omit<globalThis.RequestInit, 'headers'>
->
+> & {
+  /**
+   * Language code to fetch data for in multilang Kirby setups
+   */
+  language?: string
+}
 
 export function useKql<
   ResT extends KirbyQueryResponse = KirbyQueryResponse,
@@ -34,7 +40,10 @@ export function useKql<
     method: 'POST',
     body: {
       query: _query.value,
-      headers: opts.headers,
+      headers: {
+        ...headersToObject(opts.headers),
+        ...(opts.language ? { 'X-Language': opts.language } : {}),
+      },
     },
   }) as AsyncData<ResT, true | Error>
 }
diff --git a/src/runtime/composables/usePublicKql.ts b/src/runtime/composables/usePublicKql.ts
@@ -18,7 +18,12 @@ export type UseKqlOptions<T> = Omit<
   | 'response'
   | 'transform'
   | keyof Omit<globalThis.RequestInit, 'headers'>
->
+> & {
+  /**
+   * Language code to fetch data for in multilang Kirby setups
+   */
+  language?: string
+}
 
 export function usePublicKql<
   ResT extends KirbyQueryResponse = KirbyQueryResponse,
@@ -43,6 +48,8 @@ export function usePublicKql<
     headers: {
       ...headersToObject(opts.headers),
       ...getAuthHeaders(kql as ModuleOptions),
+      ...(opts.language ? { 'X-Language': opts.language } : {}),
+
     },
   }) as AsyncData<ResT, true | Error>
 }

Original file line number	Diff line number	Diff line change
`@@ -86,6 +86,7 @@ function sidebarGuide(): DefaultTheme.SidebarGroup[] {`
`86`	`86`	`collapsible: true,`
`87`	`87`	`items: [`
`88`	`88`	`{ text: 'Token-Based Authentication', link: '/guide/token-authentication' },`
	`89`	`+ { text: 'Multi-Language Sites', link: '/guide/multi-language-sites' },`
`89`	`90`	`],`
`90`	`91`	`},`
`91`	`92`	`{`