docus 4.0.0-beta.8 → 4.0.0

package/README.md

@@ -14,6 +14,7 @@ This is the official Nuxt layer for [Docus](https://docus.dev), providing a comp
 - ✨ **Beautiful Design** - Clean, modern documentation theme
 - 📱 **Responsive** - Mobile-first responsive design
 - 🌙 **Dark Mode** - Built-in dark/light mode support
+- 🌍 **Internationalization** - Native i18n support with automatic routing and language switching
 - 🔍 **Search** - Full-text search functionality
 - 📝 **Markdown Enhanced** - Extended markdown with custom components
 - 🎨 **Customizable** - Easy theming and customization
@@ -46,6 +47,13 @@ npm run dev
 
 This creates a complete documentation project pre-configured with `docus`.
 
+For multi-language documentation, use the i18n template:
+
+```bash
+# Create a new i18n documentation project
+npx create docus my-docs -t i18n
+```
+
 ### Option 2: Manual Setup
 
 #### Option 2a: Nuxt Config (recommended)
@@ -58,6 +66,21 @@ export default defineNuxtConfig({
 })
 ```
 
+For internationalization, also add the `@nuxtjs/i18n` module:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/i18n'],
+  i18n: {
+    defaultLocale: 'en',
+    locales: [
+      { code: 'en', name: 'English' },
+      { code: 'fr', name: 'Français' },
+    ],
+  }
+})
+```
+
 #### Option 2b: CLI Usage 
 
 Use directly with Nuxt CLI:

package/app/app.config.ts

@@ -29,7 +29,4 @@ export default defineAppConfig({
       },
     },
   },
-  toc: {
-    title: 'On this page',
-  },
 })

package/app/app.vue

@@ -1,11 +1,25 @@
 <script setup lang="ts">
+import type { PageCollections } from '@nuxt/content'
+import * as locales from '@nuxt/ui-pro/locale'
+
 const { seo } = useAppConfig()
 const site = useSiteConfig()
 
