새로운 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에서는 빌드 프로세스를 가속화하는 캐싱 전략을 구현했습니다.

npx intlayer build

새로운 캐싱 시스템:

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

TypeScript: 로케일별 타입 생성

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

v6 동작:

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

v7 동작:

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

장점:

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

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

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

v6:

import { Locales } from "intlayer";// 모든 로케일을 포함하는 enum -> 트리 쉐이커블하지 않음const locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";// 문자열 타입 -> 완전히 트리 쉐이커블const locale: Locale = Locales.ENGLISH;

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

자세한 내용은 구현 세부사항을 참조하세요.

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

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

기본 구성

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

GDPR 준수: localStorage / 쿠키 저장

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

저장 구성 옵션

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

// 저장소 비활성화storage: false// 간단한 저장소 유형storage: 'cookie'storage: 'localStorage'storage: 'sessionStorage'// 사용자 정의 속성을 가진 쿠키storage: {  type: 'cookie',  name: 'custom-locale',  domain: '.example.com',  secure: true,  sameSite: 'strict'}// 사용자 정의 키를 가진 localStoragestorage: {  type: 'localStorage',  name: 'custom-locale'}// 중복성을 위한 다중 저장소 유형storage: ['cookie', 'localStorage']

GDPR 준수 구성 예시

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

typescript;// intlayer.config.tsexport 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 사용 예시:

전역으로 정의 가능:

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

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

const { setLocale } = useLocale({ isCookieEnabled: false });setLocale("en");

참고: 쿠키는 기본적으로 활성화되어 있습니다. 참고: 특정 사용 사례에 대한 GDPR 쿠키 요구 사항을 확인하세요.

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

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

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

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

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

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

새로운 fill 동작

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

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

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

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

이점

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

사용 예시

// 모든 로케일로 현재 파일을 다시 작성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 컨텍스트 창을 초과하지 않으면서 대용량 콘텐츠 파일을 처리합니다:

예시 워크플로우

// 대용량 콘텐츠 파일이 자동으로 청킹됩니다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):

export default {#### 구성 매핑| 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` 또는 저장소 배열에서 쿠키 제거       |#### 마이그레이션 예시**이전 (v6):**```typescriptexport default {  middleware: {    headerName: "x-intlayer-locale",    cookieName: "intlayer-locale",    prefixDefault: false,    basePath: "",    serverSetCookie: "always",    noPrefix: false,  },};

이후 (v7):

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

사전 내용 매핑

마이그레이션 예시

이전 (v6):

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

After (v7):

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

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

자세한 내용은 v5에서 v6로의 마이그레이션 노트를 확인하세요.

유용한 링크

• 설정 참조
• 미들웨어 문서
• TypeScript 타입
• GDPR 쿠키 가이드라인