Skip to content

i18n(ko-KR): update api-reference.mdx #14266

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dreyfus92 merged 2 commits into from
Jul 22, 2026
Merged

i18n(ko-KR): update api-reference.mdx #14266

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ea1744a
Update api-reference.mdx
jsparkdev Jul 17, 2026
1e535c6
Merge branch 'main' into api-ref-260717
dreyfus92 Jul 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
207 changes: 159 additions & 48 deletions src/content/docs/ko/reference/api-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -332,9 +332,14 @@ const socialImageURL = new URL('/images/preview.png', Astro.url);

```astro "Astro.response"
---
if (condition) {
import { getPost } from "../api";

const post = await getPost(Astro.params.id);

// 이 ID로 게시물을 찾을 수 없는 경우
if (!post) {
Astro.response.status = 404;
Astro.response.statusText = '찾을 수 없음';
Astro.response.statusText = "찾을 수 없음";
}
---
```
Expand Down Expand Up @@ -384,14 +389,15 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
</TabItem>
<TabItem label="context.redirect()">
```ts "redirect"
import type { APIContext } from 'astro';

import type { APIContext } from "astro";
import { isLoggedIn } from "../utils";

export function GET({ redirect, request }: APIContext) {
const cookie = request.headers.get('cookie');
const cookie = request.headers.get("cookie");
if (!isLoggedIn(cookie)) {
return redirect('/login', 302);
return redirect("/login", 302);
} else {
// 사용자의 정보를 반환합니다.
// 사용자 정보를 반환합니다.
}
}
```
Expand Down Expand Up @@ -443,10 +449,10 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
</TabItem>
<TabItem label="context.rewrite()">
```ts
import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
return rewrite(new URL("../", Astro.url));
import type { APIContext } from "astro";
export function GET({ rewrite, url }: APIContext) {
return rewrite(new URL("../", url));
}
```
</TabItem>
Expand All @@ -468,14 +474,16 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
</TabItem>
<TabItem label="context.rewrite()">
```ts
import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
return rewrite(new Request(new URL("../", Astro.url), {
headers: {
"x-custom-header": JSON.stringify(Astro.locals.someValue)
}
}));
import type { APIContext } from "astro";

export function GET({ locals, rewrite, url }: APIContext) {
return rewrite(
new Request(new URL("../", url), {
headers: {
"x-custom-header": JSON.stringify(locals.someValue),
},
}),
);
}
```
</TabItem>
Expand All @@ -500,7 +508,8 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
</TabItem>
<TabItem label="context.originPathname">
```ts title="src/middleware.ts"
import { defineMiddleware } from 'astro:middleware';
import { defineMiddleware } from "astro:middleware";
import { recordPageVisit } from "./utils/analytics";

export const onRequest = defineMiddleware(async (context, next) => {
// URL을 다시 작성하기 전에 원래 경로 이름을 기록합니다.
Expand Down Expand Up @@ -555,6 +564,8 @@ Astro 컴포넌트와 API 엔드포인트는 렌더링할 때 `locals`에서 값
</TabItem>
</Tabs>

<ReadMore>Astro 미들웨어를 사용해 [타입 안전성](/ko/guides/middleware/#미들웨어-타입)을 유지하면서 [`locals`에 데이터를 저장하는 방법](/ko/guides/middleware/#contextlocals에-데이터-저장)에 대해 자세히 알아보세요.</ReadMore>

### `preferredLocale`

<p>
Expand Down Expand Up @@ -908,10 +919,10 @@ Astro 프로젝트에서 세션을 사용하는 방법에 대한 더 자세한
</TabItem>
<TabItem label="context.session">
```ts title="src/pages/api/cart.ts" "session.get('cart')"
import type { APIContext } from 'astro';
import type { APIContext } from "astro";

export async function GET({ session }: APIContext) {
const cart = await session.get('cart');
const cart = await session?.get("cart");
return Response.json({ cart });
}
```
Expand Down Expand Up @@ -940,14 +951,14 @@ Astro 프로젝트에서 세션을 사용하는 방법에 대한 더 자세한
</TabItem>
<TabItem label="context.session">
```ts title="src/pages/api/add-to-cart.ts" "session.set('cart', cart)"
import type { APIContext } from 'astro';

import type { APIContext } from "astro";
export async function POST({ session, request }: APIContext) {
const cart = await session.get('cart');
const cart = (await session?.get("cart")) ?? [];
const newItem = await request.json();
cart.push(newItem);
// 업데이트된 장바구니를 세션에 저장합니다.
session.set('cart', cart);
// 업데이트된 장바구니를 세션에 저장
session?.set("cart", cart);
return Response.json({ cart });
}
```
Expand Down Expand Up @@ -975,13 +986,14 @@ Astro 프로젝트에서 세션을 사용하는 방법에 대한 더 자세한
</TabItem>
<TabItem label="context.session">
```ts title="src/pages/api/login.ts" "session.regenerate()"
import type { APIContext } from 'astro';
import type { APIContext } from "astro";
import { doLogin } from "../../lib/auth";

