Intlayer로 Vite and Preact 번역하기 | 국제화(i18n)

VideoCode데모

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-vite-preact-template.vercel.app

Open embedded page in fullscreen

목차

대안보다 Intlayer를 선택해야 하는 이유는 무엇입니까?

'preact-i18n' 또는 'i18next'와 같은 주요 솔루션과 비교하여 Intlayer는 다음과 같은 통합 최적화 기능을 제공하는 솔루션입니다.

Vite 및 Preact 애플리케이션에서 Intlayer 설정 단계별 가이드

GitHub에서 애플리케이션 템플릿을 확인하세요.

1. 1

   의존성 설치

   npm을 사용하여 필요한 패키지를 설치하세요:

   bash

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   npx intlayer init --interactive
   

   --interactive 플래그는 선택 사항입니다. AI 에이전트인 경우 intlayer-cli init를 사용하세요.

   이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:

   bash

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   npm install intlayer preact-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

     구성 관리, 번역, 콘텐츠 선언, 컴파일 및 CLI 명령어를 위한 핵심 패키지입니다.

   • vite-intlayer

     Intlayer를 Vite 번들러와 통합하기 위한 Vite 플러그인과, 사용자의 선호 로케일 감지, 쿠키 관리, URL 리디렉션 처리를 위한 미들웨어를 포함합니다.

2. 2

   프로젝트 구성

   애플리케이션의 언어를 구성하기 위해 설정 파일을 만드세요:

   intlayer.config.ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // 다른 로케일들
       ],
       defaultLocale: Locales.ENGLISH,
     },
     routing: {
       mode: "prefix-no-default", // 기본값: 기본 로케일을 제외한 모든 로케일에 접두사 추가
       storage: ["cookie", "header"], // 기본값: 쿠키에 로케일 저장 및 헤더에서 감지
     },
   };
   
   export default config;
   

   이 설정 파일을 통해 로컬라이즈된 URL, 라우팅 모드, 저장 옵션, 쿠키 이름, 콘텐츠 선언 위치 및 확장자, 콘솔에서 Intlayer 로그 비활성화 등을 설정할 수 있습니다. 사용 가능한 모든 매개변수 목록은 설정 문서를 참고하세요.

3. 3

   Vite 구성에 Intlayer 통합하기

   intlayer 플러그인을 구성에 추가하세요.

   vite.config.ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { defineConfig } from "vite";
   import preact from "@preact/preset-vite";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [preact(), intlayer()],
   });
   

   intlayer() Vite 플러그인은 Intlayer를 Vite와 통합하기 위해 사용됩니다. 이 플러그인은 콘텐츠 선언 파일의 빌드를 보장하고 개발 모드에서 이를 모니터링합니다. 또한 Vite 애플리케이션 내에서 Intlayer 환경 변수를 정의하며, 성능 최적화를 위해 별칭(alias)도 제공합니다.