-const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('docs'), {
-  transform: data => data.find(item => item.path === '/docs')?.children || data || [],
+const { locale, isEnabled } = useDocusI18n()
+
+const lang = computed(() => locales[locale.value as keyof typeof locales]?.code || 'en')
+const dir = computed(() => locales[locale.value as keyof typeof locales]?.dir || 'ltr')
+const collectionName = computed(() => isEnabled.value ? `docs_${locale.value}` : 'docs')
+
+const { data: navigation } = await useAsyncData(`navigation_${collectionName.value}`, () => queryCollectionNavigation(collectionName.value as keyof PageCollections), {
+  transform: (data) => {
+    const rootResult = data.find(item => item.path === '/docs')?.children || data || []
+
+    return rootResult.find(item => item.path === `/${locale.value}`)?.children || rootResult
+  },
+  watch: [locale],
 })
-const { data: files } = useLazyAsyncData('search', () => queryCollectionSearchSections('docs'), {
+const { data: files } = useLazyAsyncData(`search_${collectionName.value}`, () => queryCollectionSearchSections(collectionName.value as keyof PageCollections), {
   server: false,
 })
 
@@ -17,7 +31,8 @@ useHead({
     { rel: 'icon', href: '/favicon.ico' },
   ],
   htmlAttrs: {
-    lang: 'en',
+    lang,
+    dir,
   },
 })
 
@@ -33,7 +48,7 @@ provide('navigation', navigation)
 </script>
 
 <template>
-  <UApp>
+  <UApp :locale="locales[locale as keyof typeof locales]">
     <NuxtLoadingIndicator color="var(--ui-primary)" />
 
     <AppHeader />

package/app/components/LanguageSelect.vue

@@ -0,0 +1,82 @@
+<script setup lang="ts">
+const { locale, locales, switchLocalePath } = useDocusI18n()
+
+function getEmojiFlag(locale: string): string {
+  const languageToCountry: Record<string, string> = {
+    ar: 'sa', // Arabic -> Saudi Arabia
+    bn: 'bd', // Bengali -> Bangladesh
+    ca: 'es', // Catalan -> Spain
+    ckb: 'iq', // Central Kurdish -> Iraq
+    cs: 'cz', // Czech -> Czech Republic (note: modern country code is actually 'cz')
+    da: 'dk', // Danish -> Denmark
+    el: 'gr', // Greek -> Greece
+    en: 'gb', // English -> Great Britain
+    et: 'ee', // Estonian -> Estonia
+    he: 'il', // Hebrew -> Israel
+    hi: 'in', // Hindi -> India
+    hy: 'am', // Armenian -> Armenia
+    ja: 'jp', // Japanese -> Japan
+    kk: 'kz', // Kazakh -> Kazakhstan
+    km: 'kh', // Khmer -> Cambodia
+    ko: 'kr', // Korean -> South Korea
+    ky: 'kg', // Kyrgyz -> Kyrgyzstan
+    lb: 'lu', // Luxembourgish -> Luxembourg
+    ms: 'my', // Malay -> Malaysia
+    nb: 'no', // Norwegian Bokmål -> Norway
+    sl: 'si', // Slovenian -> Slovenia
+    sv: 'se', // Swedish -> Sweden
+    uk: 'ua', // Ukrainian -> Ukraine
+    ur: 'pk', // Urdu -> Pakistan
+    vi: 'vn', // Vietnamese -> Vietnam
+  }
+
+  const baseLanguage = locale.split('-')[0]?.toLowerCase() || locale
+  const countryCode = languageToCountry[baseLanguage] || locale.replace(/^.*-/, '').slice(0, 2)
+
+  return countryCode.toUpperCase()
+    .split('')
+    .map(char => String.fromCodePoint(0x1F1A5 + char.charCodeAt(0)))
+    .join('')
+}
+</script>
+
+<template>
+  <UPopover
+    mode="hover"
+    :content="{ align: 'end' }"
+  >
+    <UButton
+      color="neutral"
+      variant="ghost"
+      class="size-8"
+    >
+      <template #trailing>
+        <span class="text-lg">
+          {{ getEmojiFlag(locale) }}
+        </span>
+      </template>
+    </UButton>
+
+    <template #content>
+      <ul class="flex flex-col gap-2">
+        <li
+          v-for="localeItem in locales"
+          :key="localeItem.code"
+        >
+          <NuxtLink
+            class="flex justify-between py-2 px-1.5 gap-1 hover:bg-neutral-100 dark:hover:bg-neutral-800"
+            :to="switchLocalePath(localeItem.code) as string"
+            :aria-label="localeItem.name"
+          >
+            <span class="text-sm">
+              {{ localeItem.name }}
+            </span>
+            <span class="size-5 text-center">
+              {{ getEmojiFlag(localeItem.code) }}
+            </span>
+          </NuxtLink>
+        </li>
+      </ul>
+    </template>
+  </UPopover>
+</template>

package/app/components/app/AppHeader.vue

@@ -1,7 +1,11 @@
 <script setup lang="ts">
+import { useDocusI18n } from '../../composables/useDocusI18n'
+
 const appConfig = useAppConfig()
 const site = useSiteConfig()
 
+const { localePath, isEnabled } = useDocusI18n()
+
 const links = computed(() => appConfig.github?.url
   ? [
       {
@@ -17,7 +21,7 @@ const links = computed(() => appConfig.github?.url
 <template>
   <UHeader
     :ui="{ center: 'flex-1' }"
-    to="/"
+    :to="localePath('/')"
     :title="appConfig.header?.title || site.name"
   >
     <AppHeaderCenter />
@@ -29,9 +33,30 @@ const links = computed(() => appConfig.github?.url
     <template #right>
       <AppHeaderCTA />
 
+      <template v-if="isEnabled">
+        <ClientOnly>
+          <LanguageSelect />
+
+          <template #fallback>
+            <div class="h-8 w-8 animate-pulse bg-neutral-200 dark:bg-neutral-800 rounded-md" />
+          </template>
+        </ClientOnly>
+
+        <USeparator
+          orientation="vertical"
+          class="h-8"
+        />
+      </template>
+
       <UContentSearchButton class="lg:hidden" />
 
-      <UColorModeButton />
+      <ClientOnly>
+        <UColorModeButton />
+
+        <template #fallback>
+          <div class="h-8 w-8 animate-pulse bg-neutral-200 dark:bg-neutral-800 rounded-md" />
+        </template>
+      </ClientOnly>
 
       <template v-if="links?.length">
         <UButton

package/app/components/docs/DocsAsideRightBottom.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 const appConfig = useAppConfig()
+const { t } = useDocusI18n()
 </script>
 
 <template>
@@ -10,7 +11,7 @@ const appConfig = useAppConfig()
     <USeparator type="dashed" />
 
     <UPageLinks
-      :title="appConfig.toc?.bottom?.title || 'Links'"
+      :title="appConfig.toc?.bottom?.title || t('docs.links')"
       :links="appConfig.toc?.bottom?.links"
     />
   </div>

package/app/components/docs/DocsPageHeaderLinks.vue

@@ -4,9 +4,9 @@ import { useClipboard } from '@vueuse/core'
 const route = useRoute()
 const toast = useToast()
 const { copy, copied } = useClipboard()
+const { t } = useDocusI18n()
 
 const markdownLink = computed(() => `${window?.location?.origin}/raw${route.path}.md`)
-
 const items = [
   {
     label: 'Copy Markdown link',
@@ -15,44 +15,49 @@ const items = [
       copy(markdownLink.value)
 
       toast.add({
-        title: 'Markdown link copied to clipboard',
+        title: t('docs.copy.link'),
         icon: 'i-lucide-check-circle',
         color: 'success',
       })
     },
   },
   {
-    label: 'View as Markdown',
+    label: t('docs.copy.view'),
     icon: 'i-simple-icons:markdown',
     target: '_blank',
     to: markdownLink.value,
   },
   {
-    label: 'Open in ChatGPT',
+    label: t('docs.copy.gpt'),
     icon: 'i-simple-icons:openai',
     target: '_blank',
     to: `https://chatgpt.com/?hints=search&q=${encodeURIComponent(`Read ${markdownLink.value} so I can ask questions about it.`)}`,
   },
   {
-    label: 'Open in Claude',
+    label: t('docs.copy.claude'),
     icon: 'i-simple-icons:anthropic',
     target: '_blank',
     to: `https://claude.ai/new?q=${encodeURIComponent(`Read ${markdownLink.value} so I can ask questions about it.`)}`,
   },
 ]
+
+async function copyPage() {
+  const page = await $fetch<string>(`/raw${route.path}.md`)
+  copy(page)
+}
 </script>
 
 <template>
   <UButtonGroup size="sm">
     <UButton
-      label="Copy page"
+      :label="t('docs.copy.page')"
       :icon="copied ? 'i-lucide-copy-check' : 'i-lucide-copy'"
       color="neutral"
       variant="outline"
       :ui="{
         leadingIcon: [copied ? 'text-primary' : 'text-neutral', 'size-3.5'],
       }"
-      @click="copy(markdownLink)"
+      @click="copyPage"
     />
 
     <UDropdownMenu

package/app/composables/useDocusI18n.ts

@@ -0,0 +1,31 @@
+import en from '../../i18n/locales/en.json'
+
+export const useDocusI18n = () => {
+  const config = useRuntimeConfig().public
+  const isEnabled = ref(!!config.i18n)
+
+  if (!isEnabled.value) {
+    return {
+      isEnabled,
+      locale: ref('en'),
+      locales: ref([]),
+      localePath: (path: string) => path,
+      switchLocalePath: () => {},
+      t: (key: string): string => {
+        const path = key.split('.')
+        return path.reduce((acc: unknown, curr) => (acc as Record<string, unknown>)?.[curr], en) as string
+      },
+    }
+  }
+
+  const { locale, locales, t } = useI18n()
+
+  return {
+    isEnabled,
+    locale,
+    locales,
+    t,
+    localePath: useLocalePath(),
+    switchLocalePath: useSwitchLocalePath(),
+  }
+}

package/app/error.vue

@@ -16,12 +16,12 @@ useSeoMeta({
   description: 'We are sorry but this page could not be found.',
 })
 
-const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('docs'))
-const { data: files } = useLazyAsyncData('search', () => queryCollectionSearchSections('docs'), {
-  server: false,
-})
+// const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('docs'))
+// const { data: files } = useLazyAsyncData('search', () => queryCollectionSearchSections('docs'), {
+//   server: false,
+// })
 
-provide('navigation', navigation)
+// provide('navigation', navigation)
 </script>
 
 <template>
@@ -33,10 +33,10 @@ provide('navigation', navigation)
     <AppFooter />
 
     <ClientOnly>
-      <LazyUContentSearch
+      <!-- <LazyUContentSearch
         :files="files"
         :navigation="navigation"
-      />
+      /> -->
     </ClientOnly>
   </UApp>
 </template>

package/app/pages/{[...slug].vue → [[lang]]/[...slug].vue}

@@ -1,21 +1,24 @@
 <script setup lang="ts">
 import { kebabCase } from 'scule'
-import type { ContentNavigationItem } from '@nuxt/content'
+import type { ContentNavigationItem, Collections, DocsCollectionItem } from '@nuxt/content'
 import { findPageHeadline } from '@nuxt/content/utils'
-import { addPrerenderPath } from '../utils/prerender'
+import { addPrerenderPath } from '../../utils/prerender'
 
 definePageMeta({
   layout: 'docs',
 })
 
 const route = useRoute()
+const { locale, isEnabled, t } = useDocusI18n()
 const appConfig = useAppConfig()
 const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')
 
+const collectionName = computed(() => isEnabled.value ? `docs_${locale.value}` : 'docs')
+
 const [{ data: page }, { data: surround }] = await Promise.all([
-  useAsyncData(kebabCase(route.path), () => queryCollection('docs').path(route.path).first()),
+  useAsyncData(kebabCase(route.path), () => queryCollection(collectionName.value as keyof Collections).path(route.path).first()),
   useAsyncData(`${kebabCase(route.path)}-surround`, () => {
-    return queryCollectionItemSurroundings('docs', route.path, {
+    return queryCollectionItemSurroundings(collectionName.value as keyof Collections, route.path, {
       fields: ['description'],
     })
   }),
@@ -71,7 +74,7 @@ const editLink = computed(() => {
     >
       <template #links>
         <UButton
-          v-for="(link, index) in page.links"
+          v-for="(link, index) in (page as DocsCollectionItem).links"
           :key="index"
           size="sm"
           v-bind="link"
@@ -100,9 +103,9 @@ const editLink = computed(() => {
             icon="i-lucide-pen"
             :ui="{ leadingIcon: 'size-4' }"
           >
-            Edit this page
+            {{ t('docs.edit') }}
           </UButton>
-          or
+          <span>{{ t('common.or') }}</span>
           <UButton
             variant="link"
             color="neutral"
@@ -111,7 +114,7 @@ const editLink = computed(() => {
             icon="i-lucide-alert-circle"
             :ui="{ leadingIcon: 'size-4' }"
           >
-            Report an issue
+            {{ t('docs.report') }}
           </UButton>
         </div>
       </USeparator>
@@ -124,7 +127,7 @@ const editLink = computed(() => {
     >
       <UContentToc
         highlight
-        :title="appConfig.toc?.title || 'Table of Contents'"
+        :title="appConfig.toc?.title || t('docs.toc')"
         :links="page.body?.toc?.links"
       >
         <template #bottom>

package/app/pages/{index.vue → [[lang]]/index.vue}

@@ -1,5 +1,12 @@
 <script setup lang="ts">
-const { data: page } = await useAsyncData('index', () => queryCollection('landing').path('/').first())
+import type { Collections } from '@nuxt/content'
+
+const route = useRoute()
+const { locale, isEnabled } = useDocusI18n()
+
+const collectionName = computed(() => isEnabled.value ? `landing_${locale.value}` : 'landing')
+
+const { data: page } = await useAsyncData(collectionName.value, () => queryCollection(collectionName.value as keyof Collections).path(route.path).first())
 if (!page.value) {
   throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
 }

package/content.config.ts

@@ -1,12 +1,50 @@
+import type { DefinedCollection } from '@nuxt/content'
 import { defineContentConfig, defineCollection, z } from '@nuxt/content'
 import { useNuxt } from '@nuxt/kit'
 import { joinURL } from 'ufo'
 
 const { options } = useNuxt()
 const cwd = joinURL(options.rootDir, 'content')
+const locales = options.i18n?.locales
 
-export default defineContentConfig({
-  collections: {
+const createDocsSchema = () => z.object({
+  links: z.array(z.object({
+    label: z.string(),
+    icon: z.string(),
+    to: z.string(),
+    target: z.string().optional(),
+  })).optional(),
+})
+
+let collections: Record<string, DefinedCollection>
+
+if (locales && Array.isArray(locales)) {
+  collections = {}
+  for (const locale of locales) {
+    const code = typeof locale === 'string' ? locale : locale.code
+
+    collections[`landing_${code}`] = defineCollection({
+      type: 'page',
+      source: {
+        cwd,
+        include: `${code}/index.md`,
+      },
+    })
+
+    collections[`docs_${code}`] = defineCollection({
+      type: 'page',
+      source: {
+        cwd,
+        include: `${code}/**/*.md`,
+        prefix: `/${code}`,
+        exclude: [`${code}/index.md`],
+      },
+      schema: createDocsSchema(),
+    })
+  }
+}
+else {
+  collections = {
     landing: defineCollection({
       type: 'page',
       source: {
@@ -21,14 +59,9 @@ export default defineContentConfig({
         include: '**',
         exclude: ['index.md'],
       },
-      schema: z.object({
-        links: z.array(z.object({
-          label: z.string(),
-          icon: z.string(),
-          to: z.string(),
-          target: z.string().optional(),
-        })).optional(),
-      }),
+      schema: createDocsSchema(),
     }),
-  },
-})
+  }
+}
+
+export default defineContentConfig({ collections })

package/i18n/i18n.config.ts

@@ -0,0 +1,15 @@
+export default defineI18nConfig(async () => {
+  const config = useRuntimeConfig().public
+
+  const messages: Record<string, Record<string, never>> = {}
+  await Promise.all(
+    config.i18n.locales.map(async (locale) => {
+      const localeFile = await import(`./locales/${locale.code}.json`)
+      messages[locale.code] = localeFile.default
+    }),
+  )
+
+  return {
+    messages,
+  }
+})

package/i18n/locales/en.json

@@ -0,0 +1,18 @@
+{
+  "common": {
+    "or": "or"
+  },
+  "docs": {
+    "copy": {
+      "page": "Copy page",
+      "link": "Copy Markdown page",
+      "view": "View as Markdown",
+      "gpt": "Open in ChatGPT",
+      "claude": "Open in Claude"
+    },
+    "links": "Community",
+    "toc": "On this page",
+    "report": "Report an issue",
+    "edit": "Edit this page"
+  }
+}

package/i18n/locales/fr.json

@@ -0,0 +1,18 @@
+{
+  "common": {
+    "or": "ou"
+  },
+  "docs": {
+    "copy": {
+      "page": "Copier la page",
+      "link": "Copier la page Markdown",
+      "view": "Voir en Markdown",
+      "gpt": "Ouvrir dans ChatGPT",
+      "claude": "Ouvrir dans Claude"
+    },
+    "links": "Communauté",
+    "toc": "Sur cette page",
+    "report": "Signaler un problème",
+    "edit": "Éditer cette page"
+  }
+} 

package/modules/default-configs.ts

@@ -50,5 +50,16 @@ export default defineNuxtModule({
     nuxt.options.appConfig.toc = defu(nuxt.options.appConfig.toc, {
       title: 'On this page',
     })
+
+    /*
+    ** I18N
+    */
+    if (nuxt.options.i18n && nuxt.options.i18n.locales) {
+      // Override strategy to prefix
+      nuxt.options.i18n = {
+        ...nuxt.options.i18n,
+        strategy: 'prefix',
+      }
+    }
   },
 })

package/nuxt.config.ts

@@ -4,6 +4,7 @@ const { resolve } = createResolver(import.meta.url)
 
 export default defineNuxtConfig({
   modules: [
+    resolve('./modules/default-configs'),
     '@nuxt/ui-pro',
     '@nuxt/content',
     '@nuxt/image',

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "docus",
   "description": "Nuxt layer for Docus documentation theme",
-  "version": "4.0.0-beta.8",
+  "version": "4.0.0",
   "type": "module",
   "main": "./nuxt.config.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nuxtlabs/docus.git"
+  },
   "private": false,
+  "license": "MIT",
   "files": [
     "app",
+    "i18n",
     "content.config.ts",
     "modules",
     "nuxt.config.ts",
@@ -22,20 +28,22 @@
     "@nuxt/content": "^3.6.3",
     "@nuxt/image": "^1.10.0",
     "@nuxt/kit": "^4.0.1",
-    "@nuxt/ui-pro": "^3.2.0",
+    "@nuxt/ui-pro": "^3.3.0",
+    "@nuxtjs/i18n": "^10.0.3",
     "@nuxtjs/mdc": "^0.17.2",
     "@nuxtjs/robots": "^5.4.0",
     "@vueuse/core": "^13.5.0",
     "defu": "^6.1.4",
     "git-url-parse": "^16.1.0",
     "minimark": "^0.2.0",
-    "motion-v": "^1.6.0",
+    "motion-v": "^1.6.1",
     "nuxt-llms": "^0.1.3",
     "nuxt-og-image": "^5.1.9",
     "pkg-types": "^2.2.0",
     "scule": "^1.3.0",
     "tailwindcss": "^4.1.11",
-    "ufo": "^1.6.1"
+    "ufo": "^1.6.1",
+    "unist-util-visit": "^5.0.0"
   },
   "peerDependencies": {
     "better-sqlite3": "12.x",

package/server/routes/raw/[...slug].md.get.ts

@@ -1,6 +1,7 @@
 import { withLeadingSlash } from 'ufo'
 import { stringify } from 'minimark/stringify'
 import { queryCollection } from '@nuxt/content/nitro'
+import type { Collections } from '@nuxt/content'
 
 export default eventHandler(async (event) => {
   const slug = getRouterParams(event)['slug.md']
@@ -9,7 +10,26 @@ export default eventHandler(async (event) => {
   }
 
   const path = withLeadingSlash(slug.replace('.md', ''))
-  const page = await queryCollection(event, 'docs').path(path).first()
+  const config = useRuntimeConfig(event).public
+
+  let collectionName = 'docs'
+  if (config.i18n?.locales) {
+    const pathSegments = path.split('/').filter(Boolean)
+    const firstSegment = pathSegments[0]
+
+    const availableLocales = config.i18n.locales.map((locale: string | { code: string }) =>
+      typeof locale === 'string' ? locale : locale.code,
+    )
+
+    if (firstSegment && availableLocales.includes(firstSegment)) {
+      collectionName = `docs_${firstSegment}`
+    }
+    else if (config.i18n.defaultLocale) {
+      collectionName = `docs_${config.i18n.defaultLocale}`
+    }
+  }
+
+  const page = await queryCollection(event, collectionName as keyof Collections).path(path).first()
   if (!page) {
     throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
   }