From d2e132a29808c9462201a24601b823d15cae565f Mon Sep 17 00:00:00 2001 From: leejooy96 Date: Tue, 29 Oct 2024 13:34:58 +0900 Subject: [PATCH] docs: add internationalization document --- .../en/advanced-usage/internationalization.md | 216 ++++++++++++++++++ .../ko/advanced-usage/internationalization.md | 216 ++++++++++++++++++ .../advanced-usage/internationalization.md | 216 ++++++++++++++++++ 3 files changed, 648 insertions(+) create mode 100644 docs/en/advanced-usage/internationalization.md create mode 100644 docs/ko/advanced-usage/internationalization.md create mode 100644 docs/zhHans/advanced-usage/internationalization.md diff --git a/docs/en/advanced-usage/internationalization.md b/docs/en/advanced-usage/internationalization.md new file mode 100644 index 00000000..dc988cb0 --- /dev/null +++ b/docs/en/advanced-usage/internationalization.md @@ -0,0 +1,216 @@ +# Internationalization + +This page describes how to achieve internationalization (i18n) using VitePress Sidebar. + +VitePress supports multilingual documentation. If you place translated markdown files in a directory for each language and use the `locales` option in VitePress's `defineConfig`, a language selector will be displayed and will show documents in the specified directory for each language. + +## Translate page layouts (manually) + +First, VitePress allows you to translate various layout interface elements. By layout, we mean all the associated text for features like 'Previous', 'Next', 'Table of Contents', and 'Change Theme'. It also includes translating any text that appears in the search function. + +Various interface (layout) texts on a VitePress page can provide language-specific translations for `locales`. For example + +```shell +"locales": { + "root": { + "lang": "en-US", + "label": "English", + "description": "VitePress Sidebar is a VitePress plugin that automatically generates sidebar menus with one setup and no hassle. Save time by easily creating taxonomies for tons of articles.", + "themeConfig": { + "docFooter": { + "prev": "Previous page", + "next": "Next page" + }, + "outline": { + "label": "On this page" + }, + "lastUpdated": { + "text": "Last updated" + }, + "langMenuLabel": "Change language", + "returnToTopLabel": "Return to top", + "sidebarMenuLabel": "Menu", + "darkModeSwitchLabel": "Appearance", + "lightModeSwitchTitle": "Switch to light theme", + "darkModeSwitchTitle": "Switch to dark theme" + } + }, + "ko": { + "lang": "ko-KR", + "label": "한국어", + "description": "VitePress Sidebar는 번거로운 작업 없이 한번의 설정만으로 사이드바 메뉴를 자니다. 수많은 문서에 대한 분류를 손쉽게 만들어 시간을 절약하세요.", + "themeConfig": { + "docFooter": { + "prev": "이전", + "next": "다음" + }, + "outline": { + "label": "이 페이지 콘텐츠" + }, + "lastUpdated": { + "text": "업데이트 일자" + }, + "langMenuLabel": "언어 변경", + "returnToTopLabel": "맨 위로", + "sidebarMenuLabel": "사이드바 메뉴", + "darkModeSwitchLabel": "다크 모드", + "lightModeSwitchTitle": "라이트 모드로 변경", + "darkModeSwitchTitle": "다크 모드로 변경" + } + } +} +``` + +(The `root` language is the primary language on the page). + +To learn more about translating layouts, see the following articles: https://vitepress.dev/guide/i18n + +For the text that appears in the search function, you need to set it in the `themeConfig.search` option in `defineConfig`, for example + +```shell +"themeConfig": { + "search": { + "provider": "local", + "options": { + "locales": { + "root": { + "translations": { + "button": { + "buttonText": "Search", + "buttonAriaLabel": "Search" + }, + "modal": { + "displayDetails": "Display detailed list", + "resetButtonTitle": "Reset search", + "backButtonTitle": "Close search", + "noResultsText": "No results for", + "footer": { + "selectText": "to select", + "selectKeyAriaLabel": "enter", + "navigateText": "to navigate", + "navigateUpKeyAriaLabel": "up arrow", + "navigateDownKeyAriaLabel": "down arrow", + "closeText": "to close", + "closeKeyAriaLabel": "escape" + } + } + } + }, + "ko": { + "translations": { + "button": { + "buttonText": "검색", + "buttonAriaLabel": "검색" + }, + "modal": { + "displayDetails": "상세 목록 표시", + "resetButtonTitle": "검색 초기화", + "backButtonTitle": "검색 닫기", + "noResultsText": "결과를 찾을 수 없음", + "footer": { + "selectText": "선택", + "selectKeyAriaLabel": "선택하기", + "navigateText": "탐색", + "navigateUpKeyAriaLabel": "위로", + "navigateDownKeyAriaLabel": "아래로", + "closeText": "닫기", + "closeKeyAriaLabel": "esc" + } + } + } + } + } + } + } +} +``` + +## Translate page layouts (automatic) + +[VitePress I18n](https://vitepress-i18n.cdget.com), a family plugin of VitePress Sidebar, allows you to automate the process of translating manually like above. With a few simple settings, you can stop spending hours translating layouts! + +Install the VitePress I18n module with the command below: + +```shell +$ npm i -D vitepress-i18n +``` + +And in `defineConfig`, set the following + +```javascript +const vitePressConfig = { + // VitePress config +}; + +const vitePressI18nConfig = { + // VitePress I18n config + locales: ['en', 'ko'], // first locale 'en' is root locale + searchProvider: 'local' // enable search with auto translation +}; + +export default defineConfig(withI18n(vitePressConfig, vitePressI18nConfig)); +``` + +Now leave the interface translation to the module! Of course, you can customize the detailed text as well. + +For more information, read the documentation page for VitePress I18n: https://vitepress-i18n.cdget.com/guide/getting-started + +## Language-specific sidebar settings + +In VitePress, you can display the sidebar differently for different languages. For example, let's say you have a folder structure like this + +```text +/ +├─ package.json +├─ docs/ +│ ├─ .vitepress/ +│ │ └─ config.js +│ ├─ en/ +│ │ └─ abc.md +│ ├─ ko/ +│ │ └─ abc.md +│ └─ zhHans/ +│ └─ abc.md +└─ ... +``` + +In the example, `abc.md` is the same document translated into each language. If you change the language to English, Korean, and Chinese respectively, the sidebar will scan each directory `en`, `ko`, and `zhHans` to get the title for the language. + +Here's an example of how to accomplish this: + +```shell +const rootLocale = 'en' +const supportedLocales = [rootLocale, 'ko', 'zhHans']; + +const commonSidebarConfig = { + // Sidebar common configurations +} + +export default defineConfig({ + rewrites: { + 'en/:rest*': ':rest*' + }, + themeConfig: { + sidebar: generateSidebar([ + ...supportedLocales.map((lang) => { + return { + ...commonSidebarConfig, + ...(rootLocale === lang ? {} : { basePath: `/${lang}/` }), // If using `rewrites` option + documentRootPath: `/docs/${lang}`, + resolvePath: rootLocale === lang ? '/' : `/${lang}/`, + }; + }) + ]), + } +}) +``` + +First, `rewrites` allows you to suppress `/en/` in the URI path when you are using English as the root language (the `en` directory). (This is optional.) + +Next, the setup of `sidebar` is similar to the previous one, but you need to set up multiple sidebars with directories for each language. Here's a description of each option: + +- `basePath`: When used in conjunction with the `rewrites` rule, it prevents the root locale from pointing to the `/en/` path. +- `documentRootPath`: The root path where the actual documentation files are located. For each language, look for the `en`, `ko`, and `zhHans` directories. +- `resolvePath`: `/docs` The location of the file from the directory that should actually scan the sidebar listings. Specify the directory location for each language, excluding the root locale. + +This ensures that the sidebar only displays articles from the specified directory per language. The above is an example, so you may need to set the options differently depending on the size of your project or directory structure. diff --git a/docs/ko/advanced-usage/internationalization.md b/docs/ko/advanced-usage/internationalization.md new file mode 100644 index 00000000..a6701b5e --- /dev/null +++ b/docs/ko/advanced-usage/internationalization.md @@ -0,0 +1,216 @@ +# 국제화 + +이 페이지에서는 VitePress Sidebar를 사용하여 i18n (internationalization)을 달성하는 방법을 기술합니다. + +VitePress에서는 다국어 문서를 지원합니다. 번역된 마크다운 파일을 각 언어별 디렉토리에 배치하고 VitePress의 `defineConfig`의 `locales` 옵션을 사용할 경우 언어 선택기가 표시되며 각 언어별로 지정된 디렉토리의 문서를 표시합니다. + +## 페이지 레이아웃 번역 (수동) + +먼저 VitePress에서는 각종 레이아웃 인터페이스 요소를 번역할 수 있습니다. 여기서 레이아웃은 '이전', '다음', '목차', '테마 변경'과 같은 기능에 대한 관련된 모든 텍스트를 의미합니다. 또한 검색 기능에 표시되는 모든 텍스트 번역을 포함합니다. + +VitePress 페이지에 있는 각종 인터페이스(레이아웃) 텍스트는 `locales`에 언어별로 번역된 텍스트를 제공할 수 있습니다. 예를 들면 다음과 같습니다: + +```shell +"locales": { + "root": { + "lang": "en-US", + "label": "English", + "description": "VitePress Sidebar is a VitePress plugin that automatically generates sidebar menus with one setup and no hassle. Save time by easily creating taxonomies for tons of articles.", + "themeConfig": { + "docFooter": { + "prev": "Previous page", + "next": "Next page" + }, + "outline": { + "label": "On this page" + }, + "lastUpdated": { + "text": "Last updated" + }, + "langMenuLabel": "Change language", + "returnToTopLabel": "Return to top", + "sidebarMenuLabel": "Menu", + "darkModeSwitchLabel": "Appearance", + "lightModeSwitchTitle": "Switch to light theme", + "darkModeSwitchTitle": "Switch to dark theme" + } + }, + "ko": { + "lang": "ko-KR", + "label": "한국어", + "description": "VitePress Sidebar는 번거로운 작업 없이 한번의 설정만으로 사이드바 메뉴를 자니다. 수많은 문서에 대한 분류를 손쉽게 만들어 시간을 절약하세요.", + "themeConfig": { + "docFooter": { + "prev": "이전", + "next": "다음" + }, + "outline": { + "label": "이 페이지 콘텐츠" + }, + "lastUpdated": { + "text": "업데이트 일자" + }, + "langMenuLabel": "언어 변경", + "returnToTopLabel": "맨 위로", + "sidebarMenuLabel": "사이드바 메뉴", + "darkModeSwitchLabel": "다크 모드", + "lightModeSwitchTitle": "라이트 모드로 변경", + "darkModeSwitchTitle": "다크 모드로 변경" + } + } +} +``` + +(`root` 언어는 페이지에서 주 언어를 의미합니다.) + +레이아웃 번역을 자세히 알아보려면 다음 문서를 참고하세요: https://vitepress.dev/guide/i18n + +검색 기능에 표시되는 텍스트의 경우 `defineConfig`의 `themeConfig.search` 옵션에서 설정해야 합니다. 예를 들면 다음과 같습니다: + +```shell +"themeConfig": { + "search": { + "provider": "local", + "options": { + "locales": { + "root": { + "translations": { + "button": { + "buttonText": "Search", + "buttonAriaLabel": "Search" + }, + "modal": { + "displayDetails": "Display detailed list", + "resetButtonTitle": "Reset search", + "backButtonTitle": "Close search", + "noResultsText": "No results for", + "footer": { + "selectText": "to select", + "selectKeyAriaLabel": "enter", + "navigateText": "to navigate", + "navigateUpKeyAriaLabel": "up arrow", + "navigateDownKeyAriaLabel": "down arrow", + "closeText": "to close", + "closeKeyAriaLabel": "escape" + } + } + } + }, + "ko": { + "translations": { + "button": { + "buttonText": "검색", + "buttonAriaLabel": "검색" + }, + "modal": { + "displayDetails": "상세 목록 표시", + "resetButtonTitle": "검색 초기화", + "backButtonTitle": "검색 닫기", + "noResultsText": "결과를 찾을 수 없음", + "footer": { + "selectText": "선택", + "selectKeyAriaLabel": "선택하기", + "navigateText": "탐색", + "navigateUpKeyAriaLabel": "위로", + "navigateDownKeyAriaLabel": "아래로", + "closeText": "닫기", + "closeKeyAriaLabel": "esc" + } + } + } + } + } + } + } +} +``` + +## 페이지 레이아웃 번역 (자동) + +VitePress Sidebar의 패밀리 플러그인인 [VitePress I18n](https://vitepress-i18n.cdget.com)을 사용하면 위와 같이 수동으로 번역하는 과정을 자동화할 수 있습니다. 몇가지 간단한 설정만으로 레이아웃 번역에 시간을 투자하지 않아도 됩니다! + +아래 명령어로 VitePress I18n 모듈을 설치하세요: + +```shell +$ npm i -D vitepress-i18n +``` + +그리고 `defineConfig`에 다음과 같이 설정합니다. + +```javascript +const vitePressConfig = { + // VitePress config +}; + +const vitePressI18nConfig = { + // VitePress I18n config + locales: ['en', 'ko'], // first locale 'en' is root locale + searchProvider: 'local' // enable search with auto translation +}; + +export default defineConfig(withI18n(vitePressConfig, vitePressI18nConfig)); +``` + +이제 인터페이스 번역은 모듈에게 맡기세요! 물론 세부적인 텍스트도 커스터마이징 할 수 있습니다. + +자세한 내용은 VitePress I18n의 문서 페이지를 읽어주세요: https://vitepress-i18n.cdget.com/guide/getting-started + +## 언어별 사이드바 설정 + +VitePress에서 언어별로 사이드바를 다르게 표시할 수 있습니다. 예를 들면 다음과 같은 폴더 구조를 가지고 있다고 가정해보겠습니다: + +```text +/ +├─ package.json +├─ docs/ +│ ├─ .vitepress/ +│ │ └─ config.js +│ ├─ en/ +│ │ └─ abc.md +│ ├─ ko/ +│ │ └─ abc.md +│ └─ zhHans/ +│ └─ abc.md +└─ ... +``` + +예시의 `abc.md`는 각 언어로 번역된 같은 문서입니다. 언어를 각각 영어, 한국어, 중국어로 변경할 경우 사이드바는 각 디렉토리 `en`, `ko`, `zhHans`를 스캔하여 언어에 맞는 제목을 가져 올 것입니다. + +이를 달성하는 예시는 다음과 같습니다: + +```shell +const rootLocale = 'en' +const supportedLocales = [rootLocale, 'ko', 'zhHans']; + +const commonSidebarConfig = { + // Sidebar common configurations +} + +export default defineConfig({ + rewrites: { + 'en/:rest*': ':rest*' + }, + themeConfig: { + sidebar: generateSidebar([ + ...supportedLocales.map((lang) => { + return { + ...commonSidebarConfig, + ...(rootLocale === lang ? {} : { basePath: `/${lang}/` }), // If using `rewrites` option + documentRootPath: `/docs/${lang}`, + resolvePath: rootLocale === lang ? '/' : `/${lang}/`, + }; + }) + ]), + } +}) +``` + +먼저 `rewrites`는 root 언어인 영어(`en` 디렉토리)를 사용 중일 때, URI 경로에 `/en/`을 표시하지 않게 해줍니다. (이는 선택사항입니다.) + +다음으로 `sidebar`의 설정은 기존과 비슷하지만, 각 언어별 디렉토리로 구성된 다중 사이드바를 설정해야 합니다. 각 옵션에 대한 설명은 다음과 같습니다: + +- `basePath`: `rewrites` 규칙과 함께 사용 중일 때 root 로캐일이면 `/en/` 경로를 가리키지 않도록 합니다. +- `documentRootPath`: 실제 문서 파일이 위치한 루트 경로입니다. 각 언어별로 `en`, `ko`, `zhHans` 디렉토리를 찾도록 합니다. +- `resolvePath`: `/docs` 디렉토리로부터 실제로 사이드바 목록을 스캔해야 할 파일의 위치입니다. root 로캐일을 제외하고 각 언어별로 디렉토리 위치를 지정합니다. + +이렇게 하면 언어 마다 지정한 디렉토리의 문서만 사이드바에서 표시할 수 있도록 합니다. 위는 예시이므로 프로젝트의 규모나 디렉토리 구조에 따라 옵션 설정을 다르게 해야 할 수 있습니다. diff --git a/docs/zhHans/advanced-usage/internationalization.md b/docs/zhHans/advanced-usage/internationalization.md new file mode 100644 index 00000000..b4e22e0f --- /dev/null +++ b/docs/zhHans/advanced-usage/internationalization.md @@ -0,0 +1,216 @@ +# 国际化 + +本页介绍如何使用 VitePress Sidebar 实现国际化（i18n）。 + +VitePress 支持多语言文档。如果您将翻译好的标记文件放在每种语言的目录中，并在 VitePress 的 `defineConfig` 中使用 `locales` 选项，就会显示语言选择器，并显示指定目录中每种语言的文档。 + +## 翻译页面布局（手动） + +首先，VitePress 允许您翻译各种布局界面元素。所谓布局，是指 “上一页”、“下一页”、“目录”、“更改主题 ”等功能的所有相关文本。 它还包括翻译搜索功能中出现的所有文本。 + +VitePress 页面上的各种界面（布局）文本可提供特定语言的 `locales` 翻译。例如: + +```shell +"locales": { + "root": { + "lang": "en-US", + "label": "English", + "description": "VitePress Sidebar is a VitePress plugin that automatically generates sidebar menus with one setup and no hassle. Save time by easily creating taxonomies for tons of articles.", + "themeConfig": { + "docFooter": { + "prev": "Previous page", + "next": "Next page" + }, + "outline": { + "label": "On this page" + }, + "lastUpdated": { + "text": "Last updated" + }, + "langMenuLabel": "Change language", + "returnToTopLabel": "Return to top", + "sidebarMenuLabel": "Menu", + "darkModeSwitchLabel": "Appearance", + "lightModeSwitchTitle": "Switch to light theme", + "darkModeSwitchTitle": "Switch to dark theme" + } + }, + "ko": { + "lang": "ko-KR", + "label": "한국어", + "description": "VitePress Sidebar는 번거로운 작업 없이 한번의 설정만으로 사이드바 메뉴를 자니다. 수많은 문서에 대한 분류를 손쉽게 만들어 시간을 절약하세요.", + "themeConfig": { + "docFooter": { + "prev": "이전", + "next": "다음" + }, + "outline": { + "label": "이 페이지 콘텐츠" + }, + "lastUpdated": { + "text": "업데이트 일자" + }, + "langMenuLabel": "언어 변경", + "returnToTopLabel": "맨 위로", + "sidebarMenuLabel": "사이드바 메뉴", + "darkModeSwitchLabel": "다크 모드", + "lightModeSwitchTitle": "라이트 모드로 변경", + "darkModeSwitchTitle": "다크 모드로 변경" + } + } +} +``` + +(`root` "语言指页面上的主要语言）。 + +要了解有关翻译布局的更多信息，请参阅以下文章: https://vitepress.dev/guide/i18n + +对于搜索功能中出现的文本，需要在 `defineConfig` 中的 `themeConfig.search` 选项中进行设置，例如: + +```shell +"themeConfig": { + "search": { + "provider": "local", + "options": { + "locales": { + "root": { + "translations": { + "button": { + "buttonText": "Search", + "buttonAriaLabel": "Search" + }, + "modal": { + "displayDetails": "Display detailed list", + "resetButtonTitle": "Reset search", + "backButtonTitle": "Close search", + "noResultsText": "No results for", + "footer": { + "selectText": "to select", + "selectKeyAriaLabel": "enter", + "navigateText": "to navigate", + "navigateUpKeyAriaLabel": "up arrow", + "navigateDownKeyAriaLabel": "down arrow", + "closeText": "to close", + "closeKeyAriaLabel": "escape" + } + } + } + }, + "ko": { + "translations": { + "button": { + "buttonText": "검색", + "buttonAriaLabel": "검색" + }, + "modal": { + "displayDetails": "상세 목록 표시", + "resetButtonTitle": "검색 초기화", + "backButtonTitle": "검색 닫기", + "noResultsText": "결과를 찾을 수 없음", + "footer": { + "selectText": "선택", + "selectKeyAriaLabel": "선택하기", + "navigateText": "탐색", + "navigateUpKeyAriaLabel": "위로", + "navigateDownKeyAriaLabel": "아래로", + "closeText": "닫기", + "closeKeyAriaLabel": "esc" + } + } + } + } + } + } + } +} +``` + +## 翻译页面布局（自动） + +[VitePress I18n](https://vitepress-i18n.cdget.com)是VitePress侧边栏的一个家族插件，可让您自动完成上述手动翻译过程。只需进行一些简单的设置，您就不必花费数小时来翻译布局！ + +使用以下命令安装 VitePress I18n 模块: + +```shell +$ npm i -D vitepress-i18n +``` + +在 `defineConfig` 中，将其设置为. + +```javascript +const vitePressConfig = { + // VitePress config +}; + +const vitePressI18nConfig = { + // VitePress I18n config + locales: ['en', 'ko'], // first locale 'en' is root locale + searchProvider: 'local' // enable search with auto translation +}; + +export default defineConfig(withI18n(vitePressConfig, vitePressI18nConfig)); +``` + +现在，您可以将界面翻译工作交给模块来完成！当然，您也可以自定义详细文本。 + +更多信息，请阅读 VitePress I18n 文档页面: https://vitepress-i18n.cdget.com/guide/getting-started + +## 特定语言侧边栏设置 + +在 VitePress 中，您可以根据不同的语言显示不同的侧边栏。例如，假设您的文件夹结构如下: + +```text +/ +├─ package.json +├─ docs/ +│ ├─ .vitepress/ +│ │ └─ config.js +│ ├─ en/ +│ │ └─ abc.md +│ ├─ ko/ +│ │ └─ abc.md +│ └─ zhHans/ +│ └─ abc.md +└─ ... +``` + +在示例中，`abc.md` 是翻译成每种语言的同一文档。如果将语言分别改为英文、韩文和中文，侧边栏将扫描每个目录`en`、`ko`和`zhHans`，以获取该语言的标题。 + +下面举例说明如何做到这一点: + +```shell +const rootLocale = 'en' +const supportedLocales = [rootLocale, 'ko', 'zhHans']; + +const commonSidebarConfig = { + // Sidebar common configurations +} + +export default defineConfig({ + rewrites: { + 'en/:rest*': ':rest*' + }, + themeConfig: { + sidebar: generateSidebar([ + ...supportedLocales.map((lang) => { + return { + ...commonSidebarConfig, + ...(rootLocale === lang ? {} : { basePath: `/${lang}/` }), // If using `rewrites` option + documentRootPath: `/docs/${lang}`, + resolvePath: rootLocale === lang ? '/' : `/${lang}/`, + }; + }) + ]), + } +}) +``` + +首先，`rewrites` 允许您在使用英语作为根语言（`en` 目录）时抑制 URI 路径中的 `/en/`（这是可选的）。 + +下一步，`sidebar` 的设置与上一步类似，但需要为每种语言设置多个侧边栏和目录。 下文将解释每个选项： + +- `basePath`: 与 `rewrites` 规则一起使用时，可防止根本地化指向 `/en/` 路径。 +- `documentRootPath`: 实际文档文件所在的根路径。 对于每种语言，查找 `en`、`ko` 和 `zhHans` 目录。 +- `resolvePath`: `/docs` 实际扫描侧边栏列表的目录中文件的位置。 为每种语言指定目录位置，不包括根本地语言。 + +这样可以确保侧边栏只显示指定目录下每种语言的文档。以上只是一个示例，您可能需要根据项目规模或目录结构设置不同的选项。