---
createdAt: 2025-09-22
updatedAt: 2025-09-23
title: 새로운 Intlayer v7 - 무엇이 새로워졌나요?
description: Intlayer v7의 새로운 기능을 확인하세요. 성능, 개발자 경험, 그리고 국제화 워크플로우를 향상시키는 주요 기능 개선 사항을 소개합니다.
keywords:
  - Intlayer
  - 현지화
  - 개발
  - 성능
  - 개발자 경험
  - 기능
  - React
  - Next.js
  - JavaScript
  - TypeScript
slugs:
  - doc
  - releases
  - v7
---

# 새로운 Intlayer v7 - 무엇이 새로워졌나요?

Intlayer v7에 오신 것을 환영합니다! 이번 주요 릴리스에서는 성능, 타입 안정성, 그리고 개발자 경험에서 큰 개선이 이루어졌습니다. 아래는 주요 내용과 마이그레이션 노트, 실용적인 예제들입니다.

## 주요 내용

- 더 빠른 빌드를 위한 캐싱 전략
- 로케일별 타입을 지원하는 향상된 TypeScript 타입 생성
- 번들 최적화: enum 대신 문자열로 로케일 처리
- 새로운 라우팅 모드: `prefix-no-default`, `prefix-all`, `no-prefix`, `search-params`
- GDPR 준수 로케일 저장소, 기본값은 localStorage
- 유연한 저장소 구성: 쿠키, localStorage, sessionStorage 또는 복수 사용 가능
- Visual Editor 패키지 크기 30% 감소
- 향상된 미들웨어 구성 옵션
- 더 나은 콘텐츠 관리를 위한 fill 명령어 동작 업데이트
- 완전한 콘텐츠 선언 파일 업데이트로 안정성 강화
- 번역 정확도를 위한 지능형 재시도 관리
- 더 빠른 번역 처리를 위한 병렬화
- AI 컨텍스트 제한 내에서 대용량 파일 처리를 위한 스마트 청킹

---

## 성능: 더 빠른 빌드를 위한 캐싱

esbuild로 매 빌드마다 콘텐츠 선언을 다시 빌드하는 대신, v7에서는 빌드 프로세스를 가속화하는 캐싱 전략을 구현했습니다.

```bash
npx intlayer build
```

새로운 캐싱 시스템:

- 중복 처리를 피하기 위해 컴파일된 콘텐츠 선언을 저장합니다.
- 변경 사항을 감지하고 수정된 파일만 다시 빌드합니다.
- 대규모 프로젝트의 빌드 시간을 크게 단축합니다.

---

## TypeScript: 로케일별 타입 생성

TypeScript 타입이 이제 로케일별로 생성되어 더 강력한 타입 검사를 제공하며 모든 로케일에 걸친 유니언 타입을 제거합니다.

**v6 동작:**

```tsx
const content = getIntlayer("my-title-content", "en");
// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
```

**v7 동작:**

```tsx
const content = getIntlayer("my-title-content", "en");
// typeof content = { title: "My title" }
```

장점:

- IDE에서 더 정확한 자동 완성 제공
- 교차 로케일 타입 오염 없이 더 나은 타입 안전성
- 타입 복잡성 감소로 성능 향상

---

## 번들 최적화: 문자열로서의 로케일

`Locales` 타입이 더 이상 enum이 아니므로, 완전히 트리 쉐이커블(tree-shakeable)하며 수천 개의 사용하지 않는 로케일 레코드로 번들이 부풀려지지 않습니다.

**v6:**

```typescript
import { Locales } from "intlayer";
// 모든 로케일을 포함하는 enum -> 트리 쉐이커블하지 않음

const locale: Locales = Locales.ENGLISH;
```

**v7:**

```typescript
import { Locales, Locale } from "intlayer";
// 문자열 타입 -> 완전히 트리 쉐이커블

const locale: Locale = Locales.ENGLISH;
```

