From 550e5849051ab23e8421565a22f0ad96f2d53864 Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 20:15:53 +0900 Subject: [PATCH 01/21] fix: remove unused link in `astro-actions.mdx` (#9819) --- src/content/docs/en/reference/modules/astro-actions.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-actions.mdx b/src/content/docs/en/reference/modules/astro-actions.mdx index bc08271b638a0..9f03148fbd2d6 100644 --- a/src/content/docs/en/reference/modules/astro-actions.mdx +++ b/src/content/docs/en/reference/modules/astro-actions.mdx @@ -173,6 +173,4 @@ The `code` property accepts human-readable versions of all HTTP status codes. Th

-The `message` property accepts a string. (e.g. "User must be logged in.") - -[canonical]: https://en.wikipedia.org/wiki/Canonical_link_element +The `message` property accepts a string. (e.g. "User must be logged in.") \ No newline at end of file From d8e2b79ae0526384387ce5d75ef531abc620eb73 Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 20:16:37 +0900 Subject: [PATCH 02/21] fix: update wrong link in `astro-assets.mdx` (#9820) --- src/content/docs/en/reference/modules/astro-assets.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/modules/astro-assets.mdx b/src/content/docs/en/reference/modules/astro-assets.mdx index 4eddc770f34ad..c041914953b16 100644 --- a/src/content/docs/en/reference/modules/astro-assets.mdx +++ b/src/content/docs/en/reference/modules/astro-assets.mdx @@ -10,7 +10,7 @@ import ReadMore from '~/components/ReadMore.astro';

- Astro provides built-in components and helper functions for optimizing and displaying your images. For features and usage examples, [see our image guide](/en/guides/content-collections/). + Astro provides built-in components and helper functions for optimizing and displaying your images. For features and usage examples, [see our image guide](/en/guides/images/). ## Imports from `astro:assets` From 65149e25510a1153c242856910f8f859d98aec15 Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 20:17:27 +0900 Subject: [PATCH 03/21] fix: wrong codeblock in `astro-content.mdx` (#9821) --- src/content/docs/en/reference/modules/astro-content.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/modules/astro-content.mdx b/src/content/docs/en/reference/modules/astro-content.mdx index b391ae48835d2..c101a1c158ffd 100644 --- a/src/content/docs/en/reference/modules/astro-content.mdx +++ b/src/content/docs/en/reference/modules/astro-content.mdx @@ -329,7 +329,7 @@ const { Content, headings, remarkPluginFrontmatter } = await entry.render(); A string union of all collection names defined in your `src/content/config.*` file. This type can be useful when defining a generic function that accepts any collection name. ```ts -import type { CollectionKey, getCollection } from 'astro:content'; +import { type CollectionKey, getCollection } from 'astro:content'; async function getCollection(collection: CollectionKey) { return getCollection(collection); From eeeea944c47e39b36dca9205c69b1f1e3422dee6 Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 20:36:44 +0900 Subject: [PATCH 04/21] i18n(ko-KR): update `nav.ts` (#9802) Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- src/i18n/ko/nav.ts | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/src/i18n/ko/nav.ts b/src/i18n/ko/nav.ts index 4780fdf6d1dc3..38f8bdaf40090 100644 --- a/src/i18n/ko/nav.ts +++ b/src/i18n/ko/nav.ts @@ -61,23 +61,31 @@ export default NavDictionary({ 'guides/testing': '테스팅', 'guides/troubleshooting': '문제 해결', + communityResources: '커뮤니티 리소스', + 'community-resources/content': '강의, 가이드, 레시피', + 'community-resources/talks': '강연, 인터뷰, 스트림', + reference: '참조', 'reference/configuration-reference': '구성', - 'reference/api-reference': 'Astro 런타임 API', 'reference/cli-reference': 'Astro CLI', 'reference/directives-reference': '지시어 참조', 'reference/components-reference': '기본 제공 컴포넌트', 'guides/typescript': 'TypeScript 참조', 'reference/error-reference': '오류 참조', + 'api-reference': 'Astro API 참조', + 'reference/api-reference': 'Astro 런타임 API', + 'reference/modules/astro-actions': 'astro:actions', + 'reference/modules/astro-assets': 'astro:assets', + 'reference/modules/astro-content': 'astro:content', + 'reference/modules/astro-i18n': 'astro:i18n', + 'reference/modules/astro-middleware': 'astro:middleware', + 'reference/modules/astro-transitions': 'astro:transitions', + dev: '기타 개발 API', 'reference/integrations-reference': '통합 API', 'reference/adapter-reference': '어댑터 API', 'reference/image-service-reference': '이미지 서비스 API', 'reference/dev-toolbar-app-reference': '개발 툴바 앱 API', 'reference/container-reference': '컨테이너 API (실험적 기능)', - - communityResources: '커뮤니티 리소스', - 'community-resources/content': '강의, 가이드, 레시피', - 'community-resources/talks': '강연, 인터뷰, 스트림', }); From 5e6f5c30f0d88f7a4b45b352ca0bc8036f3d9646 Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 20:43:51 +0900 Subject: [PATCH 05/21] i18n(ko-KR): update `imports.mdx` (#9806) Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- src/content/docs/ko/guides/imports.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ko/guides/imports.mdx b/src/content/docs/ko/guides/imports.mdx index f4a431a1d36d4..16f57164461ad 100644 --- a/src/content/docs/ko/guides/imports.mdx +++ b/src/content/docs/ko/guides/imports.mdx @@ -249,7 +249,7 @@ glob 패턴은 특수 와일드카드 문자를 지원하는 파일 경로입니 #### `Astro.glob()` vs `getCollection()` -[콘텐츠 컬렉션](/ko/guides/content-collections/)은 `Astro.glob()` 대신 여러 파일을 가져오기 위한 [`getCollection()` API](/ko/reference/api-reference/#getcollection)를 제공합니다. 콘텐츠 파일 (예: Markdown, MDX, Markdoc)이 `src/content/` 디렉터리의 컬렉션에 있는 경우 `getCollection()`을 사용하여 [컬렉션을 쿼리](/ko/guides/content-collections/#컬렉션-쿼리)하고 콘텐츠 항목을 반환합니다. +[콘텐츠 컬렉션](/ko/guides/content-collections/)은 `Astro.glob()` 대신 여러 파일을 가져오기 위한 [`getCollection()` API](/ko/reference/modules/astro-content/#getcollection)를 제공합니다. 콘텐츠 파일 (예: Markdown, MDX, Markdoc)이 `src/content/` 디렉터리의 컬렉션에 있는 경우 `getCollection()`을 사용하여 [컬렉션을 쿼리](/ko/guides/content-collections/#컬렉션-쿼리)하고 콘텐츠 항목을 반환합니다. ## WASM From 2836aa8438c8edd0285e11f28c738780eb8bbe32 Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 20:49:48 +0900 Subject: [PATCH 06/21] i18n(ko-KR): update `fleek.mdx` (#9805) Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- src/content/docs/ko/guides/deploy/fleek.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ko/guides/deploy/fleek.mdx b/src/content/docs/ko/guides/deploy/fleek.mdx index 8543c8c169416..f8b629208cd57 100644 --- a/src/content/docs/ko/guides/deploy/fleek.mdx +++ b/src/content/docs/ko/guides/deploy/fleek.mdx @@ -75,4 +75,4 @@ Astro 프로젝트는 정적 사이트로 Fleek에 배포할 수 있습니다. ## 자세히 알아보기 [Fleek UI로 사이트 배포](https://fleek.xyz/docs/platform/deployments/) -[Fleek CLI로 사이트 배포](https://fleek.xyz/docs/cli/sites/) +[Fleek CLI로 사이트 배포](https://fleek.xyz/docs/cli/hosting/) From 0e6c1f7a31b3a2a77c5c7d35025580b38d71d3de Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 20:56:07 +0900 Subject: [PATCH 07/21] i18n(ko-KR): update `markdown-content.mdx` (#9808) Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- src/content/docs/ko/guides/markdown-content.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ko/guides/markdown-content.mdx b/src/content/docs/ko/guides/markdown-content.mdx index d12b7298ab24d..7b270cf0abed3 100644 --- a/src/content/docs/ko/guides/markdown-content.mdx +++ b/src/content/docs/ko/guides/markdown-content.mdx @@ -61,7 +61,7 @@ const posts = Object.values(await import.meta.glob('../posts/*.md', { eager: tru 도우미 함수를 통해 컬렉션에서 데이터를 가져올 때 Markdown의 frontmatter 속성은 `data` 객체 (예: `post.data.title`)에서 사용할 수 있습니다. 또한 `body`에는 컴파일되지 않은 원시 본문 콘텐츠가 문자열로 포함됩니다. -[CollectionEntry 타입](/ko/reference/api-reference/#컬렉션-항목-타입)에 대해 알아보세요. +[CollectionEntry 타입](/ko/reference/modules/astro-content/#collectionentry)에 대해 알아보세요. #### Markdown 가져오기 From 838aafabacf034b83e118ed1af9bc9110e5dcf4f Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 21:02:43 +0900 Subject: [PATCH 08/21] i18n(ko-KR): update `add-content-collections.mdx` (#9811) Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- src/content/docs/ko/tutorials/add-content-collections.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ko/tutorials/add-content-collections.mdx b/src/content/docs/ko/tutorials/add-content-collections.mdx index 53f0c4ee3fec8..b362e4cc29bae 100644 --- a/src/content/docs/ko/tutorials/add-content-collections.mdx +++ b/src/content/docs/ko/tutorials/add-content-collections.mdx @@ -250,7 +250,7 @@ import { Steps } from '@astrojs/starlight/components'; -11. 튜토리얼의 블로그 페이지(`src/pages/blog.astro/`)처럼, 블로그 게시물 목록이 있는 곳이라면 어디서든 `Astro.glob()`을 [`getCollection()`](/ko/reference/api-reference/#getcollection)로 대체하여 Markdown 파일에서 콘텐츠 및 메타데이터를 가져올 수 있습니다. +11. 튜토리얼의 블로그 페이지(`src/pages/blog.astro/`)처럼, 블로그 게시물 목록이 있는 곳이라면 어디서든 `Astro.glob()`을 [`getCollection()`](/ko/reference/modules/astro-content/#getcollection)로 대체하여 Markdown 파일에서 콘텐츠 및 메타데이터를 가져올 수 있습니다. ```astro title="src/pages/blog.astro" "post.data" "getCollection(\"posts\")" "/posts/${post.slug}/" del={7} ins={2,8} --- From ba16973d93f0e8ede24379a599507a9ba77dbbd2 Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 21:09:04 +0900 Subject: [PATCH 09/21] i18n(ko-KR): update `internationalization.mdx` (#9807) Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../docs/ko/guides/internationalization.mdx | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/src/content/docs/ko/guides/internationalization.mdx b/src/content/docs/ko/guides/internationalization.mdx index 086d187ef70dc..c9d6c461e5f87 100644 --- a/src/content/docs/ko/guides/internationalization.mdx +++ b/src/content/docs/ko/guides/internationalization.mdx @@ -58,7 +58,7 @@ export default defineConfig({ ### 링크 생성 -i18n 라우팅이 구성되면 이제 [`astro:i18n` 모듈](/ko/reference/api-reference/#국제화-astroi18n)에서 사용할 수 있는 [`getRelativeLocaleUrl()`](/ko/reference/api-reference/#getrelativelocaleurl)과 같은 도우미 함수를 사용하여 사이트 내 페이지에 대한 링크를 계산할 수 있습니다. 생성된 링크는 항상 정확하고 현지화된 경로를 제공하며 사이트에서 URL을 올바르게 사용하거나 확인하는 데 도움이 될 수 있습니다. +i18n 라우팅이 구성되면 이제 [`astro:i18n` 모듈](/ko/reference/modules/astro-i18n/)에서 사용할 수 있는 [`getRelativeLocaleUrl()`](/ko/reference/modules/astro-i18n/#getrelativelocaleurl)과 같은 도우미 함수를 사용하여 사이트 내 페이지에 대한 링크를 계산할 수 있습니다. 생성된 링크는 항상 정확하고 현지화된 경로를 제공하며 사이트에서 URL을 올바르게 사용하거나 확인하는 데 도움이 될 수 있습니다. 링크를 수동으로 작성할 수도 있습니다. @@ -70,8 +70,8 @@ const aboutURL = getRelativeLocaleUrl("es", "about"); --- ¡Vamos! Blog -Acerca -``` +Acerca +``` ## `routing` @@ -91,7 +91,7 @@ i18n 라우팅을 구성하면 이 파일 구조 (및 생성된 해당 URL 경 또한 이 설정은 파일 구조와 URL 구조가 모든 언어에 대해 일치해야 하므로 기본 언어에 대한 페이지 파일이 존재해야 하는 위치 (예: `src/pages/about/` 또는 `src/pages/en/about`)를 결정합니다. -- `"prefixDefaultLocale: false"` (기본값): 기본 언어로 된 URL에는 `/[locale]/` 접두사가 **없습니다**. 다른 모든 로케일에는 적용됩니다. +- `"prefixDefaultLocale: false"` (기본값): 기본 언어로 된 URL에는 `/[locale]/` 접두사가 **없습니다**. 다른 모든 로케일에는 적용됩니다. - `"prefixDefaultLocale: true"`: 기본 언어를 포함한 모든 URL에는 `/[locale]/` 접두사가 붙습니다. @@ -125,8 +125,8 @@ export default defineConfig({ - index.astro -- `src/pages/about.astro`는 `example.com/about/` 경로를 생성합니다. -- `src/pages/fr/about.astro`는 `example.com/fr/about/` 경로를 생성합니다. +- `src/pages/about.astro`는 `example.com/about/` 경로를 생성합니다. +- `src/pages/fr/about.astro`는 `example.com/fr/about/` 경로를 생성합니다. #### `prefixDefaultLocale: true` @@ -193,7 +193,7 @@ export default defineConfig({ }) ``` -Astro는 미들웨어를 위한 도우미 함수를 제공하므로 기본 라우팅, 예외, 대체 동작, 오류 캐치 등을 제어할 수 있습니다: [`redirectToDefaultLocale()`](/ko/reference/api-reference/#redirecttodefaultlocale), [`notFound ()`](/ko/reference/api-reference/#notfound) 및 [`redirectToFallback()`](/ko/reference/api-reference/#redirecttofallback): +Astro는 미들웨어를 위한 도우미 함수를 제공하므로 기본 라우팅, 예외, 대체 동작, 오류 캐치 등을 제어할 수 있습니다: [`redirectToDefaultLocale()`](/ko/reference/modules/astro-i18n/#redirecttodefaultlocale), [`notFound ()`](/ko/reference/modules/astro-i18n/#notfound) 및 [`redirectToFallback()`](/ko/reference/modules/astro-i18n/#redirecttofallback): ```js title="src/middleware.js" import { defineMiddleware } from "astro:middleware"; @@ -211,7 +211,7 @@ export const onRequest = defineMiddleware(async (ctx, next) => { [`middleware`](#미들웨어-함수) 함수는 Astro의 i18n 미들웨어를 수동으로 생성합니다. 이를 통해 Astro의 i18n 라우팅을 완전히 교체하는 대신 확장할 수 있습니다. -순서를 결정하기 위해 [`sequence`](/ko/reference/api-reference/#sequence) 유틸리티를 사용하여 자체 미들웨어와 함께 [라우팅 옵션](#routing)과 함께 `middleware`를 실행할 수 있습니다. +순서를 결정하기 위해 [`sequence`](/ko/reference/modules/astro-middleware/#sequence) 유틸리티를 사용하여 자체 미들웨어와 함께 [라우팅 옵션](#routing)과 함께 `middleware`를 실행할 수 있습니다. ```js title="src/middleware.js" import {defineMiddleware, sequence} from "astro:middleware"; @@ -283,7 +283,7 @@ export default defineConfig({ 위 URL은 `getAbsoluteLocaleUrl()` 및 `getAbsoluteLocaleUrlList()` 함수에서도 반환됩니다. -## 대체하기 +## 대체하기 한 언어로 된 페이지가 존재하지 않는 경우 (예: 아직 번역되지 않은 페이지), 404 페이지를 표시하는 대신 언어별로 다른 `locale`의 대체 콘텐츠를 표시하도록 선택할 수 있습니다. 이는 아직 모든 경로에 대한 페이지가 없지만 방문자에게 일부 콘텐츠를 제공하려는 경우에 유용합니다. @@ -298,14 +298,14 @@ export default defineConfig({ 예를 들어, 아래 구성은 누락된 `fr` 경로에 대한 대체 로케일로 `es`를 설정합니다. 즉, `example.com/fr/my-page/`를 방문하는 사용자는 `src/pages/fr/my-page.astro`가 없는 경우 404 페이지로 이동하는 대신 리디렉션되지 않고 `example.com/es/my-page/`의 콘텐츠를 보게 됩니다. -```js title="astro.config.mjs" ins={6-8,10} +```js title="astro.config.mjs" ins={6-8,10} import { defineConfig } from "astro/config" export default defineConfig({ i18n: { defaultLocale: "en", locales: ["es", "en", "fr"], fallback: { - fr: "es" + fr: "es" }, routing: { fallbackType: "rewrite" @@ -343,15 +343,15 @@ export default defineConfig({ }); ``` -[`astro:i18n` 가상 모듈](/ko/reference/api-reference/#국제화-astroi18n)의 함수를 사용하여 구성 (예: `getRelativeLocaleUrl()`)에 따라 유효한 URL 경로를 계산하는 경우, [해당 `path`를 `locale` 값으로 사용](/ko/reference/api-reference/#getlocalebypath)하세요. +[`astro:i18n` 가상 모듈](/ko/reference/modules/astro-i18n/)의 함수를 사용하여 구성 (예: `getRelativeLocaleUrl()`)에 따라 유효한 URL 경로를 계산하는 경우, [해당 `path`를 `locale` 값으로 사용](/ko/reference/modules/astro-i18n/#getlocalebypath)하세요. #### 제한 사항 이 기능에는 몇 가지 제한사항이 있습니다. -- `site` 옵션은 필수입니다. -- `output` 옵션은 `"server"`로 설정되어야 합니다. -- 사전 렌더링된 개별 페이지는 있을 수 없습니다. +- `site` 옵션은 필수입니다. +- `output` 옵션은 `"server"`로 설정되어야 합니다. +- 사전 렌더링된 개별 페이지는 있을 수 없습니다. - 어댑터 기능 [`functionPerRoute`](/ko/reference/adapter-reference/#functionperroute)는 지원되지 않습니다. Astro는 이 기능을 지원하기 위해 다음 헤더를 사용합니다. From eaefaa1bc8fae5478c58f58f095a53ef786a06be Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 21:17:37 +0900 Subject: [PATCH 10/21] i18n(ko-KR): update `middleware.mdx` (#9809) Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- src/content/docs/ko/guides/middleware.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/ko/guides/middleware.mdx b/src/content/docs/ko/guides/middleware.mdx index fc55969d66389..dc87a4b5eaffa 100644 --- a/src/content/docs/ko/guides/middleware.mdx +++ b/src/content/docs/ko/guides/middleware.mdx @@ -16,7 +16,7 @@ import Since from '~/components/Since.astro'; 1. `src/middleware.js|ts` 파일을 생성합니다. (또는 `src/middleware/index.js|ts` 파일을 생성할 수도 있습니다.) -2. 이 파일에서 [`context` 객체](#context-객체)와 `next()` 함수를 전달할 수 있는 [`onRequest()`](/ko/reference/api-reference/#onrequest) 함수를 내보냅니다. 이는 기본 내보내기가 아니어야 합니다. +2. 이 파일에서 [`context` 객체](#context-객체)와 `next()` 함수를 전달할 수 있는 [`onRequest()`](/ko/reference/modules/astro-middleware/#onrequest) 함수를 내보냅니다. 이는 기본 내보내기가 아니어야 합니다. ```js title="src/middleware.js" export function onRequest (context, next) { @@ -158,7 +158,7 @@ declare namespace App { ## 미들웨어 체이닝 -[`sequence()`](/ko/reference/api-reference/#sequence)를 사용하여 여러 미들웨어를 지정된 순서로 결합할 수 있습니다. +[`sequence()`](/ko/reference/modules/astro-middleware/#sequence)를 사용하여 여러 미들웨어를 지정된 순서로 결합할 수 있습니다. ```js title="src/middleware.js" import { sequence } from "astro:middleware"; From 69ef625765888e3f9bb7f0ec13891e5499943c3d Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 21:25:08 +0900 Subject: [PATCH 11/21] i18n(ko-KR): create `astro-i18n.mdx` (#9816) Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../docs/ko/reference/modules/astro-i18n.mdx | 335 ++++++++++++++++++ 1 file changed, 335 insertions(+) create mode 100644 src/content/docs/ko/reference/modules/astro-i18n.mdx diff --git a/src/content/docs/ko/reference/modules/astro-i18n.mdx b/src/content/docs/ko/reference/modules/astro-i18n.mdx new file mode 100644 index 0000000000000..6b9441d5126b0 --- /dev/null +++ b/src/content/docs/ko/reference/modules/astro-i18n.mdx @@ -0,0 +1,335 @@ +--- +title: 국제화 API 참조 +i18nReady: true +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 6 +--- +import Since from '~/components/Since.astro'; +import ReadMore from '~/components/ReadMore.astro'; + +

+ +이 모듈은 프로젝트에 구성된 로케일을 사용하여 URL을 생성하는 데 도움이 되는 함수를 제공합니다. + +i18n 라우터를 사용하여 프로젝트에 대한 경로를 생성하는 것은 페이지 경로에 영향을 주는 특정 구성 값에 따라 달라집니다. 이러한 함수를 사용하여 경로를 생성할 때 다음에 대한 개별 설정을 고려해야 합니다. + +- [`base`](/ko/reference/configuration-reference/#base) +- [`trailingSlash`](/ko/reference/configuration-reference/#trailingslash) +- [`build.format`](/ko/reference/configuration-reference/#buildformat) +- [`site`](/ko/reference/configuration-reference/#site) + +또한 `defaultLocale`에 대해 이러한 함수에서 반환된 URL은 `i18n.routing` 구성을 반영합니다. + +기능 및 사용 예시는 [i18n 라우팅 가이드](/ko/guides/internationalization/)를 참조하세요. + +## `astro:i18n`에서 가져오기 + +```js +import { + getRelativeLocaleUrl, + getAbsoluteLocaleUrl, + getRelativeLocaleUrlList, + getAbsoluteLocaleUrlList, + getPathByLocale, + getLocaleByPath, + redirectToDefaultLocale, + redirectToFallback, + notFound, + middleware, + requestHasLocale, + } from 'astro:i18n'; +``` + +### `getRelativeLocaleUrl()` + +

+ +**타입:** `(locale: string, path?: string, options?: GetLocaleOptions) => string` +

+ +이 함수를 사용하여 로케일의 상대 경로를 검색합니다. 해당 로케일이 존재하지 않으면 Astro는 오류를 발생시킵니다. + +```astro +--- +import { getRelativeLocaleUrl } from 'astro:i18n'; + +getRelativeLocaleUrl("fr"); +// /fr 반환 + +getRelativeLocaleUrl("fr", ""); +// /fr 반환 + +getRelativeLocaleUrl("fr", "getting-started"); +// /fr/getting-started 반환 + +getRelativeLocaleUrl("fr_CA", "getting-started", { + prependWith: "blog" +}); +// /blog/fr-ca/getting-started 반환 + +getRelativeLocaleUrl("fr_CA", "getting-started", { + prependWith: "blog", + normalizeLocale: false +}); +// /blog/fr_CA/getting-started 반환 +--- +``` + +### `getAbsoluteLocaleUrl()` + +

+ +**타입:** `(locale: string, path: string, options?: GetLocaleOptions) => string` +

+ +[`site`]의 값이 존재할 때 로케일의 절대 경로를 검색하려면 이 함수를 사용하세요. [`site`]가 구성되지 않은 경우 함수는 상대 URL을 반환합니다. 해당 로케일이 존재하지 않으면 Astro는 오류를 발생시킵니다. + +```astro title="src/pages/index.astro" +--- +import { getAbsoluteLocaleUrl } from 'astro:i18n'; + +// `site`가 `https://example.com`로 설정된 경우 + +getAbsoluteLocaleUrl("fr"); +// https://example.com/fr 반환 + +getAbsoluteLocaleUrl("fr", ""); +// https://example.com/fr 반환 + +getAbsoluteLocaleUrl("fr", "getting-started"); +// https://example.com/fr/getting-started 반환 + +getAbsoluteLocaleUrl("fr_CA", "getting-started", { + prependWith: "blog" +}); +// https://example.com/blog/fr-ca/getting-started 반환 + +getAbsoluteLocaleUrl("fr_CA", "getting-started", { + prependWith: "blog", + normalizeLocale: false +}); +// https://example.com/blog/fr_CA/getting-started 반환 +--- +``` + +### `getRelativeLocaleUrlList()` + +

+ +**타입:** `(path?: string, options?: GetLocaleOptions) => string[]` +

+ +모든 로케일에 대한 상대 경로 목록을 반환하려면 [`getRelativeLocaleUrl`](#getrelativelocaleurl)처럼 이 함수를 사용하세요. + +### `getAbsoluteLocaleUrlList()` + +

+ +**타입:** `(path?: string, options?: GetLocaleOptions) => string[]` +

+ +모든 로케일에 대한 절대 경로 목록을 반환하려면 [`getAbsoluteLocaleUrl`](/ko/guides/internationalization/#사용자-정의-로케일-경로)처럼 이 함수를 사용하세요. + +### `getPathByLocale()` + +

+ +**타입:** `(locale: string) => string` +

+ +[사용자 정의 로케일 경로](/ko/guides/internationalization/#사용자-정의-로케일-경로)가 구성된 경우 하나 이상의 `codes`와 연결된 `path`를 반환하는 함수입니다. + +```js title="astro.config.mjs" +export default defineConfig({ + i18n: { + locales: ["es", "en", { + path: "french", + codes: ["fr", "fr-BR", "fr-CA"] + }] + } +}) +``` + +```astro title="src/pages/index.astro" +--- +import { getPathByLocale } from 'astro:i18n'; + +getPathByLocale("fr"); // "french" 반환 +getPathByLocale("fr-CA"); // "french" 반환 +--- +``` + +### `getLocaleByPath()` + +

+ +**타입:** `(path: string) => string` +

+ +로케일 `path`와 연관된 `code`를 반환하는 함수입니다. + +```js title="astro.config.mjs" +export default defineConfig({ + i18n: { + locales: ["es", "en", { + path: "french", + codes: ["fr", "fr-BR", "fr-CA"] + }] + } +}) +``` + +```astro title="src/pages/index.astro" +--- +import { getLocaleByPath } from 'astro:i18n'; + +getLocaleByPath("french"); // 구성된 첫 번째 code이기 때문에 "fr"을 반환합니다. +--- +``` + +### `redirectToDefaultLocale()` + +

+ +**타입:** `(context: APIContext, statusCode?: ValidRedirectStatus) => Promise`
+ +

+ +:::note +`i18n.routing`이 `"manual"`로 설정된 경우에만 사용할 수 있습니다. +::: + +구성된 `defaultLocale`로 리디렉션되는 `Response`를 반환하는 함수입니다. 유효한 리디렉션 상태 코드를 선택적으로 허용합니다. + +```js title="middleware.js" +import { defineMiddleware } from "astro:middleware"; +import { redirectToDefaultLocale } from "astro:i18n"; + +export const onRequest = defineMiddleware((context, next) => { + if (context.url.pathname.startsWith("/about")) { + return next(); + } else { + return redirectToDefaultLocale(context, 302); + } +}) +``` + +### `redirectToFallback()` + +

+ +**타입:** `(context: APIContext, response: Response) => Promise`
+ +

+ +:::note +`i18n.routing`이 `"manual"`로 설정된 경우에만 사용할 수 있습니다. +::: + +자체 미들웨어에서 [`i18n.fallback` 구성](/ko/reference/configuration-reference/#i18nfallback)을 사용할 수 있게 해주는 함수입니다. + +```js title="middleware.js" +import { defineMiddleware } from "astro:middleware"; +import { redirectToFallback } from "astro:i18n"; + +export const onRequest = defineMiddleware(async (context, next) => { + const response = await next(); + if (response.status >= 300) { + return redirectToFallback(context, response) + } + return response; +}) +``` + +### `notFound()` + +

+ +**타입:** `(context: APIContext, response?: Response) => Promise | undefined`
+ +

+ +:::note +`i18n.routing`이 `"manual"`로 설정된 경우에만 사용할 수 있습니다. +::: + +다음과 같은 경우 라우팅 미들웨어에서 이 함수를 사용하여 404를 반환합니다. +- 현재 경로가 루트가 아닌 경우. 예를 들어 `/` 또는 `/` +- URL에 로케일이 포함되어 있지 않은 경우 + +`Response`가 전달되면 이 함수에서 내보낸 새 `Response`에는 원래 응답과 동일한 헤더가 포함됩니다. + +```js title="middleware.js" +import { defineMiddleware } from "astro:middleware"; +import { notFound } from "astro:i18n"; + +export const onRequest = defineMiddleware((context, next) => { + const pathNotFound = notFound(context); + if (pathNotFound) { + return pathNotFound; + } + return next(); +}) +``` + +### `middleware()` + +

+ +**타입:** `(options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler`
+ +

+ +:::note +`i18n.routing`이 `"manual"`로 설정된 경우에만 사용할 수 있습니다. +::: + +Astro i18n 미들웨어를 프로그래밍 방식으로 생성할 수 있는 함수입니다. + +이는 기본 i18n 로직을 계속 사용하고 싶지만 웹 사이트에 몇 가지 예외만 추가하려는 경우에 유용합니다. + +```js title="middleware.js" +import { middleware } from "astro:i18n"; +import { sequence, defineMiddleware } from "astro:middleware"; + +const customLogic = defineMiddleware(async (context, next) => { + const response = await next(); + + // 응답을 해결한 후 사용자 정의 로직. + // Astro i18n 미들웨어에서 오는 응답을 캐치할 수 있습니다. + + return response; +}); + +export const onRequest = sequence(customLogic, middleware({ + prefixDefaultLocale: true, + redirectToDefaultLocale: false +})) +``` + +### `requestHasLocale()` + +

+ +**타입:** `(context: APIContext) => boolean`
+ +

+ +:::note +`i18n.routing`이 `"manual"`로 설정된 경우에만 사용할 수 있습니다. +::: + +현재 URL에 구성된 로케일이 포함되어 있는지 확인합니다. 내부적으로 이 함수는 `APIContext#url.pathname`을 사용합니다. + +```js title="middleware.js" +import { defineMiddleware } from "astro:middleware"; +import { requestHasLocale } from "astro:i18n"; + +export const onRequest = defineMiddleware(async (context, next) => { + if (requestHasLocale(context)) { + return next(); + } + return new Response("Not found", { status: 404 }); +}) +``` From 9e2b10ae0d218240fd0e3f2eecde5ac49b09e0e0 Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 21:32:16 +0900 Subject: [PATCH 12/21] i18n(ko-KR): create `astro-middleware.mdx` (#9817) Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../ko/reference/modules/astro-middleware.mdx | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 src/content/docs/ko/reference/modules/astro-middleware.mdx diff --git a/src/content/docs/ko/reference/modules/astro-middleware.mdx b/src/content/docs/ko/reference/modules/astro-middleware.mdx new file mode 100644 index 0000000000000..f56145541a414 --- /dev/null +++ b/src/content/docs/ko/reference/modules/astro-middleware.mdx @@ -0,0 +1,122 @@ +--- +title: 미들웨어 API 참조 +i18nReady: true +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 6 +--- +import Since from '~/components/Since.astro'; +import ReadMore from '~/components/ReadMore.astro'; + +

+ +미들웨어를 사용하면 페이지나 엔드포인트가 렌더링될 때마다 요청과 응답을 가로채고 동작을 동적으로 주입할 수 있습니다. 기능 및 사용 예시는 [미들웨어 가이드](/ko/guides/middleware/)를 확인하세요. + +## `astro:middleware`에서 가져오기 + +```js +import { + sequence, + createContext, + trySerializeLocals, + defineMiddleware, + } from 'astro:middleware'; +``` + +### `defineMiddleware()` + +타입 안전성을 활용하기 위해 유틸리티 함수 `defineMiddleware()`를 가져와 사용할 수 있습니다: + +```ts +// src/middleware.ts +import { defineMiddleware } from "astro:middleware"; + +// `context` 및 `next`의 타입이 자동으로 설정됩니다. +export const onRequest = defineMiddleware((context, next) => { + +}); +``` + +### `sequence()` + +

+ +**타입:** `(...handlers: MiddlewareHandler[]) => MiddlewareHandler` +

+ +미들웨어 함수를 인수로 받아 전달된 순서대로 실행하는 함수입니다. + +```js title="src/middleware.js" +import { sequence } from "astro:middleware"; + +async function validation(_, next) {...} +async function auth(_, next) {...} +async function greeting(_, next) {...} + +export const onRequest = sequence(validation, auth, greeting); +``` + +### `createContext()` + +

+ +**타입:** `(context: CreateContext) => APIContext`
+ +

+ +Astro 미들웨어 `onRequest()` 함수에 전달될 [`APIContext`](/ko/reference/api-reference/#엔드포인트-context)를 생성하는 저수준 API입니다. + +이 함수는 Astro 미들웨어를 프로그래밍 방식으로 실행하기 위해 통합/어댑터에서 사용할 수 있습니다. + +### `trySerializeLocals()` + +

+ +**타입:** `(value: unknown) => string`
+ +

+ +모든 값을 받아들여 해당 값의 직렬화된 버전 (문자열)을 반환하려고 시도하는 저수준 API입니다. 값을 직렬화할 수 없으면 함수에서 런타임 오류가 발생합니다. + +## 미들웨어 내보내기 + +프로젝트의 미들웨어를 `src/middleware.js`에서 정의할 때, 다음 사용자 정의 함수를 내보내세요: + +### `onRequest()` + +**타입:** `(context: APIContext, next: MiddlewareNext) => Promise | Response | Promise | void` + +모든 페이지 또는 API 경로를 렌더링하기 전에 호출되는 `src/middleware.js`에서 내보낸 필수 함수입니다. 두 개의 인수 [context](#context) 및 [next()](#next)를 전달받습니다. `onRequest()`는 `Response`를 직접 반환하거나 `next()`를 호출하여 반환해야 합니다. + +```js title="src/middleware.js" +export function onRequest (context, next) { + // 요청의 응답 데이터를 가로챕니다. + // 선택적으로 응답을 변환합니다. + // Response를 직접 반환하거나 `next()` 호출 결과를 반환합니다. + return next(); +}; +``` + +`onRequest()` 함수는 다음 인자를 전달받아 호출됩니다. + +#### `context` + +

+ +**타입:** `APIContext` +

+ +`onRequest()`의 첫 번째 인수는 컨텍스트 객체입니다. 이는 많은 `Astro` 전역 프로퍼티를 반영합니다. + +컨텍스트 객체에 대해 더 자세히 알아보기 위해 [엔드포인트 컨텍스트](/ko/reference/api-reference/#엔드포인트-context)를 방문하세요. + +#### `next()` + +

+ +**타입:** `(rewritePayload?: string | URL | Request) => Promise`
+

+ +`onRequest()`의 두 번째 인수는 체인의 모든 후속 미들웨어를 호출하고 `Response`를 반환하는 함수입니다. 예를 들어, 다른 미들웨어가 응답의 HTML 본문을 수정할 수 있으며 `next()`의 결과를 기다리면 미들웨어가 이러한 변경 사항에 응답할 수 있습니다. + +Astro v4.13.0부터 `next()`는 새 렌더링 단계를 다시 트리거하지 않고 현재 요청을 [리라이트](/ko/guides/routing/#리라이트)하기 위해 문자열 형식의 선택적 URL 경로 매개 변수인 `URL` 또는 `Request`를 허용합니다. From 87dbd4d457875542c209a31fb5faa86ccafb0cbf Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 21:40:02 +0900 Subject: [PATCH 13/21] i18n(ko-KR): create `astro-transitions.mdx` (#9818) Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../reference/modules/astro-transitions.mdx | 458 ++++++++++++++++++ 1 file changed, 458 insertions(+) create mode 100644 src/content/docs/ko/reference/modules/astro-transitions.mdx diff --git a/src/content/docs/ko/reference/modules/astro-transitions.mdx b/src/content/docs/ko/reference/modules/astro-transitions.mdx new file mode 100644 index 0000000000000..e7c6927fa04bb --- /dev/null +++ b/src/content/docs/ko/reference/modules/astro-transitions.mdx @@ -0,0 +1,458 @@ +--- +title: View Transitions API 참조 +i18nReady: true +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 6 +--- +import Since from '~/components/Since.astro'; +import ReadMore from '~/components/ReadMore.astro'; + +

+ +이 모듈은 View Transitions API 및 클라이언트 측 라우터를 제어하고 상호 작용하는 함수를 제공합니다. + +기능 및 사용 예시는 [View Transitions 가이드](/ko/guides/view-transitions/)를 참조하세요. + +## `astro:transitions`에서 가져오기 + +```ts +import { ViewTransitions, fade, slide } from 'astro:transitions'; +``` + +### `` + +

+ +원하는 모든 페이지의 ``에 `` 라우팅 컴포넌트를 가져오고 추가하여 개별 페이지에서 트랜지션을 사용하도록 선택합니다. + +```astro title="src/pages/index.astro" ins={2,7} +--- +import { ViewTransitions } from 'astro:transitions'; +--- + + + My Homepage + + + +

Welcome to my website!

+ + +``` + +페이지 요소와 컴포넌트에 [라우터 제어](/ko/guides/view-transitions/#라우터-제어) 및 [전환 지시어를 추가](/ko/guides/view-transitions/#전환-지시어)하는 방법에 대해 자세히 알아보세요. + +### `fade` + +

+ +**타입:** `(opts: { duration?: string | number }) => TransitionDirectionalAnimations` + +

+ +기본적으로 제공되는 `fade` 애니메이션의 지속 시간을 설정할 수 있는 유틸리티 함수입니다. + +```astro {2} /fade\\(.+\\)/ +--- +import { fade } from 'astro:transitions'; +--- + + +
+ + +
+``` + +### `slide` + +

+ +**타입:** `(opts: { duration?: string | number }) => TransitionDirectionalAnimations` + +

+ +기본적으로 제공되는 `slide` 애니메이션의 지속 시간을 설정할 수 있는 유틸리티 함수입니다. + +```astro {2} /slide\\(.+\\)/ +--- +import { slide } from 'astro:transitions'; +--- + + +
+ + +
+``` + +## `astro:transitions/client`에서 가져오기 + +```astro + +``` + +### `navigate()` + +

+ +**타입:** `(href: string, options?: Options) => void`
+ +

+ +View Transitions API를 사용하여 지정된 `href`로 탐색을 실행하는 함수입니다. + +이 함수 시그니처는 [브라우저 Navigation API의 `navigate` 함수](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate)를 기반으로 합니다. 이 함수는 Navigation API를 기반으로 하지만, 페이지를 다시 로드하지 않고 탐색할 수 있도록 [History API](https://developer.mozilla.org/ko/docs/Web/API/History_API) 위에 구현되어 있습니다. + +#### `history` 옵션 + +

+ +**타입:** `'auto' | 'push' | 'replace'`
+**기본값:** `'auto'`
+ +

+ +이 탐색을 브라우저 기록에 추가하는 방법을 정의합니다. + +- `'push'`: 라우터는 `history.pushState`를 사용하여 브라우저 기록에 새 항목을 생성합니다. +- `'replace'`: 라우터는 `history.replaceState`를 사용하여 탐색에 새 항목을 추가하지 않고 URL을 업데이트합니다. +- `'auto'` (기본값): 라우터는 `history.pushState`를 시도하지만, URL을 전환할 수 없는 경우 현재 URL은 브라우저 기록을 변경하지 않고 그대로 유지됩니다. + +이 옵션은 브라우저 Navigation API의 [`history` 옵션](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate#history)을 따르지만, Astro 프로젝트에서 발생할 수 있는 경우를 위해 단순화되었습니다. + +#### `formData` 옵션 + +

+ +**타입:** `FormData`
+ +

+ +`POST` 요청을 위한 `FormData` 객체입니다. + +이 옵션을 제공하면 탐색 대상 페이지에 대한 요청이 양식 데이터 객체를 콘텐츠로 하는 `POST` 요청으로 전송됩니다. + +트랜지션이 활성화된 HTML 양식을 제출하면 페이지 새로 고침이 있는 기본 탐색 대신 이 메서드가 사용됩니다. 이 메서드를 호출하면 프로그래밍 방식으로 동일한 동작을 트리거할 수 있습니다. + +#### `info` 옵션 + +

+ +**타입:** `any`
+ +

+ +이 탐색으로 인해 발생하는 `astro:before-preparation` 및 `astro:before-swap` 이벤트에 포함될 임의의 데이터입니다. + +이 옵션은 브라우저 Navigation API의 [`info` 옵션](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate#info)을 모방합니다. + +#### `state` 옵션 + +

+ +**타입:** `any`
+ +

+ +이 탐색에서 생성된 `NavitationHistoryEntry` 객체에 연결할 임의의 데이터입니다. 이 데이터는 History API의 [`history.getState` 함수](https://developer.mozilla.org/en-US/docs/Web/API/NavigationHistoryEntry/getState)를 사용하여 검색할 수 있습니다. + +이 옵션은 브라우저 Navigation API의 [`state` 옵션](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate#state)을 모방합니다. + +#### `sourceElement` 옵션 + +

+ +**타입:** `Element`
+ +

+ +존재하는 경우, 이 탐색을 트리거한 요소입니다. 이 요소는 다음 이벤트에서 사용할 수 있습니다: +- `astro:before-preparation` +- `astro:before-swap` + +### `supportsViewTransitions` + +

+ +**타입:** `boolean`
+ +

+ +현재 브라우저에서 트랜지션이 지원되고 활성화되어 있는지 여부입니다. + +### `transitionEnabledOnThisPage` + +

+ +**타입:** `boolean`
+ +

+ +현재 페이지에 클라이언트 측 탐색을 위한 트랜지션이 활성화되어 있는지 여부입니다. 트랜지션이 있는 페이지에서 다르게 동작하는 컴포넌트를 만드는 데 사용할 수 있습니다. + +### `getFallback()` + +

+ +**타입:** `() => 'none' | 'animate' | 'swap'`
+ +

+ +트랜지션을 지원하지 않는 브라우저에서 사용할 대체 전략을 반환합니다. + +대체 동작을 선택하고 구성하는 방법은 [대체 제어](/ko/guides/view-transitions/#대체-제어) 가이드를 참조하세요. + +### `swapFunctions` + +

+ + +

+ +Astro의 기본 스왑 함수를 빌드하는 데 사용되는 유틸리티 함수가 포함된 객체입니다. +[사용자 정의 스왑 함수를 만들때](/ko/guides/view-transitions/#사용자-정의-스왑-함수-구현) 유용할 수 있습니다. + +`swapFunctions`는 다음과 같은 메서드를 제공합니다: + +#### `deselectScripts()` + +

+ +**타입:** `(newDocument: Document) => void` +

+ +새 문서에서 실행해서는 안 되는 스크립트를 표시합니다. 이러한 스크립트는 이미 현재 문서에 있으며 [`data-astro-rerun`](/ko/guides/view-transitions/#data-astro-rerun)을 사용하여 다시 실행하도록 플래그가 지정되지 않습니다. + +#### `swapRootAttributes()` + +

+ +**타입:** `(newDocument: Document) => void` +

+ +`lang` 속성과 같은 문서 루트 간 속성을 스왑합니다. 여기에는 `data-astro-transition`과 같은 Astro에서 삽입한 내부 속성도 포함되어 있어, 트랜지션 방향을 Astro에서 생성된 CSS 규칙에 사용할 수 있습니다. + +사용자 지정 스왑 함수를 만들 때, 트랜지션의 애니메이션이 깨지지 않도록 이 함수를 호출하는 것이 중요합니다. + +#### `swapHeadElements()` + +

+ +**타입:** `(newDocument: Document) => void` +

+ +현재 문서의 ``에서 새 문서에 유지되지 않는 모든 요소를 제거합니다. 그런 다음 새 문서의 ``에 있는 모든 새 요소를 현재 문서의 ``에 추가합니다. + +#### `saveFocus()` + +

+ +**타입:** `() => () => void` +

+ +현재 페이지에서 포커스된 요소를 저장하고, 포커스된 요소가 유지되는 경우, 호출 시 해당 요소에 포커스를 제공하는 함수를 반환합니다. + + +#### `swapBodyElement()` + +

+ +**타입:** `(newBody: Element, oldBody: Element) => void` +

+ +이전 body를 새 body로 교체합니다. 그런 다음 이전 body에서 유지되어야 하는 모든 요소를 검토하고 새 body에서 일치하는 요소를 찾아 이전 요소를 다시 제자리로 바꿉니다. + +## 라이프사이클 이벤트 + +### `astro:before-preparation` 이벤트 + +View Transitions를 사용하여 탐색을 시작할 때 전송되는 이벤트입니다. 이 이벤트는 요청이 이루어지고 브라우저 상태가 변경되기 전에 발생합니다. + +이 이벤트에는 속성이 있습니다: +- [`info`](#info) +- [`sourceElement`](#sourceelement) +- [`navigationType`](#navigationtype) +- [`direction`](#direction) +- [`from`](#from) +- [`to`](#to) +- [`formData`](#formdata) +- [`loader()`](#loader) + +이 이벤트의 사용 방법에 대한 자세한 내용은 [View Transitions 가이드](/ko/guides/view-transitions/#astrobefore-preparation)에서 확인하세요. + +### `astro:after-preparation` 이벤트 + +View Transitions를 사용하는 탐색에서 다음 페이지가 로드된 후 전송되는 이벤트입니다. + +이 이벤트에는 속성이 없습니다. + +이 이벤트의 사용 방법에 대한 자세한 내용은 [View Transitions 가이드](/ko/guides/view-transitions/#astroafter-preparation)에서 확인하세요. + +### `astro:before-swap` 이벤트 + +다음 페이지가 구문 분석되고, 준비되고, 트랜지션을 준비하면서 문서에 링크된 후, 문서 간 콘텐츠가 교환되기 전에 전송되는 이벤트입니다. + +이 이벤트는 취소할 수 없습니다. `preventDefault()`를 호출하는 것은 아무 작업도 하지 않습니다. + +이 이벤트에는 속성이 있습니다: +- [`info`](#info) +- [`sourceElement`](#sourceelement) +- [`navigationType`](#navigationtype) +- [`direction`](#direction) +- [`from`](#from) +- [`to`](#to) +- [`viewTransition`](#viewtransition) +- [`swap()`](#swap) + +이 이벤트의 사용 방법에 대한 자세한 내용은 [View Transitions 가이드](/ko/guides/view-transitions/#astrobefore-swap)에서 확인하세요. + +### `astro:after-swap` 이벤트 + +페이지의 콘텐츠가 교체된 후, 트랜지션이 끝나기 전에 전달되는 이벤트입니다. + +기록 항목과 스크롤 위치가 업데이트된 후, 이 이벤트가 트리거됩니다. + +### `astro:page-load` 이벤트 + +트랜지션을 사용하는 탐색이나 브라우저의 기본 기능으로 페이지 로드가 완료된 후 전달되는 이벤트입니다. + +페이지에서 트랜지션이 활성화되면 일반적으로 `DOMContentLoaded`에서 실행되는 코드가 이 이벤트에서 실행되도록 변경되어야 합니다. + +### 라이프사이클 이벤트 속성 + +

+ +#### `info` + +

+ +**타입:** `URL` +

+ +탐색 중에 정의된 임의의 데이터입니다. + +이는 [`navigate()` 함수](#navigate)의 [`info` 옵션](#info-옵션)에 전달된 리터럴 값입니다. + +#### `sourceElement` + +

+ +**타입:** `Element | undefined` +

+ +탐색을 트리거한 요소입니다. 예를 들어 클릭된 `` 요소가 될 수 있습니다. + +[`navigate()` 함수](#navigate)를 사용할 때는 호출에서 지정된 요소가 됩니다. + +#### `newDocument` + +

+ +**타입:** `Document` +

+ +탐색의 다음 페이지에 대한 문서입니다. 이 문서의 내용은 현재 문서의 내용 대신 교체됩니다. + +#### `navigationType` + +

+ +**타입:** `'push' | 'replace' | 'traverse'` +

+ +어떤 종류의 기록 탐색이 일어나고 있나요. +- `push`: 새 페이지에 대한 새 `NavigationHistoryEntry`가 만들어지고 있습니다. +- `replace`: 현재 `NavigationHistoryEntry`가 새 페이지의 항목으로 대체되고 있습니다. +- `traverse`: `NavigationHistoryEntry`이 생성되지 않습니다. 히스토리 내 위치가 변경되고 있습니다. + 순회 방향은 [`direction` 속성](#direction)에서 지정됩니다. + +#### `direction` + +

+ +**타입:** `Direction` +

+ +트랜지션 방향입니다. +- `forward`: 기록의 다음 페이지 또는 새 페이지로 이동합니다. +- `back`: 기록의 이전 페이지로 이동합니다. +- 다른 리스너가 설정했을 수 있는 기타 모든 항목. + +#### `from` + +

+ +**타입:** `URL` +

+ +The URL of the page initiating the navigation. +탐색을 시작하는 페이지의 URL입니다. + +#### `to` + +

+ +**타입:** `URL` +

+ +탐색 중인 페이지의 URL입니다. 이 속성을 수정할 수 있으며, 라이프사이클이 끝날 때의 값이 다음 페이지의 `NavigationHistoryEntry`에 사용됩니다. + +#### `formData` + +

+ +**타입:** `FormData | undefined` +

+ +`POST` 요청을 위한 `FormData` 객체입니다. + +이 속성을 설정하면 일반적인 `GET` 요청 대신 지정된 양식 데이터 객체를 콘텐츠로 하는 `POST` 요청이 [`to` URL](#to)로 전송됩니다. + +트랜지션이 활성화된 HTML 양식을 제출할 때 이 필드는 양식의 데이터로 자동 설정됩니다. [`navigate()` 함수](#navigate)를 사용하는 경우 이 값은 옵션에 지정된 것과 동일합니다. + +#### `loader()` + +

+ +**타입:** `() => Promise` +

+ +탐색에서 다음 단계 (다음 페이지 로딩)를 구현합니다. 이 구현을 재정의하여 동작을 추가할 수 있습니다. + +#### `viewTransition` + +

+ +**타입:** [`ViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition) +

+ +이 탐색에 사용된 트랜지션 객체입니다. [View Transitions API](https://developer.mozilla.org/ko/docs/Web/API/View_Transitions_API)를 지원하지 않는 브라우저에서는 편의를 위해 동일한 API를 구현하지만 DOM 통합이 없는 객체입니다. + +#### `swap()` + +

+ +**타입:** `() => void` +

+ +문서 스왑 로직을 구현합니다. + +[사용자 지정 스왑 함수를 구현](/ko/guides/view-transitions/#사용자-정의-스왑-함수-구현)하는 방법에 대한 자세한 내용은 View Transitions 가이드를 참조하세요. + +기본적으로 이 구현은 다음 함수를 순서대로 호출합니다: + +1. [`deselectScripts()`](#deselectscripts) +2. [`swapRootAttributes()`](#swaprootattributes) +3. [`swapHeadElements()`](#swapheadelements) +4. [`saveFocus()`](#savefocus) +5. [`swapBodyElement()`](#swapbodyelement) From 42c872aeb4e63897600108ba2d3ec974b5e520a4 Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 21:47:32 +0900 Subject: [PATCH 14/21] i18n(ko-KR): create `astro-actions.mdx` (#9813) * i18n(ko-KR): create `astro-actions.mdx` * fix typo --------- Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../ko/reference/modules/astro-actions.mdx | 176 ++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 src/content/docs/ko/reference/modules/astro-actions.mdx diff --git a/src/content/docs/ko/reference/modules/astro-actions.mdx b/src/content/docs/ko/reference/modules/astro-actions.mdx new file mode 100644 index 0000000000000..560316b6d8da7 --- /dev/null +++ b/src/content/docs/ko/reference/modules/astro-actions.mdx @@ -0,0 +1,176 @@ +--- +title: 액션 API 참조 +i18nReady: true +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 6 +--- +import Since from '~/components/Since.astro'; +import ReadMore from '~/components/ReadMore.astro'; + +

+ +

+ +액션을 사용하면 클라이언트 코드 및 HTML 양식에서 호출할 수 있는 타입 안정성을 갖춘 백엔드를 구축할 수 있습니다. 액션을 정의하고 호출하는 모든 유틸리티는 `astro:actions` 모듈에 의해 노출됩니다. 예시 및 사용 지침은 [액션 가이드](/ko/guides/actions/)를 참조하세요. + +## `astro:actions`에서 가져오기 + +```js +import { + actions, + defineAction, + isInputError, + ActionError, + } from 'astro:actions'; +``` + +### `defineAction()` + +

+ +

+ +`defineAction()` 유틸리티는 `src/actions/index.ts` 파일에서 새 액션을 정의하는 데 사용됩니다. 이 함수는 실행할 서버 로직이 포함된 [`handler()`](#handler-속성) 함수와 런타임에 입력 매개변수를 검사하는 선택적인 [`input`](#input-유효성-검사기) 속성을 받습니다. + +```ts title="src/actions/index.ts" +import { defineAction } from 'astro:actions'; +import { z } from 'astro:schema'; + +export const server = { + getGreeting: defineAction({ + input: z.object({ + name: z.string(), + }), + handler: async (input, context) => { + return `Hello, ${input.name}!` + } + }) +} +``` + +#### `handler()` 속성 + +

+ +**Type:** `(input, context) => any` +

+ +`defineAction()`에는 액션이 호출될 때 실행할 서버 로직이 포함된 `handler()` 함수가 필요합니다. 핸들러에서 반환된 데이터는 자동으로 직렬화되어 호출자에게 전송됩니다. + +`handler()`는 사용자 입력을 첫 번째 인수로 받아 호출됩니다. [`input`](#input-유효성-검사기) 유효성 검사기가 설정되어 있으면 사용자 입력은 핸들러로 전달되기 전에 유효성이 검사됩니다. 두 번째 인수는 `getActionResult()`, `callAction()` 및 `redirect()`를 제외한 대부분의 Astro [표준 엔드포인트 컨텍스트](/ko/reference/api-reference/#엔드포인트-context)를 포함하는 `context` 객체입니다. + +반환 값은 [devalue 라이브러리](https://github.com/Rich-Harris/devalue)를 사용하여 구문 분석됩니다. 이 라이브러리는 `Date()`, `Map()`, `Set()`, `URL()`의 인스턴스와 JSON 값을 지원합니다. + +#### `input` 유효성 검사기 + +

+ +**Type:** `ZodType | undefined` +

+ +선택적 `input` 속성은 런타임에 핸들러 입력의 유효성을 검사하기 위해 Zod 유효성 검사기를 전달받습니다. 액션이 유효성 검사에 실패하면 [`BAD_REQUEST` 오류](#actionerror)가 반환되고 `handler`가 호출되지 않습니다. + +`input`을 생략하면 `handler`는 JSON 요청의 경우 `unknown` 타입의 입력을, 양식 요청의 경우 `FormData` 타입의 입력을 받습니다. + +##### `accept: 'form'`과 함께 사용 + +액션이 양식 입력을 전달받는 경우 `z.object()` 유효성 검사기를 사용하여 양식 데이터를 타입이 정해진 객체로 자동 구문 분석합니다. 양식 데이터 필드에 지원되는 유효성 검사기는 다음과 같습니다: + +- `number` 유형의 입력은 `z.number()`를 사용하여 검증할 수 있습니다. +- `checkbox` 유형의 입력은 `z.boolean()`을 사용하여 검증할 수 있습니다. +- `file` 유형의 입력은 `z.instanceof(File)`을 사용하여 검증할 수 있습니다. +- 동일한 `name`의 여러 입력은 `z.array(/* validator */)`를 사용하여 검증할 수 있습니다. +- 다른 모든 입력은 `z.string()`을 사용하여 검증할 수 있습니다. + +`.refine()`, `.transform()`, `.pipe()`를 포함한 확장 함수도 `z.object()` 유효성 검사기에서 지원됩니다. + +서로 다른 유효성 검사기의 조합을 적용하려면 `z.discriminatedUnion()` 래퍼를 사용하여 특정 양식 필드를 기준으로 타입을 좁히세요. 이 예시는 사용자 "생성" 또는 "업데이트" 중 하나로 양식 제출을 처리하며, `type`이라는 이름의 양식 필드를 사용하여 어떤 객체에 대해 유효성 검사를 수행할지 결정합니다. + +```ts +import { defineAction } from 'astro:actions'; +import { z } from 'astro:schema'; + +export const server = { + changeUser: defineAction({ + accept: 'form', + input: z.discriminatedUnion('type', [ + z.object({ + // `type` 필드에 `create` 값이 있을 때 일치합니다. + type: z.literal('create'), + name: z.string(), + email: z.string().email(), + }), + z.object({ + // `type` 필드에 `update` 값이 있을 때 일치합니다. + type: z.literal('update'), + id: z.number(), + name: z.string(), + email: z.string().email(), + }), + ]), + async handler(input) { + if (input.type === 'create') { + // input은 { type: 'create', name: string, email: string } + } else { + // input은 { type: 'update', id: number, name: string, email: string } + } + }, + }), +}; +``` + +### `isInputError()` + +

+ +**Type:** (error?: unknown | ActionError) => boolean
+ +

+ +`isInputError()` 유틸리티는 `ActionError`가 입력 유효성 검사 오류인지 확인하는 데 사용됩니다. `input` 유효성 검사기가 `z.object()`인 경우 입력 오류에는 이름별로 그룹화된 오류 메시지가 있는 `fields` 객체가 포함됩니다. + +[양식 입력 오류 가이드](/ko/guides/actions/#양식-입력-오류-표시)에서 `isInputError()` 사용에 대한 자세한 내용을 참조하세요. + +### `ActionError` + +

+ +

+ +액션 `handler`가 던지는 오류를 생성하는 데 `ActionError()` 생성자가 사용됩니다. 이는 발생한 오류 (예: `"UNAUTHORIZED"`)를 설명하는 `code` 속성과 추가 세부정보가 포함된 선택적 `message` 속성을 허용합니다. + +#### `code` + +

+ +

+ +`code` 속성은 모든 HTTP 상태 코드의 사람이 읽을 수 있는 버전을 허용합니다. 지원되는 코드는 다음과 같습니다: + +- `BAD_REQUEST` (400): 클라이언트가 잘못된 입력을 보냈습니다. 이 오류는 액션 `input` 유효성 검사기가 유효성 검사에 실패할 때 발생합니다. +- `UNAUTHORIZED` (401): 클라이언트에 유효한 인증 자격 증명이 없습니다. +- `FORBIDDEN` (403): 클라이언트가 리소스에 액세스할 수 있는 권한이 없습니다. +- `NOT_FOUND` (404): 서버가 요청된 리소스를 찾을 수 없습니다. +- `METHOD_NOT_SUPPORTED` (405): 서버가 요청된 메서드를 지원하지 않습니다. +- `TIMEOUT` (408): 서버가 요청을 처리하는 동안 시간 초과가 발생했습니다. +- `CONFLICT` (409): 충돌로 인해 서버에서 리소스를 업데이트할 수 없습니다. +- `PRECONDITION_FAILED` (412): 서버가 요청의 전제 조건을 충족하지 않습니다. +- `PAYLOAD_TOO_LARGE` (413): 페이로드가 너무 커서 서버가 요청을 처리할 수 없습니다. +- `UNSUPPORTED_MEDIA_TYPE` (415): 서버가 요청의 미디어 유형을 지원하지 않습니다. 참고: 액션은 이미 JSON 및 양식 요청에 대해 [`Content-Type` 헤더](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Content-Type)를 확인하므로 이 코드를 수동으로 사용할 필요가 없을 것입니다. +- `UNPROCESSABLE_CONTENT` (422): 시멘틱 오류로 인해 서버가 요청을 처리할 수 없습니다. +- `TOO_MANY_REQUESTS` (429): 서버가 지정된 속도 제한을 초과했습니다. +- `CLIENT_CLOSED_REQUEST` (499): 서버가 응답하기 전에 클라이언트가 요청을 종료했습니다. +- `INTERNAL_SERVER_ERROR` (500): 서버가 예기치 않게 실패했습니다. +- `NOT_IMPLEMENTED` (501): 서버가 요청된 기능을 지원하지 않습니다. +- `BAD_GATEWAY` (502): 서버가 업스트림 서버로부터 잘못된 응답을 받았습니다. +- `SERVICE_UNAVAILABLE` (503): 서버를 일시적으로 사용할 수 없습니다. +- `GATEWAY_TIMEOUT` (504): 서버가 업스트림 서버로부터 시간 초과를 받았습니다. + +#### `message` + +

+ +

+ +`message` 속성은 문자열을 받습니다. (예: "사용자는 로그인해야 합니다.") \ No newline at end of file From 41f38cc29b95dd1f28d45837ae89f779d04b5f07 Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 21:55:17 +0900 Subject: [PATCH 15/21] i18n(ko-KR): create `astro-assets.mdx` (#9814) * i18n(ko-KR): create `astro-assets.mdx` * fix typo --------- Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../ko/reference/modules/astro-assets.mdx | 159 ++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 src/content/docs/ko/reference/modules/astro-assets.mdx diff --git a/src/content/docs/ko/reference/modules/astro-assets.mdx b/src/content/docs/ko/reference/modules/astro-assets.mdx new file mode 100644 index 0000000000000..57119e0c66cc8 --- /dev/null +++ b/src/content/docs/ko/reference/modules/astro-assets.mdx @@ -0,0 +1,159 @@ +--- +title: 자산 API 참조 +i18nReady: true +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 6 +--- +import Since from '~/components/Since.astro'; +import ReadMore from '~/components/ReadMore.astro'; + +

+ + Astro는 최적화된 이미지를 표시하기 위한 기본 컴포넌트와 도우미 함수를 제공합니다. 기능 및 사용 예시는 [이미지 가이드](/ko/guides/images/)를 참조하세요. + +## `astro:assets`에서 가져오기 + +```js +import { + Image, + Picture, + getImage, + } from 'astro:assets'; +``` + +### `` + +```astro title="src/components/MyComponent.astro" +--- +// Image 컴포넌트 및 이미지 가져오기 +import { Image } from 'astro:assets'; +import myImage from "../assets/my_image.png"; // 1600x900의 이미지 +--- + + +A description of my image. +``` + +```html + + +A description of my image. +``` +#### 속성 + +- src (필수) +- alt (필수) +- width 및 height (`public/` 및 원격 이미지를 사용하는 경우 필수) +- format +- quality +- densities +- widths + +위 속성 외에도 `` 컴포넌트는 HTML `` 태그에서 허용하는 모든 속성을 허용합니다. + +[이미지 가이드](/ko/guides/images/#image--astroassets)에서 자세한 내용을 확인하세요. + +### `` + +

+ +다양한 형식 및/또는 크기로 반응형 이미지를 표시하려면 Astro의 `` 컴포넌트를 사용하세요. + +```astro title="src/pages/index.astro" +--- +import { Picture } from 'astro:assets'; +import myImage from "../assets/my_image.png"; // 1600x900의 이미지 +--- + + + +``` + +```html + + + + + A description of my image. + +``` + +[이미지 안내서](/ko/guides/images/#picture-)에서 자세한 내용을 확인하세요. + +#### 속성 + +``는 `` 컴포넌트의 모든 속성과 함께 다음을 허용합니다. + +##### `formats` + +`` 태그에 사용할 이미지 형식의 배열입니다. 기본적으로 `['webp']`로 설정되어 있습니다. + +##### `fallbackFormat` + +`` 태그에 대한 대체 값으로 사용할 형식입니다. 정적 이미지의 경우 기본값은 `.png`, 애니메이션 이미지의 경우 `.gif`, SVG 파일의 경우 `.svg`입니다. + +##### `pictureAttributes` + +`` 태그에 추가될 속성의 객체입니다. 이 속성을 사용하여 외부 `` 요소 자체에 속성을 적용합니다. `` 컴포넌트에 직접 적용된 속성은 이미지 변환에 사용되는 속성을 제외하고 내부 `` 요소에 적용됩니다. + +### `getImage()` + +

+ +**타입:** `(options: UnresolvedImageTransform) => Promise` +

+ +:::caution +`getImage()`는 서버 전용 API에 의존하며 클라이언트에서 사용될 때 빌드를 중단합니다. +::: + +`getImage()` 함수는 HTML이 아닌 다른 곳 (예: [API 경로](/ko/guides/endpoints/#서버-엔드포인트-api-라우트))에서 사용할 이미지를 생성하기 위한 것입니다. 또한 사용자 정의 `` 컴포넌트를 만들 수도 있습니다. + +`getImage()`는 [Image 컴포넌트와 동일한 속성](/ko/reference/components-reference/#속성)을 가진 옵션 객체를 사용합니다 (`alt` 제외). + +```astro +--- +import { getImage } from "astro:assets"; +import myBackground from "../background.png" + +const optimizedBackground = await getImage({src: myBackground, format: 'avif'}) +--- + +
+``` + +다음 타입을 가진 객체를 반환합니다. + +```ts +type GetImageResult = { + /* 이미지 렌더링에 필요한 추가 HTML 속성 (width, height, style 등) */ + attributes: Record; + /* 검증된 매개변수 전달 */ + options: ImageTransform; + /* 원본 매개변수 전달 */ + rawOptions: ImageTransform; + /* 생성된 이미지의 경로 */ + src: string; + srcSet: { + /* 생성된 srcset의 값, 각 항목에는 URL과 크기 설명자가 있습니다. */ + values: SrcSetValue[]; + /* `srcset` 속성에서 사용할 수 있는 값 */ + attribute: string; + }; +} +``` From ead30afb2a71f2b01eb848f1248aef2a33d24f63 Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 22:02:54 +0900 Subject: [PATCH 16/21] i18n(ko-KR): create `astro-content.mdx` (#9815) * i18n(ko-KR): create `astro-content.mdx` * fix typo --------- Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../ko/reference/modules/astro-content.mdx | 373 ++++++++++++++++++ 1 file changed, 373 insertions(+) create mode 100644 src/content/docs/ko/reference/modules/astro-content.mdx diff --git a/src/content/docs/ko/reference/modules/astro-content.mdx b/src/content/docs/ko/reference/modules/astro-content.mdx new file mode 100644 index 0000000000000..d5fed161485e0 --- /dev/null +++ b/src/content/docs/ko/reference/modules/astro-content.mdx @@ -0,0 +1,373 @@ +--- +title: 콘텐츠 컬렉션 API 참조 +i18nReady: true +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 6 +--- +import Since from '~/components/Since.astro'; +import ReadMore from '~/components/ReadMore.astro'; + +

+ +콘텐츠 컬렉션은 `src/content/`에서 Markdown 또는 MDX 문서를 구성하고 쿼리하는 API를 제공합니다. 기능 및 사용 예시는 [콘텐츠 컬렉션 안내서를 참조하세요](/ko/guides/content-collections/). + +## `astro:content`에서 가져오기 + +```js +import { + z, + defineCollection, + getCollection, + getEntry, + getEntries, + reference, + } from 'astro:content'; +``` +### `defineCollection()` + +

+ +**타입:** `(input: CollectionConfig) => CollectionConfig` +

+ +`defineCollection()`은 `src/content/config.*` 파일에 컬렉션을 구성하는 유틸리티입니다. + +```ts +// src/content/config.ts +import { z, defineCollection } from 'astro:content'; +const blog = defineCollection({ + type: 'content', + schema: z.object({ + title: z.string(), + permalink: z.string().optional(), + }), +}); + +// `collections` 내보내기를 통해 정의된 컬렉션을 Astro에 노출합니다. +export const collections = { blog }; +``` + +이 함수는 다음 속성을 허용합니다. + +#### `type` + +

+ +**타입:** `'content' | 'data'`
+**기본값:** `'content'`
+ +

+ +`type`은 컬렉션에 저장된 항목의 형식을 정의하는 문자열입니다. + +- `'content'` - Markdown (`.md`), MDX (`.mdx`), Markdoc (`.mdoc`)와 같은 콘텐츠 작성 형식 +- `'data'` - JSON (`.json`) 또는 YAML (`.yaml`)과 같은 데이터 전용 형식의 경우 + +:::tip +즉, 컬렉션은 콘텐츠와 데이터 형식을 혼합하여 저장할 수 **없습니다**. 이러한 항목을 유형별로 별도의 컬렉션으로 분할해야 합니다. +::: + +#### `schema` + +

+ +**타입:** ZodType | (context: SchemaContext) => ZodType +

+ +`schema`는 컬렉션에 대한 문서 프런트매터의 타입과 모양을 구성하는 선택적 Zod 객체입니다. 각 값은 [Zod 유효성 검사기](https://github.com/colinhacks/zod)를 사용해야 합니다. + +사용 예시는 [`콘텐츠 컬렉션` 안내서를 참조하세요](/ko/guides/content-collections/#컬렉션-스키마-정의). + +### `reference()` + +

+ +**타입:** `(collection: string) => ZodEffects`
+ +

+ +`reference()` 함수는 콘텐츠 구성에서 한 컬렉션에서 다른 컬렉션으로의 관계 또는 "reference"를 정의하는 데 사용됩니다. 이는 컬렉션 이름을 전달받고 콘텐츠 프런트매터 또는 데이터 파일에 지정된 항목 식별자의 유효성을 검사합니다. + +이 예시에서는 `authors` 컬렉션에 대한 블로그 작성자의 참조와 동일한 `blog` 컬렉션에 대한 관련 게시물 배열을 정의합니다. + +```ts +import { defineCollection, reference, z } from 'astro:content'; + +const blog = defineCollection({ + type: 'content', + schema: z.object({ + // `id`로 `authors` 컬렉션에서 단일 저자 참조 + author: reference('authors'), + // `slug`의 `blog` 컬렉션에서 관련 게시물 배열을 참조하세요. + relatedPosts: z.array(reference('blog')), + }) +}); + +const authors = defineCollection({ + type: 'data', + schema: z.object({ /* ... */ }) +}); + +export const collections = { blog, authors }; +``` + +사용 예시는 [`콘텐츠 컬렉션` 안내서를 참조하세요](/ko/guides/content-collections/#컬렉션-참조-정의하기). + +### `getCollection()` + +

+ +**타입:** `(collection: string, filter?: (entry: CollectionEntry) => boolean) => CollectionEntry[]` +

+ +`getCollection()`은 컬렉션 이름별로 콘텐츠 컬렉션 항목 목록을 검색하는 함수입니다. + +기본적으로 컬렉션의 모든 항목을 반환하고 항목 속성별로 범위를 좁힐 수 있는 선택적 `filter` 함수를 허용합니다. 이를 통해 `data` 객체를 통해 `id`, `slug` 또는 프런트매터 값을 기반으로 컬렉션의 일부 항목만 쿼리할 수 있습니다. + +```astro +--- +import { getCollection } from 'astro:content'; + +// 모든 `src/content/blog/` 항목을 가져옵니다. +const allBlogPosts = await getCollection('blog'); + +// 프런트매터에 `draft: true`가 포함된 게시물만 반환합니다. +const draftBlogPosts = await getCollection('blog', ({ data }) => { + return data.draft === true; +}); +--- +``` + +사용 예시는 [`콘텐츠 컬렉션` 안내서를 참조하세요](/ko/guides/content-collections/#컬렉션-쿼리). + +### `getEntry()` + +

+ +**타입:** +- `(collection: string, contentSlugOrDataId: string) => CollectionEntry` +- `({ collection: string, id: string }) => CollectionEntry` +- `({ collection: string, slug: string }) => CollectionEntry` + +`getEntry()`는 컬렉션 이름과 항목 `id` (`type: 'data'` 컬렉션의 경우) 또는 항목 `slug` (`type: 'content'` 컬렉션의 경우)로 단일 컬렉션 항목을 검색하는 함수입니다. `getEntry()`는 `data`, `body`, `render()` 속성에 액세스하기 위해 참조된 항목을 가져오는 데에도 사용할 수 있습니다. + +```astro +--- +import { getEntry } from 'astro:content'; + +// `src/content/blog/enterprise.md` 가져오기 +const enterprisePost = await getEntry('blog', 'enterprise'); + +// `src/content/captains/picard.yaml` 가져오기 +const picardProfile = await getEntry('captains', 'picard'); + +// `data.captain`이 참조하는 프로필 가져오기 +const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain); +--- +``` + +[컬렉션 항목 쿼리](/ko/guides/content-collections/#컬렉션-쿼리)의 예시는 `콘텐츠 컬렉션` 가이드를 참조하세요. + +### `getEntries()` + +

+ +**타입:** +- `(Array<{ collection: string, id: string }>) => CollectionEntry[]` +- `(Array<{ collection: string, slug: string }>) => CollectionEntry[]` + +`getEntries()`는 동일한 컬렉션에서 여러 컬렉션 항목을 검색하는 함수입니다. 이는 [참조된 항목의 배열을 반환](/ko/guides/content-collections/#컬렉션-참조-정의하기)하여 관련 `data`, `body`, `render()` 속성에 액세스하는 데 유용합니다. + +```astro +--- +import { getEntries } from 'astro:content'; + +const enterprisePost = await getEntry('blog', 'enterprise'); + +// `data.relatedPosts`에 의해 참조되는 관련 게시물 가져오기 +const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts); +--- +``` + +### `getEntryBySlug()` + +

+ +**타입:** `(collection: string, slug: string) => Promise>` +

+ +:::caution[사용되지 않음] +콘텐츠 항목을 쿼리하려면 [`getEntry()` 함수](#getentry)를 사용하세요. 이는 `getEntryBySlug()`와 동일한 인수를 허용하며 JSON 또는 YAML 컬렉션에 대해 `id`를 통한 쿼리를 지원합니다. +::: + +`getEntryBySlug()`는 컬렉션 이름과 항목 `slug`로 단일 컬렉션 항목을 검색하는 함수입니다. + +```astro +--- +import { getEntryBySlug } from 'astro:content'; + +const enterprise = await getEntryBySlug('blog', 'enterprise'); +--- +``` + +사용 예시는 [`콘텐츠 컬렉션` 가이드를 참조하세요](/ko/guides/content-collections/#컬렉션-쿼리). + +### `getDataEntryById()` + +

+ +**타입:** `(collection: string, id: string) => Promise>`
+ +

+ +:::caution[사용되지 않음] +데이터 항목을 쿼리하려면 [`getEntry()` 함수](#getentry)를 사용합니다. 이 함수는 `getDataEntryById()`와 동일한 인수를 전달받으며, Markdown과 같은 콘텐츠 작성 형식의 경우 `slug`로 쿼리할 수 있습니다. +::: + +`getDataEntryById()`는 컬렉션 이름과 항목 `id`로 단일 컬렉션 항목을 검색하는 함수입니다. + +```astro +--- +import { getDataEntryById } from 'astro:content'; + +const picardProfile = await getDataEntryById('captains', 'picard'); +--- +``` + +## `astro:content` 타입 + +```ts +import type { + CollectionEntry, + CollectionKey, + ContentCollectionKey, + DataCollectionKey, + SchemaContext, + } from 'astro:content'; +``` + +### `CollectionEntry` + +[`getCollection()`](#getcollection), [`getEntry()`](#getentry), [`getEntries()`](#getentries)를 포함한 쿼리 함수는 각각 `CollectionEntry` 타입의 항목을 반환합니다. 이 타입은 `astro:content`에서 유틸리티로 사용할 수 있습니다. + +```ts +import type { CollectionEntry } from 'astro:content'; +``` + +`CollectionEntry`는 제네릭 타입입니다. 이 타입을 쿼리하려는 컬렉션의 이름과 함께 사용하세요. +예를 들어, `blog` 컬렉션의 항목은 `CollectionEntry<'blog'>`와 같은 타입을 가질 것입니다. + +각 `CollectionEntry`는 다음 값을 가지는 객체입니다. + +#### `id` + +**사용 가능 대상:** `type: 'content'` 및 `type: 'data'` 컬렉션 +**타입 예시:** + - 콘텐츠 컬렉션: `'entry-1.md' | 'entry-2.md' | ...` + - 데이터 컬렉션: `'author-1' | 'author-2' | ...` + +`src/content/[collection]`에 상대적인 파일 경로를 사용하는 고유 ID입니다. 컬렉션 항목 파일 경로를 기반으로 가능한 모든 문자열 값을 열거합니다. [`type: 'content'`로 정의된](#type) 컬렉션은 ID에 파일 확장자를 포함하지만 `type: 'data'`로 정의된 컬렉션은 포함하지 않습니다. + +#### `collection` + +**사용 가능 대상:** `type: 'content'` 및 `type: 'data'` 컬렉션 +**타입 예시:** `'blog' | 'authors' | ...` + +항목이 위치한 `src/content/` 아래의 최상위 폴더 이름입니다. 이는 스키마 및 쿼리 함수에서 컬렉션을 참조하는 데 사용되는 이름입니다. + +#### `data` + +**사용 가능 대상:** `type: 'content'` 및 `type: 'data'` 컬렉션 +**타입:** `CollectionSchema` + +컬렉션 스키마에서 추론된 프런트매터 속성의 객체입니다 ([`defineCollection()` 참조를 확인하세요](#definecollection)). 스키마가 구성되지 않은 경우 기본값은 `any`입니다. + +#### `slug` + +**사용 가능 대상:** `type: 'content'` 컬렉션 전용 +**타입 예시:** `'entry-1' | 'entry-2' | ...` + +Markdown 또는 MDX 문서용 URL 지원 슬러그입니다. 파일 확장자가 없는 `id`가 기본값이지만 파일의 프런트매터에서 [`slug` 속성](/ko/guides/content-collections/#사용자-정의-슬러그-정의)을 설정하여 재정의할 수 있습니다. + +#### `body` + +**사용 가능 대상:** `type: 'content'` 컬렉션 전용 +**타입:** `string` + +Markdown 또는 MDX 문서의 컴파일되지 않은 원시 본문을 포함하는 문자열입니다. + +#### `render()` + +**사용 가능 대상:** `type: 'content'` 컬렉션 전용 +**타입:** `() => Promise` + +렌더링을 위해 지정된 Markdown 또는 MDX 문서를 컴파일하는 함수입니다. 이 함수는 다음 속성을 반환합니다. + +- `` - Astro 파일에서 문서의 내용을 렌더링하는 데 사용되는 컴포넌트입니다. +- `headings` - Markdown 및 MDX 가져오기에 대해 생성된 제목 목록, [Astro의 `getHeadings()` 유틸리티 미러링](/ko/guides/markdown-content/#사용-가능한-속성). +- `remarkPluginFrontmatter ` - [remark 또는 rehype 플러그인이 적용된 후](/ko/guides/markdown-content/#프로그래밍-방식으로-프런트매터-수정하기) 수정된 frontmatter 객체. `any` 타입으로 설정됩니다. + +```astro +--- +import { getEntryBySlug } from 'astro:content'; +const entry = await getEntryBySlug('blog', 'entry-1'); + +const { Content, headings, remarkPluginFrontmatter } = await entry.render(); +--- +``` + +사용 예시는 [`콘텐츠 컬렉션` 가이드를 참조하세요](/ko/guides/content-collections/#콘텐츠를-html로-렌더링). + +### `CollectionKey` + +

+ +`src/content/config.*` 파일에 정의된 모든 컬렉션 이름의 문자열 유니언 타입입니다. 이 타입은 모든 컬렉션 이름을 허용하는 일반 함수를 정의할 때 유용할 수 있습니다. + +```ts +import { type CollectionKey, getCollection } from 'astro:content'; + +async function getCollection(collection: CollectionKey) { + return getCollection(collection); +} +``` + +### `ContentCollectionKey` + +

+ +`src/content/config.*` 파일에 정의된 `type: 'content'` 컬렉션의 모든 이름에 대한 문자열 유니언 타입입니다. + +### `DataCollectionKey` + +

+ +`src/content/config.*` 파일에 정의된 `type: 'data'` 컬렉션의 모든 이름에 대한 문자열 유니언 타입입니다. + +### `SchemaContext` + +`defineCollection`이 `schema`의 함수 모양을 위해 사용하는 `context` 객체입니다. 이 타입은 여러 컬렉션에 대해 재사용 가능한 스키마를 구축할 때 유용할 수 있습니다. + +여기에는 다음 속성이 포함됩니다. + +- `image` - [콘텐츠 컬렉션에서 로컬 이미지를 사용](/ko/guides/images/#콘텐츠-컬렉션의-이미지)할 수 있게 해주는 `image()` 스키마 도우미 + +```ts +import type { SchemaContext } from 'astro:content'; + +export const imageSchema = ({ image }: SchemaContext) => + z.object({ + image: image(), + description: z.string().optional(), + }); + +const blog = defineCollection({ + type: 'content', + schema: ({ image }) => z.object({ + title: z.string(), + permalink: z.string().optional(), + image: imageSchema({ image }) + }), +}); +``` From 533ff335219f9a69500f2934acde1cdffd1c1541 Mon Sep 17 00:00:00 2001 From: Junseong Park Date: Sat, 26 Oct 2024 22:09:53 +0900 Subject: [PATCH 17/21] i18n(ko-KR): update `actions.mdx` (#9803) Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- src/content/docs/ko/guides/actions.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/ko/guides/actions.mdx b/src/content/docs/ko/guides/actions.mdx index 9b7bf14b3fa71..cf5b101fc05a1 100644 --- a/src/content/docs/ko/guides/actions.mdx +++ b/src/content/docs/ko/guides/actions.mdx @@ -16,7 +16,7 @@ Astro 액션을 사용하면 타입 안전성을 갖춘 백엔드 함수를 정 - [Zod 유효성 검사](https://zod.dev/?id=primitives)를 사용하여 JSON 및 양식 데이터 입력의 유효성을 자동으로 검사하세요. - 클라이언트는 물론 [HTML 양식 액션에서도](#html-양식-액션에서-액션-호출) 백엔드를 호출할 수 있는 타입이 안전한 함수를 생성하세요. 수동 `fetch()` 호출이 필요 없습니다. -- [`ActionError`](/ko/reference/api-reference/#actionerror) 객체로 백엔드 오류를 표준화하세요. +- [`ActionError`](/ko/reference/modules/astro-actions/#actionerror) 객체로 백엔드 오류를 표준화하세요. ## 기본 사용법 @@ -129,7 +129,7 @@ async () => { -[`defineAction()`](/ko/reference/api-reference/#defineaction) 및 해당 속성에 대한 자세한 내용은 전체 액션 API 설명서를 참조하세요. +[`defineAction()`](/ko/reference/modules/astro-actions/#defineaction) 및 해당 속성에 대한 자세한 내용은 전체 액션 API 설명서를 참조하세요. ## 액션 조직화 @@ -340,7 +340,7 @@ export const server = { } ``` - 사용 가능한 모든 양식 유효성 검사기는 [`input` API 참조](/ko/reference/api-reference/#input-유효성-검사기)를 확인하세요. + 사용 가능한 모든 양식 유효성 검사기는 [`input` API 참조](/ko/reference/modules/astro-actions/#input-유효성-검사기)를 확인하세요. 3. HTML 양식에 `