Next.js에서 Markdoc 현지화하기

Next.js 앱 라우터 애플리케이션에서 로캘별 Markdoc 문서와 별도의 사용자 인터페이스 카탈로그를 함께 라우팅하고, 불러오고, 번역하고, 렌더링합니다.

번역된 문서는 문서를 둘러싼 페이지와 언어가 일치해야 합니다. Next.js 사이트에서는 경로의 로캘에 따라 Markdoc 문서와 별도의 탐색용 사용자 인터페이스 카탈로그를 선택할 수 있습니다. 이 가이드에서는 해당 파일을 앱 라우터 페이지에 연결한 뒤 CLI로 번역하는 방법을 안내합니다.

Markdoc을 사용하는 기존 Next.js 앱 라우터 프로젝트를 준비하세요. 이 예제는 서버에서 로컬 파일을 읽으며, React 현지화 어댑터는 사용하지 않습니다.

로캘별 파일 구조 정하기 #

예를 들어 문서와 사용자 인터페이스 카탈로그를 다음과 같이 로캘별로 모아 둘 수 있습니다.

text
src/content/
  en/
    pages/home.mdoc
    blog/welcome.mdoc
    ui.json
  es/
    pages/home.mdoc
    blog/welcome.mdoc
    ui.json
src/app/[lang]/

콘텐츠 식별자로 쓰이는 슬러그는 그대로 유지하세요. 제목을 번역해도 home.mdoc의 이름까지 바꿀 필요는 없습니다. 의도적으로 슬러그를 현지화한다면 탐색 링크와 다른 언어 링크에 사용할 명시적인 매핑을 관리하세요. 본문을 번역한다고 이 매핑이 만들어지지는 않습니다.

파일 시스템 경로를 구성하기 전에 경로의 로캘과 문서 슬러그가 미리 정해 둔 값인지 확인하세요. 번역이 없을 때는 찾을 수 없음 응답을 반환할지, 원문 언어로 명시적으로 대체할지 정하세요. 아래 홈페이지 예제는 고정된 문서 이름을 사용하며, 지원하지 않는 로캘이거나 파일이 없으면 찾을 수 없음 응답을 반환합니다.

Markdoc 핸들러와 표시할 메타데이터 선택하기 #

프로젝트 루트에서 CLI를 설치하고 연결하세요.

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'src/content/en/pages/*.mdoc' --yes
lingo link

생성된 조직 및 로컬라이제이션 엔진 식별자를 .lingo/config.json에 그대로 두고, 원본 선택 설정 전체를 구성하세요.

json
{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es"],
  "files": [
    {
      "pattern": "src/content/en/pages/*.mdoc",
      "format": "markdoc",
      "translateFrontmatterFields": ["title", "description"]
    },
    {
      "pattern": "src/content/en/blog/*.mdoc",
      "format": "markdoc",
      "translateFrontmatterFields": ["title", "description"]
    },
    { "pattern": "src/content/en/ui.json" }
  ]
}

.mdoc는 Markdoc을 자동으로 선택하지만, 형식을 명시하면 설정 의도가 더 분명해집니다. 기존 프로젝트에서 Markdoc 구문을 .md에 저장한다면 format: "markdoc"를 명시적으로 설정하세요. 그렇지 않으면 확장자 감지에 따라 일반 마크다운이 선택됩니다. 이 차이는 사용자 정의 태그와 선택한 컴포넌트 속성을 처리할 때 중요합니다.

독자에게 표시되는 프런트매터 필드를 번역 대상으로 신중하게 선택하세요. 콘텐츠 정책상 특정 변환이 필요한 경우가 아니라면 날짜, 작성자, 고정 식별자, 라우팅 메타데이터는 그대로 유지하세요. 컴포넌트 속성은 독자에게 표시되는 텍스트를 담고 있을 때만 번역 대상으로 선언하세요. 핸들러 동작은 Markdoc을, 파일 옵션 이름은 CLI 설정을 참고하세요. 문서 API 옵션은 다른 스키마를 사용합니다.

