api.md

vue-i18n-routing API References

Table Of Contents

• TypeAlias
  • BaseUrlResolveHandler
  • BrowserLocaleMatcher
  • Directions
  • ExtendComposerHook
  • ExtendExportedGlobalHook
  • ExtendVueI18nHook
  • I18nCommonRoutingOptions
  • I18nCommonRoutingOptionsWithComposable
  • I18nRoute
  • I18nRoutingGlobalOptions
  • I18nRoutingOptions
  • LocaleLocationFunction
  • LocalePathFunction
  • LocaleRouteFunction
  • LocalizeRoutesPrefixable
  • MetaAttrs
  • Prefixable
  • PrefixableOptions
  • RouteBaseNameFunction
  • RouteOptionsResolver
  • Strategies
  • SwitchLocalePathFunction
  • SwitchLocalePathIntercepter
  • TargetLocale
  • VueI18nExtendOptions
• Interface
  • BrowserLocale
  • ComposableOptions
  • ComputedRouteOptions
  • ExtendHooks
  • ExtendProperyDescripters
  • FindBrowserLocaleOptions
  • I18nHeadMetaInfo
  • I18nHeadOptions
  • LocaleObject
  • LocalizeRoutesPrefixableOptions
  • RouteLegacy
  • RoutingProxy
  • SeoAttributesOptions
  • VueI18nRoutingPluginOptions
• Function
  • createLocaleFromRouteGetter
  • createRouter
  • extendI18n
  • findBrowserLocale
  • getComposer
  • getGlobalOptions
  • getLocale
  • getLocaleCodes
  • getLocales
  • getLocalesRegex
  • getRouteBaseName
  • isComposer
  • isExportedGlobalComposer
  • isI18nInstance
  • isLegacyVueI18n
  • isVueI18n
  • localeHead
  • localeLocation
  • localePath
  • localeRoute
  • localizeRoutes
  • proxyVueInstance
  • registerGlobalOptions
  • resolveBaseUrl
  • resolveRoute
  • setLocale
  • switchLocalePath
  • useLocaleHead
  • useLocaleLocation
  • useLocalePath
  • useLocaleRoute
  • useRouteBaseName
  • useSwitchLocalePath
• Variable
  • DefaultLocalizeRoutesPrefixable
  • DefaultPrefixable
  • DefaultSwitchLocalePathIntercepter
  • VERSION

TypeAlias

BaseUrlResolveHandler

Signature:

export declare type BaseUrlResolveHandler<Context = unknown> = (context: Context) => string;

BrowserLocaleMatcher

The browser locale matcher

Signature:

export declare type BrowserLocaleMatcher = (locales: TargetLocale[], browserLocales: string[]) => BrowserLocale[];

Remarks

This matcher is used by findBrowserLocale function

Directions

Direction

Signature:

export declare type Directions = 'ltr' | 'rtl' | 'auto';

ExtendComposerHook

ExtendExportedGlobalHook

ExtendVueI18nHook

I18nCommonRoutingOptions

Signature:

export declare type I18nCommonRoutingOptions = Pick<I18nRoutingOptions, 'defaultLocale' | 'strategy' | 'defaultLocaleRouteNameSuffix' | 'trailingSlash' | 'locales' | 'routesNameSeparator'>;

I18nCommonRoutingOptionsWithComposable

Signature:

export declare type I18nCommonRoutingOptionsWithComposable = I18nCommonRoutingOptions & ComposableOptions;

I18nRoute

Route config for vue-i18n-routing

Signature:

export declare type I18nRoute = Route & RouteLegacy & {
    redirect?: string;
};

I18nRoutingGlobalOptions

Global options for i18n routing

Signature:

export declare type I18nRoutingGlobalOptions<Context = unknown> = Pick<I18nRoutingOptions<Context>, 'defaultLocale' | 'defaultDirection' | 'defaultLocaleRouteNameSuffix' | 'trailingSlash' | 'routesNameSeparator' | 'strategy' | 'prefixable' | 'switchLocalePathIntercepter' | 'dynamicRouteParamsKey'> & {
    localeCodes?: string[];
};

