작가:
    Aymeric PINEAU
    생성:2025-03-01마지막 업데이트:2026-10-27

    콘텐츠 테스트하기

    이 가이드는 사전이 완전한지 자동으로 확인하고, 배포 전에 누락된 번역을 잡아내며, 앱에서 현지화된 UI를 테스트하는 방법을 보여줍니다.

    테스트할 수 있는 항목

    • 누락된 번역: 필수 로케일이 사전에서 누락된 경우 CI 실패 처리.
    • 현지화된 UI 렌더링: 특정 로케일 제공자와 함께 컴포넌트를 렌더링하고, 표시된 텍스트/속성을 검증.
    • 빌드 시 감사: npx intlayer content test를 로컬 또는 CI에서 실행하세요. 필수 번역이 누락되면 0이 아닌 코드로 종료됩니다.

    빠른 시작: CLI를 통한 감사

    프로젝트 루트에서 감사를 실행하세요:

    bash
    npx intlayer content test

    유용한 플래그:

    • --env-file [path]: 파일에서 환경 변수를 로드합니다.
    • -e, --env [name]: 환경 프로필을 선택합니다.
    • --base-dir [path]: 해석을 위한 앱 기본 디렉터리를 설정합니다.
    • --verbose: 자세한 로그를 표시합니다.
    • --prefix [label]: 로그 라인에 접두사를 붙입니다.

    필수 로케일이 누락되면 명령이 코드 1로 종료되고, 그렇지 않으면 0으로 종료됩니다(구성의 requiredLocales 참조). CI 작업이나 커밋 훅을 실패시키는 데 직접 사용할 수 있습니다. 아래의 프로그래밍 방식 테스트는 선택적 대안입니다.

    프로그래밍 방식 테스트 (Vitest/Jest)

    Intlayer CLI API를 사용하여 필수 로케일에 누락된 번역이 없는지 확인하세요.

    /* @vitest-environment node */
import { listMissingTranslations } from "intlayer/cli";
import { describe, expect, it } from "vitest";

describe("번역", () => {
  it("필수 로케일이 누락되지 않음", () => {
    const result = listMissingTranslations();

    if (result.missingRequiredLocales.length > 0) {
      // 테스트가 로컬 또는 CI에서 실패할 때 도움이 됨
      console.log(result.missingTranslations);
    }

    expect(result.missingRequiredLocales).toHaveLength(0);
  });
});

    Jest 동등 코드:

    import { listMissingTranslations } from "intlayer/cli";

test("필수 로케일이 누락되지 않음", () => {
  const result = listMissingTranslations();

  if (result.missingRequiredLocales.length > 0) {
    console.log(result.missingTranslations);
  }

  expect(result.missingRequiredLocales).toHaveLength(0);
});

    작동 방식:

    • Intlayer는 구성(locales, requiredLocales)과 선언된 사전을 읽고 다음을 보고합니다:
      • missingTranslations: 키별로 어떤 로케일이 누락되었고 어떤 파일에서 누락되었는지.
      • missingLocales: 누락된 모든 로케일의 합집합.
      • missingRequiredLocales: requiredLocales로 제한된 부분집합 (또는 requiredLocales가 설정되지 않은 경우 모든 로케일).

    지역화된 UI 테스트 (React / Next.js)

    Intlayer 프로바이더 하에 컴포넌트를 렌더링하고 화면에 보이는 내용을 검증합니다.

    React 예제 (Testing Library):

    tsx
    import { IntlayerProvider } from "react-intlayer/client";
import { render, screen } from "@testing-library/react";
import { MyComponent } from "./MyComponent";

test("renders localized title in English", () => {
  render(
    <IntlayerProvider locale="en-US">
      <MyComponent />
    </IntlayerProvider>
  );

  expect(screen.getByText("Expected English title")).toBeInTheDocument();
});

    Next.js (앱 라우터) 예제: 프레임워크 래퍼 사용:

    tsx
    import { IntlayerClientProvider } from "next-intlayer/client";
import { render, screen } from "@testing-library/react";
import { MyPage } from "./MyPage";

test("프랑스어로 현지화된 제목을 렌더링합니다", () => {
  render(
    <IntlayerClientProvider locale="fr-FR">
      <MyPage />
    </IntlayerClientProvider>
  );
  expect(
    screen.getByRole("heading", { name: "Titre attendu" })
  ).toBeInTheDocument();
});

    팁:

    • 속성(예: aria-label)에 대한 원시 문자열 값이 필요할 때는 React에서 useIntlayer가 반환하는 .value 필드에 접근하세요.
    • 단위 테스트 및 정리를 쉽게 하기 위해 사전을 컴포넌트와 함께 배치하세요.

    지속적 통합

    CI에서 CLI 감사를 실행하세요. 필수 번역이 누락되면 작업이 실패합니다.

    package.json:

    json
    {
  "scripts": {
    "test:i18n": "npx intlayer content test"
  }
}

    대안: Vitest

    json
    {
  "scripts": {
    "test:i18n": "vitest run"
  }
}

    GitHub Actions 예제:

    yaml
    name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx intlayer content test

    선택 사항: 테스트와 함께 사람이 읽기 쉬운 요약을 위해 CLI 감사를 실행하세요:

    bash
    npx intlayer content test --verbose

    문제 해결

    • Intlayer 구성에 locales 및 (선택적으로) requiredLocales가 정의되어 있는지 확인하세요.
    • 앱이 동적 또는 원격 사전을 사용하는 경우, 사전이 사용 가능한 환경에서 테스트를 실행하세요.
    • 혼합 모노레포의 경우, CLI가 올바른 애플리케이션 루트를 가리키도록 --base-dir을 사용하세요.
    자동 채우기번들 최적화