mirror of https://github.com/vuejs/vitepress
feat: add i18n feature (#1339)
fix #291 fix #628 fix #631 fix #902 fix #955 fix #1253 fix #1381 Co-authored-by: Hiroki Okada <hirokio@tutanota.com> Co-authored-by: Sadegh Barati <sadeghbaratiwork@gmail.com>pull/1811/head
Divyansh Singh
2 years ago
committed by
GitHub
parent
471f00a68d
commit
8de2f4499d
@ -0,0 +1,99 @@
|
||||
# Internationalization
|
||||
|
||||
To use the built-in i18n features, one needs to create a directory structure as follows:
|
||||
|
||||
```
|
||||
docs/
|
||||
├─ es/
|
||||
│ ├─ foo.md
|
||||
├─ fr/
|
||||
│ ├─ foo.md
|
||||
├─ foo.md
|
||||
```
|
||||
|
||||
Then in `docs/.vitepress/config.ts`:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
// shared properties and other top-level stuff...
|
||||
|
||||
locales: {
|
||||
root: {
|
||||
label: 'English',
|
||||
lang: 'en'
|
||||
},
|
||||
fr: {
|
||||
label: 'French',
|
||||
lang: 'fr', // optional, will be added as `lang` attribute on `html` tag
|
||||
link: '/fr/guide' // default /fr/ -- shows on navbar translations menu, can be external
|
||||
|
||||
// other locale specific properties...
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
The following properties can be overridden for each locale (including root):
|
||||
|
||||
```ts
|
||||
interface LocaleSpecificConfig<ThemeConfig = any> {
|
||||
lang?: string
|
||||
dir?: string
|
||||
title?: string
|
||||
titleTemplate?: string | boolean
|
||||
description?: string
|
||||
head?: HeadConfig[] // will be merged with existing head entries, duplicate meta tags are automatically removed
|
||||
themeConfig?: ThemeConfig // will be shallow merged, common stuff can be put in top-level themeConfig entry
|
||||
}
|
||||
```
|
||||
|
||||
Refer [`DefaultTheme.Config`](https://github.com/vuejs/vitepress/blob/main/types/default-theme.d.ts) interface for details on customizing the placeholder texts of the default theme. Don't override `themeConfig.algolia` or `themeConfig.carbonAds` at locale-level. Refer [Algolia docs](./theme-search#i18n) for using multilingual search.
|
||||
|
||||
**Pro tip:** Config file can be stored at `docs/.vitepress/config/index.ts` too. It might help you organize stuff by creating a configuration file per locale and then merge and export them from `index.ts`.
|
||||
|
||||
## Separate directory for each locale
|
||||
|
||||
The following is a perfectly fine structure:
|
||||
|
||||
```
|
||||
docs/
|
||||
├─ en/
|
||||
│ ├─ foo.md
|
||||
├─ es/
|
||||
│ ├─ foo.md
|
||||
├─ fr/
|
||||
├─ foo.md
|
||||
```
|
||||
|
||||
However, VitePress won't redirect `/` to `/en/` by default. You'll need to configure your server for that. For example, on Netlify, you can add a `docs/public/_redirects` file like this:
|
||||
|
||||
```
|
||||
/* /es/:splat 302 Language=es
|
||||
/* /fr/:splat 302 Language=fr
|
||||
/* /en/:splat 302
|
||||
```
|
||||
|
||||
**Pro tip:** If using the above approach, you can use `nf_lang` cookie to persist user's language choice. A very basic way to do this is register a watcher inside the [setup](./theme-introduction#using-a-custom-theme) function of custom theme:
|
||||
|
||||
```ts
|
||||
// docs/.vitepress/theme/index.ts
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
|
||||
export default {
|
||||
...DefaultTheme,
|
||||
setup() {
|
||||
const { lang } = useData()
|
||||
watchEffect(() => {
|
||||
if (inBrowser) {
|
||||
document.cookie = `nf_lang=${lang.value}; expires=Mon, 1 Jan 2024 00:00:00 UTC; path=/`
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## RTL Support (Experimental)
|
||||
|
||||
For RTL support, specify `dir: 'rtl'` in config and use some RTLCSS PostCSS plugin like <https://github.com/MohammadYounes/rtlcss>, <https://github.com/vkalinichev/postcss-rtl> or <https://github.com/elchininet/postcss-rtlcss>. You'll need to configure your PostCSS plugin to use `:where([dir="ltr"])` and `:where([dir="rtl"])` as prefixes to prevent CSS specificity issues.
|
||||
@ -1,3 +1,85 @@
|
||||
# Search
|
||||
|
||||
Documentation coming soon...
|
||||
VitePress supports searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Refer their getting started guide. In your `.vitepress/config.ts` you'll need to provide at least the following to make it work:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
algolia: {
|
||||
appId: '...',
|
||||
apiKey: '...',
|
||||
indexName: '...'
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
If you are not eligible for DocSearch, you might wanna use some community plugins like <https://github.com/emersonbottero/vitepress-plugin-search> or explore some custom solutions on [this GitHub thread](https://github.com/vuejs/vitepress/issues/670).
|
||||
|
||||
## i18n
|
||||
|
||||
You can use a config like this to use multilingual search:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
// ...
|
||||
themeConfig: {
|
||||
// ...
|
||||
|
||||
algolia: {
|
||||
appId: '...',
|
||||
apiKey: '...',
|
||||
indexName: '...',
|
||||
locales: {
|
||||
zh: {
|
||||
placeholder: '搜索文档',
|
||||
translations: {
|
||||
button: {
|
||||
buttonText: '搜索文档',
|
||||
buttonAriaLabel: '搜索文档'
|
||||
},
|
||||
modal: {
|
||||
searchBox: {
|
||||
resetButtonTitle: '清除查询条件',
|
||||
resetButtonAriaLabel: '清除查询条件',
|
||||
cancelButtonText: '取消',
|
||||
cancelButtonAriaLabel: '取消'
|
||||
},
|
||||
startScreen: {
|
||||
recentSearchesTitle: '搜索历史',
|
||||
noRecentSearchesText: '没有搜索历史',
|
||||
saveRecentSearchButtonTitle: '保存至搜索历史',
|
||||
removeRecentSearchButtonTitle: '从搜索历史中移除',
|
||||
favoriteSearchesTitle: '收藏',
|
||||
removeFavoriteSearchButtonTitle: '从收藏中移除'
|
||||
},
|
||||
errorScreen: {
|
||||
titleText: '无法获取结果',
|
||||
helpText: '你可能需要检查你的网络连接'
|
||||
},
|
||||
footer: {
|
||||
selectText: '选择',
|
||||
navigateText: '切换',
|
||||
closeText: '关闭',
|
||||
searchByText: '搜索提供者'
|
||||
},
|
||||
noResultsScreen: {
|
||||
noResultsText: '无法找到相关结果',
|
||||
suggestedQueryText: '你可以尝试查询',
|
||||
reportMissingResultsText: '你认为该查询应该有结果？',
|
||||
reportMissingResultsLinkText: '点击反馈'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
[These options](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) can be overridden. Refer official Algolia docs to learn more about them.
|
||||
|
||||
@ -1,13 +0,0 @@
|
||||
<script setup lang="ts">
|
||||
import { defineAsyncComponent } from 'vue'
|
||||
|
||||
const VPCarbonAds = __CARBON__
|
||||
? defineAsyncComponent(() => import('./VPCarbonAds.vue'))
|
||||
: () => null
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="VPDocAsideCarbonAds">
|
||||
<VPCarbonAds />
|
||||
</div>
|
||||
</template>
|
||||
@ -0,0 +1,4 @@
|
||||
import { useData as useData$ } from 'vitepress'
|
||||
import type { DefaultTheme } from 'vitepress/theme'
|
||||
|
||||
export const useData: typeof useData$<DefaultTheme.Config> = useData$
|
||||
@ -0,0 +1,50 @@
|
||||
import { computed } from 'vue'
|
||||
import { useData } from './data.js'
|
||||
import { ensureStartingSlash } from '../support/utils.js'
|
||||
|
||||
export function useLangs({
|
||||
removeCurrent = true,
|
||||
correspondingLink = false
|
||||
} = {}) {
|
||||
const { site, localeIndex, page, theme } = useData()
|
||||
const currentLang = computed(() => ({
|
||||
label: site.value.locales[localeIndex.value]?.label,
|
||||
link:
|
||||
site.value.locales[localeIndex.value]?.link ||
|
||||
(localeIndex.value === 'root' ? '/' : `/${localeIndex.value}/`)
|
||||
}))
|
||||
|
||||
const localeLinks = computed(() =>
|
||||
Object.entries(site.value.locales).flatMap(([key, value]) =>
|
||||
removeCurrent && currentLang.value.label === value.label
|
||||
? []
|
||||
: {
|
||||
text: value.label,
|
||||
link: normalizeLink(
|
||||
value.link || (key === 'root' ? '/' : `/${key}/`),
|
||||
theme.value.i18nRouting !== false && correspondingLink,
|
||||
page.value.relativePath.slice(currentLang.value.link.length - 1),
|
||||
site.value.cleanUrls === 'disabled'
|
||||
)
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
return { localeLinks, currentLang }
|
||||
}
|
||||
|
||||
function normalizeLink(
|
||||
link: string,
|
||||
addPath: boolean,
|
||||
path: string,
|
||||
addExt: boolean
|
||||
) {
|
||||
return addPath
|
||||
? link.replace(/\/$/, '') +
|
||||
ensureStartingSlash(
|
||||
path
|
||||
.replace(/(^|\/)?index.md$/, '$1')
|
||||
.replace(/\.md$/, addExt ? '.html' : '')
|
||||
)
|
||||
: link
|
||||
}
|
||||
@ -0,0 +1,143 @@
|
||||
export interface DocSearchProps {
|
||||
appId: string
|
||||
apiKey: string
|
||||
indexName: string
|
||||
placeholder?: string
|
||||
searchParameters?: SearchOptions
|
||||
disableUserPersonalization?: boolean
|
||||
initialQuery?: string
|
||||
translations?: DocSearchTranslations
|
||||
}
|
||||
|
||||
export interface SearchOptions {
|
||||
query?: string
|
||||
similarQuery?: string
|
||||
facetFilters?: string | string[]
|
||||
optionalFilters?: string | string[]
|
||||
numericFilters?: string | string[]
|
||||
tagFilters?: string | string[]
|
||||
sumOrFiltersScores?: boolean
|
||||
filters?: string
|
||||
page?: number
|
||||
hitsPerPage?: number
|
||||
offset?: number
|
||||
length?: number
|
||||
attributesToHighlight?: string[]
|
||||
attributesToSnippet?: string[]
|
||||
attributesToRetrieve?: string[]
|
||||
highlightPreTag?: string
|
||||
highlightPostTag?: string
|
||||
snippetEllipsisText?: string
|
||||
restrictHighlightAndSnippetArrays?: boolean
|
||||
facets?: string[]
|
||||
maxValuesPerFacet?: number
|
||||
facetingAfterDistinct?: boolean
|
||||
minWordSizefor1Typo?: number
|
||||
minWordSizefor2Typos?: number
|
||||
allowTyposOnNumericTokens?: boolean
|
||||
disableTypoToleranceOnAttributes?: string[]
|
||||
queryType?: 'prefixLast' | 'prefixAll' | 'prefixNone'
|
||||
removeWordsIfNoResults?: 'none' | 'lastWords' | 'firstWords' | 'allOptional'
|
||||
advancedSyntax?: boolean
|
||||
advancedSyntaxFeatures?: ('exactPhrase' | 'excludeWords')[]
|
||||
optionalWords?: string | string[]
|
||||
disableExactOnAttributes?: string[]
|
||||
exactOnSingleWordQuery?: 'attribute' | 'none' | 'word'
|
||||
alternativesAsExact?: (
|
||||
| 'ignorePlurals'
|
||||
| 'singleWordSynonym'
|
||||
| 'multiWordsSynonym'
|
||||
)[]
|
||||
enableRules?: boolean
|
||||
ruleContexts?: string[]
|
||||
distinct?: boolean | number
|
||||
analytics?: boolean
|
||||
analyticsTags?: string[]
|
||||
synonyms?: boolean
|
||||
replaceSynonymsInHighlight?: boolean
|
||||
minProximity?: number
|
||||
responseFields?: string[]
|
||||
maxFacetHits?: number
|
||||
percentileComputation?: boolean
|
||||
clickAnalytics?: boolean
|
||||
personalizationImpact?: number
|
||||
enablePersonalization?: boolean
|
||||
restrictSearchableAttributes?: string[]
|
||||
sortFacetValuesBy?: 'count' | 'alpha'
|
||||
typoTolerance?: boolean | 'min' | 'strict'
|
||||
aroundLatLng?: string
|
||||
aroundLatLngViaIP?: boolean
|
||||
aroundRadius?: number | 'all'
|
||||
aroundPrecision?: number | { from: number; value: number }[]
|
||||
minimumAroundRadius?: number
|
||||
insideBoundingBox?: number[][]
|
||||
insidePolygon?: number[][]
|
||||
ignorePlurals?: boolean | string[]
|
||||
removeStopWords?: boolean | string[]
|
||||
naturalLanguages?: string[]
|
||||
getRankingInfo?: boolean
|
||||
userToken?: string
|
||||
enableABTest?: boolean
|
||||
decompoundQuery?: boolean
|
||||
relevancyStrictness?: number
|
||||
}
|
||||
|
||||
export interface DocSearchTranslations {
|
||||
button?: ButtonTranslations
|
||||
modal?: ModalTranslations
|
||||
}
|
||||
|
||||
export interface ButtonTranslations {
|
||||
buttonText?: string
|
||||
buttonAriaLabel?: string
|
||||
}
|
||||
|
||||
export interface ModalTranslations extends ScreenStateTranslations {
|
||||
searchBox?: SearchBoxTranslations
|
||||
footer?: FooterTranslations
|
||||
}
|
||||
|
||||
export interface ScreenStateTranslations {
|
||||
errorScreen?: ErrorScreenTranslations
|
||||
startScreen?: StartScreenTranslations
|
||||
noResultsScreen?: NoResultsScreenTranslations
|
||||
}
|
||||
|
||||
export interface SearchBoxTranslations {
|
||||
resetButtonTitle?: string
|
||||
resetButtonAriaLabel?: string
|
||||
cancelButtonText?: string
|
||||
cancelButtonAriaLabel?: string
|
||||
}
|
||||
|
||||
export interface FooterTranslations {
|
||||
selectText?: string
|
||||
selectKeyAriaLabel?: string
|
||||
navigateText?: string
|
||||
navigateUpKeyAriaLabel?: string
|
||||
navigateDownKeyAriaLabel?: string
|
||||
closeText?: string
|
||||
closeKeyAriaLabel?: string
|
||||
searchByText?: string
|
||||
}
|
||||
|
||||
export interface ErrorScreenTranslations {
|
||||
titleText?: string
|
||||
helpText?: string
|
||||
}
|
||||
|
||||
export interface StartScreenTranslations {
|
||||
recentSearchesTitle?: string
|
||||
noRecentSearchesText?: string
|
||||
saveRecentSearchButtonTitle?: string
|
||||
removeRecentSearchButtonTitle?: string
|
||||
favoriteSearchesTitle?: string
|
||||
removeFavoriteSearchButtonTitle?: string
|
||||
}
|
||||
|
||||
export interface NoResultsScreenTranslations {
|
||||
noResultsText?: string
|
||||
suggestedQueryText?: string
|
||||
reportMissingResultsText?: string
|
||||
reportMissingResultsLinkText?: string
|
||||
}
|
||||
Loading…
Reference in new issue