I18nRoutingOptions

Options to initialize a VueRouter instance

Signature:

export declare type I18nRoutingOptions<Context = unknown> = {
    version?: 3 | 4;
    defaultLocale?: string;
    locales?: string[] | LocaleObject[];
    strategy?: Strategies;
    trailingSlash?: boolean;
    routesNameSeparator?: string;
    defaultLocaleRouteNameSuffix?: string;
    defaultDirection?: Directions;
    baseUrl?: string | BaseUrlResolveHandler<Context>;
    routeOptionsResolver?: RouteOptionsResolver;
    prefixable?: Prefixable;
    switchLocalePathIntercepter?: SwitchLocalePathIntercepter;
    localizeRoutesPrefixable?: LocalizeRoutesPrefixable;
    dynamicRouteParamsKey?: string | symbol;
} & RouterOptions;

Remarks

This options is extended from Vue Router RouterOptioins, so you can specify those options.

LocaleLocationFunction

The function that resolve locale location.

Signature:

export declare type LocaleLocationFunction = (route: RawLocation | RouteLocationRaw, locale?: Locale) => Location | RouteLocation | undefined;

Remarks

The parameter sygnatures of this function is same as localeLocation.

LocalePathFunction

The function that resolve locale path.

Signature:

export declare type LocalePathFunction = (route: RawLocation | RouteLocation, locale?: Locale) => string;

Remarks

The parameter sygnatures of this function is same as localePath.

LocaleRouteFunction

The function that resolve route.

Signature:

export declare type LocaleRouteFunction = (route: RawLocation | RouteLocationRaw, locale?: Locale) => Route | ReturnType<Router['resolve']> | undefined;

Remarks

The parameter sygnatures of this function is same as localeRoute.

LocalizeRoutesPrefixable

Localize route path prefix judgment logic in localizeRoutes function

Signature:

export declare type LocalizeRoutesPrefixable = (options: LocalizeRoutesPrefixableOptions) => boolean;

MetaAttrs

Meta attributes for head properties.

Signature:

export declare type MetaAttrs = Record<string, any>;

Prefixable

Route path prefix judgment logic in resolveRoute function

Signature:

export declare type Prefixable = (optons: PrefixableOptions) => boolean;

PrefixableOptions

Route path prefix judgment options used in Prefixable

Signature:

export declare type PrefixableOptions = Pick<LocalizeRoutesPrefixableOptions, 'currentLocale' | 'defaultLocale' | 'strategy'>;

RouteBaseNameFunction

The function that resolves the route base name.

Signature:

export declare type RouteBaseNameFunction = (givenRoute?: Route | RouteLocationNormalizedLoaded) => string | undefined;

Remarks

The parameter signatures of this function is the same as getRouteBaseName.

RouteOptionsResolver

Resolver for route localizing options

Signature:

export declare type RouteOptionsResolver = (route: I18nRoute, localeCodes: string[]) => ComputedRouteOptions | null;

Strategies

Routing strategy

Signature:

export declare type Strategies = typeof STRATEGIES[keyof typeof STRATEGIES];

SwitchLocalePathFunction

The functin that swtich locale path.

Signature:

export declare type SwitchLocalePathFunction = (locale?: Locale) => string;

Remarks

The parameter sygnatures of this function is same as switchLocalePath.

SwitchLocalePathIntercepter

The intercept handler which is called in switchLocalePath function

Signature:

export declare type SwitchLocalePathIntercepter = (path: string, locale: Locale) => string;

TargetLocale

The target locale info

Signature:

export declare type TargetLocale = Required<Pick<LocaleObject, 'code' | 'iso'>>;

Remarks

This type is used by BrowserLocaleMatcher first argument

VueI18nExtendOptions

Interface

BrowserLocale

The browser locale info

