From 2d648b9d327785b7b79e8e8b1191eb27dfc85b3a Mon Sep 17 00:00:00 2001
From: Junseong Park <39112954+jsparkdev@users.noreply.github.com>
Date: Fri, 20 Jun 2025 11:00:49 +0900
Subject: [PATCH 1/6] update doc
---
.../ko/reference/configuration-reference.mdx | 62 +++++++++++--------
1 file changed, 37 insertions(+), 25 deletions(-)
diff --git a/src/content/docs/ko/reference/configuration-reference.mdx b/src/content/docs/ko/reference/configuration-reference.mdx
index b95b7c7861134..9808d707a1944 100644
--- a/src/content/docs/ko/reference/configuration-reference.mdx
+++ b/src/content/docs/ko/reference/configuration-reference.mdx
@@ -1151,62 +1151,74 @@ Sharp 이미지 서비스의 기본 이미지 크기 제한을 우회하고 큰
- 모든 하위 경로 ('startsWith')를 허용하려면 '/\*\*' 로 끝납니다.
- 한 수준의 하위 경로만 허용하려면 '/\*' 로 끝납니다.
-### image.experimentalLayout
+### image.responsiveStyles
+
+
+
+**타입:** `boolean`
+
+반응형 이미지에 전역 스타일을 자동으로 추가할지 여부입니다. 이미지를 직접 스타일링하는 경우가 아니라면 이 옵션을 활성화해야 합니다.
+
+이 옵션은 구성 또는 이미지 컴포넌트의 `layout` prop을 사용하여 `layout`이 `constrained`, `full-width`, `fixed`로 설정된 경우에만 사용할 수 있습니다.
+
+자세한 내용은 [이미지 문서](/ko/guides/images/#반응형-이미지-스타일)를 참조하세요.
+
+### image.layout
**타입:** `ImageLayout`
반응형 이미지의 기본 레이아웃 타입입니다. 이미지 컴포넌트의 `layout` 속성으로 재정의할 수 있습니다.
-`experimental.responsiveImages` 플래그를 활성화해야 합니다.
- `constrained` - 이미지가 지정된 크기를 초과하지 않으면서 종횡비를 유지한 채로 컨테이너에 맞게 크기가 조정됩니다.
- `fixed` - 이미지가 원래 크기를 유지합니다.
- `full-width` - 이미지가 종횡비를 유지한 채로 컨테이너에 맞게 크기가 조정됩니다.
-### image.experimentalObjectFit
+자세한 내용은 [`layout` 컴포넌트 속성](/ko/reference/modules/astro-assets/#layout)을 참조하세요.
+
+### image.objectFit
**타입:** `ImageFit`
-반응형 이미지의 기본 object-fit 값입니다. 이미지 컴포넌트의 `fit` 속성으로 재정의할 수 있습니다.
-`experimental.responsiveImages` 플래그를 활성화해야 합니다.
+반응형 이미지의 [`object-fit` CSS 속성 값](https://developer.mozilla.org/ko/docs/Web/CSS/object-fit)입니다. 이미지 컴포넌트의 `fit` prop을 사용하여 재정의할 수 있습니다.
+`layout`의 값을 먼저 설정해야 합니다.
+
+자세한 내용은 [`fit` 컴포넌트 속성](/ko/reference/modules/astro-assets/#fit)을 참조하세요.
-### image.experimentalObjectPosition
+### image.objectPosition
**타입:** `string`
-반응형 이미지의 기본 object-position 값입니다. 이미지 컴포넌트의 `position` 속성으로 재정의할 수 있습니다.
-`experimental.responsiveImages` 플래그를 활성화해야 합니다.
-
-### image.experimentalBreakpoints
+반응형 이미지의 기본 [`object-position` CSS 속성 값](https://developer.mozilla.org/ko/docs/Web/CSS/object-position)입니다. 개별 이미지 컴포넌트의 `position` prop을 사용하여 재정의할 수 있습니다. `layout`의 값을 먼저 설정해야 합니다.
-
+자세한 내용은 [`position` 컴포넌트 속성](/ko/reference/modules/astro-assets/#position)을 참조하세요.
-**타입:** `Array`
-
-반응형 이미지를 생성하는 데 사용되는 중단점입니다. `experimental.responsiveImages` 플래그를 활성화해야 합니다. 전체 목록은 일반적으로 사용되지 않으며, 소스 및 출력 크기에 따라 필터링됩니다. 사용되는 기본값은 로컬 또는 원격 이미지 서비스를 사용하는지에 따라 다릅니다. 원격 서비스의 경우 필요한 크기만 생성되므로 더 포괄적인 목록이 사용됩니다. 로컬 서비스의 경우 생성되는 이미지 수를 줄이기 위해 더 짧은 목록이 사용됩니다.
-
-### image.experimentalDefaultStyles
+### image.breakpoints
-**타입:** `boolean``
-실험적 이미지의 크기가 올바르게 조정되도록 전역 스타일을 자동으로 추가할지 여부입니다. 이 옵션은 기본적으로 활성화되어 있지만, 스타일을 직접 관리하려는 경우 비활성화할 수 있습니다.
-이 옵션은 `experimental.responsiveImages` 플래그가 활성화된 경우에만 사용할 수 있습니다.
+반응형 이미지를 생성하는 데 사용되는 중단점입니다. `layout`의 값을 먼저 설정해야 합니다. 전체 목록은 일반적으로 사용되지 않으며, 소스 및 출력 크기에 따라 필터링됩니다. 사용되는 기본값은 로컬 또는 원격 이미지 서비스를 사용하는지에 따라 다릅니다. 원격 서비스의 경우 필요한 크기만 생성되므로 더 포괄적인 목록이 사용됩니다. 로컬 서비스의 경우 생성되는 이미지 수를 줄이기 위해 더 짧은 목록이 사용됩니다.
## Markdown 옵션
From 4ebd1821e70e31ba52ecec7ce8a520b1b8a6fc59 Mon Sep 17 00:00:00 2001
From: Junseong Park <39112954+jsparkdev@users.noreply.github.com>
Date: Fri, 20 Jun 2025 11:02:46 +0900
Subject: [PATCH 2/6] additional
---
src/content/docs/ko/reference/configuration-reference.mdx | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/src/content/docs/ko/reference/configuration-reference.mdx b/src/content/docs/ko/reference/configuration-reference.mdx
index 9808d707a1944..36563bdf3ec51 100644
--- a/src/content/docs/ko/reference/configuration-reference.mdx
+++ b/src/content/docs/ko/reference/configuration-reference.mdx
@@ -1205,7 +1205,8 @@ Sharp 이미지 서비스의 기본 이미지 크기 제한을 우회하고 큰
+
+**옵션:** ``, SVG 컴포넌트
+
+
+Astro의 템플릿 언어를 사용하면 [``를 포함한 모든 네이티브 HTML 태그는 `.astro` 컴포넌트에서 사용할 수 있습니다. [HTML 태그를 통해 렌더링된 이미지](#HTML의-img-태그를-통한-처리되지-않은-이미지-표시)는 처리되지 않은 상태 (예: 최적화, 변환 등) 그대로 빌드 폴더에 복사됩니다.
-최적화된 이미지를 위해 Astro의 기본 [`[`
+[`
+
+**옵션:** `![]()`, `
+
+`.md` 파일에 표준 Markdown `` 구문을 사용하세요. `src/`에 저장된 로컬 이미지와 원격 이미지는 처리 및 최적화됩니다. [전역 반응형 이미지를 구성](/ko/reference/configuration-reference/#imagelayout)하면 이러한 이미지도 [반응형 이미지](#반응형-이미지-동작)가 됩니다.
+
+`public/` 폴더에 저장된 이미지는 최적화되지 않습니다.
+
+```md
+
+
+# Markdown 페이지
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+HTML `
+
+**옵션:** `
+
+`.mdx` 파일에서 이미지와 Astro의 `[`
+
+## UI 프레임워크 컴포넌트의 이미지
+
+
+
+**이미지 옵션:** 프레임워크 자체 이미지 구문 (예: JSX의 `
+
+`src`와 같은 이미지 속성에 접근하기 위해 [로컬 이미지를 먼저 가져와야 합니다.](#display-unprocessed-images-with-the-html-img-tag) 그러면 프레임워크의 자체 이미지 구문을 사용하여 이미지를 렌더링할 수 있습니다.
+
+```jsx title="src/components/ReactImage.jsx"
+import stars from "../assets/stars.png";
+
+export default function ReactImage() {
+ return (
+
+
+```
+
+## Astro 컴포넌트의 이미지
-기본으로 제공되는 `
-다양한 형식 및 크기로 반응형 이미지를 표시하려면 내장된 `` 태그를 생성할 수 있습니다. 이를 통해 표시할 기본 파일 형식을 지정하면서, 대체 형식을 제공할 수 있습니다. [`
```
[`
-### HTML `
-#### `public/`의 이미지
+반응형 이미지는 다양한 기기에서 성능을 개선하기 위해 조정되는 이미지입니다. 이러한 이미지는 컨테이너에 맞게 크기가 조정될 수 있으며 방문자의 화면 크기와 해상도에 따라 다양한 크기로 제공될 수 있습니다.
-`public/`에 있는 이미지의 경우 `src` 값으로 이미지의 public 폴더에 상대적인 파일 경로를 사용합니다.
+`[MDN 웹 문서에서 반응형 이미지](https://developer.mozilla.org/ko/docs/Web/HTML/Guides/Responsive_images)에 대해 자세히 알아보세요.
-현재 모든 `
Astro를 사용하면 SVG 파일을 가져와서 Astro 컴포넌트처럼 사용할 수 있습니다. Astro는 SVG의 콘텐츠를 HTML 출력에 인라인으로 삽입합니다.
@@ -296,7 +420,7 @@ import Logo from './path/to/svg/file.svg';
`` 요소](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg)에서 허용하는 다른 모든 속성을 전달할 수 있습니다. 이러한 속성은 자동으로 내부 `` 요소에 적용됩니다. 원본 `.svg` 파일에 속성이 있지만, 속성이 컴포넌트에 전달되면, 컴포넌트에 전달된 값이 원본 값을 덮어씁니다.
@@ -309,76 +433,119 @@ import Logo from '../assets/logo.svg';
[`
+```astro title="src/components/BlogPostImage.astro"
+---
+import { Image } from 'astro:assets';
-## Markdown 파일의 이미지
+const { src, ...attrs } = Astro.props;
+---
+[`
+## 원격 이미지 승인
+
+이미지 최적화를 위해 [`image.domains`](/ko/reference/configuration-reference/#imagedomains) 및 [`image.remotePatterns`](/ko/reference/configuration-reference/#imageremotepatterns)를 사용하여 승인된 이미지 소스 URL 도메인 및 패턴 목록을 구성할 수 있습니다. 이 구성은 외부 소스의 이미지를 표시할 때 사이트를 보호하기 위한 추가 안전 계층입니다.
+
+다른 소스의 원격 이미지는 최적화되지 않지만 이러한 이미지에 `
-
-```
-
-또한 프레임워크의 자체 이미지 구문을 사용하여 이미지를 렌더링할 수 있습니다 (예: JSX의 `` 및 `` 컴포넌트가 지원하지 않는 옵션이 필요한 경우, `getImage()` 함수를 사용하여 사용자 정의 `
+
+**타입:** `string | undefined`
+
+각 미디어 조건 목록에 대한 이미지의 레이아웃 너비를 지정합니다. `widths`를 지정할 때 반드시 제공해야 합니다.
+
+`layout` 속성을 사용하는 반응형 이미지는 `widths` 및 `sizes` 속성을 자동으로 생성합니다. 일반적으로 이러한 값을 제공할 필요는 없지만 자동으로 생성된 값을 재정의하는 데 사용할 수 있습니다.
+
+`constrained` 및 `full-width` 이미지에 대해 생성된 `sizes` 속성은 뷰포트가 이미지 너비보다 작은 경우 이미지가 화면 전체 너비에 가깝게 표시된다는 가정을 기반으로 합니다. 크게 다른 경우 (예: 작은 화면의 다중 열 레이아웃)에는 최상의 결과를 위해 `sizes` 속성을 수동으로 조정해야 할 수 있습니다.
+
##### format
@@ -248,6 +272,7 @@ import myImage from '../assets/my_image.png'; // 1600x900의 이미지
**타입:** `boolean`
@@ -257,7 +282,7 @@ import myImage from '../assets/my_image.png'; // 1600x900의 이미지
`
+
+**타입:** `boolean`
+
+웹 페이지에 접속 시, 스크롤하지 않아도 화면에 바로 나타나는 이미지에 대해 `loading`, `decoding`, `fetchpriority` 속성을 최적화된 값으로 자동 설정합니다.
+
+```astro title="src/components/MyComponent.astro" "priority"
+---
+import { Image } from 'astro:assets';
+import myImage from '../assets/my_image.png';
+---
+
-다양한 형식 및/또는 크기로 반응형 이미지를 표시하려면 Astro의 `
```
+### 반응형 이미지 속성
+
+[`
+
+**타입:** `'constrained' | 'full-width' | 'fixed' | 'none'`
+
+[반응형 이미지](#반응형-이미지-속성)를 정의하고 컨테이너 크기가 변경될 때 이미지의 크기를 조정하는 방법을 결정합니다. [`image.layout`](/ko/reference/configuration-reference/#imagelayout)의 기본값을 재정의하는 데 사용할 수 있습니다.
+
+- `constrained` - 이미지가 컨테이너에 맞게 축소되어 가로 세로 비율을 유지하지만 지정된 `width`와 `height` 또는 이미지의 원래 크기를 초과하여 확대되지는 않습니다.
+
+ 이미지를 가능한 한 요청된 크기로 표시하되 작은 화면에 맞게 축소하려면 이 옵션을 사용합니다. 이는 Tailwind를 사용할 때 이미지의 기본 동작과 일치합니다. 잘 모르겠다면 이 레이아웃을 선택하는 것이 좋습니다.
+
+- `full-width` - 이미지가 가로 세로 비율을 유지하면서 컨테이너 너비에 맞게 크기가 조정됩니다.
+
+ 히어로 이미지 또는 페이지의 전체 너비를 차지해야 하는 이미지에 이 옵션을 사용합니다.
+
+- `fixed` - 이미지 크기가 조정되지 않고 요청된 크기를 유지합니다. 고밀도 디스플레이를 지원하기 위해 `srcset`을 생성하지만 다른 화면 크기에는 적용되지 않습니다.
+
+ 화면 너비보다 작은 아이콘이나 로고, 고정 너비 컨테이너의 이미지 등 이미지 크기가 조정되지 않는 경우에 이 옵션을 사용합니다.
+
+- `none` - 이미지가 반응형으로 작동하지 않습니다. `srcset` 또는 `sizes`가 자동으로 생성되지 않으며 스타일이 적용되지 않습니다.
+
+ 기본 레이아웃을 사용하도록 설정했지만 특정 이미지에 대해 사용하지 않으려는 경우에 유용합니다.
+
+예를 들어, 기본 레이아웃으로 `constrained`를 설정하면 개별 이미지의 `layout` 속성을 재정의할 수 있습니다:
+
+```astro title="src/components/MyComponent.astro"
+---
+import { Image } from 'astro:assets';
+import myImage from '../assets/my_image.png';
+---
+
+
+**타입:** `'contain' | 'cover' | 'fill' | 'none' | 'scale-down'`
+
+[`layout`](#layout) 속성이 설정되거나 구성된 경우 활성화됩니다. 가로 세로 비율이 변경된 경우 반응형 이미지를 자르는 방법을 정의합니다.
+
+값은 CSS `object-fit`의 값과 일치합니다. 기본값은 `cover`이지만, [`image.objectFit`](/ko/reference/configuration-reference/#imageobjectfit)이 설정된 경우 이 속성의 값이 기본값입니다. 기본 `object-fit` 스타일을 재정의하는 데 사용할 수 있습니다.
+
+##### position
+
+
+
+**타입:** `string`
+
+[`layout`](#layout) 속성이 설정 또는 구성된 경우 활성화됩니다. 가로 세로 비율이 변경된 경우 반응형 이미지를 자르는 위치를 정의합니다.
+
+값은 CSS `object-position`의 값과 일치합니다. 기본값은 `center`이지만, [`image.objectPosition`](/ko/reference/configuration-reference/#imageobjectposition)이 설정된 경우 이 속성의 값이 기본값입니다. 기본 `object-position` 스타일을 재정의하는 데 사용할 수 있습니다.
+
+##### priority
+
+
+
+**타입:** `boolean`
+
+Enabled when the [`layout`](#layout) property is set or configured. If set, eagerly loads a responsive image. Otherwise, images will be lazy-loaded. Use this for your largest above-the-fold image. Defaults to `false`.
+
+[`layout`](#layout) 속성이 설정되거나 구성되면 활성화됩니다. 설정된 경우 반응형 이미지를 적극적으로 로드합니다. 설정하지 않으면 이미지가 지연 로드됩니다. 웹 페이지에 접속 시, 스크롤하지 않아도 화면에 바로 나타나는 큰 이미지에 이 옵션을 사용하세요. 기본값은 `false`입니다.
+
### `getImage()`
From 22b7e0ae8e410ab23538ae56072b370cd79eacff Mon Sep 17 00:00:00 2001
From: Junseong Park <39112954+jsparkdev@users.noreply.github.com>
Date: Fri, 20 Jun 2025 16:16:24 +0900
Subject: [PATCH 5/6] update broken links
---
src/content/docs/ko/guides/images.mdx | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/src/content/docs/ko/guides/images.mdx b/src/content/docs/ko/guides/images.mdx
index 9777eaf3bb824..e6c455dfa3fca 100644
--- a/src/content/docs/ko/guides/images.mdx
+++ b/src/content/docs/ko/guides/images.mdx
@@ -46,7 +46,7 @@ Astro의 템플릿 언어를 사용하면 [``를 포함한 모든 네이티브 HTML 태그는 `.astro` 컴포넌트에서 사용할 수 있습니다. [HTML 태그를 통해 렌더링된 이미지](#HTML의-img-태그를-통한-처리되지-않은-이미지-표시)는 처리되지 않은 상태 (예: 최적화, 변환 등) 그대로 빌드 폴더에 복사됩니다.
+``를 포함한 모든 네이티브 HTML 태그는 `.astro` 컴포넌트에서 사용할 수 있습니다. [HTML 태그를 통해 렌더링된 이미지](#html의-img-태그를-사용하여-처리되지-않은-이미지-표시)는 처리되지 않은 상태 (예: 최적화, 변환 등) 그대로 빌드 폴더에 복사됩니다.
`.astro` 파일의 모든 **이미지의 `src` 속성의 값은 이미지 파일의 위치에 의해 결정됩니다**.
@@ -116,7 +116,7 @@ HTML `
-`.mdx` 파일에서 이미지와 Astro의 `