From 86d85c4ac48aadd79e040c7818fbd13525cf9aae Mon Sep 17 00:00:00 2001
From: ComicIvans <isalidocobo@gmail.com>
Date: Thu, 13 Nov 2025 21:34:47 +0100
Subject: [PATCH 1/5] feat(i18n): add Spanish (es) locale

---
 layer/i18n/locales/es.json | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 layer/i18n/locales/es.json

diff --git a/layer/i18n/locales/es.json b/layer/i18n/locales/es.json
new file mode 100644
index 000000000..74cc279a8
--- /dev/null
+++ b/layer/i18n/locales/es.json
@@ -0,0 +1,22 @@
+{
+  "common": {
+    "or": "o",
+    "error": {
+      "title": "Página no encontrada",
+      "description": "Lo sentimos, no se pudo encontrar esta página."
+    }
+  },
+  "docs": {
+    "copy": {
+      "page": "Copiar página",
+      "link": "Copiar página en Markdown",
+      "view": "Ver como Markdown",
+      "gpt": "Abrir en ChatGPT",
+      "claude": "Abrir en Claude"
+    },
+    "links": "Comunidad",
+    "toc": "En esta página",
+    "report": "Reportar un problema",
+    "edit": "Editar esta página"
+  }
+}

From 07092b754788438b0ada1d73064b10a94049e9be Mon Sep 17 00:00:00 2001
From: ComicIvans <isalidocobo@gmail.com>
Date: Fri, 14 Nov 2025 00:39:26 +0100
Subject: [PATCH 2/5] First try to enable changing single locale

---
 layer/app/app.config.ts                 |  1 +
 layer/app/app.vue                       |  8 ++++---
 layer/app/components/LanguageSelect.vue |  1 +
 layer/app/composables/useDocusI18n.ts   | 30 +++++++++++++++++++++++--
 layer/app/types/index.d.ts              |  1 +
 layer/nuxt.schema.ts                    |  7 ++++++
 6 files changed, 43 insertions(+), 5 deletions(-)

