์ž‘๊ฐ€:
    ์ƒ์„ฑ:2026-01-21๋งˆ์ง€๋ง‰ ์—…๋ฐ์ดํŠธ:2026-01-21

    next-intlayer ํŒจํ‚ค์ง€

    next-intlayer ํŒจํ‚ค์ง€๋Š” Intlayer๋ฅผ Next.js ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์— ํ†ตํ•ฉํ•˜๊ธฐ ์œ„ํ•œ ํ•„์ˆ˜ ๋„๊ตฌ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. App Router์™€ Page Router ๋‘˜ ๋‹ค๋ฅผ ์ง€์›ํ•˜๋ฉฐ, ๋กœ์ผ€์ผ ๊ธฐ๋ฐ˜ ๋ผ์šฐํŒ…์„ ์œ„ํ•œ ๋ฏธ๋“ค์›จ์–ด๋„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค.

    ์„ค์น˜

    bash
    npm install next-intlayer
    

    ๋‚ด๋ณด๋‚ด๊ธฐ

    ๋ฏธ๋“ค์›จ์–ด

    ๊ฐ€์ ธ์˜ค๊ธฐ:

    tsx
    import "next-intlayer/middleware";
    
    ํ•จ์ˆ˜ ์„ค๋ช… ๊ด€๋ จ ๋ฌธ์„œ
    intlayerMiddleware ๋กœ์ผ€์ผ ๊ธฐ๋ฐ˜ ๋ผ์šฐํŒ… ๋ฐ ๋ฆฌ๋‹ค์ด๋ ‰ํŠธ๋ฅผ ์ฒ˜๋ฆฌํ•˜๋Š” Next.js ๋ฏธ๋“ค์›จ์–ด์ž…๋‹ˆ๋‹ค. ์š”์ฒญ ํ—ค๋”/์ฟ ํ‚ค์—์„œ ๋กœ์ผ€์ผ์„ ๊ฐ์ง€ํ•˜๊ณ  ์ ์ ˆํ•œ ๋กœ์ผ€์ผ ๊ฒฝ๋กœ๋กœ ๋ฆฌ๋‹ค์ด๋ ‰ํŠธํ•ฉ๋‹ˆ๋‹ค. intlayerMiddleware

    ๊ตฌ์„ฑ ํ—ฌํผ

    ๊ฐ€์ ธ์˜ค๊ธฐ:

    tsx
    import "next-intlayer/server";
    
    ํ•จ์ˆ˜ ์„ค๋ช… ๊ด€๋ จ ๋ฌธ์„œ
    withIntlayer Next.js ๊ตฌ์„ฑ์„ ๋ž˜ํ•‘ํ•˜๋Š” ๋น„๋™๊ธฐ ํ—ฌํผ๋กœ, ๋นŒ๋“œ ์ „์— Intlayer ๋”•์…”๋„ˆ๋ฆฌ๊ฐ€ ์ค€๋น„๋˜๋„๋ก ๋ณด์žฅํ•ฉ๋‹ˆ๋‹ค. ์ฝ˜ํ…์ธ  ํŒŒ์ผ์„ ์ค€๋น„ํ•˜๊ณ  webpack/SWC ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. -
    withIntlayerSync ๋น„๋™๊ธฐ ์ฒ˜๋ฆฌ๊ฐ€ ๋ถˆ๊ฐ€๋Šฅํ•˜๊ฑฐ๋‚˜ ์›์น˜ ์•Š๋Š” ์„ค์ •์— ์ ํ•ฉํ•œ Next.js ๊ตฌ์„ฑ์„ ๋™๊ธฐ์ ์œผ๋กœ ๋ž˜ํ•‘ํ•˜๋Š” ํ—ฌํผ์ž…๋‹ˆ๋‹ค. ์„œ๋ฒ„ ์‹œ์ž‘ ์‹œ ๋”•์…”๋„ˆ๋ฆฌ๋ฅผ ์ค€๋น„ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. -

    ํ”„๋กœ๋ฐ”์ด๋”

    ์ž„ํฌํŠธ:

    tsx
    import "next-intlayer";
    

    ๋˜๋Š”

    tsx
    import "next-intlayer/server";
    
    ์ปดํฌ๋„ŒํŠธ ์„ค๋ช… ๊ด€๋ จ ๋ฌธ์„œ
    IntlayerClientProvider Next.js App Router์˜ ํด๋ผ์ด์–ธํŠธ ์ธก ์ปดํฌ๋„ŒํŠธ๋ฅผ ์œ„ํ•œ Provider. react-intlayer์˜ IntlayerProvider๋ฅผ ๋ž˜ํ•‘ํ•ฉ๋‹ˆ๋‹ค. -
    IntlayerServerProvider Next.js(App Router)์˜ ์„œ๋ฒ„ ์ธก ์ปดํฌ๋„ŒํŠธ๋ฅผ ์œ„ํ•œ Provider. ์„œ๋ฒ„์—์„œ locale ์ปจํ…์ŠคํŠธ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. -
    IntlayerServer App Router์—์„œ Intlayer ์ฝ˜ํ…์ธ ๋ฅผ ์œ„ํ•œ ์„œ๋ฒ„ ์‚ฌ์ด๋“œ ๋ž˜ํผ. ์„œ๋ฒ„ ์ปดํฌ๋„ŒํŠธ์—์„œ ์ ์ ˆํ•œ locale ์ฒ˜๋ฆฌ๋ฅผ ๋ณด์žฅํ•ฉ๋‹ˆ๋‹ค. -

    ํ›… (ํด๋ผ์ด์–ธํŠธ ์ธก)

    ์ž„ํฌํŠธ:

    tsx
    import "next-intlayer";
    

    react-intlayer์˜ ๋Œ€๋ถ€๋ถ„์˜ ํ›…์„ ์žฌ๋‚ด๋ณด๋ƒ…๋‹ˆ๋‹ค.

    ํ›… ์„ค๋ช… ๊ด€๋ จ ๋ฌธ์„œ
    useIntlayer ํ‚ค๋กœ ํ•˜๋‚˜์˜ dictionary๋ฅผ ์„ ํƒํ•˜์—ฌ ๊ทธ ๋‚ด์šฉ์„ ๋ฐ˜ํ™˜ํ•˜๋Š” ํด๋ผ์ด์–ธํŠธ ์‚ฌ์ด๋“œ ํ›…์ž…๋‹ˆ๋‹ค. locale์ด ์ œ๊ณต๋˜์ง€ ์•Š์œผ๋ฉด context์—์„œ ๊ฐ€์ ธ์˜ต๋‹ˆ๋‹ค. useIntlayer
    useDictionary dictionary ๊ฐ์ฒด๋ฅผ ๋ณ€ํ™˜ํ•˜๊ณ  ํ˜„์žฌ locale์— ๋งž๋Š” ์ฝ˜ํ…์ธ ๋ฅผ ๋ฐ˜ํ™˜ํ•˜๋Š” ํ›…์ž…๋‹ˆ๋‹ค. t() ๋ฒˆ์—ญ, ์—ด๊ฑฐํ˜• ์ฒ˜๋ฆฌ ๋“ฑ๋„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. useDictionary
    useDictionaryAsync ๋น„๋™๊ธฐ ์‚ฌ์ „์„ ์ฒ˜๋ฆฌํ•˜๋Š” ํ›…์ž…๋‹ˆ๋‹ค. Promise ๊ธฐ๋ฐ˜์˜ dictionary ๋งต์„ ๋ฐ›์•„ ํ˜„์žฌ ๋กœ์ผ€์ผ์— ๋งž๊ฒŒ ์ด๋ฅผ ํ•ด๊ฒฐ(resolve)ํ•ฉ๋‹ˆ๋‹ค. -
    useDictionaryDynamic ํ‚ค๋กœ ๋กœ๋“œ๋˜๋Š” ๋™์  ์‚ฌ์ „์„ ์ฒ˜๋ฆฌํ•˜๋Š” ํ›…์ž…๋‹ˆ๋‹ค. ๋กœ๋”ฉ ์ƒํƒœ ๊ด€๋ฆฌ๋ฅผ ์œ„ํ•ด ๋‚ด๋ถ€์ ์œผ๋กœ React Suspense๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. -
    useLocale ํด๋ผ์ด์–ธํŠธ ์‚ฌ์ด๋“œ ํ›…์œผ๋กœ ํ˜„์žฌ ๋กœ์ผ€์ผ๊ณผ ์ด๋ฅผ ์„ค์ •ํ•˜๋Š” ํ•จ์ˆ˜๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. Next.js App Router์˜ navigation ์ง€์›์„ ์œ„ํ•ด ํ™•์žฅ๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. useLocale
    usePathname ๋กœ์ผ€์ผ ์ ‘๋‘์‚ฌ์™€ ๋กœ์ผ€์ผ ๋งค๊ฐœ๋ณ€์ˆ˜๊ฐ€ ์ œ๊ฑฐ๋œ ์ฟผ๋ฆฌ ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ์ œ์™ธํ•œ ํ˜„์žฌ ๊ฒฝ๋กœ ์ด๋ฆ„์„ ๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค. usePathname
    useRewriteURL URL ์žฌ์ž‘์„ฑ(rewrite)์„ ๊ด€๋ฆฌํ•˜๋Š” ํด๋ผ์ด์–ธํŠธ ์‚ฌ์ด๋“œ ํ›…์ž…๋‹ˆ๋‹ค. ๋ณด๋‹ค ๋ณด๊ธฐ ์ข‹์€ ๋กœ์ปฌ๋ผ์ด์ฆˆ๋œ ๋ฆฌ๋ผ์ดํŠธ ๊ทœ์น™์ด ์žˆ์œผ๋ฉด URL์„ ์ž๋™์œผ๋กœ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. useRewriteURL
    useLocalePageRouter Next.js Page Router ์ „์šฉ ๋กœ์ผ€์ผ ๊ด€๋ฆฌ ํ›…์ž…๋‹ˆ๋‹ค. ๋กœ์ผ€์ผ ๋ณ€๊ฒฝ ์‹œ ๋ฆฌ๋””๋ ‰์…˜ ๋ฐ ํŽ˜์ด์ง€ ๋ฆฌ๋กœ๋“œ๋ฅผ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค. -
    useI18n ํ‚ค๋กœ ์ค‘์ฒฉ๋œ ์ฝ˜ํ…์ธ ์— ์ ‘๊ทผํ•˜๊ธฐ ์œ„ํ•œ ๋ฒˆ์—ญ ํ•จ์ˆ˜ t()๋ฅผ ์ œ๊ณตํ•˜๋Š” ํ›…์ž…๋‹ˆ๋‹ค. i18next/next-intl ํŒจํ„ด์„ ๋ชจ๋ฐฉํ•ฉ๋‹ˆ๋‹ค. useI18n
    useIntl ๋กœ์ผ€์ผ์— ๋ฐ”์ธ๋”ฉ๋œ Intl ๊ฐ์ฒด๋ฅผ ์ œ๊ณตํ•˜๋Š” ํ›…. ํ˜„์žฌ ๋กœ์ผ€์ผ์„ ์ž๋™์œผ๋กœ ์ฃผ์ž…ํ•˜๊ณ  ์ตœ์ ํ™”๋œ ์บ์‹ฑ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. -
    useLoadDynamic React Suspense๋ฅผ ์‚ฌ์šฉํ•ด ๋™์  ์‚ฌ์ „์„ ๋กœ๋“œํ•˜๋Š” ํ›…. ํ‚ค์™€ ํ”„๋ผ๋ฏธ์Šค(promise)๋ฅผ ๋ฐ›์•„ ๊ฒฐ๊ณผ๋ฅผ ์บ์‹œํ•ฉ๋‹ˆ๋‹ค. -

    ํ•จ์ˆ˜๋“ค (์„œ๋ฒ„ ์‚ฌ์ด๋“œ)

    ์ž„ํฌํŠธ:

    tsx
    import "next-intlayer/server";
    
    ํ•จ์ˆ˜ ์„ค๋ช… ๊ด€๋ จ ๋ฌธ์„œ
    t Next.js App Router์šฉ ๋ฒˆ์—ญ ํ•จ์ˆ˜์˜ ์„œ๋ฒ„ ์ธก ๋ฒ„์ „์ž…๋‹ˆ๋‹ค. ์„œ๋ฒ„ ๋กœ์ผ€์ผ์— ๋งž๋Š” ๋‹ค๊ตญ์–ด ์ฝ˜ํ…์ธ  ๋ฒˆ์—ญ์„ ๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค. translation
    getLocale Next.js ํ—ค๋”์™€ ์ฟ ํ‚ค์—์„œ ํ˜„์žฌ ๋กœ์ผ€์ผ์„ ์ถ”์ถœํ•˜๋Š” ํ—ฌํผ ํ•จ์ˆ˜์ž…๋‹ˆ๋‹ค. Server Components, Server Actions, ๋˜๋Š” Route Handlers์šฉ์œผ๋กœ ์„ค๊ณ„๋˜์—ˆ์Šต๋‹ˆ๋‹ค. -
    generateStaticParams ๊ตฌ์„ฑ๋œ ๋กœ์ผ€์ผ์„ ๊ธฐ๋ฐ˜์œผ๋กœ Next.js์˜ ๋™์  ๋ผ์šฐํŠธ์— ๋Œ€ํ•œ ์ •์  ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. ์‚ฌ์ „ ๋ Œ๋”๋ง์„ ์œ„ํ•ด ๋กœ์ผ€์ผ ๊ฐ์ฒด์˜ ๋ฐฐ์—ด์„ ๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค. -
    locale ์„œ๋ฒ„ ์ปจํ…์ŠคํŠธ(App Router)์—์„œ ๋กœ์ผ€์ผ์„ ๊ฐ€์ ธ์˜ค๊ฑฐ๋‚˜ ์„ค์ •ํ•˜๋Š” ํ•จ์ˆ˜์ž…๋‹ˆ๋‹ค. Server Components์—์„œ ๋กœ์ผ€์ผ ๊ด€๋ฆฌ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. -

    ํƒ€์ž…

    Import:

    tsx
    import "next-intlayer";
    
    ํƒ€์ž… ์„ค๋ช…
    NextPageIntlayer Intlayer ์ง€์›์„ ๊ฐ–์ถ˜ Next.js ํŽ˜์ด์ง€์šฉ ํƒ€์ž…. locale ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ํฌํ•จํ•˜๋Š” ์ œ๋„ค๋ฆญ ํƒ€์ž….
    Next14PageIntlayer Intlayer ์ง€์›์„ ๊ฐ–์ถ˜ Next.js 14 ํŽ˜์ด์ง€์šฉ ํƒ€์ž….
    Next15PageIntlayer Intlayer ์ง€์›์„ ๊ฐ–์ถ˜ Next.js 15 ํŽ˜์ด์ง€์šฉ ํƒ€์ž….
    NextLayoutIntlayer Intlayer ์ง€์›์„ ๊ฐ–์ถ˜ Next.js ๋ ˆ์ด์•„์›ƒ์šฉ ํƒ€์ž…. locale ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ํฌํ•จํ•˜๋Š” ์ œ๋„ค๋ฆญ ํƒ€์ž….
    Next14LayoutIntlayer Intlayer ์ง€์›์ด ํฌํ•จ๋œ Next.js 14 ๋ ˆ์ด์•„์›ƒ์šฉ ํƒ€์ž….
    Next15LayoutIntlayer Intlayer ์ง€์›์ด ํฌํ•จ๋œ Next.js 15 ๋ ˆ์ด์•„์›ƒ์šฉ ํƒ€์ž….
    LocalParams locale๋ฅผ ํฌํ•จํ•œ Next.js ๋ผ์šฐํŠธ ๋งค๊ฐœ๋ณ€์ˆ˜์šฉ ํƒ€์ž…. locale ์†์„ฑ์„ ๊ฐ€์ง„ ๊ฐ์ฒด.
    LocalPromiseParams locale๋ฅผ ํฌํ•จํ•œ Next.js ๋ผ์šฐํŠธ ๋งค๊ฐœ๋ณ€์ˆ˜์šฉ ํƒ€์ž…(๋น„๋™๊ธฐ ๋ฒ„์ „). locale ์†์„ฑ์„ ๊ฐ€์ง„ ๊ฐ์ฒด๋กœ ํ•ด๊ฒฐ๋˜๋Š” Promise.