next-intl 4
이 스킬은 https://next-intl.dev/docs/getting-started (4.14.9 버전 기준 문서)에 문서화된 대로 next-intl 4.x를 다룹니다. 일반적인 습관과 다른 점, 예상치 못한 기본값, 함정, 레거시 API 및 문서에서 권장하는 패턴을 포함합니다. 참조 파일의 각 주장은 해당 페이지 출처로 끝납니다.
탐색 방법
- 아래의 빠른 시작 및 빠른 규칙을 읽으십시오. 가장 빈번한 실수를 잡아냅니다.
- 작업과 일치하는 하나의 참조 파일을 마지막 표에서 열어 보십시오.
- 코드에서
setRequestLocale,requestLocale또는middleware.ts를 사용하는 경우, 먼저 "이전 패턴" 표를 읽으십시오.
빠른 시작 (App Router)
App Router가 권장 경로입니다. Pages Router는 계속 지원되며, references/setup.md를 참조하십시오. https://next-intl.dev/docs/getting-started/pages-router
// next.config.ts
import {NextConfig} from 'next';
import createNextIntlPlugin from 'next-intl/plugin';
const nextConfig: NextConfig = {};
const withNextIntl = createNextIntlPlugin();
export default withNextIntl(nextConfig);
https://next-intl.dev/docs/getting-started/app-router
로케일 기반 URL이 없는 경우, src/i18n/request.ts는 사용자 기본 설정, 가장 간단하게는 쿠키에서 로케일을 확인합니다:
// src/i18n/request.ts
import {cookies} from 'next/headers';
import {getRequestConfig} from 'next-intl/server';
export default getRequestConfig(async () => {
const store = await cookies();
const locale = store.get('locale')?.value || 'en';
return {
locale,
messages: (await import(`../../messages/${locale}.json`)).default
};
});
https://next-intl.dev/docs/getting-started/app-router
// src/app/layout.tsx
import {NextIntlClientProvider} from 'next-intl';
import {getLocale} from 'next-intl/server';
export default async function RootLayout({children}) {
const locale = await getLocale();
return (
<html lang={locale}>
<body>
<NextIntlClientProvider>{children}</NextIntlClientProvider>
</body>
</html>
);
}
https://next-intl.dev/docs/getting-started/app-router , https://next-intl.dev/docs/usage/configuration
import {useTranslations} from 'next-intl';
import {getTranslations} from 'next-intl/server';
export function HomePage() {
const t = useTranslations('HomePage'); // 비동기 컴포넌트 아님
return <h1>{t('title')}</h1>;
}
export async function Profile() {
const t = await getTranslations('ProfilePage'); // async 컴포넌트
return <h1>{t('title')}</h1>;
}
https://next-intl.dev/docs/getting-started/app-router
/en/about 스타일 URL의 경우, src/i18n/routing.ts, src/proxy.ts, src/i18n/navigation.ts 및 최상위 [locale] 세그먼트를 추가하십시오: references/routing.md. https://next-intl.dev/docs/routing/setup
빠른 규칙
설정
- 플러그인은
src/또는 프로젝트 루트(.ts,.tsx,.js,.jsx)에서i18n/request.ts를 찾습니다. 다른 위치에 있는 경우 경로를 전달하십시오:createNextIntlPlugin('./somewhere/else/request.ts'). https://next-intl.dev/docs/getting-started/app-router - 문서 예제는
const locale = 'en'을 하드코딩합니다. 실제 확인(쿠키, 사용자 설정 또는next/root-params)으로 바꾸십시오. https://next-intl.dev/docs/getting-started/app-router getRequestConfig는 요청당 한 번, Server Components 렌더링 패스에서 실행되므로cookies()및headers()가 거기서 작동합니다. https://next-intl.dev/docs/usage/configuration- 요청 구성에
timeZone을 설정하십시오. 기본값은 서버 런타임의 시간대입니다. https://next-intl.dev/docs/usage/configuration
라우팅
- Next.js 16에서는 파일 이름을
src/proxy.ts로 지정하십시오. import는next-intl/middleware의createMiddleware로 유지됩니다. https://next-intl.dev/docs/routing/setup next/root-params의await rootParams.locale()로 로케일을 읽고,hasLocale(routing.locales, value)로 유효성을 검사한 후, 그렇지 않으면notFound()를 호출하십시오. Next.js 16.3 이전에는experimental.rootParams가 필요합니다. https://next-intl.dev/docs/routing/setupnext/link또는next/navigation대신i18n/navigation.ts에서Link,redirect,usePathname,useRouter및getPathname을 가져오십시오. https://next-intl.dev/docs/routing/navigation- 해당 모듈의
router.replace(pathname, {locale})로 로케일을 전환하십시오.<Link locale>은 프리페치되지 않으므로 로케일 쿠키를 덮어쓰지 않습니다. https://next-intl.dev/docs/routing/navigation redirect는 항상 로케일을 사용합니다:redirect({href: '/login', locale}). TypeScript가 좁혀지도록return redirect(...)를 작성하십시오. https://next-intl.dev/docs/routing/navigation- 기본 매처는 점이 포함된 경로를 건너뜁니다.
/users/jane.doe와 같은 경로에 대해 명시적 항목을 추가하십시오. https://next-intl.dev/docs/routing/middleware
클라이언트 컴포넌트
messagesprop이 없는NextIntlClientProvider는 모든 메시지를 클라이언트로 보냅니다.messages={pick(messages, 'Namespace')}또는messages={null}을 전달하여 제한하십시오. https://next-intl.dev/docs/environments/server-client-components- Server Component에서 번역하고 레이블을 props 또는
children으로 Client Component에 전달하는 것을 선호하십시오. https://next-intl.dev/docs/environments/server-client-components onError및getMessageFallback은 Server Component에서 전달할 수 없습니다. 서버 프로바이더 내에 중첩된 자체'use client'프로바이더에서 설정하십시오. 이렇게 하면 로케일과 메시지를 계속 상속받으므로 수동으로 전달하지 마십시오. https://next-intl.dev/docs/usage/configuration
메시지
- 키와 네임스페이스는
.을 포함할 수 없으며, 이는 중첩을 의미합니다. 중첩된 JSON만 사용하십시오. https://next-intl.dev/docs/usage/translations - ICU 인수 이름 및
select값은 문자, 숫자 및_만 허용하며, 대시는 사용할 수 없습니다:en-GB를en_GB로 매핑하십시오.select에는other케이스가 필요합니다. https://next-intl.dev/docs/usage/translations - 자체-종료 태그는 메시지에 닫는 태그가 필요합니다:
<br></br>. https://next-intl.dev/docs/usage/translations - Server Actions, 메타데이터 및 Route Handlers에서, 로케일이 추론되지 않을 수 있는 경우
getTranslations({locale, namespace})를 사용하십시오. https://next-intl.dev/docs/environments/actions-metadata-route-handlers
테스트
createNavigation을 사용한 Vitest:server.deps.inline: ['next-intl']. Jest:transformIgnorePatterns: ['node_modules/(?!next-intl)/']. next-intl은 ESM 전용입니다. https://next-intl.dev/docs/environments/testing
이전 패턴
| 이전 | 현재 |
|---|---|
src/middleware.ts | Next.js 16에서는 src/proxy.ts, 동일한 createMiddleware 코드 |
모든 레이아웃과 페이지 상단의 setRequestLocale(locale) | i18n/request.ts의 next/root-params, 정적 렌더링이 없이도 작동 |
getRequestConfig(async ({requestLocale}) => ...) | rootParams.locale() fallback이 있는 getRequestConfig(async ({locale}) => ...) |
플랫 메시지 키 "HomePage.title" | 중첩 객체 {"HomePage": {"title": ...}} |
dangerouslySetInnerHTML의 t.raw HTML | t.rich (React) 또는 t.markup (문자열), t.raw는 파싱을 건너뛰고 살균된 경우에만 사용 |
세부 사항: references/routing.md 및 references/messages.md.
참조 파일
| 파일 | 읽을 대상 |
|---|---|
| references/setup.md | 플러그인, 요청 구성, 프로바이더 기본값, 라우팅 없는 로케일, 메시지 저장소, Pages Router |
| references/routing.md | defineRouting, [locale] 세그먼트, proxy.ts, 매처, next/root-params, 정적 렌더링, localePrefix, 도메인, 쿠키, 대체 링크, 지역화된 경로명, 정적 내보내기, 문제 해결 |
| references/navigation.md | createNavigation, Link, useRouter, usePathname, redirect, getPathname, 로케일 전환기, 타입이 지정된 href |
| references/messages.md | useTranslations, 네임스페이스, ICU 복수형 및 선택형, 리치 텍스트, t.markup, t.raw, t.has, 배열, 누락된 메시지, onError, 시간대, now |
| references/formatting.md | useFormatter: 날짜, 상대 시간, 범위, 숫자, 목록, 표시 이름, ICU 스켈레톤, 전역 형식 |
| references/server-and-client.md | Server vs Client Components, 메시지 선택, 메타데이터, Server Actions, Zod, Route Handlers, 사이트맵, OG 이미지, 404 및 오류 파일 |
| references/extraction.md | 실험적 useExtracted 및 getExtracted, 플러그인 experimental 옵션, PO 파일, 사전 컴파일, 사용자 정의 코덱, 모노레포 |
| references/typescript-and-tooling.md | AppConfig augmentation, 타입-세이프 인수, Jest 및 Vitest 테스트, Storybook, use-intl 코어, 런타임 요구 사항, 린팅, 번역 관리, 에이전트 규칙 |
크롤링된 페이지: SOURCES.md.