diff --git a/layer/app/app.config.ts b/layer/app/app.config.ts
index e81b4a401..ebc3e98da 100644
--- a/layer/app/app.config.ts
+++ b/layer/app/app.config.ts
@@ -1,4 +1,5 @@
 export default defineAppConfig({
+  locale: 'en',
   ui: {
     colors: {
       primary: 'emerald',
diff --git a/layer/app/app.vue b/layer/app/app.vue
index a1003cc2d..251b2fe91 100644
--- a/layer/app/app.vue
+++ b/layer/app/app.vue
@@ -6,8 +6,10 @@ const { seo } = useAppConfig()
 const site = useSiteConfig()
 const { locale, locales, isEnabled, switchLocalePath } = useDocusI18n()
 
-const lang = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales]?.code || 'en')
-const dir = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales]?.dir || 'ltr')
+const matchedUiLocale = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales])
+const uiLocale = computed(() => matchedUiLocale.value || nuxtUiLocales.en)
+const lang = computed(() => matchedUiLocale.value.code || 'en')
+const dir = computed(() => matchedUiLocale.value?.dir || 'ltr')
 const collectionName = computed(() => isEnabled.value ? `docs_${locale.value}` : 'docs')
 
 useHead({
@@ -58,7 +60,7 @@ provide('navigation', navigation)
 </script>
 
 <template>
-  <UApp :locale="nuxtUiLocales[locale as keyof typeof nuxtUiLocales]">
+  <UApp :locale="uiLocale">
     <NuxtLoadingIndicator color="var(--ui-primary)" />
 
     <AppHeader v-if="$route.meta.header !== false" />
diff --git a/layer/app/components/LanguageSelect.vue b/layer/app/components/LanguageSelect.vue
index 9f08ea05c..9f1952a62 100644
--- a/layer/app/components/LanguageSelect.vue
+++ b/layer/app/components/LanguageSelect.vue
@@ -28,6 +28,7 @@ function getEmojiFlag(locale: string): string {
     uk: 'ua', // Ukrainian -> Ukraine
     ur: 'pk', // Urdu -> Pakistan
     vi: 'vn', // Vietnamese -> Vietnam
+    es: 'es', // Spanish -> Spain
   }
 
   const baseLanguage = locale.split('-')[0]?.toLowerCase() || locale
diff --git a/layer/app/composables/useDocusI18n.ts b/layer/app/composables/useDocusI18n.ts
index 28feec563..15d838f26 100644
--- a/layer/app/composables/useDocusI18n.ts
+++ b/layer/app/composables/useDocusI18n.ts
@@ -1,20 +1,46 @@
 import type { LocaleObject } from '@nuxtjs/i18n'
 import en from '../../i18n/locales/en.json'
 
+type LocaleMessages = typeof en
+
+const localeFiles = import.meta.glob('../../i18n/locales/*.json', {
+  import: 'default',
+  eager: true,
+}) as Record<string, LocaleMessages>
+
+const localeMessages = Object.entries(localeFiles).reduce<Record<string, LocaleMessages>>((acc, [path, messages]) => {
+  const localeCode = path.split('/').pop()?.replace('.json', '')
+  if (localeCode) {
+    acc[localeCode] = messages
+  }
+  return acc
+}, {})
+
 export const useDocusI18n = () => {
   const config = useRuntimeConfig().public
+  const appConfig = useAppConfig()
   const isEnabled = ref(!!config.i18n)
 
   if (!isEnabled.value) {
+    const configuredLocale = appConfig.locale
+    const messages = localeMessages[configuredLocale]
+
+    if (!messages && configuredLocale !== 'en') {
+      console.warn(`[Docus] Missing locale file for "${configuredLocale}". Falling back to "en".`)
+    }
+
+    const locale = messages ? configuredLocale : 'en'
+    const resolvedMessages = messages || en
+
     return {
       isEnabled,
-      locale: ref('en'),
+      locale: ref(locale),
       locales: [],
       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
+        return path.reduce((acc: unknown, curr) => (acc as Record<string, unknown>)?.[curr], resolvedMessages) as string
       },
     }
   }
diff --git a/layer/app/types/index.d.ts b/layer/app/types/index.d.ts
index fb5a005b7..6ccc6725d 100644
--- a/layer/app/types/index.d.ts
+++ b/layer/app/types/index.d.ts
@@ -1,5 +1,6 @@
 declare module 'nuxt/schema' {
   interface AppConfig {
+    locale: string
     seo: {
       titleTemplate: string
       title: string
diff --git a/layer/nuxt.schema.ts b/layer/nuxt.schema.ts
index 209e8784e..2d9a920c6 100644
--- a/layer/nuxt.schema.ts
+++ b/layer/nuxt.schema.ts
@@ -2,6 +2,13 @@ import { field, group } from '@nuxt/content/preview'
 
 export default defineNuxtSchema({
   appConfig: {
+    locale: field({
+      type: 'string',
+      title: 'Locale',
+      description: 'Locale to use when @nuxtjs/i18n is not being used.',
+      icon: 'i-lucide-languages',
+      default: 'en',
+    }),
     ui: group({
       title: 'UI',
       description: 'UI Customization.',

From 2346417d0bafb920d8257e0d16810da6b321b931 Mon Sep 17 00:00:00 2001
From: ComicIvans <isalidocobo@gmail.com>
Date: Fri, 14 Nov 2025 12:36:57 +0100
Subject: [PATCH 3/5] Also set the locale in error pages

---
 layer/app/error.vue | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/layer/app/error.vue b/layer/app/error.vue
index 1ad556376..3c9faa23b 100644
--- a/layer/app/error.vue
+++ b/layer/app/error.vue
@@ -9,6 +9,9 @@ const props = defineProps<{
 
 const { locale, locales, isEnabled, t, switchLocalePath } = useDocusI18n()
 
+const matchedUiLocale = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales])
+const uiLocale = computed(() => matchedUiLocale.value || nuxtUiLocales.en)
+
 const lang = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales]?.code || 'en')
 const dir = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales]?.dir || 'ltr')
 useHead({
@@ -22,6 +25,7 @@ const localizedError = computed(() => {
   return {
     ...props.error,
     statusMessage: t('common.error.title'),
+    message: t('common.error.description'),
   }
 })
 
@@ -59,7 +63,7 @@ provide('navigation', navigation)
 </script>
 
 <template>
-  <UApp>
+  <UApp :locale="uiLocale">
     <AppHeader />
 
     <UError :error="localizedError" />

From 8c7b3ebc5b02f6d7885aefd8cc7f47e7f2fa26f0 Mon Sep 17 00:00:00 2001
From: Baptiste Leproux <leproux.baptiste@gmail.com>
Date: Wed, 26 Nov 2025 12:39:26 +0100
Subject: [PATCH 4/5] fix: avoid bundling all locales + refactor

---
 layer/app/app.config.ts               |  4 +++-
 layer/app/app.vue                     | 13 ++++++------
 layer/app/composables/useDocusI18n.ts | 30 +++------------------------
 layer/app/error.vue                   | 13 ++++++------
 layer/app/plugins/i18n.ts             | 28 ++++++++++++++++++++++---
 layer/app/types/index.d.ts            |  4 +++-
 layer/nuxt.schema.ts                  |  7 -------
 7 files changed, 46 insertions(+), 53 deletions(-)

diff --git a/layer/app/app.config.ts b/layer/app/app.config.ts
index ebc3e98da..11c3b91bf 100644
--- a/layer/app/app.config.ts
+++ b/layer/app/app.config.ts
@@ -1,5 +1,7 @@
 export default defineAppConfig({
-  locale: 'en',
+  docus: {
+    locale: 'en',
+  },
   ui: {
     colors: {
       primary: 'emerald',
diff --git a/layer/app/app.vue b/layer/app/app.vue
index 251b2fe91..679c45bfa 100644
--- a/layer/app/app.vue
+++ b/layer/app/app.vue
@@ -1,15 +1,14 @@
 <script setup lang="ts">
-import type { PageCollections } from '@nuxt/content'
+import type { ContentNavigationItem, PageCollections } from '@nuxt/content'
 import * as nuxtUiLocales from '@nuxt/ui/locale'
 
 const { seo } = useAppConfig()
 const site = useSiteConfig()
 const { locale, locales, isEnabled, switchLocalePath } = useDocusI18n()
 
-const matchedUiLocale = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales])
-const uiLocale = computed(() => matchedUiLocale.value || nuxtUiLocales.en)
-const lang = computed(() => matchedUiLocale.value.code || 'en')
-const dir = computed(() => matchedUiLocale.value?.dir || 'ltr')
+const nuxtUiLocale = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales] || nuxtUiLocales.en)
+const lang = computed(() => nuxtUiLocale.value.code)
+const dir = computed(() => nuxtUiLocale.value.dir)
 const collectionName = computed(() => isEnabled.value ? `docs_${locale.value}` : 'docs')
 
 useHead({
@@ -45,7 +44,7 @@ if (isEnabled.value) {
 }
 
 const { data: navigation } = await useAsyncData(() => `navigation_${collectionName.value}`, () => queryCollectionNavigation(collectionName.value as keyof PageCollections), {
-  transform: (data) => {
+  transform: (data: ContentNavigationItem[]) => {
     const rootResult = data.find(item => item.path === '/docs')?.children || data || []
 
     return rootResult.find(item => item.path === `/${locale.value}`)?.children || rootResult
@@ -60,7 +59,7 @@ provide('navigation', navigation)
 </script>
 
 <template>
-  <UApp :locale="uiLocale">
+  <UApp :locale="nuxtUiLocale">
     <NuxtLoadingIndicator color="var(--ui-primary)" />
 
     <AppHeader v-if="$route.meta.header !== false" />
diff --git a/layer/app/composables/useDocusI18n.ts b/layer/app/composables/useDocusI18n.ts
index 15d838f26..bfa6bfeec 100644
--- a/layer/app/composables/useDocusI18n.ts
+++ b/layer/app/composables/useDocusI18n.ts
@@ -1,36 +1,12 @@
 import type { LocaleObject } from '@nuxtjs/i18n'
-import en from '../../i18n/locales/en.json'
-
-type LocaleMessages = typeof en
-
-const localeFiles = import.meta.glob('../../i18n/locales/*.json', {
-  import: 'default',
-  eager: true,
-}) as Record<string, LocaleMessages>
-
-const localeMessages = Object.entries(localeFiles).reduce<Record<string, LocaleMessages>>((acc, [path, messages]) => {
-  const localeCode = path.split('/').pop()?.replace('.json', '')
-  if (localeCode) {
-    acc[localeCode] = messages
-  }
-  return acc
-}, {})
 
 export const useDocusI18n = () => {
   const config = useRuntimeConfig().public
-  const appConfig = useAppConfig()
   const isEnabled = ref(!!config.i18n)
 
   if (!isEnabled.value) {
-    const configuredLocale = appConfig.locale
-    const messages = localeMessages[configuredLocale]
-
-    if (!messages && configuredLocale !== 'en') {
-      console.warn(`[Docus] Missing locale file for "${configuredLocale}". Falling back to "en".`)
-    }
-
-    const locale = messages ? configuredLocale : 'en'
-    const resolvedMessages = messages || en
+    const locale = useNuxtApp().$locale
+    const localeMessages = useNuxtApp().$localeMessages as Record<string, unknown>
 
     return {
       isEnabled,
@@ -40,7 +16,7 @@ export const useDocusI18n = () => {
       switchLocalePath: () => {},
       t: (key: string): string => {
         const path = key.split('.')
-        return path.reduce((acc: unknown, curr) => (acc as Record<string, unknown>)?.[curr], resolvedMessages) as string
+        return path.reduce((acc: unknown, curr) => (acc as Record<string, unknown>)?.[curr], localeMessages) as string
       },
     }
   }
diff --git a/layer/app/error.vue b/layer/app/error.vue
index 3c9faa23b..0b6dd828b 100644
--- a/layer/app/error.vue
+++ b/layer/app/error.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { NuxtError } from '#app'
-import type { PageCollections } from '@nuxt/content'
+import type { ContentNavigationItem, PageCollections } from '@nuxt/content'
 import * as nuxtUiLocales from '@nuxt/ui/locale'
 
 const props = defineProps<{
@@ -9,11 +9,10 @@ const props = defineProps<{
 
 const { locale, locales, isEnabled, t, switchLocalePath } = useDocusI18n()
 
-const matchedUiLocale = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales])
-const uiLocale = computed(() => matchedUiLocale.value || nuxtUiLocales.en)
+const nuxtUiLocale = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales] || nuxtUiLocales.en)
+const lang = computed(() => nuxtUiLocale.value.code)
+const dir = computed(() => nuxtUiLocale.value.dir)
 
-const lang = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales]?.code || 'en')
-const dir = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales]?.dir || 'ltr')
 useHead({
   htmlAttrs: {
     lang,
@@ -48,7 +47,7 @@ if (isEnabled.value) {
 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) => {
+  transform: (data: ContentNavigationItem[]) => {
     const rootResult = data.find(item => item.path === '/docs')?.children || data || []
 
     return rootResult.find(item => item.path === `/${locale.value}`)?.children || rootResult
@@ -63,7 +62,7 @@ provide('navigation', navigation)
 </script>
 
 <template>
-  <UApp :locale="uiLocale">
+  <UApp :locale="nuxtUiLocale">
     <AppHeader />
 
     <UError :error="localizedError" />
diff --git a/layer/app/plugins/i18n.ts b/layer/app/plugins/i18n.ts
index e4fc6a6e5..7f026aed8 100644
--- a/layer/app/plugins/i18n.ts
+++ b/layer/app/plugins/i18n.ts
@@ -1,12 +1,34 @@
-export default defineNuxtPlugin(() => {
+import en from '../../i18n/locales/en.json'
+import type { RouteLocationNormalized } from 'vue-router'
+
+export default defineNuxtPlugin(async () => {
   const nuxtApp = useNuxtApp()
 
   const i18nConfig = nuxtApp.$config.public.i18n
+
+  // If i18n is not enabled, fetch and provide the configured locale in app config
   if (!i18nConfig) {
-    return
+    let locale = 'en'
+    let resolvedMessages: Record<string, unknown> = en
+
+    const appConfig = useAppConfig()
+    const configuredLocale = appConfig.docus.locale
+    if (configuredLocale !== 'en') {
+      const localeMessages = await import(`../../i18n/locales/${configuredLocale}.json`)
+      if (!localeMessages) {
+        console.warn(`[Docus] Missing locale file for "${configuredLocale}". Falling back to "en".`)
+      }
+      else {
+        locale = configuredLocale
+        resolvedMessages = localeMessages
+      }
+    }
+
+    nuxtApp.provide('locale', locale)
+    nuxtApp.provide('localeMessages', resolvedMessages)
   }
 
-  addRouteMiddleware((to) => {
+  addRouteMiddleware((to: RouteLocationNormalized) => {
     if (to.path === '/') {
       const cookieLocale = useCookie('i18n_redirected').value || i18nConfig.defaultLocale || 'en'
 
diff --git a/layer/app/types/index.d.ts b/layer/app/types/index.d.ts
index 6ccc6725d..4ec153d58 100644
--- a/layer/app/types/index.d.ts
+++ b/layer/app/types/index.d.ts
@@ -1,6 +1,8 @@
 declare module 'nuxt/schema' {
   interface AppConfig {
-    locale: string
+    docus: {
+      locale: string
+    }
     seo: {
       titleTemplate: string
       title: string
diff --git a/layer/nuxt.schema.ts b/layer/nuxt.schema.ts
index 2d9a920c6..209e8784e 100644
--- a/layer/nuxt.schema.ts
+++ b/layer/nuxt.schema.ts
@@ -2,13 +2,6 @@ import { field, group } from '@nuxt/content/preview'
 
 export default defineNuxtSchema({
   appConfig: {
-    locale: field({
-      type: 'string',
-      title: 'Locale',
-      description: 'Locale to use when @nuxtjs/i18n is not being used.',
-      icon: 'i-lucide-languages',
-      default: 'en',
-    }),
     ui: group({
       title: 'UI',
       description: 'UI Customization.',

From 3a738728c6674a5b965d0b097e71448caa4897fb Mon Sep 17 00:00:00 2001
From: Baptiste Leproux <leproux.baptiste@gmail.com>
Date: Wed, 26 Nov 2025 12:43:23 +0100
Subject: [PATCH 5/5] fix types

---
 layer/app/composables/useDocusI18n.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/layer/app/composables/useDocusI18n.ts b/layer/app/composables/useDocusI18n.ts
index bfa6bfeec..d08e3b10a 100644
--- a/layer/app/composables/useDocusI18n.ts
+++ b/layer/app/composables/useDocusI18n.ts
@@ -5,7 +5,7 @@ export const useDocusI18n = () => {
   const isEnabled = ref(!!config.i18n)
 
   if (!isEnabled.value) {
-    const locale = useNuxtApp().$locale
+    const locale = useNuxtApp().$locale as string
     const localeMessages = useNuxtApp().$localeMessages as Record<string, unknown>
 
     return {