Signature:

export interface BrowserLocale 

Remarks

This type is used by in findBrowserLocale function

Properties

code

The locale code, such as BCP 47 (e.g en-US), or ja

Signature:

code: string;

score

The score number

Signature:

score: number;

Remarks

The score number that is used by sorter of FindBrowserLocaleOptions

ComposableOptions

Signature:

export interface ComposableOptions 

Properties

i18n

vue-i18n Composer instance.

Signature:

i18n?: Composer;

route

vue-router route instance, which is returned with useRoute.

Signature:

route?: ReturnType<typeof useRoute>;

router

vue-router router instance, which is returned with useRouter.

Signature:

router?: ReturnType<typeof useRouter>;

ComputedRouteOptions

Options to compute route localizing

Signature:

export interface ComputedRouteOptions 

Remarks

The route options that is compute the route to be localized on localizeRoutes

Properties

locales

paths

ExtendHooks

Properties

onExtendComposer

onExtendExportedGlobal

onExtendVueI18n

ExtendProperyDescripters

FindBrowserLocaleOptions

The options for findBrowserLocale function

Signature:

export interface FindBrowserLocaleOptions 

Properties

comparer

matcher

I18nHeadMetaInfo

I18n header meta info.

Signature:

export interface I18nHeadMetaInfo 

Properties

htmlAttrs

link

meta

I18nHeadOptions

Options for localeHead function.

Signature:

export interface I18nHeadOptions 

Properties

addDirAttribute

Adds a dir attribute to the HTML element.

Signature:

addDirAttribute?: boolean;

addSeoAttributes

Adds various SEO attributes.

Signature:

addSeoAttributes?: boolean | SeoAttributesOptions;

identifierAttribute

Identifier attribute of <meta> tag

Signature:

identifierAttribute?: string;

LocaleObject

Locale object

Signature:

export interface LocaleObject extends Record<string, any> 

Properties

code

dir

domain

file

isCatchallLocale

iso

name

LocalizeRoutesPrefixableOptions

Localize route path prefix judgment options used in LocalizeRoutesPrefixable

Signature:

export interface LocalizeRoutesPrefixableOptions 

Properties

currentLocale

Current locale

Signature:

currentLocale: Locale;

defaultLocale

Default locale

Signature:

defaultLocale: Locale;

isChild

Whether the route to be resolved is child or not

Signature:

isChild: boolean;

path

The path of route

Signature:

path: string;

strategy

Curernt strategy

Signature:

strategy: Strategies;

RouteLegacy

Route config for lagacy vue-router v3

Signature:

export interface RouteLegacy extends Pick<_Route, Exclude<keyof _Route, 'children' | 'component'>> 

Properties

children

chunkName

chunkNames

component

RoutingProxy

Routing Proxy

Signature:

export interface RoutingProxy 

Properties

defaultDirection

defaultLocale

defaultLocaleRouteNameSuffix

dynamicRouteParamsKey

getRouteBaseName

i18n

localeCodes

localeHead

localeLocation

localePath

localeRoute

prefixable

resolveRoute

route

router

routesNameSeparator

strategy

switchLocalePath

switchLocalePathIntercepter

trailingSlash

SeoAttributesOptions

SEO Attribute options.

Signature:

export interface SeoAttributesOptions 

Properties

canonicalQueries

An array of strings corresponding to query params you would like to include in your canonical URL.

Signature:

canonicalQueries?: string[];

VueI18nRoutingPluginOptions

An options of Vue I18n Routing Plugin

Signature:

export interface VueI18nRoutingPluginOptions 

Properties

inject

Whether to inject some option APIs style methods into Vue instance

Signature:

inject?: boolean;

Function

createLocaleFromRouteGetter

createRouter

Create a Vue Router instance

Signature:

export declare function createRouter<Options extends I18nRoutingOptions = I18nRoutingOptions>(i18n: I18n, options?: Options): Options['version'] extends 4 ? Router : VueRouter;

