fix(seo): emit hreflang from iso, not routing code

One alternate per locale (iso || code); optional
hreflangBaseLanguage claims bare language by list order (#243).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: s00d

docs/api/module-options.md

@@ -123,6 +123,7 @@ Parts of the module you can switch off.
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
+| `hreflangBaseLanguage` | `boolean` | `false` | Also emit a bare-language `hreflang` derived from each locale's `iso` (e.g. `es-ES` → also `es`). The first regional locale in `locales` claims the bare tag for that language. Routing `code` is never used — only `iso \|\| code`. |
 | `localizedRouteNamePrefix` | `string` | `'localized-'` | Prefix prepended to localized route names (e.g. `'localized-index'`). Used internally to distinguish original routes from generated locale variants. |
 | `routeDisableMeta` | `Record<string, boolean \| string[]>` | — | Per-route meta tag disabling, extracted from `defineI18nRoute()` calls. Maps a route path to `true` (disable all meta) or an array of locale codes for which meta should be disabled. |
 | `missingWarn` | `boolean` | `true` | Show console warnings when a translation key is missing. |

docs/api/packages.md

@@ -23,14 +23,14 @@ or CI failing.
 | [`@i18n-micro/devtools-ui`](/api/packages/devtools-ui) | `@i18n-micro/devtools-ui`, `@i18n-micro/devtools-ui/bridge`, `@i18n-micro/devtools-ui/bridge/create`, `@i18n-micro/devtools-ui/vite` | 25 |
 | [`@i18n-micro/hmr`](/api/packages/hmr) | `@i18n-micro/hmr/cache-keys`, `@i18n-micro/hmr/generate-plugin`, `@i18n-micro/hmr/watcher` | 8 |
 | [`@i18n-micro/node`](/api/packages/node) | `@i18n-micro/node` | 15 |
-| [`@i18n-micro/path-strategy`](/api/packages/path-strategy) | `@i18n-micro/path-strategy`, `@i18n-micro/path-strategy/no-prefix`, `@i18n-micro/path-strategy/prefix`, `@i18n-micro/path-strategy/prefix-and-default`, `@i18n-micro/path-strategy/prefix-except-default`, `@i18n-micro/path-strategy/types` | 37 |
+| [`@i18n-micro/path-strategy`](/api/packages/path-strategy) | `@i18n-micro/path-strategy`, `@i18n-micro/path-strategy/no-prefix`, `@i18n-micro/path-strategy/prefix`, `@i18n-micro/path-strategy/prefix-and-default`, `@i18n-micro/path-strategy/prefix-except-default`, `@i18n-micro/path-strategy/types` | 38 |
 | [`@i18n-micro/preact`](/api/packages/preact) | `@i18n-micro/preact` | 39 |
 | [`@i18n-micro/route-strategy`](/api/packages/route-strategy) | `@i18n-micro/route-strategy` | 18 |
 | [`@i18n-micro/solid`](/api/packages/solid) | `@i18n-micro/solid` | 33 |
 | [`@i18n-micro/test-utils`](/api/packages/test-utils) | `@i18n-micro/test-utils`, `@i18n-micro/test-utils/publish-smoke` | 36 |
 | [`@i18n-micro/types`](/api/packages/types) | `@i18n-micro/types` | 26 |
 | [`@i18n-micro/types-generator`](/api/packages/types-generator) | `@i18n-micro/types-generator`, `@i18n-micro/types-generator/nuxt` | 7 |
-| [`@i18n-micro/utils`](/api/packages/utils) | `@i18n-micro/utils/accept-language`, `@i18n-micro/utils/active-locales`, `@i18n-micro/utils/app-path`, `@i18n-micro/utils/build`, `@i18n-micro/utils/cache-control`, `@i18n-micro/utils/cookie`, `@i18n-micro/utils/deep-merge`, `@i18n-micro/utils/merge-i18n-head`, `@i18n-micro/utils/merge-source`, `@i18n-micro/utils/normalize`, `@i18n-micro/utils/parse-path`, `@i18n-micro/utils/payload-config`, `@i18n-micro/utils/payload-fetch`, `@i18n-micro/utils/payload-stats`, `@i18n-micro/utils/payload-url`, `@i18n-micro/utils/resolve-locale`, `@i18n-micro/utils/resolve-og-locale`, `@i18n-micro/utils/route`, `@i18n-micro/utils/route-pattern`, `@i18n-micro/utils/runtime-config`, `@i18n-micro/utils/source-loader` | 93 |
+| [`@i18n-micro/utils`](/api/packages/utils) | `@i18n-micro/utils/accept-language`, `@i18n-micro/utils/active-locales`, `@i18n-micro/utils/app-path`, `@i18n-micro/utils/build`, `@i18n-micro/utils/cache-control`, `@i18n-micro/utils/cookie`, `@i18n-micro/utils/deep-merge`, `@i18n-micro/utils/merge-i18n-head`, `@i18n-micro/utils/merge-source`, `@i18n-micro/utils/normalize`, `@i18n-micro/utils/parse-path`, `@i18n-micro/utils/payload-config`, `@i18n-micro/utils/payload-fetch`, `@i18n-micro/utils/payload-stats`, `@i18n-micro/utils/payload-url`, `@i18n-micro/utils/resolve-hreflang`, `@i18n-micro/utils/resolve-locale`, `@i18n-micro/utils/resolve-og-locale`, `@i18n-micro/utils/route`, `@i18n-micro/utils/route-pattern`, `@i18n-micro/utils/runtime-config`, `@i18n-micro/utils/source-loader` | 97 |
 | [`@i18n-micro/vue`](/api/packages/vue) | `@i18n-micro/vue` | 27 |
 
 <!-- /generated:packages-index -->

docs/api/packages/astro.md

@@ -36,17 +36,17 @@ import { /* … */ } from '@i18n-micro/astro'
 | `Getter` | type | `(key: TranslationKey, params?: Record<string, string \| number \| boolean>, defaultValue?: string) => unknown` |
 | `I18nClientProps` | interface | 4 members |
 | `i18nIntegration` | function | `(options: I18nIntegrationOptions) => AstroIntegration` |
-| `I18nIntegrationOptions` | interface | 51 members |
+| `I18nIntegrationOptions` | interface | 52 members |
 | `I18nMiddlewareOptions` | interface | 7 members |
 | `I18nRoutingStrategy` | interface | 10 members |
 | `interpolate` | function | `(template: string, params: Params) => string` |
 | `LoadedTranslations` | interface | 2 members |
 | `loadTranslationsFromDir` | function | `(options: LoadTranslationsOptions) => LoadedTranslations` |
 | `loadTranslationsIntoI18n` | function | `(i18n: { addTranslations: (locale: string, translations: Translations, merge?: boolean) => void; addRouteTranslations: (locale: string, routeName: string, translations: Translations, merge?: boolean) => void; }, options: LoadTranslationsOptions) => void` |
 | `LoadTranslationsOptions` | interface | 3 members |
-| `Locale` | interface | 11 members |
+| `Locale` | interface | 12 members |
 | `LocaleCode` | type | `string` |
-| `LocaleHeadOptions` | interface | 3 members |
+| `LocaleHeadOptions` | interface | 4 members |
 | `LocaleHeadResult` | interface | 3 members |
 | `Params` | type | `Record<string, string \| number \| boolean>` |
 | `PluralFunc` | type | `(key: TranslationKey, count: number, params: Params, locale: string, getter: Getter) => string \| null` |
@@ -165,7 +165,7 @@ import { /* … */ } from '@i18n-micro/astro'
 
 </details>
 <details>
-<summary><code>I18nIntegrationOptions</code> — 51 members</summary>
+<summary><code>I18nIntegrationOptions</code> — 52 members</summary>
 
 | Member | Type |
 | --- | --- |
@@ -193,6 +193,7 @@ import { /* … */ } from '@i18n-micro/astro'
 | `globalLocaleRoutes?` | `GlobalLocaleRoutes` |
 | `hmr?` | `boolean \| undefined` |
 | `hooks?` | `boolean \| undefined` |
+| `hreflangBaseLanguage?` | `boolean \| undefined` |
 | `httpCacheDuration?` | `number \| undefined` |
 | `locale` | `string` |
 | `localeCookie?` | `string \| null \| undefined` |
@@ -272,15 +273,16 @@ import { /* … */ } from '@i18n-micro/astro'
 | `translationDir` | `string` |
 
 </details>
-<code>Locale</code> — 11 members, identical to [`Locale`](/api/packages/types).
+<code>Locale</code> — 12 members, identical to [`Locale`](/api/packages/types).
 <details>
-<summary><code>LocaleHeadOptions</code> — 3 members</summary>
+<summary><code>LocaleHeadOptions</code> — 4 members</summary>
 
 | Member | Type |
 | --- | --- |
 | `addDirAttribute?` | `boolean \| undefined` |
 | `addSeoAttributes?` | `boolean \| undefined` |
 | `baseUrl?` | `string \| undefined` |
+| `hreflangBaseLanguage?` | `boolean \| undefined` |
 
 </details>
 <details>

docs/api/packages/node.md

@@ -28,7 +28,7 @@ import { /* … */ } from '@i18n-micro/node'
 | `LoadedTranslations` | interface | 2 members |
 | `loadRootTranslations` | function | `(dir: string, disablePageLocales?: boolean) => Promise<Record<string, Translations>>` |
 | `loadTranslations` | function | `(dir: string, disablePageLocales?: boolean) => Promise<LoadedTranslations>` |
-| `Locale` | interface | 11 members |
+| `Locale` | interface | 12 members |
 | `LocaleCode` | type | `string` |
 | `Params` | type | `Record<string, string \| number \| boolean>` |
 | `PluralFunc` | type | `(key: TranslationKey, count: number, params: Params, locale: string, getter: Getter) => string \| null` |
@@ -103,7 +103,7 @@ import { /* … */ } from '@i18n-micro/node'
 
 </details>
 <code>LoadedTranslations</code> — 2 members, identical to [`LoadedTranslations`](/api/packages/astro).
-<code>Locale</code> — 11 members, identical to [`Locale`](/api/packages/types).
+<code>Locale</code> — 12 members, identical to [`Locale`](/api/packages/types).
 <code>Translations</code> — 1 members, identical to [`Translations`](/api/packages/types).
 
 Back to [all packages](/api/packages) · [Integration guides](/integrations/)

docs/api/packages/path-strategy.md

@@ -6,7 +6,7 @@ outline: 'deep'
 
 # `@i18n-micro/path-strategy`
 
-37 exports across 6 entry points.
+38 exports across 6 entry points.
 Generated from the API snapshot that [`pnpm run api:surface`](/guide/maintenance-commands#api-surface)
 checks against the TypeScript sources.
 
@@ -35,6 +35,7 @@ import { /* … */ } from '@i18n-micro/path-strategy'
 | `PrefixExceptDefaultPathStrategy` | class | 44 members |
 | `PrefixPathStrategy` | class | 36 members |
 | `ResolvedRouteLike` | interface | 6 members |
+| `resolvePathWithParams` | function | `(path: string, params?: Record<string, unknown>) => string` |
 | `RouteAnalysis` | interface | 2 members |
 | `RouteLike` | interface | 6 members |
 | `RouterAdapter` | interface | 3 members |

docs/api/packages/preact.md

@@ -41,9 +41,9 @@ import { /* … */ } from '@i18n-micro/preact'
 | `I18nT` | const | `(props: I18nTProps) => JSX.Element \| null` |
 | `I18nTProps` | interface | 311 members |
 | `interpolate` | function | `(template: string, params: Params) => string` |
-| `Locale` | interface | 11 members |
+| `Locale` | interface | 12 members |
 | `LocaleCode` | type | `string` |
-| `ModuleOptions` | interface | 45 members |
+| `ModuleOptions` | interface | 46 members |
 | `Params` | type | `Record<string, string \| number \| boolean>` |
 | `PluralFunc` | type | `(key: TranslationKey, count: number, params: Params, locale: string, getter: Getter) => string \| null` |
 | `PreactI18n` | class | 44 members |
@@ -1353,7 +1353,7 @@ import { /* … */ } from '@i18n-micro/preact'
 
 </details>
 <details>
-<summary><code>Locale</code> — 11 members</summary>
+<summary><code>Locale</code> — 12 members</summary>
 
 | Member | Type |
 | --- | --- |
@@ -1365,12 +1365,13 @@ import { /* … */ } from '@i18n-micro/preact'
 | `disabled?` | `boolean \| undefined` |
 | `displayName?` | `string \| undefined` |
 | `fallbackLocale?` | `string \| undefined` |
+| `isCatchallLocale?` | `boolean \| undefined` |
 | `iso?` | `string \| undefined` |
 | `og?` | `string \| undefined` |
 | `seo?` | `boolean \| undefined` |
 
 </details>
-<code>ModuleOptions</code> — 45 members, identical to [`ModuleOptions`](/api/packages/types).
+<code>ModuleOptions</code> — 46 members, identical to [`ModuleOptions`](/api/packages/types).
 <details>
 <summary><code>PreactI18n</code> — 44 members</summary>
 

docs/api/packages/solid.md

@@ -36,9 +36,9 @@ import { /* … */ } from '@i18n-micro/solid'
 | `I18nSwitcher` | const | `Component<I18nSwitcherProps>` |
 | `I18nT` | const | `Component<I18nTProps>` |
 | `interpolate` | function | `(template: string, params: Params) => string` |
-| `Locale` | interface | 11 members |
+| `Locale` | interface | 12 members |
 | `LocaleCode` | type | `string` |
-| `ModuleOptions` | interface | 45 members |
+| `ModuleOptions` | interface | 46 members |
 | `Params` | type | `Record<string, string \| number \| boolean>` |
 | `PluralFunc` | type | `(key: TranslationKey, count: number, params: Params, locale: string, getter: Getter) => string \| null` |
 | `SolidI18n` | class | 53 members |
@@ -78,8 +78,8 @@ import { /* … */ } from '@i18n-micro/solid'
 | `resolvePath?` | `((to: string \| { path?: string; }, locale: string) => string \| { path?: string; }) \| undefined` |
 
 </details>
-<code>Locale</code> — 11 members, identical to [`Locale`](/api/packages/types).
-<code>ModuleOptions</code> — 45 members, identical to [`ModuleOptions`](/api/packages/types).
+<code>Locale</code> — 12 members, identical to [`Locale`](/api/packages/types).
+<code>ModuleOptions</code> — 46 members, identical to [`ModuleOptions`](/api/packages/types).
 <details>
 <summary><code>SolidI18n</code> — 53 members</summary>
 

docs/api/packages/types.md

@@ -29,12 +29,12 @@ import { /* … */ } from '@i18n-micro/types'
 | `I18nHeadMeta` | interface | 1 members |
 | `I18nRouteParams` | type | `Record<LocaleCode, Record<string, string>> \| null` |
 | `init` | const | `() => void` |
-| `Locale` | interface | 11 members |
+| `Locale` | interface | 12 members |
 | `LocaleCode` | type | `string` |
 | `MissingHandler` | type | `(locale: string, key: TranslationKey, routeName: string, instance?: unknown, type?: string) => void` |
-| `ModuleOptions` | interface | 45 members |
-| `ModuleOptionsExtend` | interface | 48 members |
-| `ModulePrivateOptionsExtend` | interface | 48 members |
+| `ModuleOptions` | interface | 46 members |
+| `ModuleOptionsExtend` | interface | 49 members |
+| `ModulePrivateOptionsExtend` | interface | 49 members |
 | `Params` | type | `Record<string, string \| number \| boolean>` |
 | `PluralFunc` | type | `(key: TranslationKey, count: number, params: Params, locale: string, getter: Getter) => string \| null` |
 | `PluralTranslations` | interface | 2 members |
@@ -95,7 +95,7 @@ import { /* … */ } from '@i18n-micro/types'
 
 </details>
 <details>
-<summary><code>Locale</code> — 11 members</summary>
+<summary><code>Locale</code> — 12 members</summary>
 
 | Member | Type |
 | --- | --- |
@@ -107,13 +107,14 @@ import { /* … */ } from '@i18n-micro/types'
 | `disabled?` | `boolean \| undefined` |
 | `displayName?` | `string \| undefined` |
 | `fallbackLocale?` | `string \| undefined` |
+| `isCatchallLocale?` | `boolean \| undefined` |
 | `iso?` | `string \| undefined` |
 | `og?` | `string \| undefined` |
 | `seo?` | `boolean \| undefined` |
 
 </details>
 <details>
-<summary><code>ModuleOptions</code> — 45 members</summary>
+<summary><code>ModuleOptions</code> — 46 members</summary>
 
 | Member | Type |
 | --- | --- |
@@ -140,6 +141,7 @@ import { /* … */ } from '@i18n-micro/types'
 | `globalLocaleRoutes?` | `GlobalLocaleRoutes` |
 | `hmr?` | `boolean \| undefined` |
 | `hooks?` | `boolean \| undefined` |
+| `hreflangBaseLanguage?` | `boolean \| undefined` |
 | `httpCacheDuration?` | `number \| undefined` |
 | `localeCookie?` | `string \| null \| undefined` |
 | `locales?` | `Locale[] \| undefined` |
@@ -165,7 +167,7 @@ import { /* … */ } from '@i18n-micro/types'
 
 </details>
 <details>
-<summary><code>ModuleOptionsExtend</code> — 48 members</summary>
+<summary><code>ModuleOptionsExtend</code> — 49 members</summary>
 
 | Member | Type |
 | --- | --- |
@@ -193,6 +195,7 @@ import { /* … */ } from '@i18n-micro/types'
 | `hashMode` | `boolean` |
 | `hmr?` | `boolean \| undefined` |
 | `hooks?` | `boolean \| undefined` |
+| `hreflangBaseLanguage?` | `boolean \| undefined` |
 | `httpCacheDuration?` | `number \| undefined` |
 | `isSSG` | `boolean` |
 | `localeCookie?` | `string \| null \| undefined` |
@@ -220,7 +223,7 @@ import { /* … */ } from '@i18n-micro/types'
 
 </details>
 <details>
-<summary><code>ModulePrivateOptionsExtend</code> — 48 members</summary>
+<summary><code>ModulePrivateOptionsExtend</code> — 49 members</summary>
 
 | Member | Type |
 | --- | --- |
@@ -247,6 +250,7 @@ import { /* … */ } from '@i18n-micro/types'
 | `globalLocaleRoutes?` | `GlobalLocaleRoutes` |
 | `hmr?` | `boolean \| undefined` |
 | `hooks?` | `boolean \| undefined` |
+| `hreflangBaseLanguage?` | `boolean \| undefined` |
 | `httpCacheDuration?` | `number \| undefined` |
 | `localeCookie?` | `string \| null \| undefined` |
 | `locales?` | `Locale[] \| undefined` |

docs/api/packages/utils.md

@@ -6,7 +6,7 @@ outline: 'deep'
 
 # `@i18n-micro/utils`
 
-93 exports across 21 entry points.
+97 exports across 22 entry points.
 Generated from the API snapshot that [`pnpm run api:surface`](/guide/maintenance-commands#api-surface)
 checks against the TypeScript sources.
 
@@ -369,6 +369,36 @@ import { /* … */ } from '@i18n-micro/utils/payload-url'
 | `routeName?` | `string \| undefined` |
 | `routesLocaleLinks?` | `Record<string, string> \| undefined` |
 
+</details>
+## `@i18n-micro/utils/resolve-hreflang`
+
+```ts
+import { /* … */ } from '@i18n-micro/utils/resolve-hreflang'
+```
+
+| Export | Kind | Signature |
+| --- | --- | --- |
+| `HreflangAlternate` | interface | 2 members |
+| `HreflangLocaleInput` | type | ``Pick<Locale, 'code' \| 'iso'> & { /** When true and `hreflangBaseLanguage` is on, this locale claims the bare language tag even if another locale already did. */ isCatchallLocale?: boolean }`` |
+| `resolveHreflangAlternates` | function | `(locales: HreflangLocaleInput[], options?: ResolveHreflangAlternatesOptions) => HreflangAlternate[]` |
+| `ResolveHreflangAlternatesOptions` | interface | 1 members |
+
+<details>
+<summary><code>HreflangAlternate</code> — 2 members</summary>
+
+| Member | Type |
+| --- | --- |
+| `hreflang` | `string` |
+| `localeCode` | `string` |
+
+</details>
+<details>
+<summary><code>ResolveHreflangAlternatesOptions</code> — 1 members</summary>
+
+| Member | Type |
+| --- | --- |
+| `hreflangBaseLanguage?` | `boolean \| undefined` |
+
 </details>
 ## `@i18n-micro/utils/resolve-locale`