4. 4

   콘텐츠 선언하기

   번역을 저장하기 위해 콘텐츠 선언을 생성하고 관리하세요:

   src/app.content.tsx

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { t, type Dictionary } from "intlayer";
   import type { ComponentChildren } from "preact";
   
   const appContent = {
     key: "app",
     content: {
       viteLogo: t({
         en: "Vite logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
       preactLogo: t({
         en: "Preact logo",
         fr: "Logo Preact",
         es: "Logo Preact",
       }),
   
       title: "Vite + Preact",
   
       count: t({
         en: "count is ",
         fr: "le compte est ",
         es: "el recuento es ",
       }),
   
       edit: t<ComponentChildren>({
         en: (
           <>
             Edit <code>src/app.tsx</code> and save to test HMR
           </>
         ),
         fr: (
           <>
             Éditez <code>src/app.tsx</code> et enregistrez pour tester HMR
           </>
         ),
         es: (
           <>
             Edita <code>src/app.tsx</code> y guarda para probar HMR
           </>
         ),
       }),
   
       readTheDocs: t({
         en: "Click on the Vite and Preact logos to learn more",
         fr: "Cliquez sur les logos Vite et Preact pour en savoir plus",
         es: "Haga clic en los logotipos de Vite y Preact para obtener más información",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   콘텐츠 선언은 애플리케이션 내 어디에서든 contentDir 디렉토리(기본값은 ./src)에 포함되기만 하면 정의할 수 있습니다. 그리고 콘텐츠 선언 파일 확장자(기본값은 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml})와 일치해야 합니다.

   자세한 내용은 콘텐츠 선언 문서를 참조하세요.

   콘텐츠 파일에 TSX 코드가 포함된 경우, import { h } from "preact";를 임포트하거나 JSX 프래그마가 Preact에 맞게 올바르게 설정되어 있는지 확인해야 할 수 있습니다.

5. 5

   코드에서 Intlayer 사용하기

   애플리케이션 전반에서 콘텐츠 사전을 접근하세요:

   src/app.tsx

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { useState } from "preact/hooks";
   import type { FunctionalComponent } from "preact";
   import preactLogo from "./assets/preact.svg"; // preact.svg 파일이 있다고 가정합니다
   import viteLogo from "/vite.svg";
   import "./app.css"; // CSS 파일 이름이 app.css라고 가정합니다
   import { IntlayerProvider, useIntlayer } from "preact-intlayer";
   
   const AppContent: FunctionalComponent = () => {
     const [count, setCount] = useState(0);
     const content = useIntlayer("app");
   
     return (
       <>
         <div>
           <a href="https://vitejs.dev" target="_blank">
             <img src={viteLogo} class="logo" alt={content.viteLogo.value} />
           </a>
           <a href="https://preactjs.com" target="_blank">
             <img
               src={preactLogo}
               class="logo preact"
               alt={content.preactLogo.value}
             />
           </a>
         </div>
         <h1>{content.title}</h1>
         <div class="card">
           <button onClick={() => setCount((count) => count + 1)}>
             {content.count}
             {count}
           </button>
           <p>{content.edit}</p>
         </div>
         {/* Markdown 콘텐츠 */}
         <div>{content.myMarkdownContent}</div>
   
         {/* HTML 콘텐츠 */}
         <div>{content.myHtmlContent}</div>
   
         <p class="read-the-docs">{content.readTheDocs}</p>
       </>
     );
   };
   
   const App: FunctionalComponent = () => (
     <IntlayerProvider>
       <AppContent />
     </IntlayerProvider>
   );
   
   export default App;
   

   만약 alt, title, href, aria-label 등과 같은 string 속성에서 콘텐츠를 사용하려면, 함수의 값을 호출해야 합니다. 예를 들어:

   html

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   <img src="{content.image.src.value}" alt="{content.image.value}" />
   <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
   <img src="{String(content.image.src)}" alt="{String(content.image)}" />
   

   참고: Preact에서는 className 대신 일반적으로 class를 사용합니다.

   useIntlayer 훅에 대해 더 알아보려면 문서를 참고하세요 (preact-intlayer도 API가 유사합니다).

   기존 앱이 있다면, Intlayer Compiler와 extract 명령어를 사용하여 수천 개의 컴포넌트를 몇 초 만에 변환할 수 있습니다.

6. 6

   콘텐츠의 언어 변경하기

   선택사항

   콘텐츠의 언어를 변경하려면 useLocale 훅에서 제공하는 setLocale 함수를 사용할 수 있습니다. 이 함수는 애플리케이션의 로케일을 설정하고 그에 따라 콘텐츠를 업데이트할 수 있게 해줍니다.

   src/components/LocaleSwitcher.tsx

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import type { FunctionalComponent } from "preact";
   import { Locales } from "intlayer";
   import { useLocale } from "preact-intlayer";
   
   const LocaleSwitcher: FunctionalComponent = () => {
     const { setLocale } = useLocale();
   
     return (
       <button onClick={() => setLocale(Locales.ENGLISH)}>
         Change Language to English
       </button>
     );
   };
   
   export default LocaleSwitcher;
   

   useLocale 훅에 대해 더 알아보려면 문서를 참조하세요 (preact-intlayer와 API가 유사합니다).

7. 7

   애플리케이션에 로컬라이즈된 라우팅 추가

   선택사항

   이 단계의 목적은 각 언어별로 고유한 경로를 만드는 것입니다. 이는 SEO 및 SEO 친화적인 URL에 유용합니다. 예시:

   plaintext

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   - https://example.com/about
   - https://example.com/es/about
   - https://example.com/fr/about
   

   기본적으로 기본 로케일에 대해서는 경로에 접두사가 붙지 않습니다. 기본 로케일에도 접두사를 붙이려면 구성에서 routing.mode 옵션을 "prefix-all"로 설정할 수 있습니다. 자세한 내용은 구성 문서를 참조하세요.

   애플리케이션에 로컬라이즈된 라우팅을 추가하려면, 애플리케이션의 경로를 래핑하고 로케일 기반 라우팅을 처리하는 LocaleRouter 컴포넌트를 만들 수 있습니다. 다음은 preact-iso를 사용한 예시입니다:

   src/components/LocaleRouter.tsx

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { localeMap } from "intlayer";
   import { IntlayerProvider } from "preact-intlayer";
   import { LocationProvider, Router, Route } from "preact-iso";
   import type { ComponentChildren, FunctionalComponent } from "preact";
   
   /**
    * 로케일별 경로를 설정하는 라우터 컴포넌트입니다.
    * preact-iso를 사용하여 내비게이션을 관리하고 로컬라이즈된 컴포넌트를 렌더링합니다.
    */
   export const LocaleRouter: FunctionalComponent<{
     children: ComponentChildren;
   }> = ({ children }) => (
     <LocationProvider>
       <Router>
         {localeMap(({ locale, urlPrefix }) => ({ locale, urlPrefix }))
           .sort((a, b) => b.urlPrefix.length - a.urlPrefix.length)
           .map(({ locale, urlPrefix }) => (
             <Route
               key={locale}
               path={`${urlPrefix}/:rest*`}
               component={() => (
                 <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
               )}
             />
           ))}
       </Router>
     </LocationProvider>
   );
   

   그런 다음 애플리케이션에서 LocaleRouter 컴포넌트를 사용할 수 있습니다:

   src/app.tsx

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { LocaleRouter } from "./components/LocaleRouter";
   import type { FunctionalComponent } from "preact";
   
   // ... AppContent 컴포넌트
   
   const App: FunctionalComponent = () => (
     <LocaleRouter>
       <AppContent />
     </LocaleRouter>
   );
   
   export default App;
   

   동시에 intlayerProxy를 사용하여 애플리케이션에 서버 측 라우팅을 추가할 수 있습니다. 이 플러그인은 URL 기반으로 현재 로케일을 자동으로 감지하고 적절한 로케일 쿠키를 설정합니다. 로케일이 지정되지 않으면 플러그인은 사용자의 브라우저 언어 설정을 기반으로 가장 적절한 로케일을 결정합니다. 로케일이 감지되지 않으면 기본 로케일로 리다이렉트됩니다.

   intlayerProxy를 프로덕션에서 사용하려면 vite-intlayer 패키지를 devDependencies에서 dependencies로 변경해야 합니다.

   Intlayer v9부터 intlayerProxy()는 intlayer() 플러그인에 직접 번들되어 있으며 routing.enableProxy 옵션(기본값: true)을 통해 기본적으로 활성화됩니다. 아래와 같이 별도로 등록하는 것은 이제 선택 사항입니다 — 하위 호환성과 플러그인 순서를 제어해야 하는 설정을 위해 유지됩니다. routing.enableProxy: false로 설정하여 선택 해제할 수 있습니다. v9 release notes를 참조하세요.

   vite.config.ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   import preact from "@preact/preset-vite";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [
       preact(),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

8. 8

   로캘이 변경될 때 URL 변경

   선택사항

   로캘이 변경될 때 URL을 변경하려면 useLocale 훅에서 제공하는 onLocaleChange 속성을 사용할 수 있습니다. 이와 동시에 preact-iso의 useLocation에서 제공하는 route 메서드를 사용하여 URL 경로를 업데이트할 수 있습니다.

   src/components/LocaleSwitcher.tsx

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { useLocation } from "preact-iso";
   import {
     Locales,
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
   } from "intlayer";
   import { useLocale } from "preact-intlayer";
   import type { FunctionalComponent } from "preact";
   
   const LocaleSwitcher: FunctionalComponent = () => {
     const { url, route } = useLocation();
     const { locale, availableLocales, setLocale } = useLocale({
       onLocaleChange: (newLocale) => {
         // 업데이트된 로캘로 URL 구성
         // 예시: /es/about?foo=bar
         const pathWithLocale = getLocalizedUrl(url, newLocale);
   
         // URL 경로 업데이트
         route(pathWithLocale, true); // true는 교체(replace)를 의미
       },
     });
   
     return (
       <div>
         <button popovertarget="localePopover">{getLocaleName(locale)}</button>
         <div id="localePopover" popover="auto">
           {availableLocales.map((localeItem) => (
             <a
               href={getLocalizedUrl(url, localeItem)}
               hreflang={localeItem}
               aria-current={locale === localeItem ? "page" : undefined}
               onClick={(e) => {
                 e.preventDefault();
                 setLocale(localeItem);
                 // 로캘 설정 후의 프로그래밍 방식 내비게이션은 onLocaleChange에서 처리됩니다.
               }}
               key={localeItem}
             >
               <span>
                 {/* 로캘 - 예: FR */}
                 {localeItem}
               </span>
               <span>
                 {/* 해당 로캘 자체에서의 언어명 - 예: Français */}
                 {getLocaleName(localeItem, localeItem)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* 현재 로캘에서의 언어명 - 예: 현재 로캘이 Locales.SPANISH일 때 Francés */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir="ltr" lang={Locales.ENGLISH}>
                 {/* 영어에서의 언어명 - 예: French */}
                 {getLocaleName(localeItem, Locales.ENGLISH)}
               </span>
             </a>
           ))}
         </div>
       </div>
     );
   };
   
   export default LocaleSwitcher;
   

   문서 참조:

   - useLocale 훅 (API는 preact-intlayer와 유사합니다)> - getLocaleName 훅> - getLocalizedUrl 훅> - getHTMLTextDir 훅> - hreflang 속성> - lang 속성> - dir 속성> - aria-current 속성> - Popover API

   다음은 설명과 개선된 코드 예제가 추가된 업데이트된 Step 9입니다:

   ---

9. 9

   HTML 언어 및 방향 속성 전환

   선택사항

   애플리케이션이 다국어를 지원할 때, 현재 로케일에 맞춰 <html> 태그의 lang 및 dir 속성을 업데이트하는 것이 중요합니다. 이를 통해 다음을 보장할 수 있습니다:

   • 접근성: 화면 낭독기 및 보조 기술은 정확한 발음과 콘텐츠 해석을 위해 올바른 lang 속성에 의존합니다.
   • 텍스트 렌더링: dir (방향) 속성은 텍스트가 올바른 순서로 렌더링되도록 보장하여(예: 영어는 왼쪽에서 오른쪽, 아랍어나 히브리어는 오른쪽에서 왼쪽) 가독성에 필수적입니다.
   • SEO:搜索引擎은 lang 속성을 사용하여 페이지의 언어를 결정하며, 이는 검색 결과에서 적절한 로컬라이즈된 콘텐츠를 제공하는 데 도움이 됩니다.

   로케일이 변경될 때 이러한 속성을 동적으로 업데이트함으로써, 지원되는 모든 언어에서 사용자에게 일관되고 접근 가능한 경험을 보장할 수 있습니다.

   훅 구현하기

   HTML 속성을 관리하기 위한 커스텀 훅을 만듭니다. 이 훅은 로케일 변경을 감지하고 그에 따라 속성을 업데이트합니다:

   src/hooks/useI18nHTMLAttributes.tsx

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { useEffect } from "preact/hooks";
   import { useLocale } from "preact-intlayer";
   import { getHTMLTextDir } from "intlayer";
   
   /**
    * 현재 로케일에 따라 HTML <html> 요소의 `lang` 및 `dir` 속성을 업데이트합니다.
    * - `lang`: 브라우저와 검색 엔진에 페이지 언어를 알립니다.
    * - `dir`: 올바른 읽기 순서를 보장합니다 (예: 영어는 'ltr', 아랍어는 'rtl').
    *
    * 이 동적 업데이트는 올바른 텍스트 렌더링, 접근성 및 SEO에 필수적입니다.
    */
   export const useI18nHTMLAttributes = () => {
     const { locale } = useLocale();
   
     useEffect(() => {
       // 언어 속성을 현재 로케일로 업데이트합니다.
       document.documentElement.lang = locale;
   
       // 현재 로케일에 따라 텍스트 방향을 설정합니다.
       document.documentElement.dir = getHTMLTextDir(locale);
     }, [locale]);
   };
   

   애플리케이션에서 훅 사용하기

   로케일이 변경될 때마다 HTML 속성이 업데이트되도록 메인 컴포넌트에 훅을 통합하세요:

   src/app.tsx

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import type { FunctionalComponent } from "preact";
   import { IntlayerProvider } from "preact-intlayer"; // AppContent에서 필요할 경우 useIntlayer는 이미 가져옴
   import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
   import "./app.css";
   // 5단계에서의 AppContent 정의
   
   const AppWithHooks: FunctionalComponent = () => {
     // 로케일에 따라 <html> 태그의 lang 및 dir 속성을 업데이트하기 위해 훅을 적용합니다.
     useI18nHTMLAttributes();
   
     // AppContent가 5단계의 메인 콘텐츠 표시 컴포넌트라고 가정합니다.
     return <AppContent />;
   };
   
   const App: FunctionalComponent = () => (
     <IntlayerProvider>
       <AppWithHooks />
     </IntlayerProvider>
   );
   
   export default App;
   

   이러한 변경사항을 적용하면 애플리케이션은 다음을 수행합니다:

   • 언어 (lang) 속성이 현재 locale을 정확하게 반영하도록 하세요. 이는 SEO와 브라우저 동작에 중요합니다.
   • 다양한 읽기 순서를 가진 언어에 대해 텍스트 방향 (dir)을 조정하여 가독성과 사용성을 향상시키세요.
   • 보조 기술이 최적으로 작동할 수 있도록 더욱 접근 가능한 경험을 제공하세요.
10. 10

    로컬라이즈된 링크 컴포넌트 만들기

    선택사항

    애플리케이션의 내비게이션이 현재 로케일을 존중하도록 하려면, 커스텀 Link 컴포넌트를 만들 수 있습니다. 이 컴포넌트는 내부 URL에 자동으로 현재 언어 접두사를 붙입니다.

    이 동작은 여러 가지 이유로 유용합니다:

    • SEO 및 사용자 경험: 로컬라이즈된 URL은 검색 엔진이 언어별 페이지를 올바르게 색인화하도록 돕고 사용자에게 선호하는 언어로 콘텐츠를 제공합니다.
    • 일관성: 애플리케이션 전반에서 로컬라이즈된 링크를 사용함으로써 내비게이션이 현재 로케일 내에 머물도록 보장하여 예기치 않은 언어 전환을 방지합니다.
    • 유지보수성: 로컬라이제이션 로직을 단일 컴포넌트에 집중시켜 URL 관리를 단순화합니다.

    아래는 Preact에서의 로컬라이즈된 Link 컴포넌트 구현 예시입니다:

    src/components/Link.tsx

    콘텐츠 복사

    코드 복사

    코드를 클립보드에 복사

    import { getLocalizedUrl } from "intlayer";
    import { useLocale } from "preact-intlayer";
    import { forwardRef } from "preact/compat";
    import type { JSX } from "preact";
    
    export interface LinkProps extends JSX.HTMLAttributes<HTMLAnchorElement> {
      href: string;
    }
    
    /**
     * 주어진 URL이 외부 링크인지 확인하는 유틸리티 함수입니다.
     * URL이 http:// 또는 https://로 시작하면 외부 링크로 간주됩니다.
     */
    export const checkIsExternalLink = (href?: string): boolean =>
      /^https?:\/\//.test(href ?? "");
    
    /**
     * 현재 로케일에 따라 href 속성을 조정하는 커스텀 Link 컴포넌트입니다.
     * 내부 링크의 경우, `getLocalizedUrl`을 사용하여 URL에 로케일 접두사를 붙입니다 (예: /fr/about).
     * 이를 통해 내비게이션이 동일한 로케일 컨텍스트 내에서 유지되도록 보장합니다.
     */
    export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
      ({ href, children, ...props }, ref) => {
        const { locale } = useLocale();
        const isExternalLink = checkIsExternalLink(href);
    
        // 내부 링크이고 유효한 href가 제공된 경우, 로컬라이즈된 URL을 가져옵니다.
        const hrefI18n =
          href && !isExternalLink ? getLocalizedUrl(href, locale) : href;
    
        return (
          <a href={hrefI18n} ref={ref} {...props}>
            {children}
          </a>
        );
      }
    );
    
    Link.displayName = "Link";
    

    작동 방식

    • 외부 링크 감지:
      헬퍼 함수 checkIsExternalLink는 URL이 외부 링크인지 여부를 결정합니다. 외부 링크는 로컬라이제이션이 필요하지 않기 때문에 변경되지 않습니다.
    • 현재 로케일 검색:
      useLocale 훅은 현재 로케일(예: 프랑스어의 경우 fr)을 제공합니다.
    • URL 로컬라이징:
      내부 링크(즉, 외부가 아닌)의 경우, getLocalizedUrl을 사용하여 자동으로 URL에 현재 로케일을 접두사로 추가합니다. 이는 사용자가 프랑스어를 사용 중인 경우 href로 /about을 전달하면 /fr/about으로 변환된다는 의미입니다.
    • 링크 반환:
      컴포넌트는 로컬라이징된 URL과 함께 <a> 요소를 반환하여 네비게이션이 로케일과 일치하도록 보장합니다.
11. 11

    Markdown 및 HTML 렌더링

    선택사항

    Intlayer는 Preact에서 Markdown 및 HTML 콘텐츠 렌더링을 지원합니다.

    .use() 메서드를 사용하여 Markdown 및 HTML 콘텐츠의 렌더링을 커스터마이징할 수 있습니다. 이 메서드를 사용하면 특정 태그의 기본 렌더링을 재정의할 수 있습니다.

    tsx

    콘텐츠 복사

    코드 복사

    코드를 클립보드에 복사

    import { useIntlayer } from "preact-intlayer";
    
    const { myMarkdownContent, myHtmlContent } = useIntlayer("my-component");
    
    // ...
    
    return (
      <div>
        {/* 기본 렌더링 */}
        {myMarkdownContent}
    
        {/* Markdown에 대한 커스텀 렌더링 */}
        {myMarkdownContent.use({
          h1: (props) => <h1 style={{ color: "red" }} {...props} />,
        })}
    
        {/* HTML에 대한 기본 렌더링 */}
        {myHtmlContent}
    
        {/* HTML에 대한 커스텀 렌더링 */}
        {myHtmlContent.use({
          b: (props) => <strong style={{ color: "blue" }} {...props} />,
        })}
      </div>
    );
    

12. 12

    컴포넌트의 콘텐츠 추출

    선택사항

    기존 codebase가 있는 경우 수천 개의 파일을 변환하는 것은 시간이 많이 걸릴 수 있습니다.

    이 프로세스를 용이하게 하기 위해 Intlayer는 컴포넌트를 변환하고 콘텐츠를 추출할 수 있는 compiler / extractor를 제공합니다.

    이를 설정하려면 intlayer.config.ts 파일에 compiler 섹션을 추가할 수 있습니다:

    intlayer.config.ts

    콘텐츠 복사

    코드 복사

    코드를 클립보드에 복사

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... 나머지 설정
      compiler: {
        /**
         * 컴파일러를 활성화할지 여부를 나타냅니다.
         */
        enabled: true,
    
        /**
         * 출력 파일 경로를 정의합니다.
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * 변환 후 컴포넌트를 저장할지 여부를 나타냅니다.
         *
         * - `true`인 경우, 컴파일러는 컴포넌트 파일을 디스크에 다시 작성합니다. 따라서 변환이 영구적이고 컴파일러는 다음 프로세스에서 변환을 건너뜁니다. 이렇게 하면 컴파일러가 앱을 변환한 후 제거할 수 있습니다.
         *
         * - `false`인 경우, 컴파일러는 빌드 출력에만 `useIntlayer()` 함수 호출을 주입하고 기본 codebase를 그대로 유지합니다. 변환은 메모리에서만 수행됩니다.
         */
        saveComponents: false,
    
        /**
         * 사전 키 접두사
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    추출 명령Babel 컴파일러

    추출기를 실행하여 컴포넌트를 변환하고 콘텐츠를 추출합니다.

    bash

    콘텐츠 복사

    코드 복사

    코드를 클립보드에 복사

    npx intlayer extract
    

    v9부터 intlayerCompiler는 intlayer 플러그인에 포함되어 있습니다. 따라서 수동으로 추가할 필요가 없습니다.

    intlayerCompiler 플러그인을 포함하도록 vite.config.ts를 업데이트합니다:

    vite.config.ts

    콘텐츠 복사

    코드 복사

    코드를 클립보드에 복사

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // 컴파일러 플러그인 추가
      ],
    });
    

    bash

    콘텐츠 복사

    코드 복사

    코드를 클립보드에 복사

    npm run build # 또는 npm run dev
    

(선택) 사이트맵과 robots.txt(빌드 시 생성)

Intlayer는 generateSitemap과 getMultilingualUrls로 크롤러용 다국어 sitemap.xml과 robots.txt를 만들어 public/에 자동으로 쓸 수 있습니다. 보통 Vite 실행 전에 작은 Node 스크립트를 돌립니다(예: npm predev / prebuild).

사이트맵

Intlayer 사이트맵 생성기는 로케일 설정을 반영하고 크롤러용 메타데이터를 포함합니다.

생성된 사이트맵은 xhtml:link(hreflang)를 지원합니다. 단순 URL 나열이 아니라 각 페이지의 모든 언어 버전을 양방향으로 연결합니다(예: /about, /fr/about, /about?lang=fr - 라우팅 모드에 따름).

Robots.txt

getMultilingualUrls로 Disallow가 민감 경로의 모든 현지화 변형에 적용되도록 하세요.

1. 프로젝트 루트에 generate-seo.mjs 추가

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { generateSitemap, getMultilingualUrls } from "intlayer";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(
  /\/$/,
  ""
);

const pathList = [
  { path: "/", changefreq: "daily", priority: 1.0 },
  { path: "/about", changefreq: "monthly", priority: 0.7 },
];

const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });
fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);

const getAllMultilingualUrls = (urls) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));

const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);

const robotsTxt = [
  "User-agent: *",
  "Allow: /",
  ...disallowedPaths.map((path) => `Disallow: ${path}`),
  "",
  `Sitemap: ${SITE_URL}/sitemap.xml`,
].join("\n");

fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);

console.log("SEO files generated successfully.");

스크립트가 intlayer를 import하려면 패키지가 설치되어 있어야 합니다. 프로덕션에서는 환경 변수 SITE_URL을 설정하세요(CI 등).

Node ESM에는 generate-seo.mjs 사용을 권장합니다. generate-seo.js를 쓰면 package.json의 "type": "module" 등으로 ESM을 켜세요.

2. Vite 전에 스크립트 실행

{
  "scripts": {
    "dev": "vite",
    "prebuild": "node generate-seo.mjs",
    "build": "vite build",
    "preview": "vite preview"
  }
}

pnpm이나 yarn을 쓰면 명령을 맞게 바꾸세요. CI에서 호출해도 됩니다.

TypeScript 구성

Intlayer는 모듈 augmentation을 사용하여 TypeScript의 이점을 활용하고 codebase를 더욱 강화합니다.

TypeScript 설정에 자동 생성된 타입이 포함되어 있는지 확인하세요.

{
  // ... 기존 TypeScript 설정
  "compilerOptions": {
    // ...
    "jsx": "react-jsx",
    "jsxImportSource": "preact", // Preact 10+ 권장
    // ...
  },
  "include": [
    // ... 기존 TypeScript 설정
    ".intlayer/**/*.ts", // 자동 생성된 타입 포함
  ],
}

preset-vite의 기본값을 사용하지 않는 경우, 특히 이전 Preact 버전의 jsxFactory/jsxFragmentFactory에 대해 tsconfig.json이 Preact에 맞게 설정되어 있는지 확인하세요.

Git 구성

Intlayer에서 생성된 파일을 무시하는 것이 좋습니다. 이를 통해 Git 저장소에 커밋하는 것을 피할 수 있습니다.

이를 위해 .gitignore 파일에 다음 지침을 추가할 수 있습니다:

# Intlayer에서 생성된 파일 무시
.intlayer

VS Code Extension

Intlayer를 사용한 개발 경험을 개선하기 위해 공식 Intlayer VS Code Extension을 설치할 수 있습니다.

VS Code Marketplace에서 설치

이 extension은 다음을 제공합니다:

• 번역 키에 대한 자동완성.
• 누락된 번역에 대한 실시간 오류 감지.
• 번역된 콘텐츠의 인라인 미리보기.
• 번역을 쉽게 만들고 업데이트하기 위한 빠른 작업.

extension 사용 방법에 대한 자세한 내용은 Intlayer VS Code Extension 문서를 참조하세요.

더 나아가기

더 나아가려면, 비주얼 에디터를 구현하거나 CMS를 사용하여 콘텐츠를 외부화할 수 있습니다.