> `Locales`가 더 이상 enum이 아니기 때문에, 타입으로서 로케일을 얻으려면 타입을 `Locales`에서 `Locale`로 변경해야 합니다.

자세한 내용은 [구현 세부사항](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)을 참조하세요.

---

## 더 큰 유연성을 위한 새로운 라우팅 모드

v7에서는 이전의 `prefixDefault`와 `noPrefix` 옵션을 대체하는 통합된 `routing.mode` 구성을 도입하여 URL 구조에 대해 더 세밀한 제어가 가능합니다.

### 사용 가능한 라우팅 모드

- **`prefix-no-default`** (기본값): 기본 로케일에는 접두사가 없고, 다른 로케일에는 접두사가 있음
  - `/dashboard` (en) 또는 `/fr/dashboard` (fr)
- **`prefix-all`**: 모든 로케일에 접두사가 있음
  - `/en/dashboard` (en) 또는 `/fr/dashboard` (fr)
- **`no-prefix`**: URL에 로케일 접두사가 없음 (로케일은 저장소/헤더를 통해 처리)
  - 모든 로케일에 대해 `/dashboard`
- **`search-params`**: 쿼리 매개변수로 로케일 전달
  - `/dashboard?locale=en` 또는 `/dashboard?locale=fr`

### 기본 구성

```typescript
// intlayer.config.ts
export default {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default", // 기본값
  },
};
```

---

## GDPR 준수: localStorage / 쿠키 저장

v7은 쿠키 대신 `localStorage`를 기본 저장 메커니즘으로 사용하여 사용자 개인정보 보호를 우선시합니다. 이 변경은 로케일 선호도에 대한 쿠키 동의 요구를 피함으로써 GDPR 준수를 돕습니다.

### 저장 구성 옵션

새로운 `routing.storage` 필드는 이전의 `middleware.cookieName` 및 `middleware.serverSetCookie` 옵션과 함께 사용할 수 있으며, 유연한 저장소 구성을 제공합니다:

```typescript
// 저장소 비활성화
storage: false

// 간단한 저장소 유형
storage: 'cookie'
storage: 'localStorage'
storage: 'sessionStorage'

// 사용자 정의 속성을 가진 쿠키
storage: {
  type: 'cookie',
  name: 'custom-locale',
  domain: '.example.com',
  secure: true,
  sameSite: 'strict'
}

// 사용자 정의 키를 가진 localStorage
storage: {
  type: 'localStorage',
  name: 'custom-locale'
}

// 중복성을 위한 다중 저장소 유형
storage: ['cookie', 'localStorage']
```

### GDPR 준수 구성 예시

기능성과 GDPR 준수를 균형 있게 맞춰야 하는 프로덕션 애플리케이션의 경우:

```typescript
typescript;
// intlayer.config.ts
export default {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: [
      {
        type: "localStorage", // 기본 저장소 (동의 불필요)
        name: "user-locale",
      },
      {
        type: "cookie", // 선택적 쿠키 저장소 (동의 필요)
        name: "user-locale",
        secure: true,
        sameSite: "strict",
        httpOnly: false,
      },
    ],
  },
};
```

### 쿠키 저장소 활성화 / 비활성화

React / Next.js 사용 예시:

전역으로 정의 가능:

```typescript
<IntlayerProvider isCookieEnabled={false}>
  <App />
</IntlayerProvider>
```

각 훅별로 로컬에서 재정의 가능:

```ts
const { setLocale } = useLocale({ isCookieEnabled: false });

setLocale("en");
```

