i18n(ko-KR): create guides/route-data.mdx and `reference/route-data…

….mdx` (#2896) Co-authored-by: trueberryless <[email protected]>
withastro · Feb 16, 2025 · 239d937 · 239d937
1 parent bb935c3
commit 239d937
Show file tree

Hide file tree

Showing 2 changed files with 333 additions and 0 deletions.
diff --git a/docs/src/content/docs/ko/guides/route-data.mdx b/docs/src/content/docs/ko/guides/route-data.mdx
@@ -0,0 +1,137 @@
+---
+title: 경로 데이터
+description: Starlight의 페이지 데이터 모델이 페이지를 렌더링하는 데 어떻게 사용되는지, 그리고 이를 어떻게 사용자 정의할 수 있는지 알아보세요.
+---
+
+import { Steps } from '@astrojs/starlight/components';
+
+Starlight가 문서에서 페이지를 렌더링할 때, 먼저 해당 페이지의 내용을 나타내는 경로 데이터 객체를 생성합니다.
+이 가이드에서는 경로 데이터가 어떻게 생성되는지, 어떻게 사용하는지, 그리고 Starlight의 기본 동작을 수정하기 위해 어떻게 사용자 정의할 수 있는지 설명합니다.
+
+사용 가능한 속성의 전체 목록은 ["경로 데이터 참조"](/ko/reference/route-data/)를 확인하세요.
+
+## 경로 데이터란 무엇인가요?
+
+Starlight 경로 데이터는 단일 페이지를 렌더링하는 데 필요한 모든 정보를 담고 있는 객체입니다.
+여기에는 현재 페이지에 대한 정보뿐만 아니라 Starlight 구성에서 생성된 데이터도 포함됩니다.
+
+## 경로 데이터 사용하기
+
+Starlight의 모든 컴포넌트는 경로 데이터를 사용하여 각 페이지에 무엇을 렌더링할지 결정합니다. 예를 들어, [`siteTitle`](/ko/reference/route-data/#sitetitle) 문자열은 사이트 제목을 표시하는 데 사용되고, [`sidebar`](/ko/reference/route-data/#sidebar) 배열은 전역 사이드바 탐색을 렌더링하는 데 사용됩니다.
+
+Astro 컴포넌트에서 `Astro.locals.starlightRoute` 전역 변수를 통해 이 데이터에 접근할 수 있습니다.
+
+```astro title="example.astro" {2}
+---
+const { siteTitle } = Astro.locals.starlightRoute;
+---
+
+<p>The title of this site is “{siteTitle}”</p>
+```
+
+예를 들어, [컴포넌트 재정의](/ko/guides/overriding-components/)를 구축하여 표시되는 내용을 사용자 정의할 때 유용할 수 있습니다.
+
+## 경로 데이터 사용자 정의
+
+Starlight의 경로 데이터는 별도의 구성 없이 바로 작동합니다.
+하지만 고급 사용 사례의 경우, 일부 또는 모든 페이지에 대한 경로 데이터를 사용자 정의하여 사이트 표시 방식을 변경할 수 있습니다.
+
+이는 [컴포넌트 재정의](/ko/guides/overriding-components/)와 유사한 개념이지만, Starlight가 데이터를 렌더링하는 방식을 수정하는 대신 Starlight가 렌더링하는 데이터를 수정합니다.
+
+### 경로 데이터 사용자 정의가 필요한 경우
+
+경로 데이터 사용자 정의는 Starlight가 데이터를 처리하는 방식을 기존 구성 옵션으로는 불가능한 방식으로 수정하고 싶을 때 유용할 수 있습니다.
+
+예를 들어, 특정 페이지의 사이드바 항목을 필터링하거나 제목을 사용자 정의할 수 있습니다. 이와 같은 변경 사항은 Starlight의 기본 컴포넌트를 수정할 필요 없이 해당 컴포넌트에 전달되는 데이터만 수정하면 됩니다.
+
+### 경로 데이터를 사용자 정의하는 방법
+
+"미들웨어"의 특수한 형태를 사용하여 경로 데이터를 사용자 정의할 수 있습니다.
+이는 Starlight가 페이지를 렌더링할 때마다 호출되는 함수로, 경로 데이터 객체의 값을 수정할 수 있습니다.
+
+<Steps>
+
+1. Starlight의 `defineRouteMiddleware()` 유틸리티를 사용하여 `onRequest` 함수를 내보내는 새 파일을 만듭니다.
+
+   ```ts
+   // src/routeData.ts
+   import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+
+   export const onRequest = defineRouteMiddleware(() => {});
+   ```
+
+2. `astro.config.mjs`에서 경로 데이터 미들웨어 파일의 위치를 Starlight에 알려줍니다.
+
+   ```js ins={9}
+   // astro.config.mjs
+   import { defineConfig } from 'astro/config';
+   import starlight from '@astrojs/starlight';
+
+   export default defineConfig({
+   	integrations: [
+   		starlight({
+   			title: '나의 즐거운 문서 사이트',
+   			routeMiddleware: './src/routeData.ts',
+   		}),
+   	],
+   });
+   ```
+
+3. `onRequest` 함수를 업데이트하여 경로 데이터를 수정합니다.
+
+   미들웨어가 받는 첫 번째 인자는 [Astro의 `context` 객체](https://docs.astro.build/ko/reference/api-reference/)입니다.
+   여기에는 현재 URL과 `locals`를 포함하여 현재 페이지 렌더링에 대한 모든 정보가 포함되어 있습니다.
+
+   이 예제에서는 모든 페이지 제목의 끝에 느낌표를 추가하여 문서를 더욱 흥미롭게 만들 것입니다.
+
+   ```ts
+   // src/routeData.ts
+   import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+
+   export const onRequest = defineRouteMiddleware((context) => {
+     // 이 페이지의 콘텐츠 컬렉션 항목을 가져옵니다.
+   	const { entry } = context.locals.starlightRoute;
+     // 제목에 느낌표를 추가하여 업데이트합니다.
+   	entry.data.title = entry.data.title + '!';
+   });
+   ```
+
+</Steps>
+
+#### 여러 경로 미들웨어
+
+Starlight는 여러 개의 미들웨어 제공도 지원합니다.
+둘 이상의 미들웨어 핸들러를 추가하려면 `routeMiddleware`를 경로 배열로 설정하세요.
+
+```js {9}
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+	integrations: [
+		starlight({
+			title: '여러 미들웨어가 있는 내 사이트',
+			routeMiddleware: ['./src/middleware-one.ts', './src/middleware-two.ts'],
+		}),
+	],
+});
+```
+
+#### 추가된 경로 미들웨어 대기
+
+코드 실행 전에 스택에 추가된 미들웨어가 실행될 때까지 기다리려면 미들웨어 함수에 두 번째 인자로 전달되는 `next()` 콜백을 await할 수 있습니다.
+예를 들어, 변경하기 전에 플러그인의 미들웨어가 실행될 때까지 기다리는 데 유용할 수 있습니다.
+
+```ts "next" "await next();"
+// src/routeData.ts
+import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+
+export const onRequest = defineRouteMiddleware(async (context, next) => {
+	// 추가된 미들웨어가 실행될 때까지 기다립니다.
+	await next();
+	// 경로 데이터를 수정합니다.
+	const { entry } = context.locals.starlightRoute;
+	entry.data.title = entry.data.title + '!';
+});
+```
diff --git a/docs/src/content/docs/ko/reference/route-data.mdx b/docs/src/content/docs/ko/reference/route-data.mdx
@@ -0,0 +1,196 @@
+---
+title: 경로 데이터 참조
+description: Starlight의 경로 데이터 객체에 대한 전체 참조 문서입니다.
+---
+
+Starlight의 경로 데이터 객체는 현재 페이지에 대한 정보를 담고 있습니다.
+Starlight의 데이터 모델 작동 방식에 대한 자세한 내용은 ["경로 데이터" 가이드](/ko/guides/route-data/)에서 확인하세요.
+
+Astro 컴포넌트에서는 `Astro.locals.starlightRoute`를 통해 경로 데이터에 접근할 수 있습니다.
+
+```astro {4}
+---
+// src/components/Custom.astro
+
+const { hasSidebar } = Astro.locals.starlightRoute;
+---
+```
+
+[경로 미들웨어](/ko/guides/route-data/#경로-데이터-사용자-정의)에서는 미들웨어 함수에 전달된 컨텍스트 객체에서 경로 데이터에 접근합니다.
+
+```ts {5}
+// src/routeData.ts
+import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+
+export const onRequest = defineRouteMiddleware((context) => {
+	const { hasSidebar } = context.locals.starlightRoute;
+});
+```
+
+## `starlightRoute`
+
+`starlightRoute` 객체는 다음 속성을 가집니다.
+
+### `dir`
+
+**타입:** `'ltr' | 'rtl'`
+
+페이지 작성 방향입니다.
+
+### `lang`
+
+**타입:** `string`
+
+이 페이지의 로케일에 대한 BCP-47 언어 태그입니다. 예: `en`, `zh-CN` 또는 `pt-BR`
+
+### `locale`
+
+**타입:** `string | undefined`
+
+언어가 제공되는 기본 경로입니다. 루트 로케일 슬러그의 경우 `undefined`입니다.
+
+### `siteTitle`
+
+**타입:** `string`
+
+이 페이지의 로케일에 대한 사이트 제목입니다.
+
+### `siteTitleHref`
+
+**타입:** `string`
+
+`/`처럼 홈페이지와 연결되는 사이트 제목 `href` 속성의 값입니다.
+다국어 사이트의 경우 `/en/` 또는 `/zh-cn/`과 같은 현재 로케일이 포함됩니다.
+
+### `slug`
+
+**타입:** `string`
+
+콘텐츠 파일 이름에서 생성된 이 페이지의 슬러그입니다.
+
+이 속성은 더 이상 사용되지 않으며 향후 버전의 Starlight에서 제거될 예정입니다.
+[Starlight의 `docsLoader`](/ko/manual-setup/#콘텐츠-컬렉션-구성)를 사용하여 새 콘텐츠 레이어 API로 마이그레이션하고 대신 [`id`](#id) 속성을 사용하세요.
+
+### `id`
+
+**타입:** `string`
+
+이 페이지의 슬러그 또는 [`legacy.collections`](https://docs.astro.build/ko/reference/legacy-flags/#collections) 플래그를 사용하는 경우 콘텐츠 파일명을 기준으로 한 이 페이지의 고유 ID입니다.
+
+### `isFallback`
+
+**타입:** `true | undefined`
+
+이 페이지가 현재 언어로 번역되지 않고 기본 로케일의 대체 콘텐츠를 사용하는 경우 `true`입니다.
+다국어 사이트에서만 사용됩니다.
+
+### `entryMeta`
+
+**타입:** `{ dir: 'ltr' | 'rtl'; lang: string }`
+
+페이지 콘텐츠의 로케일 메타데이터입니다. 페이지가 대체 콘텐츠를 사용하는 경우 최상위 로케일 값과 다를 수 있습니다.
+
+### `entry`
+
+현재 페이지에 대한 Astro 콘텐츠 컬렉션 항목입니다.
+`entry.data`는 현재 페이지에 대한 프론트매터 값을 포함합니다.
+
+```ts
+entry: {
+	data: {
+		title: string;
+		description: string | undefined;
+		// 기타
+	}
+}
+```
+
+[Astro 컬렉션 엔트리 타입](https://docs.astro.build/ko/reference/modules/astro-content/#collectionentry) 참조에서 이 객체의 형태에 대해 자세히 알아보세요.
+
+### `sidebar`
+
+**타입:** `SidebarEntry[]`
+
+페이지에 대한 사이트 탐색 사이드바 엔트리입니다.
+
+### `hasSidebar`
+
+**타입:** `boolean`
+
+이 페이지에 사이드바를 표시할지 여부입니다.
+
+### `pagination`
+
+**타입:** `{ prev?: Link; next?: Link }`
+
+활성화된 경우 사이드바의 이전 및 다음 페이지로 이동하는 링크를 표시합니다.
+
+### `toc`
+
+**타입:** `{ minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined`
+
+활성화된 경우 이 페이지의 목차를 표시합니다.
+
+### `headings`
+
+**타입:** `{ depth: number; slug: string; text: string }[]`
+
+현재 페이지에서 추출된 모든 Markdown 제목의 배열입니다.
+Starlight의 구성 옵션을 준수하는 콘텐츠 목차 컴포넌트를 생성하기 위해서는 [`toc`](#toc)를 사용하세요.
+
+### `lastUpdated`
+
+**타입:** `Date | undefined`
+
+활성화된 경우 이 페이지가 마지막으로 업데이트된 날짜를 나타내기 위해 JavaScript `Date`객체가 사용됩니다.
+
+### `editUrl`
+
+**타입:** `URL | undefined`
+
+활성화된 경우 이 페이지를 편집할 수 있는 주소를 나타내기 위해 `URL` 객체가 사용됩니다.
+
+## 유틸리티
+
+### `defineRouteMiddleware()`
+
+`defineRouteMiddleware()` 유틸리티를 사용하여 경로 미들웨어 모듈의 타입을 지정하세요:
+
+```ts "defineRouteMiddleware"
+// src/routeData.ts
+import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+
+export const onRequest = defineRouteMiddleware((context) => {
+	// ...
+});
+```
+
+### `StarlightRouteData` 타입
+
+Starlight의 경로 데이터를 사용해야 하는 코드를 작성하는 경우, `StarlightRouteData` 타입을 가져와 `Astro.locals.starlightRoute`의 형태와 일치시킬 수 있습니다.
+
+다음 예제에서 `usePageTitleInTOC()` 함수는 경로 데이터를 업데이트하여 현재 페이지의 제목을 목차의 첫 번째 항목 레이블로 사용하고 기본 "개요" 레이블을 대체합니다. `StarlightRouteData` 타입을 사용하면 경로 데이터 변경 사항이 유효한지 확인할 수 있습니다.
+
+```ts "StarlightRouteData"
+// src/route-utils.ts
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+
+export function usePageTitleInTOC(starlightRoute: StarlightRouteData) {
+	const overviewLink = starlightRoute.toc?.items[0];
+	if (overviewLink) {
+		overviewLink.text = starlightRoute.entry.data.title;
+	}
+}
+```
+
+이 함수는 경로 미들웨어에서 호출할 수 있습니다.
+
+```ts {3,6}
+// src/route-middleware.ts
+import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+import { usePageTitleInTOC } from './route-utils';
+
+export const onRequest = defineRouteMiddleware((context) => {
+	usePageTitleInTOC(context.locals.starlightRoute);
+});
+```