export async function POST({ session }: APIContext) {
// 사용자를 인증합니다...
// 사용자 인증...
doLogin();
// 세션 고정 공격을 방지하기 위해 세션 ID를 갱신합니다.
session.regenerate();
session?.regenerate();
return Response.json({ success: true });
}
```
Expand Down Expand Up @@ -1010,10 +1022,10 @@ Astro 프로젝트에서 세션을 사용하는 방법에 대한 더 자세한
</TabItem>
<TabItem label="context.session">
```ts title="src/pages/api/logout.ts" "session.destroy()"
import type { APIContext } from 'astro';
import type { APIContext } from "astro";

export async function POST({ session }: APIContext) {
session.destroy();
session?.destroy();
return Response.json({ success: true });
}
```
Expand All @@ -1035,27 +1047,26 @@ ID를 사용하여 세션을 로드합니다. 일반적인 사용 환경에서
```astro title="src/pages/cart.astro" "Astro.session?.load('session-id')"
---
// 헤더에서 쿠키 대신 세션을 로드합니다.
const sessionId = Astro.request.headers.get('x-session-id');
await Astro.session?.load(sessionId);
const cart = await Astro.session?.get('cart');
const sessionId = Astro.request.headers.get("x-session-id");
await Astro.session?.load(sessionId ?? "fallback-session-id");
const cart = await Astro.session?.get("cart");
---

<h1>장바구니</h1>
<ul>
{cart?.map((item) => (
<li>{item.name}</li>
))}
{cart?.map((item: any) => <li>{item.name}</li>)}
</ul>
```
</TabItem>
<TabItem label="context.session">
```ts title="src/pages/api/load-session.ts" "session.load('session-id')"
import type { APIRoute } from 'astro';
import type { APIRoute } from "astro";

export const GET: APIRoute = async ({ session, request }) => {
// 헤더에서 쿠키 대신 세션을 로드합니다.
const sessionId = request.headers.get('x-session-id');
await session.load(sessionId);
const cart = await session.get('cart');
// 쿠키 대신 헤더에서 세션을 로드합니다.
const sessionId = request.headers.get("x-session-id");
await session?.load(sessionId ?? "fallback-session-id");
const cart = await session?.get("cart");
return Response.json({ cart });
};
```
Expand All @@ -1078,6 +1089,14 @@ Astro의 CSP 런타임 API는 문서가 로드할 수 있는 리소스를 제어

리소스가 여러 번 삽입되거나 여러 소스(예: [`csp` 구성](/ko/reference/configuration-reference/#securitycsp)에 정의된 것과 다음 CSP 런타임 API를 사용하여 추가된 것)에서 제공되는 경우, Astro는 모든 리소스를 병합하고 중복을 제거하여 `<meta>` 요소를 생성합니다.

:::caution[더 구체적인 지시어에 적용하기]
`kind` 옵션(`'element'` 또는 `'attribute'`)을 사용해 소스나 해시를 더 구체적인 지시어에 적용하면, 브라우저는 해당 범위에서는 일반 `script-src` 또는 `style-src` 대신 해당 구체적인 지시어를 사용하며, 일반 지시어로 대체하지 않습니다.

Astro는 인라인 스크립트와 스타일을 위해 생성한 해시를 더 구체적인 지시어로 자동으로 이동하여 계속 정상적으로 동작하도록 합니다. 하지만 일반(`'default'`) 리소스는 이동하지 **않습니다**. 동일한 지시어 계열에서 일반 리소스와 더 구체적인 리소스 또는 해시를 함께 사용하면, 일반 리소스는 구체적인 범위에 적용되지 않습니다. Astro는 이러한 상황을 감지하면 경고를 출력합니다.

이 문제를 해결하려면 모든 리소스와 해시를 구체적인 지시어로 이동하세요.
:::


#### `csp.insertDirective()`

Expand Down Expand Up @@ -1114,7 +1133,7 @@ content="

<p>

**타입:** `(resource: string) => void`<br />
**타입:** `(resource: string | { resource: string; kind: 'element' | 'attribute' | 'default' }) => void`<br />
<Since v="6.0.0" />
</p>

Expand All @@ -1138,11 +1157,34 @@ content="
>
```

<p><Since v="7.1.0" /></p>

또한 `kind` 속성이 있는 객체를 전달하여 리소스를 더 구체적인 지시어에 적용할 수 있습니다. `style-src-elem`에는 `'element'`를, `style-src-attr`에는 `'attribute'`를, `style-src`에는 `'default'`를 사용하세요. (`'default'`는 일반 문자열을 전달하는 것과 동일합니다.)

```astro title="src/pages/index.astro"
---
Astro.csp?.insertStyleResource({ resource: "'unsafe-inline'", kind: "attribute" });
---
```

