Intlayer 컴파일러 | i18n을 위한 자동화된 콘텐츠 추출

Intlayer 컴파일러란?

Intlayer 컴파일러는 애플리케이션의 국제화(i18n) 프로세스를 자동화하도록 설계된 강력한 도구입니다. 소스 코드(JSX, TSX, Vue, Svelte)에서 콘텐츠 선언을 스캔하고 추출하여 필요한 사전(dictionary) 파일을 자동으로 생성합니다. 이를 통해 콘텐츠를 컴포넌트와 함께 위치시킬 수 있으며, Intlayer가 사전의 관리 및 동기화를 처리합니다.

Intlayer 컴파일러를 사용하는 이유

• 자동화: 사전에 콘텐츠를 수동으로 복사-붙여넣기하는 작업을 제거합니다.

• Speed: 최적화된 콘텐츠 추출로 빌드 프로세스를 빠르게 유지합니다.

• 개발자 경험: 콘텐츠 선언을 사용 위치에 가깝게 유지하여 유지보수성을 개선합니다.

• 자동화: 콘텐츠를 사전에 수동으로 복사하여 붙여넣는 작업을 제거합니다.
• 속도: 빌드 프로세스가 빠르게 유지되도록 최적화된 콘텐츠 추출을 제공합니다.
• 개발자 경험: 콘텐츠 선언을 사용되는 위치에 그대로 유지하여 유지보수성을 향상시킵니다.
• 실시간 업데이트: 개발 중 즉각적인 피드백을 위한 Hot Module Replacement(HMR)를 지원합니다.

더 깊은 비교를 원한다면 Compiler vs. Declarative i18n 블로그 게시물을 참조하세요.

Intlayer 컴파일러를 사용하지 않는 이유

컴파일러는 훌륭한 "바로 작동" 경험을 제공하지만, 인지해야 할 몇 가지 트레이드오프도 도입합니다:

• 휴리스틱 모호성: 컴파일러는 사용자 지향 콘텐츠와 애플리케이션 로직(예: className="active", 상태 코드, 제품 ID)을 추측해야 합니다. 복잡한 코드베이스에서는 이것이 오탐지 또는 누락된 문자열로 이어질 수 있으며, 수동 주석 및 예외 처리가 필요합니다.

• 정적 추출만: 컴파일러 기반 추출은 정적 분석에 의존합니다. 런타임에만 존재하는 문자열(API 오류 코드, CMS 필드 등)은 컴파일러만으로는 발견하거나 번역할 수 없으므로 여전히 보완적인 런타임 i18n 전략이 필요합니다.

• 정적 전용 추출: 컴파일러 기반 추출은 정적 분석에 의존합니다. 런타임에만 존재하는 문자열(API 오류 코드, CMS 필드 등)은 컴파일러만으로는 발견하거나 번역할 수 없으므로, 여전히 보완적인 런타임 i18n 전략이 필요합니다.

더 깊은 아키텍처 비교를 위해서는 블로그 게시물 Compiler vs. Declarative i18n을 참조하세요.

대안으로, 콘텐츠에 대한 완전한 제어를 유지하면서 i18n 프로세스를 자동화하기 위해 Intlayer는 자동 추출 명령 intlayer extract(CLI 문서 참조) 또는 Intlayer VS Code 확장의 Intlayer: extract content to Dictionary 명령(VS Code 확장 문서 참조)도 제공합니다.

사용법

The quickest way to wire the compiler in is the interactive setup: run npx intlayer init --interactive and select Compiler. On Vite there is nothing to configure — the compiler is plugged in directly through the intlayerCompiler() plugin. On Next.js the command scaffolds the babel.config.js shown below. The non-interactive intlayer init leaves the compiler setup untouched.

npm install vite-intlayer

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

# Vue용
npm install @intlayer/vue-compiler

# Svelte용
npm install @intlayer/svelte-compiler

npm install @intlayer/babel

const {
  intlayerExtractBabelPlugin,
  intlayerOptimizeBabelPlugin,
  getExtractPluginOptions,
  getOptimizePluginOptions,
} = require("@intlayer/babel");

module.exports = {
  presets: ["next/babel"],
  plugins: [
    // 컴포넌트에서 콘텐츠를 추출하여 사전으로 변환
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
    // useIntlayer를 직접 사전 임포트로 대체하여 임포트 최적화
    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
  ],
};

사용자 정의 구성