Parameters

Parameter	Type	Description
i18n	I18n	A Vue I18n instance, see Vue I18n API docs
options	Options	An options, see I18nRoutingOptions

Returns

A Vue Router instance

Remarks

You can create a vue router instance to be used by the Vue app.

The routes of the created router instance are handled with i18n routing.

At the Vue 2 will return a Vue Router v3 instance, and at the Vue 3 will return a Vue Router v4 instance.

extendI18n

findBrowserLocale

Find the browser locale

Signature:

export declare function findBrowserLocale(locales: LocaleObject[], browserLocales: string[], { matcher, comparer }?: FindBrowserLocaleOptions): string | '';

Parameters

Parameter	Type	Description
locales	LocaleObject[]	The target locale list
browserLocales	string[]	The locale code list that is used in browser
{ matcher, comparer }	FindBrowserLocaleOptions

Returns

The matched the locale code

getComposer

getGlobalOptions

Get global i18n routing options

Signature:

export declare function getGlobalOptions(router: Router | VueRouter): I18nRoutingGlobalOptions;

Parameters

Parameter	Type	Description
router	Router | VueRouter	A router instance, about router type

Returns

• global options from i18n routing options registory, if registered, return it, else empty object

getLocale

Get a locale

Signature:

export declare function getLocale(i18n: I18n | Composer | VueI18n): Locale;

Parameters

Parameter	Type	Description
i18n	I18n | Composer | VueI18n	An I18n instance or a Composer instance

Returns

A locale

getLocaleCodes

getLocales

getLocalesRegex

getRouteBaseName

Returns base name of current (if argument not provided) or passed in route.

Signature:

export declare function getRouteBaseName(this: RoutingProxy, givenRoute?: Route | RouteLocationNormalizedLoaded): string | undefined;

Parameters

Parameter	Type	Description
this	RoutingProxy	A RoutingProxy instance.
givenRoute	Route | RouteLocationNormalizedLoaded	A route.

Returns

The route base name. if cannot get, undefined is returned.

Remarks

Base name is name of the route without locale suffix and other metadata added by nuxt i18n module

isComposer

isExportedGlobalComposer

isI18nInstance

isLegacyVueI18n

isVueI18n

localeHead

Returns localized head properties for locale-related aspects.

Signature:

export declare function localeHead(this: RoutingProxy, { addDirAttribute, addSeoAttributes, identifierAttribute }?: I18nHeadOptions): I18nHeadMetaInfo;

Parameters

Parameter	Type	Description
this	RoutingProxy	A RoutingProxy instance.
{ addDirAttribute, addSeoAttributes, identifierAttribute }	I18nHeadOptions

Returns

The localized head properties.

localeLocation

Returns localized location for passed in route parameters.

Signature:

export declare function localeLocation(this: RoutingProxy, route: RawLocation | RouteLocationRaw, locale?: Locale): Location | RouteLocation | undefined;

Parameters

Parameter	Type	Description
this	RoutingProxy	A RoutingProxy instance.
route	RawLocation | RouteLocationRaw	A route.
locale	Locale	A locale, optional.

Returns

A route location. if cannot resolve, undefined is returned.

Remarks

If locale is not specified, uses current locale.

localePath

Returns localized path for passed in route.

Signature:

export declare function localePath(this: RoutingProxy, route: RawLocation | RouteLocationRaw, locale?: Locale): string;

Parameters

Parameter	Type	Description
this	RoutingProxy	A RoutingProxy instance.
route	RawLocation | RouteLocationRaw	A route.
locale	Locale	A locale, optional.

Returns

A path of the current route.

Remarks

If locale is not specified, uses current locale.

localeRoute

Returns localized route for passed in route parameters.

Signature:

export declare function localeRoute(this: RoutingProxy, route: RawLocation | RouteLocationRaw, locale?: Locale): Route | ReturnType<Router['resolve']> | undefined;

Parameters

