웹 앱 로컬라이제이션
번역된 카탈로그를 프레임워크의 로캘 선택, 리소스 로딩, 렌더링 검사 과정에 연결하세요.
웹 앱이 이미 로캘 파일의 메시지를 렌더링하고 있다면 기존 방식을 그대로 유지하세요. 기존 라이브러리가 로캘을 선택하고 메시지를 로드해 렌더링하는 동안 Lingo.dev로 원본 카탈로그를 번역할 수 있습니다. 애플리케이션 전체로 확장하기 전에 한 화면에서 이 과정을 끝까지 확인하세요.
이 가이드는 여러 프레임워크에서 사용하는 기존 키 기반 카탈로그를 다룹니다. @lingo.dev/react를 사용하는 원문·문맥 기반 메시지는 리액트 빠른 시작 또는 마이그레이션 가이드를 참고하세요. 이 방식으로 추출한 식별자는 기존 i18next 또는 next-intl 카탈로그의 키와 다릅니다.
전체 과정을 검증할 테스트 화면 준비하기 #
레이블, 변수가 포함된 메시지, 복수형 또는 조건부 메시지가 있는 화면을 선택하세요. 기존 라이브러리로 이 화면을 원본 언어로 렌더링하세요. 네임스페이스, 보간 구문, 조회 키는 그대로 유지하세요. 범용 제이슨 번역 기능은 한 라이브러리의 메시지 문법을 다른 라이브러리의 문법으로 바꿔 주지 않습니다.
기존 react-i18next 원본이 public/locales/en/translation.json에 있다면 프로젝트 루트에서 CLI를 초기화하세요.
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'public/locales/en/translation.json' --yes
lingo link연결된 .lingo/config.json의 구조는 다음과 같아야 합니다.
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es"],
"files": [{ "pattern": "public/locales/en/translation.json" }]
}연결 과정에서 생성된 실제 조직 식별자와 로컬라이제이션 엔진 식별자를 그대로 유지하세요. 다른 프레임워크를 사용한다면 아래 해당 섹션의 원본 경로로 바꾸세요. 원본 카탈로그만 선택하고 대상 경로는 로더에 맞추세요. 경로에 로캘 구간이 없는 구조라면 명시적 대상 경로를 사용하세요.
다음 명령으로 누락된 대상을 번역하세요.
lingo push --backfill-missing --wait완료되면 생성된 카탈로그를 확인하고 스페인어로 화면을 로드하세요. 두 언어에 동일한 변숫값과 복수형 사례를 적용해 비교하세요. 아래의 프레임워크별 단계에서는 이 파일을 실제 요청이나 빌드에 연결합니다. 처음에는 별도 옵션 없이 푸시해 누락된 번역을 요청하지 않고 기준 상태만 저장할 수도 있습니다.
결과 반영 작업이 실행될 때까지 대상 파일을 변경하지 마세요. 기존 로컬 수정 사항을 충돌로부터 보호해야 한다면 --wait 없이 제출하고 lingo pull --dry-run를 확인한 다음, 제출에 사용한 checkout에서 결과를 가져오세요. 검토된 번역 보존하기를 참고하세요.
react-i18next를 사용하는 리액트 #
react-i18next를 사용할 때는 기존 네임스페이스와 조회 호출을 유지하세요. public/locales/en/translation.json의 원본은 public/locales/es/translation.json에 대응합니다. 애플리케이션에서 여러 네임스페이스를 사용한다면 생성된 스페인어 파일까지 잡히는 글로브 패턴 대신 영어 원본을 각각 설정하세요.
i18next 리소스 로더가 대상 로캘과 네임스페이스를 요청하도록 설정하세요. 그런 다음 기존 useTranslation 호출로 테스트 화면을 렌더링하세요. 변수 치환과 설치된 i18next 버전의 복수형 키 규칙을 확인하세요. 범용 제이슨 번역기는 한 라이브러리의 복수형 스키마를 다른 라이브러리의 스키마로 바꿔 주지 않습니다. 클라이언트 애플리케이션에서는 화면에 표시되는 텍스트와 함께 리소스 네트워크 요청도 확인하세요. 영어가 대체 언어로 표시되면 스페인어 파일의 누락을 알아채지 못할 수 있습니다.
next-intl을 사용하는 넥스트제이에스 앱 라우터 #
next-intl에서는 일반적으로 messages/en.json를 원본으로 사용해 messages/es.json를 생성합니다. next-intl 설정에서 요청 시점에 로캘을 결정하고 그에 맞는 메시지를 로드하도록 구성하세요. 로캘별 경로와 탐색 방식도 이 선택에 맞춰 일관되게 유지하세요.
대상 로캘로 직접 요청할 때와 다른 로캘에서 이동할 때 모두 테스트 화면을 렌더링하세요. 서버 렌더링 콘텐츠, 클라이언트 하이드레이션, ICU 변수 또는 복수형을 확인하세요. 메시지 파일만 번역한다고 앱 라우터에 로캘 경로 구간이나 언어 전환기가 추가되지는 않습니다. 이러한 인터페이스 카탈로그와 함께 긴 문서도 다룬다면 넥스트제이에스에서 마크독 사용하기를 참고하세요.
next-i18next를 사용하는 넥스트제이에스 페이지 라우터 #
next-i18next를 사용할 때는 원본 패턴을 기존 로캘 디렉터리와 네임스페이스에 맞추세요. 원본이 public/locales/en/common.json와 public/locales/en/checkout.json라면 두 파일 모두 같은 구조의 스페인어 파일로 번역하세요. messages/en.json를 사용한다면 실제로 해당 파일을 읽는 사용자 지정 로더를 유지하세요.
페이지에서 이미 사용하는 서버 측 또는 정적 데이터 로딩 경로로 필요한 네임스페이스를 로드하세요. 현지화된 페이지에 직접 요청하는 경우와 클라이언트 측에서 경로를 변경하는 경우를 모두 확인하세요. 초기 페이지 데이터와 클라이언트 런타임의 로캘 및 네임스페이스가 일치하는지도 확인하세요. 디스크에 번역 파일이 있어도 페이지에 포함되지 않으면 소용이 없습니다.
vue-i18n을 사용하는 뷰 #
vue-i18n은 src/locales/en.json와 src/locales/es.json 같은 사전을 로드할 수 있습니다. 영어 원본을 번역한 다음 기존 국제화 인스턴스에 스페인어 사전을 등록하거나 동적으로 로드하세요. 선택한 로캘은 앱에서 이미 로캘을 관리하는 곳에서 설정하세요.
테스트 화면에서 $t 또는 useI18n 호출을 실행해 보세요. 중첩 키, 보간, 설치된 라이브러리의 복수형 메시지 구문을 확인하세요. 페이지를 새로 로드하는 경우와 새로고침 없이 로캘을 전환하는 경우를 모두 테스트하세요. 가져오기 구문으로 사전을 번들에 포함한다면 번역 파일도 빌드에 포함되는지 확인하세요.
국제화 모듈을 사용하는 넉스트 #
넉스트 국제화 모듈에서는 locales/en.json 같은 원본을 locales/es.json로 번역하세요. 설치된 버전에 맞는 모듈 설정에 로캘과 파일을 등록하세요. 설정한 언어 디렉터리와 CLI의 출력 경로가 일치하도록 맞추세요.
번역 작업에서 별도의 경로 전략을 만들지 말고 프로젝트의 기존 로캘별 경로 전략을 따르세요. 테스트 페이지에서 서버 렌더링, 지연 로딩, 현지화된 탐색, 메타데이터를 확인하세요. 번역 설정에 대상을 추가해도 넉스트의 로캘 목록에 자동으로 추가되지는 않습니다.
스벨트 및 스벨트킷 사전 #
svelte-i18n에서는 src/lib/locales/en.json 같은 사전을 번역하세요. 대상 사전이나 해당 사전의 지연 로더를 등록하고, 컴포넌트에서 사용하기 전에 선택한 로캘을 초기화하세요.
애플리케이션의 기존 번역 저장소로 테스트 화면을 렌더링하세요. 앱에서 서버 측 렌더링을 사용한다면 먼저 새로운 서버 렌더링 요청을 테스트한 다음 클라이언트에서 로캘을 변경해 보세요. 서버 요청마다 로캘 상태가 분리되는지, 대상 사전이 끝까지 로드되는지 확인하세요. 대체 언어로 표시된 결과를 번역 완료의 근거로 삼지 마세요.
앵귤러 XLIFF #
먼저 앵귤러의 국제화 워크플로로 메시지를 표시하고 추출하세요. XLIFF 처리기는 일반 텍스트와 인라인 코드를 포함한 XLIFF 1.2 및 2.x를 지원합니다. <g>와 <pc>처럼 쌍을 이루는 코드 안의 텍스트는 구조를 유지한 채 번역되며, <ph> 같은 독립형 코드는 보호됩니다. 메시지와 인라인 코드의 식별자를 그대로 유지하고, 대상 카탈로그를 가져오기 전에 반환된 자리표시자를 확인하세요.
지원되는 입력에서는 src/locale/en/messages.xlf가 src/locale/es/messages.xlf에 대응합니다. XLIFF는 messages.en.xlf에서 messages.es.xlf로 접미사를 치환하는 방식을 사용하지 않으므로 로캘 디렉터리나 명시적 대상 템플릿을 사용하세요. 번역을 앵귤러로 다시 가져올 때는 메시지 식별자를 보존하세요.
앵귤러의 로컬라이제이션 빌드 설정에 대상 파일을 등록하고 대상 로캘의 번들을 빌드한 다음, 이를 제공해 화면을 확인하세요. 앵귤러의 컴파일 시점 로컬라이제이션은 런타임 제이슨 로더와 다릅니다. 브라우저 로캘을 바꿔도 누락된 현지화 번들이 빌드되지는 않습니다. 번들을 승인하기 전에 메시지 누락 여부와 자리표시자 렌더링을 확인하세요.
아스트로 #
인터페이스 레이블은 src/i18n/en.json를 같은 구조의 대상 파일로 번역하고 자체 사전 로더가 해당 파일을 선택하도록 설정하세요. 콘텐츠 컬렉션은 로캘별 마크다운 또는 MDX 원본을 번역하고 정적 콘텐츠 워크플로를 사용하세요.
번역과는 별개로 아스트로의 로캘 라우팅을 설정하세요. 생성된 대상 경로를 빌드하고 직접 접속해 로캘 버전 간 링크와 자체 메시지를 로드하는 클라이언트 아일랜드를 확인하세요. 콘텐츠 컬렉션과 아일랜드의 인터페이스 사전에는 별도의 입력이 필요할 수 있습니다.
Laravel #
Laravel 로컬라이제이션에서는 lang/en/messages.php 같은 PHP 원본이 lang/es/messages.php에 대응합니다. 배열 키와 런타임 치환 이름을 보존하세요. 지원되는 카탈로그 구조 외에 실행 코드가 포함된 파일을 선택하기 전에는 PHP 형식 레퍼런스를 참고하세요.
애플리케이션의 기존 미들웨어나 컨트롤러 정책으로 요청 로캘을 설정하고 Laravel의 번역 도우미로 메시지를 렌더링하세요. 치환 값과 복수형 선택을 테스트하세요. 지원되는 각 로캘의 요청과 대체 언어가 사용되는 경우를 모두 테스트하세요. 번역 파일이 요청 로캘을 선택해 주지는 않습니다.
장고 #
장고의 추출 워크플로로 locale/en/LC_MESSAGES/django.po를 만든 다음, 이 원본 PO 파일을 대상 로캘 디렉터리의 파일로 번역하세요. 겟텍스트 메시지 식별자, 문맥, 보간을 보존하세요. 프로젝트의 기존 겟텍스트 빌드 단계에서 번역된 PO 파일을 장고가 실제로 로드하는 리소스로 컴파일하세요.
장고의 언어 선택과 언어 목록을 설정하세요. 번역 미들웨어를 거치는 현지화 요청을 확인하고 단수형 및 복수형 호출을 렌더링하세요. 디스크에 PO 파일이 있다고 해서 컴파일된 카탈로그가 최신 상태라는 뜻은 아닙니다. 파일 규약은 겟텍스트를 참고하세요.
Rails #
Rails는 루트 키를 기준으로 로캘 루트 YAML 파일을 식별합니다. yaml-root-key를 선택한 다음 Rails의 로캘 설정, 도우미, 보간을 확인하세요. 관심사별 파일, 요청 로캘 전환, 범위를 지정한 업데이트를 포함한 전체 절차는 Rails 앱 로컬라이제이션에서 다룹니다.
반복 번역의 결과를 검토할 수 있도록 구성하기 #
화면이 정상적으로 작동하면 나머지 원본 카탈로그와 해당 로더를 추가하세요. 승인된 대상 파일은 원본 리비전, CLI의 Lockfile과 함께 보관하세요. 이후 원본이 변경되면 lingo push --wait로 일반적인 변경분을 처리하세요. 반면 위치 인수로 파일 패턴을 지정하면 범위를 한정해 계획을 수립합니다.
GitHub App 또는 지속적 통합 구성 예제를 통해 원본 변경 트리거와 결과 반영 방식을 선택하세요. GitLab, Bitbucket, GitHub Actions 구성 예제는 CLI를 실행하며, 저장소에 결과를 반영하는 설정은 별도로 마련해야 합니다. 결과물에 프레임워크의 빌드 또는 리소스 검사를 실행한 다음 번역의 의미를 검토하세요. lingo check는 모든 프레임워크를 검증하거나 PHP, PO, XLIFF의 완전성을 보장하지 않습니다.
에이전트의 도움을 받아 로더를 살펴보고 설정 변경을 제안받을 수 있습니다. 워크플로를 확장하기 전에 이러한 수정 사항에도 동일한 원본 선택, 빌드, 렌더링 화면 검사를 적용하세요.