From e659097ac3c0901fda4dfe51f53469c009443f2d Mon Sep 17 00:00:00 2001 From: jspark Date: Tue, 29 Aug 2023 05:50:32 +0900 Subject: i18n(ko-KR): translate `i18n.mdx` (#584) Co-authored-by: Chris Swithinbank --- docs/src/content/docs/ko/guides/customization.mdx | 400 ++++++++++++++++++++++ docs/src/content/docs/ko/guides/i18n.mdx | 218 ++++++++++++ 2 files changed, 618 insertions(+) create mode 100644 docs/src/content/docs/ko/guides/customization.mdx create mode 100644 docs/src/content/docs/ko/guides/i18n.mdx diff --git a/docs/src/content/docs/ko/guides/customization.mdx b/docs/src/content/docs/ko/guides/customization.mdx new file mode 100644 index 00000000..d2ba89e4 --- /dev/null +++ b/docs/src/content/docs/ko/guides/customization.mdx @@ -0,0 +1,400 @@ +--- +title: Starlight 사용자 정의 +description: 로고, 사용자 정의 글꼴, 랜딩 페이지 디자인 등을 사용하여 나만의 Starlight 사이트를 만드는 방법을 알아보세요. +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; +import FileTree from '../../../../components/file-tree.astro'; + +Starlight는 합리적인 기본 스타일과 기능을 제공하므로 구성 없이 빠르게 시작할 수 있습니다. Starlight 사이트의 모양과 느낌을 변경하려는 경우 이 가이드를 참조하세요. + +## 로고 추가 + +사이트 헤더에 로고를 추가하는 것은 Starlight 사이트에 브랜드를 추가하는 빠른 방법입니다. + +1. `src/assets/` 디렉토리에 로고 이미지 파일을 추가합니다. + + + + - src/ + - assets/ + - **my-logo.svg** + - content/ + - astro.config.mjs + + + +2. `astro.config.mjs` 파일에 있는 [logo.src](/ko/reference/configuration/#logo) 옵션의 값으로 로고 파일의 경로를 추가하세요. + + ```js + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import starlight from '@astrojs/starlight'; + + export default defineConfig({ + integrations: [ + starlight({ + title: '로고를 사용하는 문서', + logo: { + src: './src/assets/my-logo.svg', + }, + }), + ], + }); + ``` + +기본적으로 로고는 사이트의 `title`과 함께 표시됩니다. 로고 이미지에 사이트 제목이 이미 포함되어 있는 경우, `replacementTitle` 옵션을 설정하여 제목 텍스트를 시각적으로 숨길 수 있습니다. `title` 텍스트는 스크린 리더를 위해 남아 있기 때문에 헤더는 접근성이 유지됩니다. + +```js +starlight({ + title: '로고를 사용하는 문서', + logo: { + src: './src/assets/my-logo.svg', + replacesTitle: true, + }, +}), +``` + +### 라이트 모드와 다크 모드에서의 로고 변형 + +라이트 모드와 다크 모드에서 다른 버전의 로고를 표시할 수 있습니다. + +1. `src/assets/`에 각 변형에 대한 이미지 파일을 추가합니다. + + + + - src/ + - assets/ + - **light-logo.svg** + - **dark-logo.svg** + - content/ + - astro.config.mjs + + + +2. `astro.config.mjs` 파일에서 `src` 대신 `light` 및 `dark` 옵션을 전달하여 로고 변형에 대한 경로를 추가하세요. + + ```js + starlight({ + title: '로고를 사용하는 문서', + logo: { + light: './src/assets/light-logo.svg', + dark: './src/assets/dark-logo.svg', + }, + }), + ``` + +## 페이지 레이아웃 + +기본적으로 Starlight 페이지는 전역 탐색 사이드바와 현재 페이지 제목의 목차가 있는 레이아웃을 사용합니다. + +페이지 frontmatter에 [`template: splash`](/ko/reference/frontmatter/#template)를 설정하여 사이드바 없이 더 넓은 페이지 레이아웃을 적용할 수 있습니다. 이는 특히 랜딩 페이지에 효과적이며 [이 사이트의 홈페이지](/ko)에서 실제로 작동하는 것을 확인할 수 있습니다. + +```md +--- +# src/content/docs/index.md + +title: 랜딩 페이지 +template: splash +--- +``` + +## 목차 + +Starlight는 독자가 원하는 제목으로 쉽게 이동할 수 있도록 각 페이지에 목차를 표시합니다. Starlight 통합을 통해 모든 페이지의 목차를 변경하거나 비활성화할 수 있습니다. 또한, frontmatter를 사용하여 각 페이지별로 목차를 변경할 수도 있습니다. + +기본적으로 `

` 및 `

` 제목이 목차에 포함됩니다. 모든 페이지의 목차를 변경하려면 [`tableOfContents`](/ko/reference/configuration/#tableofcontents) 의 `minHeadingLevel` 및 `maxHeadingLevel` 옵션을 사용하세요. 개별 페이지의 기본 목차를 변경하기 위해서는 [frontmatter에 `tableOfContents`](/ko/reference/frontmatter/#tableofcontents) 속성을 추가하세요. + + + + +```md +--- +# src/content/docs/example.md +title: 목차에 H2만 있는 페이지 +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 2 +--- +``` + + + + +```js +// astro.config.mjs + +defineConfig({ + integrations: [ + starlight({ + title: '', + tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 }, + }), + ], +}); +``` + + + + +`tableOfContents` 옵션의 값을 `false`로 설정하여 모든 페이지의 목차를 비활성화 할 수 있습니다. + + + + +```md +--- +# src/content/docs/example.md +title: 목차가 없는 페이지 +tableOfContents: false +--- +``` + + + + +```js +// astro.config.mjs + +defineConfig({ + integrations: [ + starlight({ + title: '모든 목차가 비활성화된 문서', + tableOfContents: false, + }), + ], +}); +``` + + + + +## 소셜 링크 + +Starlight에는 Starlight 통합의 [`social`](/ko/reference/configuration/#social) 옵션을 통해 사이트 헤더에 소셜 미디어 계정을 링크하는 기능이 내장되어 있습니다. + +현재 Bitbucket, Codeberg, CodePen, Discord, GitHub, GitLab, Gitter, Instagram, LinkedIn, Mastodon, Microsoft Teams, Threads, Twitch, Twitter 및 Youtube에 대한 링크가 지원됩니다. 다른 서비스에 대한 지원이 필요하면 GitHub나 Discord를 통해 알려주세요! + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: '소셜 링크를 사용하는 문서', + social: { + discord: 'https://astro.build/chat', + github: 'https://github.com/withastro/starlight', + }, + }), + ], +}); +``` + +## 링크 편집 + +Starlight는 각 페이지의 아래에 "페이지 편집" 링크를 표시할 수 있습니다. 이렇게 하면 독자가 문서 개선을 위해 편집할 파일을 쉽게 찾을 수 있습니다. 특히 오픈 소스 프로젝트의 경우 이는 커뮤니티의 기여를 장려하는 데 도움이 될 수 있습니다. + +편집 링크를 활성화하려면 [`editLink.baseUrl`](/ko/reference/configuration/#editlink)를 Starlight 통합 구성에서 저장소를 편집하는 데 사용되는 URL로 설정하세요. `editLink.baseUrl` 값은 전체 편집 링크를 형성하기 위해 현재 페이지의 경로 앞에 추가됩니다. + +일반적인 패턴은 다음과 같습니다. + +- GitHub: `https://github.com/USER_NAME/REPO_NAME/edit/BRANCH_NAME/` +- GitLab: `https://gitlab.com/USER_NAME/REPO_NAME/-/edit/BRANCH_NAME/` + +Starlight 프로젝트가 저장소의 루트에 없는 경우 기본 URL 끝에 프로젝트 경로를 포함합니다. + +이 예에서는 GitHub의 `withastro/starlight` 저장소의 `main` 브랜치에 있는 `docs/` 하위 디렉토리에 있는 Starlight 문서에 대해 구성된 편집 링크를 보여줍니다. + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: '편집 링크가 있는 문서', + editLink: { + baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/', + }, + }), + ], +}); +``` + +## 사용자 정의 404 페이지 + +Starlight 사이트는 기본적으로 간단한 404 페이지를 표시합니다. `src/content/docs/` 디렉토리에 `404.md`(또는 `404.mdx`) 파일을 추가하여 이를 변경할 수 있습니다: + + + +- src/ + - content/ + - docs/ + - **404.md** + - index.md +- astro.config.mjs + + + +404 페이지에서 Starlight의 모든 페이지 레이아웃과 사용자 정의 기술을 사용할 수 있습니다. 예를 들어 기본 404 페이지는 frontmatter에서 [`splash` 템플릿](#페이지-레이아웃)과 [`hero`](/ko/reference/frontmatter/#hero) 컴포넌트를 사용합니다. + +````md +```md +--- +title: '404' +template: splash +editUrl: false +hero: + title: '404' + tagline: 페이지를 찾을 수 없습니다. URL을 확인하거나 검색창을 사용해 보세요. +--- +``` +```` + +## 사용자 정의 글꼴 + +기본적으로 Starlight는 모든 텍스트에 대해 사용자의 로컬 장치에서 사용할 수 있는 sans-serif 글꼴을 사용합니다. 이를 통해 대용량 글꼴 파일을 다운로드하기 위한 추가 대역폭 없이 각 사용자에게 친숙한 글꼴로 문서를 빠르게 로드할 수 있습니다. + +Starlight 사이트에 사용자 정의 글꼴을 추가해야 하는 경우, 사용자 정의 CSS 파일이나 다른 [Astro 스타일링 기술](https://docs.astro.build/ko/guides/styling/)을 이용해 글꼴을 설정할 수 있습니다. + +### 글꼴 설정 + +이미 글꼴 파일이 있는 경우 [로컬 설정 가이드](#로컬-글꼴-파일-설정)를 따르세요. Google Fonts를 사용하려면 [Fontsource 설정 가이드](#fontsource-글꼴-설정)를 따르세요. + +#### 로컬 글꼴 파일 설정 + +1. `src/fonts/` 디렉토리에 글꼴 파일을 추가하고 빈 `font-face.css` 파일을 만드세요. + + + + - src/ + - content/ + - fonts/ + - **CustomFont.woff2** + - **font-face.css** + - astro.config.mjs + + + +2. `src/fonts/font-face.css`에 각 글꼴에 대한 [`@font-face` 선언](https://developer.mozilla.org/ko/docs/Web/CSS/@font-face)을 추가하세요. `url()` 함수에서 글꼴 파일의 상대 경로를 사용하세요. + + ```css + /* src/fonts/font-face.css */ + + @font-face { + font-family: 'Custom Font'; + /* `url()`에서 로컬 글꼴 파일의 상대 경로를 사용하세요. */ + src: url('./CustomFont.woff2') format('woff2'); + font-weight: normal; + font-style: normal; + font-display: swap; + } + ``` + +3. `astro.config.mjs`에 있는 Starlight의 `customCss` 배열에 `font-face.css` 파일의 경로를 추가하세요. + + ```js + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import starlight from '@astrojs/starlight'; + + export default defineConfig({ + integrations: [ + starlight({ + title: '사용자 정의 글꼴을 사용하는 문서', + customCss: [ + // @font-face CSS 파일의 상대 경로입니다. + './src/fonts/font-face.css', + ], + }), + ], + }); + ``` + +#### Fontsource 글꼴 설정 + +[Fontsource](https://fontsource.org/) 프로젝트는 Google Fonts 및 기타 오픈 소스 글꼴 사용을 단순화합니다. 사용하려는 글꼴을 설치할 수 있는 npm 모듈과 프로젝트에 추가할 CSS 파일을 제공합니다. + +1. [Fontsource 카탈로그](https://fontsource.org/)에서 사용하려는 글꼴을 찾으세요. 이 예에서는 [IBM Plex Serif](https://fontsource.org/fonts/ibm-plex-serif)를 사용합니다. + +2. 선택한 글꼴에 대한 패키지를 설치합니다. Fontsource 글꼴 페이지에서 “Install”을 클릭하면 패키지 이름을 찾을 수 있습니다. + + + + + + ```sh + npm install @fontsource/ibm-plex-serif + ``` + + + + + + ```sh + pnpm install @fontsource/ibm-plex-serif + ``` + + + + + + ```sh + yarn add @fontsource/ibm-plex-serif + ``` + + + + + +3. `astro.config.mjs`에 있는 Starlight의 `customCss` 배열에 Fontsource CSS 파일을 추가합니다. + + ```js + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import starlight from '@astrojs/starlight'; + + export default defineConfig({ + integrations: [ + starlight({ + title: '사용자 정의 글꼴을 사용하는 문서', + customCss: [ + // 보통 및 약간 굵은 글꼴 두께에 대한 Fontsource 파일입니다. + '@fontsource/ibm-plex-serif/400.css', + '@fontsource/ibm-plex-serif/600.css', + ], + }), + ], + }); + ``` + + Fontsource는 각 글꼴에 대해 여러 CSS 파일을 제공합니다. 다른 굵기 및 스타일을 포함하는 방법이 궁금하다면 [Fontsource 문서](https://fontsource.org/docs/getting-started/install#4-weights-and-styles)를 참조하세요. + +### 글꼴 사용 + +설정한 글꼴을 사이트에 적용하려면 [사용자 정의 CSS 파일](/ko/guides/css-and-tailwind/#custom-css-styles)에서 선택한 글꼴 이름을 사용하세요. 예를 들어 Starlight의 기본 글꼴을 변경하려면 사용자 정의 속성인 `--sl-font`를 설정하세요. + +```css +/* src/styles/custom.css */ + +:root { + --sl-font: 'IBM Plex Serif', serif; +} +``` + +글꼴을 더 선택적으로 적용하려면 더 많은 타겟 CSS를 작성할 수도 있습니다. +예를 들어 다음과 같은 방법으로 메인 콘텐츠에만 글꼴을 설정하고 사이드바에는 글꼴을 설정하지 않을 수 있습니다. + +```css +/* src/styles/custom.css */ + +main { + font-family: 'IBM Plex Serif', serif; +} +``` + +[사용자 정의 CSS 사용법](/ko/guides/css-and-tailwind/#사용자-정의-css-스타일)에 따라 사이트에 스타일을 추가하세요. diff --git a/docs/src/content/docs/ko/guides/i18n.mdx b/docs/src/content/docs/ko/guides/i18n.mdx new file mode 100644 index 00000000..4c7c4826 --- /dev/null +++ b/docs/src/content/docs/ko/guides/i18n.mdx @@ -0,0 +1,218 @@ +--- +title: 국제화 (i18n) +description: 여러 언어를 지원하도록 Starlight 사이트를 구성하는 방법을 알아보세요. +--- + +import FileTree from '../../../../components/file-tree.astro'; + +Starlight는 라우팅, 대체 콘텐츠 및 전체 RTL(오른쪽에서 왼쪽으로) 언어 지원을 포함하여 다국어 사이트에 대한 기본 지원을 제공합니다. + +## i18n 구성 + +1. Starlight 통합에 [`locales`](/ko/reference/configuration/#locales) 및 [`defaultLocale`](/ko/reference/configuration/#defaultlocale)을 전달하여 사이트가 지원해야 할 언어에 대해 알려주세요. + + ```js + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import starlight from '@astrojs/starlight'; + + export default defineConfig({ + integrations: [ + starlight({ + title: '나의 문서', + // 사이트의 기본 언어를 영어로 설정합니다. + defaultLocale: 'en', + locales: { + // 영어 문서는 `src/content/docs/en/`에 있습니다. + en: { + label: 'English', + }, + // 중국어 간체 문서는 `src/content/docs/zh/`에 있습니다. + zh: { + label: '简体中文', + lang: 'zh-CN', + }, + // 아랍어 문서는 `src/content/docs/ar/`에 있습니다. + ar: { + label: 'العربية', + dir: 'rtl', + }, + }, + }), + ], + }); + ``` + + `defaultLocale`은 대체 콘텐츠 및 UI 라벨에 사용되므로 콘텐츠 작성을 시작할 가능성이 가장 높거나 이미 콘텐츠가 있는 언어로 선택하세요. + +2. `src/content/docs/`에 각 언어에 대한 디렉토리를 만듭니다. 예를 들어 위에서 사용한 구성의 경우 다음과 같이 디렉토리를 생성할 수 있습니다. + + + + - src/ + - content/ + - docs/ + - ar/ + - en/ + - zh/ + + + +3. 이제 언어 디렉토리에 콘텐츠 파일을 추가할 수 있습니다. 여러 언어로 작성된 페이지를 연결하기 위해 같은 이름의 파일을 사용하면 Starlight의 모든 i18n 기능(대체 콘텐츠, 번역 알림 등)을 활용할 수 있습니다. + + 예를 들어, 아랍어와 영어 홈페이지를 각각 나타내려면 `ar/index.md` 및 `en/index.md`를 만듭니다. + +### 루트 로케일 사용 + +경로에 i18n 접두사가 없는 언어를 제공하려면 "루트" 로케일을 사용할 수 있습니다. 예를 들어 영어가 루트 로케일인 경우 영어 페이지 경로는 `/en/about` 대신 `/about`가 됩니다. + +루트 로케일을 설정하려면 `locales` 구성에서 `root` 키를 사용하세요. 루트 로케일이 콘텐츠의 기본 로케일이기도 한 경우 `defaultLocale`을 제거하거나 값을 `root`로 설정하세요. + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: '나의 문서', + defaultLocale: 'root', // 선택적 + locales: { + root: { + label: 'English', + lang: 'en', // 루트 로케일은 lang이 반드시 필요합니다. + }, + zh: { + label: '简体中文', + lang: 'zh-CN', + }, + }, + }), + ], +}); +``` + +루트 로케일을 사용하는 경우 해당 언어로 작성된 페이지를 전용 언어 폴더 대신 `src/content/docs/`에 직접 보관하세요. 예를 들어 위 구성을 사용할 때 영어와 중국어에 대한 홈 페이지 파일은 다음과 같습니다. + + + +- src/ + - content/ + - docs/ + - **index.md** + - zh/ + - **index.md** + + + +#### 단일 언어를 사용하는 사이트 + +기본적으로 Starlight는 단일 언어(영어) 사이트입니다. +다른 언어로 단일 언어 사이트를 만들려면 `locales` 구성에서 `root`를 해당 언어로 설정하세요. + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: '나의 문서', + locales: { + root: { + label: '한국어', + lang: 'ko', + }, + }, + }), + ], +}); +``` + +이를 통해 언어 선택기와 같은 다국어 사이트에 대한 다른 국제화 기능을 활성화하지 않고도 Starlight의 기본 언어를 변경할 수 있습니다. + +## 대체 콘텐츠 + +Starlight는 귀하가 모든 언어로 같은 페이지를 생성할 것을 기대합니다. 예를 들어 `en/about.md` 파일이 있는 경우 지원하는 각 언어에 대해 `about.md`를 만듭니다. 이를 통해 Starlight는 아직 번역되지 않은 페이지에 자동 대체 콘텐츠를 제공합니다. + +특정 언어에 대한 번역이 아직 제공되지 않는 경우 Starlight는 독자에게 해당 페이지의 콘텐츠를 기본 언어(`defaultLocale`을 통해 설정된 언어)로 표시합니다. 예를 들어, About 페이지의 프랑스어 버전을 아직 만들지 않았고 기본 언어가 영어인 경우 `/fr/about`에 방문한 독자는 이 페이지가 아직 번역되지 않았다는 알림과 함께 `/en/about`에 있는 영어 콘텐츠를 보게 됩니다. 이를 통해 기본 언어로 콘텐츠를 추가한 다음 점진적으로 번역할 수 있습니다. + +## Starlight UI 번역 + +번역된 콘텐츠 파일을 호스팅하는 것 외에도 Starlight를 사용하면 독자가 선택한 언어로 사이트 전체를 경험할 수 있도록 기본 UI 문자열(예를 들어, 오른쪽 목차의 제목인 "목차")를 번역할 수 있습니다. + +영어, 체코어, 프랑스어, 독일어, 이탈리아어, 일본어, 포르투갈어, 네덜란드어, 덴마크어, 스페인어, 터키어, 아랍어, 노르웨이어, 페르시아어, 중국어 간체, 한국어 및 스웨덴어로 번역된 UI 문자열이 기본적으로 제공됩니다. 그리고 우리는 [더 많은 기본 언어를 추가하는 데 기여](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md)하는걸 환영합니다. + +`i18n` 데이터 컬렉션을 통해 지원하는 추가 언어에 대한 번역을 제공하거나 기본 라벨을 변경할 수 있습니다. + +1. 아직 구성되지 않은 경우 `src/content/config.ts`에서 `i18n` 데이터 컬렉션을 구성합니다. + + ```js + // src/content/config.ts + import { defineCollection } from 'astro:content'; + import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; + + export const collections = { + docs: defineCollection({ schema: docsSchema() }), + i18n: defineCollection({ type: 'data', schema: i18nSchema() }), + }; + ``` + +2. `src/content/i18n/`에 UI 번역 문자열을 제공하려는 각 추가 언어에 대한 JSON 파일을 만듭니다. 예를 들어 다음은 아랍어 및 중국어 간체에 대한 번역 파일을 추가합니다. + + + + - src/ + - content/ + - i18n/ + - ar.json + - zh-CN.json + + + +3. JSON 파일에서 번역할 키에 대한 번역을 추가합니다. 키는 영어로 남겨두고 값을 번역해야합니다. (예: `"search.label": "Buscar"`) + + Starlight와 함께 제공되는 기존 문자열의 영어 기본값은 다음과 같습니다. + + ```json + { + "skipLink.label": "Skip to content", + "search.label": "Search", + "search.shortcutLabel": "(Press / to Search)", + "search.cancelLabel": "Cancel", + "search.devWarning": "Search is only available in production builds. \nTry building and previewing the site to test it out locally.", + "themeSelect.accessibleLabel": "Select theme", + "themeSelect.dark": "Dark", + "themeSelect.light": "Light", + "themeSelect.auto": "Auto", + "languageSelect.accessibleLabel": "Select language", + "menuButton.accessibleLabel": "Menu", + "sidebarNav.accessibleLabel": "Main", + "tableOfContents.onThisPage": "On this page", + "tableOfContents.overview": "Overview", + "i18n.untranslatedContent": "This content is not available in your language yet.", + "page.editLink": "Edit page", + "page.lastUpdated": "Last updated:", + "page.previousLink": "Next", + "page.nextLink": "Previous" + } + ``` + + Starlight의 검색 모달은 [Pagefind](https://pagefind.app/) 라이브러리에 의해 구동됩니다. 동일한 JSON 파일에서 `pagefind` 키를 사용하여 Pagefind의 UI에 대한 번역을 설정할 수 있습니다. + + ```json + { + "pagefind.clear_search": "Clear", + "pagefind.load_more": "Load more results", + "pagefind.search_label": "Search this site", + "pagefind.filters_label": "Filters", + "pagefind.zero_results": "No results for [SEARCH_TERM]", + "pagefind.many_results": "[COUNT] results for [SEARCH_TERM]", + "pagefind.one_result": "[COUNT] result for [SEARCH_TERM]", + "pagefind.alt_search": "No results for [SEARCH_TERM]. Showing results for [DIFFERENT_TERM] instead", + "pagefind.search_suggestion": "No results for [SEARCH_TERM]. Try one of the following searches:", + "pagefind.searching": "Searching for [SEARCH_TERM]..." + } + ``` -- cgit