컴파일러 동작을 사용자 정의하려면 프로젝트 루트에 있는 intlayer.config.ts 파일을 업데이트할 수 있습니다.

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  compiler: {
    /**
     * 컴파일러 활성화 여부를 나타냅니다.
     * 개발 중에 컴파일러를 건너뛰고 시작 시간을 단축하려면 'build-only'로 설정하십시오.
     */
    enabled: true,

    /**
     * 출력 파일 경로를 정의합니다. `outputDir`을 대체합니다.
     *
     * - `./` 경로는 컴포넌트 디렉터리를 기준으로 해결됩니다.
     * - `/` 경로는 프로젝트 루트(`baseDir`)를 기준으로 해결됩니다.
     *
     * - 경로에 `{{locale}}` 변수를 넣으면 언어별로 분리된 사전 생성이 활성화됩니다.
     *
     * 예시:
     * ```ts
     * {
     *   // 컴포넌트 옆에 다국어 .content.ts 파일 생성
     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
     *
     *   // output: './{{fileName}}{{extension}}', // 문자열 템플릿을 사용한 동일한 표현
     * }
     * ```
     *
     * ```ts
     * {
     *   // 프로젝트 루트의 언어별 중앙 집중식 JSON 파일 생성
     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
     *
     *   // output: '/locales/{{locale}}/{{key}}.content.json', // 문자열 템플릿을 사용한 동일한 표현
     * }
     * ```
     *
     * 변수 목록:
     *   - `fileName`: 파일 이름.
     *   - `key`: 콘텐츠 키.
     *   - `locale`: 콘텐츠 로케일.
     *   - `extension`: 파일 확장자.
     *   - `componentFileName`: 컴포넌트 파일 이름.
     *   - `componentExtension`: 컴포넌트 파일 확장자.
     *   - `format`: 사전 형식.
     *   - `componentFormat`: 컴포넌트 사전 형식.
     *   - `componentDirPath`: 컴포넌트 디렉터리 경로.
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * 변환된 후 컴포넌트를 저장할지 여부를 나타냅니다.
     * 이렇게 하면 컴파일러를 한 번만 실행하여 앱을 변환한 다음 제거할 수 있습니다.
     */
    saveComponents: false,

    /**
     * 생성된 파일에 콘텐츠만 삽입합니다. 로케일당 i18next 또는 ICU MessageFormat JSON 출력에 유용합니다.
     *
     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`
     */
    noMetadata: false,

    /**
     * 사전 키 접두사
     */
    dictionaryKeyPrefix: "", // 추출된 사전 키에 선택적 접두사 추가
  },
};

export default config;

컴파일러 구성 참조

다음 속성은 intlayer.config.ts 파일의 compiler 블록에서 구성할 수 있습니다.

• enabled:

  • 형식: boolean | 'build-only'
  • 기본값: true
  • 설명: 컴파일러 활성화 여부를 나타냅니다.

• dictionaryKeyPrefix:

  • 형식: string
  • 기본값: ''
  • 설명: 추출된 사전 키의 접두사.

• transformPattern:

  • 형식: string | string[]
  • 기본값: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
  • 설명: (사용 중단됨: 대신 build.traversePattern을 사용하세요) 최적화할 코드를 탐색하는 패턴.

• excludePattern:

  • 형식: string | string[]
  • 기본값: ['**/node_modules/**']
  • 설명: (사용 중단됨: 대신 build.traversePattern을 사용하세요) 최적화에서 제외할 패턴.

• output:

  • 형식: FilePathPattern
  • 기본값: ({ key }) => 'compiler/${key}.content.json'
  • 설명: 출력 파일 경로를 정의합니다. outputDir을 대체합니다. {{locale}}, {{key}}, {{fileName}}, {{extension}}, {{format}}, {{dirPath}}, {{componentFileName}}, {{componentExtension}}, {{componentFormat}}와 같은 동적 변수를 처리합니다. 'my/{{var}}/path' 형식을 사용하여 문자열로 설정하거나 함수로 설정할 수 있습니다.
  • 참고: ./**/* 경로는 컴포넌트를 기준으로 해결됩니다. /**/* 경로는 Intlayer baseDir을 기준으로 해결됩니다.
  • 참고: 로케일이 경로에 정의된 경우 사전은 로케일별로 생성됩니다.
  • 예시: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

• noMetadata:

  • 형식: boolean
  • 기본값: false
  • 설명: 메타데이터를 파일에 저장할지 여부를 나타냅니다. true인 경우 컴파일러는 사전의 메타데이터(키, 콘텐츠 래퍼)를 저장하지 않습니다. 로케일별 i18next 또는 ICU MessageFormat JSON 출력에 유용합니다.
  • 참고: loadJSON 플러그인과 함께 사용할 때 유용합니다.
  • 예시: true인 경우: json { "key": "value" } false인 경우: json { "key": "value", "content": { "key": "value" } }

• saveComponents:

  • 형식: boolean
  • 기본값: false
  • 설명: 변환된 후 컴포넌트를 저장할지 여부를 나타냅니다.

누락된 번역 채우기

Intlayer는 누락된 번역을 채우는 데 도움이 되는 CLI 도구를 제공합니다. intlayer 명령을 사용하여 코드에서 누락된 번역을 테스트하고 채울 수 있습니다.

npx intlayer test         # 누락된 번역이 있는지 테스트

npx intlayer fill         # 누락된 번역 채우기

추출

Intlayer는 코드에서 콘텐츠를 추출하는 데 도움이 되는 CLI 도구를 제공합니다. intlayer extract 명령을 사용하여 코드에서 콘텐츠를 추출할 수 있습니다.

npx intlayer extract

자세한 내용은 CLI 문서 를 참조하세요.