로캘마다 사용자 인터페이스 카탈로그를 하나씩 사용하세요. 다른 사이트 생성기의 파일 구조는 정적 콘텐츠를 참고하세요.

로캘 경로로 원문 홈페이지 렌더링하기 #

src/content/en/pages/home.mdoc의 YAML 프런트매터에 제목과 설명을 작성하고, 그 아래에 문서 본문을 추가하세요. src/content/en/ui.json에는 탐색 레이블로 사용할 {"home": "Home"}를 추가하세요. @markdoc/markdoc와 yaml가 아직 프로젝트 의존성에 없다면 설치하세요.

최소한의 구성으로 작성한 이 src/app/[lang]/page.tsx는 동일한 로딩 경로로 원문과 대상 언어 홈페이지를 읽습니다. 현재 앱 라우터의 프로미스 기반 경로 매개변수를 사용합니다.

tsx
import { readFile } from "node:fs/promises";
import path from "node:path";
import React from "react";
import Markdoc from "@markdoc/markdoc";
import { parse as parseYaml } from "yaml";
import { notFound } from "next/navigation";

export const runtime = "nodejs";

export default async function Page({
  params,
}: {
  params: Promise<{ lang: string }>;
}) {
  const { lang } = await params;
  if (lang !== "en" && lang !== "es") notFound();

  const root = path.join(process.cwd(), "src/content", lang);
  let rawDocument: string;
  let rawUi: string;
  try {
    [rawDocument, rawUi] = await Promise.all([
      readFile(path.join(root, "pages/home.mdoc"), "utf8"),
      readFile(path.join(root, "ui.json"), "utf8"),
    ]);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") notFound();
    throw error;
  }

  const ast = Markdoc.parse(rawDocument);
  const errors = Markdoc.validate(ast);
  if (errors.some(({ error }) => ["error", "critical"].includes(error.level))) {
    throw new Error("Invalid Markdoc document");
  }
  const metadata = parseYaml(ast.attributes.frontmatter ?? "");
  const ui = JSON.parse(rawUi);
  if (typeof metadata?.title !== "string" || typeof ui.home !== "string") {
    throw new Error("Missing homepage title or navigation label");
  }

  const tree = Markdoc.transform(ast);
  return (
    <main lang={lang}>
      <nav><a href={`/${lang}`}>{ui.home}</a></nav>
      <h1>{metadata.title}</h1>
      {Markdoc.renderers.react(tree, React)}
    </main>
  );
}

먼저 /en를 여세요. 이 예제는 표준 Markdoc 노드를 사용합니다. 사용자 정의 태그를 쓰는 사이트라면 실제 사이트 설정을 Markdoc.validate와 Markdoc.transform 모두에 전달한 다음, 이름이 지정된 React 컴포넌트를 Markdoc.renderers.react에 제공하세요. 필요한 변수도 명시적으로 전달하세요. 번역 핸들러는 주석을 보존하지만 사이트의 태그 스키마까지 제공하지는 않습니다.

검증된 이 로더를 메타데이터 생성과 다른 경로에도 확장해 사용하세요. 동적 문서 슬러그를 사용한다면 경로에서 파일을 읽기 전에 미리 파악된 콘텐츠 목록에서 해당 항목을 확인하세요. Node 파일 시스템 로더를 사용하려면 배포 결과물에 콘텐츠 파일이 포함되어야 하므로, 프로덕션 빌드에 해당 파일이 포함되는지 확인하세요. 파일 시스템에 접근할 수 없는 엣지 배포 환경에서는 다른 저장소 읽기 방식이 필요합니다.

로캘 협상과 탐색 동작 일치시키기 #

로캘이 없는 경로에는 애플리케이션에 명시적으로 설정된 선호 값을 적용하거나, Accept-Language를 바탕으로 지원되는 로캘을 협상하세요. 우선순위 가중치와 지역 태그를 파싱한 뒤, 나머지 경로는 유지하면서 해당 [lang] 경로로 리디렉션하세요.

