feat: native i18n support for collections

docs/content/docs/2.collections/1.define.md

@@ -138,6 +138,38 @@ Indexes are created automatically when the database schema is generated. They wo
 - **`unique`** (optional): Set to `true` to create a unique index (default: `false`)
 - **`name`** (optional): Custom index name. If omitted, auto-generates as `idx_{collection}_{column1}_{column2}`
 
+### i18n Support
+
+Enable multi-language content for a collection by adding the `i18n` option. Pass `true` to auto-detect locales from `@nuxtjs/i18n`, or provide an explicit config:
+
+```ts [content.config.ts]
+import { defineCollection, defineContentConfig } from '@nuxt/content'
+import { z } from 'zod'
+
+export default defineContentConfig({
+  collections: {
+    // Auto-detect from @nuxtjs/i18n
+    docs: defineCollection({
+      type: 'page',
+      source: '*/docs/**',
+      i18n: true,
+    }),
+    // Explicit config
+    team: defineCollection({
+      type: 'data',
+      source: 'data/*.yml',
+      schema: z.object({ name: z.string(), role: z.string() }),
+      i18n: {
+        locales: ['en', 'fr', 'de'],
+        defaultLocale: 'en',
+      },
+    }),
+  },
+})
+```
+
+When `i18n` is configured, a `locale` column and a composite `(locale, stem)` index are automatically added to the collection. See the [i18n integration guide](/docs/integrations/i18n) for full documentation.
+
 **Performance Tips:**
 
 - Index columns used in `where()` queries for faster filtering

docs/content/docs/3.files/2.yaml.md

@@ -43,6 +43,26 @@ url: https://github.com/larbish
 ```
 ::
 
+## Inline i18n
+
+YAML files in i18n-enabled collections can include an `i18n` section for inline translations. Untranslated fields are preserved from the default locale automatically:
+
+```yaml [jane.yml]
+name: Jane Doe
+role: Developer
+country: Switzerland
+
+i18n:
+  fr:
+    role: Développeuse
+    country: Suisse
+  de:
+    role: Entwicklerin
+    country: Schweiz
+```
+
+See the [i18n integration guide](/docs/integrations/i18n) for full documentation.
+
 ## Query Data
 
 Now we can query authors:

docs/content/docs/3.files/3.json.md

@@ -51,6 +51,24 @@ Create authors files in `content/authors/` directory.
 Each file in `data` collection should contain only one object, therefore having top level array in a JSON file will cause invalid result in query time.
 ::
 
+## Inline i18n
+
+JSON files in i18n-enabled collections can include an `i18n` key for inline translations. Untranslated fields are preserved from the default locale automatically:
+
+```json [jane.json]
+{
+  "name": "Jane Doe",
+  "role": "Developer",
+  "country": "Switzerland",
+  "i18n": {
+    "fr": { "role": "Développeuse", "country": "Suisse" },
+    "de": { "role": "Entwicklerin", "country": "Schweiz" }
+  }
+}
+```
+
+See the [i18n integration guide](/docs/integrations/i18n) for full documentation.
+
 ## Query Data
 
 Now we can query authors:

docs/content/docs/4.utils/1.query-collection.md

@@ -223,6 +223,38 @@ const { data } = await useAsyncData(route.path, () => {
 })
 ```
 
+### `locale(locale: string, opts?: { fallback?: string })`
+
+Filter results by locale. Only applicable to collections with `i18n` configured.
+
+- Parameters:
+  - `locale`: The locale code to filter by (e.g. `'fr'`)
+  - `opts.fallback`: Optional fallback locale code. When set, items missing in the requested locale will be filled from the fallback locale.
+
+```ts
+// Filter by French locale
+queryCollection('docs').locale('fr').all()
+
+// With fallback to English for missing items
+queryCollection('docs').locale('fr', { fallback: 'en' }).all()
+```
+
+::tip
+When `@nuxtjs/i18n` is installed and the collection has `i18n` configured, locale filtering is applied automatically based on the current locale. You only need `.locale()` for explicit control.
+::
+
+### `stem(stem: string)`
+
+Filter by stem (filename without extension). Automatically resolves the full stem path including the collection's source prefix. Useful for querying data collections by filename.
+
+- Parameter:
+  - `stem`: The stem to match (e.g. `'navbar'` for `content/navigation/navbar.yml`)
+
+```ts
+// Matches content/navigation/navbar.yml when source is 'navigation/*.yml'
+queryCollection('navigation').stem('navbar').first()
+```
+
 ### `count()`
 
 Count the number of matched collection entries based on the query.

docs/content/docs/4.utils/5.use-query-collection.md

