메시지 카탈로그 추출 및 로드
원본 메시지를 추출하고 번역된 JSONC 파일을 가져온 뒤, 해당 원본 메타데이터로 런타임 맵을 만듭니다.
컴포넌트에는 원본 메시지와 그 맥락이 담겨 있습니다. 추출은 이러한 호출을 번역할 수 있는 파일로 모으는 작업이고, 로드는 번역된 값을 컴포넌트의 키에 다시 연결하는 작업입니다. 이 가이드에서는 첫 인사말에 이 파일 기반 워크플로를 적용해 프로바이더에 필요한 Messages 맵을 만듭니다.
원본 추출 #
애플리케이션에 CLI와 로더 의존성을 설치합니다.
npm install --save-dev @lingo.dev/cli@latest
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npx lingo extract --src src --source-locale en추출은 로컬에서 실행되며 API 키가 필요하지 않습니다. 기본적으로 locales/en.jsonc 및 lingo.d.ts 파일을 생성합니다. 명시적으로 지정한 --out 및 --types 플래그가 설정된 i18n.messagesPath 및 i18n.typesPath보다 우선하고, 설정값은 기본값보다 우선합니다. src 밖에도 호출이 있는 페이지스 애플리케이션에서는 --src pages처럼 실제 디렉터리를 사용합니다.
인사말 항목을 확인하세요. 값에는 완전한 영어 템플릿이 들어 있고, 키는 원본과 맥락을 바탕으로 생성됩니다. 항목 앞의 주석에는 의미를 나타내는 @context, 원본 위치를 나타내는 @src, 이전에 추출한 항목이 더 이상 활성 상태가 아님을 나타내는 @orphan이 기록됩니다. 번역을 요청하기 전에 이러한 변경 사항을 검토하세요.
선택한 카탈로그 번역 #
Lingo.dev 설정이 없는 애플리케이션에서는 이 파일과 번역 대상인 스페인어를 초기화한 다음, 인증을 거쳐 로컬라이제이션 엔진을 연결합니다.
npx lingo init --source en --targets es --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link활성화된 로컬라이제이션 엔진에 대한 접근 권한과 충분한 계정 사용 한도가 필요합니다. 무인 실행에 필요한 인증 정보는 CLI 인증에서 설명합니다.
.lingo/config.json이 이미 있다면 기존 바인딩과 다른 파일 항목을 유지하세요. locales/en.jsonc을 선택하는 항목을 추가하거나 업데이트하고, 프로젝트의 원본 로캘이 en인지 확인하세요. 기존 기준 버전이 있다면 먼저 npx lingo push --wait으로 기존 대상 로캘의 일반 업데이트를 마치세요. 검토가 필요한 상태나 실패 상태를 모두 해결하고 가져온 변경 사항을 확인한 뒤, targetLocales에 es을 추가하세요. 이후 누락분을 채우는 동안에는 원본 리비전을 고정해 두세요. 이 순서는 언어 추가에서 설명합니다. 설정을 편집할 때는 init --force을 사용하지 마세요. 파일 항목을 다시 생성하는 과정에서 고급 옵션이 사라질 수 있습니다. 전체 구조는 설정에서 확인할 수 있습니다.
새 프로젝트이거나 기존 프로젝트에서 위 준비를 마쳤다면, 누락된 대상 파일을 요청하고 가져오기가 끝날 때까지 기다리세요. 이 명령이 대기하는 동안에는 대상 파일을 변경하지 마세요. 다운로드 과정에서 로컬 편집 내용을 덮어쓸 수 있습니다.
npx lingo push --backfill-missing --wait실행이 끝나면 locales/es.jsonc을 확인하세요. 보고된 검토 필요 상태나 실패 상태를 모두 해결해야 결과물을 완료된 것으로 볼 수 있습니다. 이후 원본이 변경되면 다시 추출하고 npx lingo push --wait을 사용하세요. 누락분 채우기는 없는 파일을 가져오는 작업이며, 기존 대상의 일반 업데이트에 사용하는 작업이 아닙니다.
대상 리비전과 함께 원본 메타데이터 보관 #
일반적인 JSONC 번역 워크플로에서는 원본의 @orphan 표시가 대상에도 유지되지만, @context 및 @src 주석은 제거됩니다. 대상 파일만으로는 로더가 메시지가 어느 페이지에 속했는지 알 수 없습니다.
대상과 동일한 리비전에서 추출한 원본 파일을 보관하세요. 그 원본에서 활성 항목을 선택하고, 각 키를 대상의 번역된 값과 결합하세요. 이렇게 하면 삭제된 메시지를 제외하면서 원본 라우트별로 항목을 선택할 수 있습니다. 대상에 없는 키는 추가하지 않고 그대로 두어 런타임이 원본으로 대체할 수 있게 합니다.
원시 카탈로그 파싱 #
애플리케이션에서 직접 관리하는 다음 로더로 src/catalog.ts을 만듭니다.
import { parse, type ParseError } from "jsonc-parser";
import { getActiveEntries, readLocaleFile, type LocaleEntry } from "@lingo.dev/spec";
import type { Messages } from "@lingo.dev/react";
function readStringCatalog(raw: string) {
const errors: ParseError[] = [];
const value: unknown = parse(raw, errors, { allowTrailingComma: true });
if (
errors.length > 0 ||
value === null ||
typeof value !== "object" ||
Array.isArray(value) ||
Object.values(value).some((entry) => typeof entry !== "string")
) {
throw new Error("Expected a flat JSONC object with string values");
}
return readLocaleFile(raw);
}
export function loadMatchedMessages(
sourceJsonc: string,
targetJsonc: string,
include: (entry: LocaleEntry) => boolean = () => true,
): Messages {
const active = getActiveEntries(readStringCatalog(sourceJsonc).entries);
const target = new Map(readStringCatalog(targetJsonc).entries.map((entry) => [entry.key, entry.value]));
return Object.fromEntries(
active.filter(include).flatMap((entry) => {
const value = target.get(entry.key);
return value === undefined ? [] : [[entry.key, value]];
}),
);
}readLocaleFile은 JSONC 구문과 메타데이터를 파싱하지만, 런타임 데이터 구조를 검증하지는 않습니다. 선언된 항목 타입과 달리 배열과 문자열이 아닌 값도 허용하며, 루트가 원시 값이거나 널이면 항목을 반환하지 않습니다. 위의 첫 번째 함수는 값이 렌더러에 전달되기 전에 이러한 구조를 거부합니다. 두 함수 모두 로컬에서 실행되며 입출력 작업을 수행하지 않습니다.
비트 애플리케이션에서는 프로바이더에 데이터를 제공하는 모듈에서 파일을 원시 텍스트로 로드합니다.
import source from "../locales/en.jsonc?raw";
import target from "../locales/es.jsonc?raw";
import { loadMatchedMessages } from "./catalog";
export const spanishMessages = loadMatchedMessages(source, target);여기서는 모듈이 src 바로 아래에 있고 비트의 클라이언트 타입이 포함되어 있다고 가정합니다. locale="es"를 사용해 spanishMessages을 messages으로 전달하세요. 이제 인사말은 가져온 스페인어 템플릿을 사용하면서 {name}을 Ana으로 대체해야 합니다. 실제 문구를 확인하고 항목이 누락된 경우도 테스트하세요. 파일을 로드하는 작업과 언어 품질을 판단하는 작업은 별개입니다.
라우트에 필요한 원본 항목만 선택 #
선택 사항인 include 조건 함수는 결합 전에 활성 원본 항목을 대상으로 실행됩니다. 페이지 로더는 entry.metadata.src을 사용해 자체 호출과 공유 컴포넌트를 포함할 수 있습니다. 이 선택 작업은 메타데이터가 남아 있는 원본에서 수행하세요. 배포할 때는 원본과 대상을 함께 보관해 라우트 선택에 다른 리비전의 키가 사용되지 않도록 하세요.
넥스트 페이지스 가이드는 완전한 라우트 조건 함수를 제공합니다. 탠스택 가이드는 요청 카탈로그에 이 로더를 사용합니다. 두 가이드의 내장 로더는 메타데이터가 있는 파일을 필터링할 수 있지만, 어느 쪽도 주석이 없는 대상을 원본 메타데이터와 자동으로 결합하지는 않습니다.
명세 헬퍼 레퍼런스 #
| 내보내기 | 동작 규약 |
|---|---|
readLocaleFile(content): LocaleFile | 후행 쉼표를 포함한 JSONC와 항목 앞의 메타데이터 블록 주석을 파싱합니다. 구문 오류가 있으면 예외를 발생시킵니다. |
getActiveEntries(entries): LocaleEntry[] | metadata.orphan이 참으로 평가되지 않는 항목을 유지합니다. |
LocaleFile | { entries: LocaleEntry[] }. |
LocaleEntry | { key: string; value: string; metadata: EntryMetadata }. |
EntryMetadata | 선택 사항인 context, src, orphan. |
computeKey(source, context?) | 정규화된 원본/맥락의 공통 식별자이며, 리액트에서도 내보냅니다. |
buildIcuPlural(forms) | 알려진 기수 범주를 표준 순서로 출력합니다. |
buildIcuSelect(forms) | 선택지를 키 순서로 정렬해 출력합니다. |
ICU 빌더는 문자열 레코드를 받습니다. 리액트의 복수형 및 선택 타입은 필수 other 형식을 추가합니다. 생성된 런타임 카탈로그는 LocaleFile이 아니라 일반 Messages 맵입니다.
키가 있는 기존 리소스, 문서, 정적 타입스크립트 로캘 모듈은 이 추출 가이드 대신 각각의 형식 처리기를 사용합니다. 예제 프로젝트에서 이러한 구조와 리액트 애플리케이션을 함께 살펴볼 수 있습니다.