지원되는 로캘이 이미 포함된 경로, API 요청, Next.js 내부 리소스, 정적 파일은 리디렉션하지 마세요. 매처의 범위가 너무 넓으면 리디렉션이 반복되거나 이미지 요청이 문서 경로로 리디렉션될 수 있습니다. 설치된 Next.js 버전의 라우팅 가로채기 API에서 지원하는 제외 규칙을 적용하세요. 이전 프로젝트에서는 미들웨어를 사용하지만, 최신 버전에서는 이름이 바뀐 프록시 규칙을 사용할 수 있습니다. 예전 파일 이름을 모든 경우에 통하는 해법처럼 복사하지 말고, 설치된 버전에 맞춰 동작과 테스트를 관리하세요.

미리 정의한 경로 매핑을 바탕으로 내부 링크와 다른 언어 링크를 만드세요. 언어 전환기에 표시하기 전에 각 대상이 실제로 존재하는지 확인하세요. 제목을 번역하면 자동 생성되는 식별자가 달라질 수 있으므로 제목 프래그먼트도 확인하세요.

문서가 있는 경로만 생성하기 #

정적 생성 시에는 실제 콘텐츠 목록을 바탕으로 지원되는 로캘과 슬러그의 조합을 나열하세요. 이 조합을 프로젝트의 generateStaticParams 흐름에 포함하고 생성된 경로를 확인하세요. 동적으로 불러오는 경우에도 요청 시점에 같은 방식으로 콘텐츠 목록을 확인하고, 파일이 없을 때의 동작을 명시적으로 처리하세요. 번역이 있을 것이라 가정하고 로캘 목록만으로 모든 대상 경로를 생성하지 마세요.

lingo push --backfill-missing --wait로 아직 없는 대상 언어 파일을 번역하세요. 완료되면 src/content/es/pages/home.mdoc와 src/content/es/ui.json가 존재하는지 확인한 뒤, 동일한 로더로 /es를 여세요. 번역된 제목, 설명, 본문, 링크, 코드 블록, 사용자 정의 태그 구조를 점검하세요. 코드 예제와 동작을 제어하는 속성은 원문의 의미와 값을 유지해야 합니다.

대상 언어 파일을 로컬에서 수정한 내용을 덮어쓰지 않도록 보호해야 한다면 --wait 없이 제출하고, 결과를 가져오기 전에 lingo pull --dry-run를 확인하세요. 완료를 기다린 뒤 곧바로 파일에 반영하는 방식에는 이 확인 단계가 없습니다. 검토된 번역 보존하기를 따르세요.

번역을 정기적으로 실행하기 전에 페이지 검증하기 #

대상 로캘 경로를 직접 연 다음, 사이트 내 탐색으로도 이동해 보세요. 제목, 주변 인터페이스 요소, 메타데이터, 언어 전환기가 모두 의도한 로캘을 사용하는지 확인하세요. 사용자 정의 컴포넌트와 코드 예제를 점검하고, 내부 링크와 제목 프래그먼트 링크도 따라가 보세요. 번역된 파일을 대상으로 프로젝트의 기존 Next.js 빌드와 Markdoc 검증을 실행하세요.

원본, 승인된 대상 언어 파일, 설정, CLI의 Lockfile을 함께 보관하세요. 이후 원본이 바뀌면 일반적인 lingo push --wait 워크플로를 사용하세요. 페이지가 정상적으로 작동하면 관리형 GitHub 번역 또는 파일 반영 내용을 검토할 수 있는 러너 구성 예제를 선택하세요. 이 과정에서도 콘텐츠 로더 검증과 Next.js 빌드를 계속 실행하세요. lingo check만으로는 문서가 모두 갖춰졌는지, 사용자 정의 태그가 올바르게 렌더링되는지 보장할 수 없습니다.