@@ -0,0 +1,115 @@
+---
+title: useQueryCollection
+description: The useQueryCollection composable wraps queryCollection with useAsyncData for automatic caching and locale reactivity.
+---
+
+## Usage
+
+`useQueryCollection` provides the same chainable API as `queryCollection`, but wraps execution in `useAsyncData` with automatic cache key generation and locale-reactive re-fetching.
+
+```vue [pages/technologies.vue]
+<script setup>
+const { data: techs } = await useQueryCollection('technologies').all()
+</script>
+```
+
+::warning
+`useQueryCollection` must be called in a Vue component setup context, just like `useAsyncData` and `useFetch`. It cannot be called in event handlers, watchers, or lifecycle hooks.
+::
+
+## API
+
+### Type
+
+```ts
+function useQueryCollection<R = never, T extends keyof Collections = keyof Collections>(
+  collection: T
+): UseQueryCollectionBuilder<R, T>
+```
+
+The optional generic `R` overrides the return type. When omitted, the collection's generated type is used.
+
+### Methods
+
+`useQueryCollection` supports all the same chainable methods as `queryCollection`:
+
+- `.where(field, operator, value)`
+- `.andWhere(groupFactory)`
+- `.orWhere(groupFactory)`
+- `.order(field, direction)`
+- `.select(...fields)`
+- `.skip(n)`
+- `.limit(n)`
+- `.path(path)`
+- `.stem(stem)`
+- `.locale(locale, opts?)`
+
+### Terminal Methods
+
+Terminal methods execute the query and return `AsyncData`:
+
+- `.all()` — returns `AsyncData<R[], NuxtError>`
+- `.first()` — returns `AsyncData<R | null, NuxtError>`
+- `.count(field?, distinct?)` — returns `AsyncData<number, NuxtError>`
+
+## Locale Reactivity
+
+When `@nuxtjs/i18n` is installed and the collection has `i18n` configured, `useQueryCollection` automatically:
+
+1. Detects the current locale
+2. Includes it in the cache key
+3. Watches the locale ref for changes
+4. Re-fetches content when the locale changes (no page reload needed)
+
+```vue [app/layouts/default.vue]
+<script setup>
+// Automatically updates when user switches locale
+const { data: navbar } = await useQueryCollection('navigation').stem('navbar').first()
+</script>
+```
+
+## Type Override
+
+Use the generic parameter to override the return type when the collection's generated type doesn't match your component's expected interface:
+
+```vue [pages/technologies.vue]
+<script setup>
+import type { CardItemType } from '#shared/types/components/card-item'
+
+const { data: cards } = await useQueryCollection<CardItemType>('technologies').all()
+// cards is Ref<CardItemType[]>
+</script>
+```
+
+## Examples
+
+### Single Item by Stem
+
+```vue
+<script setup>
+const { data: about } = await useQueryCollection('sections').stem('about').first()
+</script>
+```
+
+### Filtered and Ordered
+
+```vue
+<script setup>
+const { data: posts } = await useQueryCollection('blog')
+  .where('published', '=', true)
+  .order('date', 'DESC')
+  .limit(10)
+  .all()
+</script>
+```
+
+### With Explicit Locale
+
+```vue
+<script setup>
+// Explicit locale disables auto-detection and locale watching
+const { data: frDocs } = await useQueryCollection('docs')
+  .locale('fr', { fallback: 'en' })
+  .all()
+</script>
+```

docs/content/docs/4.utils/6.query-collection-locales.md

@@ -0,0 +1,100 @@
+---
+title: queryCollectionLocales
+description: Query all locale variants of a content item for language switchers and hreflang tags.
+---
+
+## Usage
+
+`queryCollectionLocales` returns all locale variants for a given content stem. This is useful for building language switchers, generating hreflang SEO tags, and implementing `defineI18nRoute()` with `@nuxtjs/i18n`.
+
+```vue [app/components/LanguageSwitcher.vue]
+<script setup>
+const locales = await queryCollectionLocales('docs', 'docs/getting-started')
+</script>
+
+<template>
+  <nav>
+    <NuxtLink v-for="entry in locales" :key="entry.locale" :to="entry.path">
+      {{ entry.locale }}
+    </NuxtLink>
+  </nav>
+</template>
+```
+
+::tip
+`queryCollectionLocales` bypasses automatic locale filtering — it always returns all locale variants regardless of the current locale.
+::
+
+## API
+
+### Type
+
+```ts
+// Client-side (auto-imported)
+function queryCollectionLocales<T extends keyof Collections>(
+  collection: T,
+  stem: string
+): Promise<ContentLocaleEntry[]>
+
+// Server-side
+function queryCollectionLocales<T extends keyof Collections>(
+  event: H3Event,
+  collection: T,
+  stem: string
+): Promise<ContentLocaleEntry[]>
+
+interface ContentLocaleEntry {
+  locale: string
+  stem: string
+  path?: string   // Only for page collections
+  title?: string  // Only for page collections
+}
+```
+
+### Parameters
+
+- `collection`: The collection name
+- `stem`: The content stem (e.g. `'docs/getting-started'`)
+
+## Server Usage
+
+```ts [server/api/locales.ts]
+export default eventHandler(async (event) => {
+  const stem = getQuery(event).stem as string
+  return await queryCollectionLocales(event, 'docs', stem)
+})
+```
+
+## Use Cases
+
+### Language Switcher
+
+```vue
+<script setup>
+const route = useRoute()
+// Use the page's stem (without locale prefix) — path-based locale detection
+// already strips the locale prefix, so the stem is shared across locales
+const { data: page } = await useAsyncData(route.path, () => {
+  return queryCollection('docs').path(route.path).first()
+})
+const locales = page.value?.stem
+  ? await queryCollectionLocales('docs', page.value.stem)
+  : []
+</script>
+```
+
+### Hreflang Meta Tags
+
+```vue
+<script setup>
+const locales = await queryCollectionLocales('docs', 'docs/getting-started')
+
+useHead({
+  link: locales.map(entry => ({
+    rel: 'alternate',
+    hreflang: entry.locale,
+    href: entry.path,
+  })),
+})
+</script>
+```