{content.getStarted.pageLink}
>
);
};
const Page: NextPage = async () => {
// Next.js 15+에서 headers와 cookies를 await합니다
const headerList = await headers();
const cookieList = await cookies();
const locale = await getLocale({
// 먼저 intlayer 쿠키를 확인합니다 (기본값: 'INTLAYER_LOCALE')
getCookie: (name) => cookieList.get(name)?.value,
// 그다음 intlayer 헤더를 확인합니다 (기본값: 'x-intlayer-locale')
// 마지막으로 accept-language 헤더 ('accept-language')를 확인합니다
getHeader: (name) => headerList.get(name),
});
return (
);
};
```
- **`IntlayerClientProvider`**는 클라이언트 측 컴포넌트에 로케일을 제공하는 데 사용됩니다. 레이아웃을 포함한 모든 상위 컴포넌트에 배치할 수 있습니다. 다만 Next.js가 레이아웃 코드를 페이지 간에 공유하므로 레이아웃에 배치하는 것이 권장됩니다. 레이아웃에서 `IntlayerClientProvider`를 사용하면 페이지마다 이를 다시 초기화하는 일을 피할 수 있어 성능이 향상되고 애플리케이션 전반에 걸쳐 일관된 로컬라이제이션 컨텍스트를 유지할 수 있습니다.
- **`IntlayerServerProvider`**는 서버 자식 컴포넌트에 로케일을 제공하는 데 사용됩니다. 레이아웃에 설정할 수 없습니다.
> Layout과 page는 공통의 서버 컨텍스트를 공유할 수 없습니다. 서버 컨텍스트 시스템은 [React의 cache](https://react.dev/reference/react/cache) 메커니즘을 통해 요청별 데이터 저장소에 기반하므로 애플리케이션의 서로 다른 세그먼트마다 각 "context"가 재생성됩니다. 프로바이더를 공유 레이아웃에 배치하면 이러한 격리가 깨져 서버 컴포넌트에 서버 컨텍스트 값을 올바르게 전파하지 못하게 됩니다.
```tsx {4,7} fileName="src/components/clientComponentExample/ClientComponentExample.tsx" codeFormat="typescript"
"use client";
import type { FC } from "react";
import { useIntlayer } from "next-intlayer";
export const ClientComponentExample: FC = () => {
const content = useIntlayer("client-component-example"); // 관련 콘텐츠 선언 생성
return (
{content.title}
{content.content}
);
};
```
```jsx {3,6} fileName="src/components/clientComponentExample/ClientComponentExample.mjx" codeFormat="esm"
"use client";
import { useIntlayer } from "next-intlayer";
const ClientComponentExample = () => {
const content = useIntlayer("client-component-example"); // 관련 콘텐츠 선언 생성
return (
);
};
```
```tsx {2} fileName="src/components/serverComponentExample/ServerComponentExample.tsx" codeFormat="typescript"
import type { FC } from "react";
import { useIntlayer } from "next-intlayer/server";
export const ServerComponentExample: FC = () => {
const content = useIntlayer("server-component-example"); // 관련 콘텐츠 선언 생성
return (
{content.title}
{content.content}
);
};
```
```jsx {1} fileName="src/components/serverComponentExample/ServerComponentExample.mjx" codeFormat="esm"
import { useIntlayer } from "next-intlayer/server";
const ServerComponentExample = () => {
const content = useIntlayer("server-component-example"); // 관련 콘텐츠 선언 생성
return (
{content.title}
{content.content}
);
};
```
```jsx {1} fileName="src/components/serverComponentExample/ServerComponentExample.csx" codeFormat="commonjs"
const { useIntlayer } = require("next-intlayer/server");
const ServerComponentExample = () => {
const content = useIntlayer("server-component-example"); // 관련 콘텐츠 선언 생성
return (
{content.title}
{content.content}
);
};
```
> 콘텐츠를 `alt`, `title`, `href`, `aria-label` 등과 같은 `string` 속성에 사용하려면, 함수의 값을 호출해야 합니다. 예:
>
> ```jsx
>
> ```
>
> `useIntlayer` 훅에 대해 자세히 알아보려면 [문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/next-intlayer/useIntlayer.md)를 참조하세요.
### (선택) 7단계: 로케일 감지를 위한 프록시 구성
사용자의 선호 로케일을 감지하도록 프록시를 설정하세요:
```typescript fileName="src/proxy.ts" codeFormat="typescript"
export { intlayerProxy as proxy } from "next-intlayer/proxy";
export const config = {
matcher:
"/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};
```
```javascript fileName="src/proxy.mjs" codeFormat="esm"
export { intlayerProxy as proxy } from "next-intlayer/proxy";
export const config = {
matcher:
"/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};
```
```javascript fileName="src/proxy.cjs" codeFormat="commonjs"
const { intlayerProxy } = require("next-intlayer/proxy");
const config = {
matcher:
"/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};
module.exports = { proxy: intlayerProxy, config };
```
> `intlayerProxy`는 사용자의 선호 로케일을 감지하고 [구성](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)에 지정된 대로 적절한 URL로 리디렉션하는 데 사용됩니다. 또한 사용자의 선호 로케일을 쿠키에 저장할 수 있게 해줍니다.
> 여러 프록시를 함께 체인으로 연결해야 하는 경우(예: 인증이나 커스텀 프록시와 함께 `intlayerProxy`를 사용하는 경우), Intlayer는 이제 `multipleProxies`라는 헬퍼를 제공합니다.
```ts
import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";
import { customProxy } from "@utils/customProxy";
export const proxy = multipleProxies([intlayerProxy, customProxy]);
```
### (선택) 8단계: 콘텐츠 언어 변경
Next.js에서 콘텐츠의 언어를 변경하려면 권장되는 방법은 `Link` 컴포넌트를 사용하여 사용자를 적절한 로컬라이즈된 페이지로 리디렉션하는 것입니다. `Link` 컴포넌트는 페이지를 프리페치(prefetch)할 수 있게 하여 전체 페이지 리로드를 피하는 데 도움이 됩니다.
```tsx fileName="src/components/localeSwitcher/LocaleSwitcher.tsx" codeFormat="typescript"
"use client";
import type { FC } from "react";
import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";
import { useLocale } from "next-intlayer";
export const LocaleSwitcher: FC = () => {
const { locale, availableLocales, setLocale } = useLocale({
onChange: () => window.location.reload(),
});
return (
);
};
```
> 대안으로 `useLocale` 훅이 제공하는 `setLocale` 함수를 사용할 수 있습니다. 이 함수는 페이지를 prefetch(사전 페치)하지 않습니다. 자세한 내용은 [`useLocale` 훅 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/next-intlayer/useLocale.md)를 참조하세요.
> 문서 참조:
>
> - [`useLocale` 훅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/next-intlayer/useLocale.md)
> - [`getLocaleName` 훅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/next-intlayer/getLocaleName.md)
> - [`getLocalizedUrl` 훅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/next-intlayer/getLocalizedUrl.md)
> - [`getHTMLTextDir` 훅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getHTMLTextDir.md)
> - [`hrefLang` 속성](https://developers.google.com/search/docs/specialty/international/localized-versions?hl=fr)
> - [`lang` 속성](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang)
> - [`dir` 속성](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir)
> - [`aria-current` 속성](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)
### (선택 사항) 9단계: 서버 액션에서 현재 로케일 가져오기
Server Action 내부에서 활성 로케일이 필요하다면(예: 이메일 현지화 또는 로케일에 민감한 로직 실행), `next-intlayer/server`에서 `getLocale`을 호출하세요:
```tsx fileName="src/app/actions/getLocale.ts" codeFormat="typescript"
"use server";
import { getLocale } from "next-intlayer/server";
export const myServerAction = async () => {
const locale = await getLocale();
// locale를 사용하여 작업을 수행합니다
};
```
> `getLocale` 함수는 사용자의 로케일을 결정하기 위해 계단식 전략을 따릅니다:
>
> 1. 먼저, 프록시가 설정했을 수 있는 `locale` 값을 요청 헤더에서 확인합니다
> 2. 헤더에서 `locale`을 찾지 못하면 쿠키에 저장된 `locale`을 확인합니다
> 3. 쿠키도 없으면 브라우저 설정에서 사용자의 선호 언어를 감지하려고 시도합니다
> 4. 마지막 수단으로 애플리케이션에 구성된 기본 `locale`로 대체됩니다
>
> 이를 통해 사용 가능한 컨텍스트에 따라 가장 적절한 로케일이 선택됩니다.
### (선택 사항) 10단계: 번들 크기 최적화
`next-intlayer`를 사용할 때 사전(dictionaries)은 기본적으로 모든 페이지의 번들에 포함됩니다. 번들 크기를 최적화하기 위해 Intlayer는 매크로를 사용해 `useIntlayer` 호출을 지능적으로 대체하는 선택적 SWC 플러그인을 제공합니다. 이를 통해 사전은 실제로 해당 사전을 사용하는 페이지의 번들에만 포함됩니다.
이 최적화를 활성화하려면 `@intlayer/swc` 패키지를 설치하세요. 설치하면 `next-intlayer`가 플러그인을 자동으로 감지하여 사용합니다:
```bash packageManager="npm"
npm install @intlayer/swc --save-dev
npx intlayer init
```
```bash packageManager="pnpm"
pnpm add @intlayer/swc --save-dev
pnpm intlayer init
```
```bash packageManager="yarn"
yarn add @intlayer/swc --save-dev
yarn intlayer init
```
```bash packageManager="bun"
bun add @intlayer/swc --dev
bunx intlayer init
```
> 참고: 이 최적화는 Next.js 13 이상에서만 사용할 수 있습니다.
> 참고: 이 패키지는 SWC 플러그인이 Next.js에서 아직 실험적이기 때문에 기본적으로 설치되어 있지 않습니다. 향후 변경될 수 있습니다.
> 참고: 옵션을 `importMode: 'dynamic'` 또는 `importMode: 'live'`로 설정하면 Suspense에 의존하게 되므로 `useIntlayer` 호출을 `Suspense` 경계로 감싸야 합니다. 즉, Page / Layout 컴포넌트의 최상위 수준에서 `useIntlayer`를 직접 사용할 수 없습니다.
### Turbopack에서 딕셔너리 변경 사항 감시
Turbopack을 개발 서버로 사용하여 `next dev` 명령을 실행하는 경우, 사전(dictionary) 변경 사항은 기본적으로 자동으로 감지되지 않습니다.
이 제한은 Turbopack이 콘텐츠 파일의 변경을 모니터링하기 위해 webpack 플러그인을 병렬로 실행할 수 없기 때문에 발생합니다. 이를 해결하려면 개발 서버와 Intlayer 빌드 워처를 동시에 실행하기 위해 `intlayer watch` 명령을 사용해야 합니다.
```json5 fileName="package.json"
{
// ... 기존 package.json 구성
"scripts": {
// ... 기존 scripts 구성
"dev": "intlayer watch --with 'next dev'",
},
}
```
> 만약 next-intlayer@<=6.x.x를 사용 중이라면, Next.js 16 애플리케이션이 Turbopack과 올바르게 작동하도록 `--turbopack` 플래그를 유지해야 합니다. 이 제한을 피하려면 next-intlayer@>=7.x.x 사용을 권장합니다.
### TypeScript 구성
Intlayer는 TypeScript의 이점을 얻고 코드베이스를 더욱 견고하게 만들기 위해 module augmentation을 사용합니다.


TypeScript 구성에 자동 생성된 타입들이 포함되어 있는지 확인하세요.
````json5 fileName="tsconfig.json"
{
// ... 기존 TypeScript 구성
"include": [
// ... 기존 TypeScript 구성
".intlayer/**/*.ts", // 자동으로 생성된 타입 포함
],
}
### Git 구성
Intlayer에 의해 생성된 파일을 무시하는 것을 권장합니다. 이렇게 하면 Git 저장소에 해당 파일들이 커밋되는 것을 방지할 수 있습니다.
이를 위해 다음 지침을 `.gitignore` 파일에 추가할 수 있습니다:
```plaintext fileName=".gitignore"
# Intlayer에 의해 생성된 파일 무시
.intlayer
````
### VS Code 확장
Intlayer로 개발 환경을 개선하려면 공식 **Intlayer VS Code Extension**을 설치할 수 있습니다.
[Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
이 확장 기능은 다음을 제공합니다:
- **번역 키에 대한 자동 완성**.
- **누락된 번역에 대한 실시간 오류 감지**.
- **번역된 콘텐츠의 인라인 미리보기.**
- **빠른 작업(Quick actions)**을 통해 번역을 손쉽게 생성하고 업데이트할 수 있습니다.
자세한 사용 방법은 [Intlayer VS Code 확장 문서](https://intlayer.org/doc/vs-code-extension)를 참조하세요.
### 더 나아가기
더 나아가, [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_visual_editor.md)를 구현하거나 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)를 사용해 콘텐츠를 외부화할 수 있습니다.