Parameter	Type	Description
this	RoutingProxy	A RoutingProxy instance.
route	RawLocation | RouteLocationRaw	A route.
locale	Locale	A locale, optional.

Returns

A route. if cannot resolve, undefined is returned.

Remarks

If locale is not specified, uses current locale.

localizeRoutes

Localize routes

Signature:

export declare function localizeRoutes(routes: I18nRoute[], { defaultLocale, strategy, trailingSlash, routesNameSeparator, defaultLocaleRouteNameSuffix, includeUprefixedFallback, optionsResolver, localizeRoutesPrefixable, locales }?: Pick<I18nRoutingOptions, 'defaultLocale' | 'strategy' | 'locales' | 'routesNameSeparator' | 'trailingSlash' | 'defaultLocaleRouteNameSuffix' | 'localizeRoutesPrefixable'> & {
    includeUprefixedFallback?: boolean;
    optionsResolver?: RouteOptionsResolver;
}): I18nRoute[];

Parameters

Parameter	Type	Description
routes	I18nRoute[]	Some routes
{ defaultLocale, strategy, trailingSlash, routesNameSeparator, defaultLocaleRouteNameSuffix, includeUprefixedFallback, optionsResolver, localizeRoutesPrefixable, locales }	Pick<I18nRoutingOptions, 'defaultLocale' | 'strategy' | 'locales' | 'routesNameSeparator' | 'trailingSlash' | 'defaultLocaleRouteNameSuffix' | 'localizeRoutesPrefixable'> & {

includeUprefixedFallback?: boolean;
optionsResolver?: RouteOptionsResolver;

} | |

Returns

Localized routes

proxyVueInstance

registerGlobalOptions

Register global i18n routing option registory

Signature:

export declare function registerGlobalOptions<Context = unknown>(router: Router | VueRouter, options: I18nRoutingGlobalOptions<Context>): void;

Parameters

Parameter	Type	Description
router	Router | VueRouter	A router instance, about router type
options	I18nRoutingGlobalOptions<Context>	A global options, about options type, see I18nRoutingGlobalOptions

resolveBaseUrl

Resolve base url

Signature:

export declare function resolveBaseUrl<Context = unknown>(baseUrl: string | BaseUrlResolveHandler<Context>, context: Context): string;

Parameters

Parameter	Type	Description
baseUrl	string | BaseUrlResolveHandler<Context>	A base url to resolve on SEO and domain. if you want to resolve with dynamically, you can spacify BaseUrlResolveHandler
context	Context	A context to resolve base url, if you want to resolve base url with BaseUrlResolveHandler

Returns

A resolved base url

resolveRoute

setLocale

Set a locale

Signature:

export declare function setLocale(i18n: I18n | Composer, locale: Locale): void;

Parameters

Parameter	Type	Description
i18n	I18n | Composer	An I18n instance or a Composer instance
locale	Locale	A target locale

switchLocalePath

Returns path of the current route for specified locale.

Signature:

export declare function switchLocalePath(this: RoutingProxy, locale: Locale): string;

Parameters

Parameter	Type	Description
this	RoutingProxy	A RoutingProxy instance.
locale	Locale	A locale

Returns

A path of the current route.

useLocaleHead

The useLocaleHead composable returns localized head properties for locale-related aspects.

Signature:

export declare function useLocaleHead({ addDirAttribute, addSeoAttributes, identifierAttribute, strategy, defaultLocale, route, router, i18n }?: Pick<I18nCommonRoutingOptionsWithComposable, 'strategy' | 'defaultLocale' | 'route' | 'router' | 'i18n'> & I18nHeadOptions): Ref<I18nHeadMetaInfo>;

Parameters

Parameter	Type	Description
{ addDirAttribute, addSeoAttributes, identifierAttribute, strategy, defaultLocale, route, router, i18n }	Pick<I18nCommonRoutingOptionsWithComposable, 'strategy' | 'defaultLocale' | 'route' | 'router' | 'i18n'> & I18nHeadOptions