**참고:** 쿠키는 기본적으로 활성화되어 있습니다.
**참고:** 특정 사용 사례에 대한 [GDPR 쿠키 요구 사항](https://gdpr.eu/cookies/)을 확인하세요.

---

## 비주얼 에디터: 30% 더 작아진 패키지

비주얼 에디터 패키지는 다음 덕분에 이전 버전보다 30% 더 작아지도록 최적화되었습니다:

- 코드 에디터 성능 향상
- Intlayer 핵심 패키지에 대한 불필요한 의존성 제거
- 향상된 트리 쉐이킹 및 모듈 번들링

이로 인해 애플리케이션의 다운로드 시간이 빨라지고 런타임 성능이 향상됩니다.

---

## fill 명령어: 더 나은 콘텐츠 관리를 위한 동작 업데이트

v7에서는 `fill` 명령어의 동작이 개선되어 더 예측 가능하고 유연한 콘텐츠 관리를 제공합니다:

### 새로운 fill 동작

- **`fill: true`** - 모든 로케일에 대해 채워진 콘텐츠로 현재 파일을 다시 작성합니다.
- **`fill: "path/to/file"`** - 현재 파일을 수정하지 않고 지정된 파일을 채웁니다.
- **`fill: false`** - 자동 채우기를 완전히 비활성화합니다.

### 복잡한 콘텐츠 구조에 대한 향상된 지원

fill 명령은 이제 다음을 포함한 복잡한 콘텐츠 선언 구조를 지원합니다:

- **구성된 객체**: 다른 객체를 참조하는 콘텐츠 선언
- **구조 분해된 콘텐츠**: 구조 분해 패턴을 사용하는 콘텐츠
- **중첩 참조**: 복잡한 계층 구조에서 서로 호출하는 객체들
- **동적 콘텐츠 구조**: 조건부 또는 계산된 속성을 가진 콘텐츠

### 이점

- **명확한 의도**: 수정되는 내용에 대해 더 명확해졌습니다.
- **더 나은 분리**: 콘텐츠 파일을 채워진 번역과 별도로 유지할 수 있습니다.
- **향상된 워크플로우**: 개발자가 번역이 저장되는 위치를 더 잘 제어할 수 있습니다.
- **복잡한 구조 지원**: 여러 상호 연결된 객체가 있는 정교한 콘텐츠 아키텍처를 처리할 수 있습니다.

### 사용 예시

```typescript
// 모든 로케일로 현재 파일을 다시 작성
const content = {
  key: "example",
  fill: true, // 이 파일을 다시 작성합니다
  content: {
    title: "Hello World",
  },
};

// 현재 파일을 수정하지 않고 별도의 파일을 채움
const content = {
  key: "example",
  fill: "./translations.json", // translations.json을 생성/업데이트합니다
  content: {
    title: "Hello World",
  },
};

// 자동 채우기 비활성화
const content = {
  key: "example",
  fill: false, // 자동 채우기 없음
  content: {
    title: "Hello World",
  },
};

// 복합 객체로 구성된 복잡한 콘텐츠 구조
const sharedContent = {
  buttons: {
    save: "저장",
    cancel: "취소",
  },
};

const content = {
  key: "complex-example",
  fill: true,
  content: {
    // 다른 객체에 대한 참조
    sharedContent,

    // 구조 분해된 콘텐츠
    ...sharedContent,

    // 중첩된 참조
    sections: [
      {
        ...sharedContent.buttons,
        header: "섹션 1",
      },
    ],
  },
};
```

---

## 향상된 안정성과 번역 관리

v7은 콘텐츠 번역을 보다 신뢰성 있고 효율적으로 만들기 위해 여러 개선 사항을 도입했습니다:

### 완전한 콘텐츠 선언 파일 업데이트

시스템은 이제 부분 업데이트 대신 `.content.{ts,js,cjs,mjs}` 파일 전체를 업데이트하여 다음을 보장합니다:

- **데이터 무결성**: 전체 파일을 다시 작성하여 부분 업데이트로 인한 콘텐츠 손상을 방지합니다.
- **일관성**: 모든 로케일이 원자적으로 업데이트되어 동기화를 유지합니다.
- **신뢰성**: 불완전하거나 잘못된 콘텐츠 파일의 위험을 줄입니다.

### 지능형 재시도 관리

새로운 재시도 메커니즘은 잘못된 형식의 콘텐츠 푸시를 방지하고, 하나의 요청 실패 시 전체 채우기 프로세스가 중단되는 것을 방지합니다.

### 빠른 처리를 위한 병렬화

번역 작업이 이제 큐에서 병렬로 실행되어 처리 속도를 크게 향상시킵니다.

### 대용량 파일을 위한 스마트 청킹

고급 청킹 전략은 AI 컨텍스트 창을 초과하지 않으면서 대용량 콘텐츠 파일을 처리합니다:

### 예시 워크플로우

```typescript
// 대용량 콘텐츠 파일이 자동으로 청킹됩니다
const content = {
  key: "large-documentation",
  fill: true,
  content: {
    // AI 처리를 위해 자동으로 청크 분할된 대용량 콘텐츠
    introduction: "..." // 5000자 이상
    sections: [
      // 여러 개의 대용량 섹션
    ]
  }
};
```

시스템은 자동으로:

1. 콘텐츠 크기와 구조를 분석합니다.
2. 콘텐츠를 적절하게 청크로 분할합니다.
3. 청크들을 병렬로 처리합니다.
4. 필요 시 검증하고 재시도합니다.
5. 완전한 파일을 재구성합니다.

---

## v6에서의 마이그레이션 노트

### 제거된 설정

- **`middleware.cookieName`**: `routing.storage`로 대체됨
- **`middleware.serverSetCookie`**: `routing.storage`로 대체됨
- **`middleware.prefixDefault`**: `routing.mode`로 대체됨
- **`middleware.noPrefix`**: `routing.mode`로 대체됨

### 마이그레이션 매핑

#### 구성 매핑

| v6 구성                    | v7 구성                                          |
| -------------------------- | ------------------------------------------------ |
| `autoFill: xxx`            | `fill: xxx`                                      |
| `prefixDefault: false`     | `mode: 'prefix-no-default'`                      |
| `prefixDefault: true`      | `mode: 'prefix-all'`                             |
| `noPrefix: true`           | `mode: 'no-prefix'`                              |
| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }` |
| `serverSetCookie: 'never'` | `storage: false` 또는 storage 배열에서 쿠키 제거 |

#### 마이그레이션 예시

**이전 (v6):**

```typescript
export default {
  middleware: {
    headerName: "x-intlayer-locale",
    cookieName: "intlayer-locale",
    prefixDefault: false,
    basePath: "",
    serverSetCookie: "always",
    noPrefix: false,
  },
};
```

**이후 (v7):**

```typescript
export default {
  routing: {
    mode: "prefix-no-default",
    storage: "localStorage", // 또는 쿠키 저장소가 필요하면 'cookie'
    headerName: "x-intlayer-locale",
    basePath: "",
  },
};
```

#### 사전 내용 매핑

| v6 사전 내용    | v7 사전 내용 |
| --------------- | ------------ |
| `autoFill: xxx` | `fill: xxx`  |

#### 마이그레이션 예시

**이전 (v6):**

```typescript
const content = {
  key: "example",
  autoFill: true, // 이 파일을 다시 작성합니다
  content: {
    title: "Hello World",
  },
};
```

**After (v7):**

```typescript
const content = {
  key: "example",
  fill: true, // 이 파일을 다시 작성합니다
  content: {
    title: "Hello World",
  },
};
```

---

## v5에서 v6로의 마이그레이션 노트

자세한 내용은 [v5에서 v6로의 마이그레이션 노트](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/releases/v6.md)를 확인하세요.

---

## 유용한 링크

- [설정 참조](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)
- [미들웨어 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/next-intlayer/index.md)
- [TypeScript 타입](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
- [GDPR 쿠키 가이드라인](https://gdpr.eu/cookies/)