빌드가 완료되면 이 페이지의 `<meta>` 요소는 해당 리소스를 `style-src-attr` 지시어에 추가합니다. 이 지시어는 인라인 `style` 속성에만 적용됩니다.

```html
<meta
http-equiv="content-security-policy"
content="
script-src 'self';
style-src 'self';
style-src-attr 'unsafe-inline';
"
>
```

#### `csp.insertStyleHash()`

<p>

**타입:** `(hash: CspHash) => void`<br />
**타입:** `(hash: CspHash | { hash: CspHash; kind: 'element' | 'attribute' | 'default' }) => void`<br />
<Since v="6.0.0" />
</p>

Expand All @@ -1166,11 +1208,34 @@ content="
>
```

<p><Since v="7.1.0" /></p>

또한 `kind` 속성이 있는 객체를 전달하여 해시를 더 구체적인 지시어에 적용할 수 있습니다. `style-src-elem`에는 `'element'`를, `style-src-attr`에는 `'attribute'`를, `style-src`에는 `'default'`를 사용하세요. (`'default'`는 일반 해시를 전달하는 것과 동일합니다.)

```astro title="src/pages/index.astro"
---
Astro.csp?.insertStyleHash({ hash: "sha512-styleHash", kind: "element" });
---
```

빌드가 완료되면 이 페이지의 `<meta>` 요소는 해당 해시를 `style-src-elem` 지시어에 추가합니다. `style-src-elem`은 `<style>` 및 `<link>` 요소에 대해 `style-src`보다 우선 적용되므로, Astro가 자동으로 생성한 스타일 해시도 이 지시어로 이동합니다.

```html
<meta
http-equiv="content-security-policy"
content="
script-src 'self' 'sha256-somehash';
style-src 'self';
style-src-elem 'self' 'sha256-somehash' 'sha512-styleHash';
"
>
```

#### `csp.insertScriptResource()`

<p>

**타입:** `(resource: string) => void`<br />
**타입:** `(resource: string | { resource: string; kind: 'element' | 'attribute' | 'default' }) => void`<br />
<Since v="6.0.0" />
</p>

Expand All @@ -1194,11 +1259,34 @@ content="
>
```

<p><Since v="7.1.0" /></p>

또한 `kind` 속성이 있는 객체를 전달하여 소스를 더 구체적인 지시어에 적용할 수 있습니다. `script-src-elem`에는 `'element'`를, `script-src-attr`에는 `'attribute'`를, `script-src`에는 `'default'`를 사용하세요. (`'default'`는 일반 문자열을 전달하는 것과 동일합니다.)

```astro title="src/pages/index.astro"
---
Astro.csp?.insertScriptResource({ resource: "https://scripts.cdn.example.com", kind: "element" });
---
```

빌드가 완료되면 이 페이지의 `<meta>` 요소는 해당 소스를 `script-src-elem` 지시어에 추가합니다. 이 지시어는 `<script>` 요소에 적용됩니다.

```html
<meta
http-equiv="content-security-policy"
content="
script-src 'self';
script-src-elem https://scripts.cdn.example.com;
style-src 'self';
"
>
```

#### `csp.insertScriptHash()`

<p>

**타입:** `(hash: CspHash) => void`<br />
**타입:** `(hash: CspHash | { hash: CspHash; kind: 'element' | 'attribute' | 'default' }) => void`<br />
<Since v="6.0.0" />
</p>

Expand All @@ -1216,7 +1304,30 @@ Astro.csp?.insertScriptHash("sha512-scriptHash");
<meta
http-equiv="content-security-policy"
content="
script-src 'self' 'sha256-somehash' 'sha512-styleHash';
script-src 'self' 'sha256-somehash' 'sha512-scriptHash';
style-src 'self' 'sha256-somehash';
"
>
```

<p><Since v="7.1.0" /></p>

또한 `kind` 속성이 있는 객체를 전달하여 해시를 더 구체적인 지시어에 적용할 수 있습니다. `script-src-elem`에는 `'element'`를, `script-src-attr`에는 `'attribute'`를, `script-src`에는 `'default'`를 사용하세요. (`'default'`는 일반 해시를 전달하는 것과 동일합니다.)

```astro title="src/pages/index.astro"
---
Astro.csp?.insertScriptHash({ hash: "sha512-scriptHash", kind: "element" });
---
```

빌드가 완료되면 이 페이지의 `<meta>` 요소는 해당 해시를 `script-src-elem` 지시어에 추가합니다. `script-src-elem`은 `<script>` 요소에 대해 `script-src`보다 우선 적용되므로, Astro가 자동으로 생성한 스크립트 해시도 이 지시어로 이동합니다.

```html
<meta
http-equiv="content-security-policy"
content="
script-src 'self';
script-src-elem 'self' 'sha256-somehash' 'sha512-scriptHash';
style-src 'self' 'sha256-somehash';
"
>
Expand Down
Loading