Returns

The localized head properties with Vue ref.

useLocaleLocation

The useLocaleLocation composable returns function that resolve the locale location.

Signature:

export declare function useLocaleLocation({ router, route, i18n, defaultLocale, defaultLocaleRouteNameSuffix, routesNameSeparator, strategy, trailingSlash }?: I18nCommonRoutingOptionsWithComposable): LocaleLocationFunction;

Parameters

Parameter	Type	Description
{ router, route, i18n, defaultLocale, defaultLocaleRouteNameSuffix, routesNameSeparator, strategy, trailingSlash }	I18nCommonRoutingOptionsWithComposable

Returns

A LocaleLocationFunction.

Remarks

The function returned by useLocaleLocation is the wrapper function with the same signature as localeLocation.

useLocalePath

The useLocalePath composable returns function that resolve the locale path.

Signature:

export declare function useLocalePath({ router, route, i18n, defaultLocale, defaultLocaleRouteNameSuffix, routesNameSeparator, strategy, trailingSlash }?: I18nCommonRoutingOptionsWithComposable): LocalePathFunction;

Parameters

Parameter	Type	Description
{ router, route, i18n, defaultLocale, defaultLocaleRouteNameSuffix, routesNameSeparator, strategy, trailingSlash }	I18nCommonRoutingOptionsWithComposable

Returns

A LocalePathFunction.

Remarks

The function returned by useLocalePath is the wrapper function with the same signature as localePath.

useLocaleRoute

The useLocaleRoute composable returns function that resolve the locale route.

Signature:

export declare function useLocaleRoute({ router, route, i18n, defaultLocale, defaultLocaleRouteNameSuffix, routesNameSeparator, strategy, trailingSlash }?: I18nCommonRoutingOptionsWithComposable): LocaleRouteFunction;

Parameters

Parameter	Type	Description
{ router, route, i18n, defaultLocale, defaultLocaleRouteNameSuffix, routesNameSeparator, strategy, trailingSlash }	I18nCommonRoutingOptionsWithComposable

Returns

A LocaleRouteFunction.

Remarks

The function returned by useLocaleRoute is the wrapper function with the same signature as localeRoute.

useRouteBaseName

The useRouteBaseName composable returns a function which returns the route base name.

Signature:

export declare function useRouteBaseName({ router, route, i18n, defaultLocale, defaultLocaleRouteNameSuffix, routesNameSeparator, strategy, trailingSlash }?: I18nCommonRoutingOptionsWithComposable): RouteBaseNameFunction;

Parameters

Parameter	Type	Description
{ router, route, i18n, defaultLocale, defaultLocaleRouteNameSuffix, routesNameSeparator, strategy, trailingSlash }	I18nCommonRoutingOptionsWithComposable

Returns

A RouteBaseNameFunction.

Remarks

The function returned by useRouteBaseName is the wrapper function with the same signature as getRouteBaseName.

useSwitchLocalePath

The useSwitchLocalePath composable returns function that resolve the locale location.

Signature:

export declare function useSwitchLocalePath({ router, route, i18n, defaultLocale, defaultLocaleRouteNameSuffix, routesNameSeparator, strategy, trailingSlash }?: I18nCommonRoutingOptionsWithComposable): SwitchLocalePathFunction;

Parameters

Parameter	Type	Description
{ router, route, i18n, defaultLocale, defaultLocaleRouteNameSuffix, routesNameSeparator, strategy, trailingSlash }	I18nCommonRoutingOptionsWithComposable

Returns

A SwitchLocalePathFunction.

Remarks

The function returned by useSwitchLocalePath is the wrapper function with the same signature as switchLocalePath.

Variable

DefaultLocalizeRoutesPrefixable

DefaultPrefixable

DefaultSwitchLocalePathIntercepter

VERSION

Vue I18n Routing Version

Signature:

VERSION: string

Remarks

Semver format. Same format as the package.json version field.